fix(build): 修复 Web 构建组件注册和用户脚本打包问题 (#302)

* refactor(build): 重构 Web 构建管线，支持配置驱动的 Import Maps

- 重构 WebBuildPipeline 支持 split-bundles 和 single-bundle 两种构建模式
- 使用 module.json 的 isCore 字段识别核心模块，消除硬编码列表
- 动态生成 Import Map，从模块清单的 name 字段获取包名映射
- 动态扫描 module.json 文件，不再依赖固定模块列表
- 添加 HTTP 服务器启动脚本 (start-server.bat/sh) 支持 ESM 模块
- 更新 BuildSettingsPanel UI 支持新的构建模式选项
- 添加多语言支持 (zh/en/es)

* fix(build): 修复 Web 构建组件注册和用户脚本打包问题

主要修复:
- 修复组件反序列化时找不到类型的问题
- @ECSComponent 装饰器现在自动注册到 ComponentRegistry
- 添加未使用装饰器的组件警告
- 构建管线自动扫描用户脚本（无需入口文件）

架构改进:
- 解决 Decorators ↔ ComponentRegistry 循环依赖
- 新建 ComponentTypeUtils.ts 作为底层无依赖模块
- 移除冗余的防御性 register 调用
- 统一 ComponentType 定义位置

* refactor(build): 统一 WASM 配置架构，移除硬编码

- 新增 wasmConfig 统一配置替代 wasmPaths/wasmBindings
- wasmConfig.files 支持多候选源路径和明确目标路径
- wasmConfig.runtimePath 指定运行时加载路径
- 重构 _copyWasmFiles 使用统一配置
- HTML 生成使用配置中的 runtimePath
- 移除 physics-rapier2d 的冗余 WASM 配置（由 rapier2d 负责）
- IBuildFileSystem 新增 deleteFile 方法

* feat(build): 单文件构建模式完善和场景配置驱动

## 主要改动

### 单文件构建（single-file mode）
- 修复 WASM 初始化问题，支持 initSync 同步初始化
- 配置驱动的 WASM 识别，通过 wasmConfig.isEngineCore 标识核心引擎模块
- 从 wasmConfig.files 动态获取 JS 绑定路径，消除硬编码

### 场景配置
- 构建验证：必须选择至少一个场景才能构建
- 自动扫描：项目加载时扫描 scenes 目录
- 抽取 _filterScenesByWhitelist 公共方法统一过滤逻辑

### 构建面板优化
- availableScenes prop 传递场景列表
- 场景复选框可点击切换启用状态
- 移除动态 import，使用 prop 传入数据

* chore(build): 补充构建相关的辅助改动

- 添加 BuildFileSystemService 的 listFilesByExtension 优化
- 更新 module.json 添加 externalDependencies 配置
- BrowserRuntime 支持 wasmModule 参数传递
- GameRuntime 添加 loadSceneFromData 方法
- Rust 构建命令更新
- 国际化文案更新

* feat(build): 持久化构建设置到项目配置

## 设计架构

### ProjectService 扩展
- 新增 BuildSettingsConfig 接口定义构建配置字段
- ProjectConfig 添加 buildSettings 字段
- 新增 getBuildSettings / updateBuildSettings 方法

### BuildSettingsPanel
- 组件挂载时从 projectService 加载已保存配置
- 设置变化时自动保存（500ms 防抖）
- 场景选择状态与项目配置同步

### 配置保存位置
保存在项目的 ecs-editor.config.json 中：
- scenes: 选中的场景列表
- buildMode: 构建模式
- companyName/productName/version: 产品信息
- developmentBuild/sourceMap: 构建选项

* fix(editor): Ctrl+S 仅在主编辑区域触发保存场景

- 模态窗口打开时跳过（构建设置、设置、关于等）
- 焦点在 input/textarea/contenteditable 时跳过

* fix(tests): 修复 ECS 测试中 Component 注册问题

- 为所有测试 Component 类添加 @ECSComponent 装饰器
- 移除 beforeEach 中的 ComponentRegistry.reset() 调用
- 将内联 Component 类移到文件顶层以支持装饰器
- 更新测试预期值匹配新的组件类型名称
- 添加缺失的 HierarchyComponent 导入

所有 1388 个测试现已通过。

packages/runtime-core/src/GameRuntime.ts

@@ -641,6 +641,15 @@ export class GameRuntime {
         await this.loadScene(sceneJson);
     }
 
+    /**
+     * 从数据对象加载场景（用于单文件模式）
+     * Load scene from data object (for single-file mode)
+     */
+    async loadSceneFromData(sceneData: unknown): Promise<void> {
+        const sceneJson = JSON.stringify(sceneData);
+        await this.loadScene(sceneJson);
+    }
+
     /**
      * 调整视口大小
      * Resize viewport

packages/runtime-core/src/index.ts

@@ -66,11 +66,18 @@ export {
 export {
     BrowserFileSystemService,
     createBrowserFileSystem,
-    type AssetCatalog,
-    type AssetCatalogEntry,
     type BrowserFileSystemOptions
 } from './services/BrowserFileSystemService';
 
+// Re-export catalog types from asset-system (canonical source)
+// 从 asset-system 重新导出目录类型（规范来源）
+export type {
+    IAssetCatalog,
+    IAssetCatalogEntry,
+    IAssetBundleInfo,
+    AssetLoadStrategy
+} from '@esengine/asset-system';
+
 // Re-export Input System from engine-core for convenience
 export {
     Input,

packages/runtime-core/src/services/BrowserFileSystemService.ts

@@ -9,28 +9,16 @@
  * Uses asset catalog to resolve GUIDs to actual URLs.
  */
 
-/**
- * Asset catalog entry
- */
-export interface AssetCatalogEntry {
-    guid: string;
-    path: string;
-    type: string;
-    size: number;
-    hash: string;
-}
-
-/**
- * Asset catalog loaded from JSON
- */
-export interface AssetCatalog {
-    version: string;
-    createdAt: number;
-    entries: Record<string, AssetCatalogEntry>;
-}
+import type {
+    IAssetCatalog,
+    IAssetCatalogEntry,
+    IAssetBundleInfo,
+    AssetLoadStrategy
+} from '@esengine/asset-system';
 
 /**
  * Browser file system service options
+ * 浏览器文件系统服务配置
  */
 export interface BrowserFileSystemOptions {
     /** Base URL for assets (e.g., '/assets' or 'https://cdn.example.com/assets') */
@@ -43,15 +31,19 @@ export interface BrowserFileSystemOptions {
 
 /**
  * Browser File System Service
+ * 浏览器文件系统服务
  *
  * Provides file system-like API for browser environments
- * by fetching files over HTTP.
+ * by fetching files over HTTP. Supports both file-based and bundle-based loading.
+ * 为浏览器环境提供类文件系统 API，通过 HTTP fetch 加载文件。
+ * 支持基于文件和基于包的两种加载模式。
  */
 export class BrowserFileSystemService {
     private _baseUrl: string;
     private _catalogUrl: string;
-    private _catalog: AssetCatalog | null = null;
+    private _catalog: IAssetCatalog | null = null;
     private _cache = new Map<string, string>();
+    private _bundleCache = new Map<string, ArrayBuffer>();
     private _enableCache: boolean;
     private _initialized = false;
 
@@ -63,6 +55,7 @@ export class BrowserFileSystemService {
 
     /**
      * Initialize service and load catalog
+     * 初始化服务并加载目录
      */
     async initialize(): Promise<void> {
         if (this._initialized) return;
@@ -70,24 +63,62 @@ export class BrowserFileSystemService {
         try {
             await this._loadCatalog();
             this._initialized = true;
-            console.log('[BrowserFileSystem] Initialized with',
-                Object.keys(this._catalog?.entries ?? {}).length, 'assets');
+
+            const strategy = this._catalog?.loadStrategy ?? 'file';
+            const assetCount = Object.keys(this._catalog?.entries ?? {}).length;
+            console.log(`[BrowserFileSystem] Initialized: ${assetCount} assets, strategy=${strategy}`);
         } catch (error) {
             console.warn('[BrowserFileSystem] Failed to load catalog:', error);
             // Continue without catalog - will use path-based loading
+            // 无目录时继续，使用基于路径的加载
             this._initialized = true;
         }
     }
 
     /**
      * Load asset catalog
+     * 加载资产目录
      */
     private async _loadCatalog(): Promise<void> {
         const response = await fetch(this._catalogUrl);
         if (!response.ok) {
             throw new Error(`Failed to fetch catalog: ${response.status}`);
         }
-        this._catalog = await response.json();
+
+        const rawCatalog = await response.json();
+
+        // Normalize catalog format (handle legacy format without loadStrategy)
+        // 规范化目录格式（处理没有 loadStrategy 的旧格式）
+        this._catalog = this._normalizeCatalog(rawCatalog);
+    }
+
+    /**
+     * Normalize catalog to ensure it has all required fields
+     * 规范化目录，确保包含所有必需字段
+     */
+    private _normalizeCatalog(raw: Record<string, unknown>): IAssetCatalog {
+        // Determine load strategy
+        // 确定加载策略
+        let loadStrategy: AssetLoadStrategy = 'file';
+        if (raw.loadStrategy === 'bundle' || raw.bundles) {
+            loadStrategy = 'bundle';
+        }
+
+        return {
+            version: (raw.version as string) ?? '1.0.0',
+            createdAt: (raw.createdAt as number) ?? Date.now(),
+            loadStrategy,
+            entries: (raw.entries as Record<string, IAssetCatalogEntry>) ?? {},
+            bundles: (raw.bundles as Record<string, IAssetBundleInfo>) ?? undefined
+        };
+    }
+
+    /**
+     * Get current load strategy
+     * 获取当前加载策略
+     */
+    get loadStrategy(): AssetLoadStrategy {
+        return this._catalog?.loadStrategy ?? 'file';
     }
 
     /**
@@ -237,8 +268,9 @@ export class BrowserFileSystemService {
 
     /**
      * Get asset metadata from catalog
+     * 从目录获取资产元数据
      */
-    getAssetMetadata(guidOrPath: string): AssetCatalogEntry | null {
+    getAssetMetadata(guidOrPath: string): IAssetCatalogEntry | null {
         if (!this._catalog) return null;
 
         // Try as GUID
@@ -258,8 +290,9 @@ export class BrowserFileSystemService {
 
     /**
      * Get all assets of a specific type
+     * 获取指定类型的所有资产
      */
-    getAssetsByType(type: string): AssetCatalogEntry[] {
+    getAssetsByType(type: string): IAssetCatalogEntry[] {
         if (!this._catalog) return [];
 
         return Object.values(this._catalog.entries)
@@ -268,6 +301,7 @@ export class BrowserFileSystemService {
 
     /**
      * Clear cache
+     * 清除缓存
      */
     clearCache(): void {
         this._cache.clear();
@@ -275,8 +309,9 @@ export class BrowserFileSystemService {
 
     /**
      * Get catalog
+     * 获取目录
      */
-    get catalog(): AssetCatalog | null {
+    get catalog(): IAssetCatalog | null {
         return this._catalog;
     }