@fulgurjs/federation 5.7.1 → 5.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 5.9.0
+
+- **新增 CLI：`fulgurjs create`——完整工程创建向导（新项目入口）**。从已安装 npm 包内复制一个完整模板工程（workspace + 子应用 + 锁文件 + 统一启动脚本）并默认执行 `pnpm install --frozen-lockfile`；交互（TTY）与显式参数（`create <模板> [--dir] [--no-install] [--force] [--json]`）双形态；目标目录非空默认拒绝（`--force` 只增量复制不删除）；复制后校验关键文件齐全；安装失败非零退出并透传原因；完成后打印进入/启动/构建/部署命令（入口从模板 `scripts/dev.config.json` 读取）。与 `init` 职责区分：init 面向已有项目生成单文件配置（`--template` 语义不变，仍是输出路径）；create 从零创建完整工程，模板唯一来源为包内 `examples/templates/`，不 clone 插件仓库、不依赖作者路径。不做应用名称/端口改写（改端口清单在模板 README）。
+- **模板统一 dev 启动器**：五个模板根 `dev` 脚本由 shell `&` 改为 `node scripts/dev.mjs`（规范源 `examples/scripts/dev-runner.mjs`，经同步脚本分发五模板，`check-catalog` 门禁校验逐字节一致）。行为：启动前端口预检（占用即拒绝并指认处理方法，不杀既有进程）→ 远程先宿主后按序启动、逐个探活 → 任一应用失败/超时/运行中退出即整组清理并打印日志尾部（非零退出码）→ Ctrl+C/SIGTERM 只清理本次启动的子进程（进程组级，无 PID 文件依赖）。单独调试入口 `dev:remote`/`dev:host`（showcase 四个）保留。平台：macOS/Linux 实测，Windows 兜底路径未验证（模板 README 如实标注）。
+- **CLI/文档引导一致性**：`init` 成功提示不再把 hostPages 页面表写进默认后续步骤（普通组件接入无需页面表，仅页面表接入才需要）；`init` 生成模板注释与核对清单、`doctor --apps` 全部统一为「部署子目录」语义（此前 init 提示写「容器名」，与 doctor 实现——拼 `<base>/<app>/` 部署路径——不一致，易填错）。
+- **explain 桥接完备性 WARN**（纯本地启发式，不新增错误码）：exposes 含 `./bridge` 的子应用未以 `singleton: true` 共享本框架（React 子应用需 react+react-dom 双键）；shared 同时含 vue 与 react 的桥接宿主未三键全 singleton——输出现象/修法，提前拦住 Invalid hook call/双实例类配置错误。
+- **README 中英同步**：跨框架桥接节新增「最短理解」表（两端框架安装合同、shared/singleton 作用、入口导出、宿主挂载、URL 同步时机、会话与卸载）与「appProps 挂载快照」三通道表（稳定回调/共享 store/key 显式重挂各自适用场景）；新增「从零开始」create 入口；API 手册（中英）补 CLI 命令总表。
+- 模板依赖随发布升级 5.9.0（精确版本 + 锁文件重生成，冻结安装验证）。
+- 版本 5.8.0 → 5.9.0。
+
+## 5.8.0
+
+- **修复：保留用户 manualChunks 时生产启动挂起/爆 TDZ（MC-FIX，rollup/vite 5–7 路径）**——此前「双向宿主 + 保留业务 manualChunks」与「纯远程 + manualChunks」的生产构建会零报错死锁或 `Cannot access 'x' before initialization`，唯一出路是停用 manualChunks（旧验收记录的"生产三前提①"）。本轮在真实项目（MES admin，对象形式 vue-vendor/antd-vue-vendor 分组）复现并以 chunk 成员图 + 首错栈定位出三层叠加根因，全部修复：
+  - **MC-FIX-1（post 兜底改写缺 node_modules 闸门）**——`buildFallbackTransform`（D6 后置注入兜底，`fulgurjs:vue-post` 与 `fulgurjs:post-last` 共用）此前直接调用 `transformModule`，而 `allowNodeModules` 只存在于 ctx 声明、`transformModule` 从不读取——纯宿主构建里 2000+ 个 node_modules 模块（vue-router/ant-design-vue/element-plus…）对 shared 键的静态导入被错误门面化（pre 阶段闸门正确，post 兜底语义未对齐）。现补齐与 pre.transform 完全一致的 `isTransformableId(id, devSharedSelf || 纯remote || providerCjs)` 闸门。
+  - **MC-FIX-2（对象形式 manualChunks 包装漏 provider 隔离）**——函数形式包装自 5.2.1 起有 `providerChunkOf ?? userFn` 优先级，对象形式只查用户分组表：真实共享本体（vue）被用户 `vue-vendor` 组吞并与被改写的消费方（vue-router）同 chunk，构成「消费方 chunk →静态→ TLA 协商门面 →fallback 动态→ 消费方 chunk」自等待环，页面零报错卡加载（shareScopeMap 恒空、入口 init 永不执行）。现四处 manualChunks 包装（devSharedSelf 函数/对象、宿主隔离 函数/对象/无配置、远程 exposes combined）全部统一为 provider 隔离优先。
+  - **MC-FIX-2C（provider 闭包割裂 → 跨 chunk TDZ）**——仅按包目录前缀归组时，本体闭包内的第三方模块（如 @vue/compiler-dom 依赖的 entities）按共同消费方指纹落入用户 vendor 大组，provider chunk 长出指向用户组的静态边、用户组又静态依赖 provider chunk，环上求值顺序由入口导入序决定，provider chunk 先入环即 TDZ。新增 `providerChunkOfWithClosure`：manualChunks 成组期经 `meta.getModuleInfo` 从 provider 入口（Node 解析的 CJS 链 + Vite 解析的 ESM 链双种子）BFS 收集完整静态闭包并入 provider 组，provider chunk 成为零静态出边的叶子，环被彻底移除。
+  - 验收：单测 654→656（新增纯宿主 manualChunks 回归 + 死锁防线锚点迁移）；e2e dev 43/43 + prod 28/28；真实项目 MES admin（对象分组）manualChunks 保留构建 → chunk 图无环 → 浏览器登录/菜单/深链正常，shareScope=vue@3.5.43；bpm/lowcode（函数形式全量 vendor 分组，最恶劣场景）chunk 图无环；双版本最小复现（host vue 3.5.13 × remote 3.4.38）singleton 协商收敛宿主实例。**旧文档中"必须停用 manualChunks"的兼容结论作废。**
+- 版本 5.7.1 → 5.8.0（含 runtime 同步升版与产物再生）。
+
 ## 5.7.1
 
 - React 桥接兼容 react-dom/client 的 default-only CJS 命名空间（Vite 6 + React 18），使用同一 renderer 完成真实提交与卸载。
@@ -10,7 +29,7 @@
 - HTML 入口配置 runtimePlugins 时增加异步协商屏障；远程 expose 执行前准备共享决策，消费方门面保持原有同步形态。异步选择的外部条目与静态/动态实例统一复用；provider 失败后允许重新裁决。
 - 首次消费者接管单例时按真实物理版本登记，不再把 React 18 实例填入标注 React 19 的槽位而绕过 strictVersion；另一版本的单例正在异步加载时拒绝同步接管，避免并发双实例。
 - runtimePlugins 的相对路径以项目 root 解析，避免入口/虚拟模块位置改变后解析错误。
-- 新增 demo/react-versions：React 19 嵌 React 18 隔离、异步 hook 覆盖首次静态导入、严格拒绝与版本对齐远程的同页恢复、Vue 宿主对齐 React 18。新增 Vite 6/8 dev+prod 浏览器 CI。
+- 新增 examples/demos/react-versions：React 19 嵌 React 18 隔离、异步 hook 覆盖首次静态导入、严格拒绝与版本对齐远程的同页恢复、Vue 宿主对齐 React 18。新增 Vite 6/8 dev+prod 浏览器 CI。
 - 自定义无 HTML 的入口须先完成动态协商再执行消费者，已求值的静态绑定不能追溯改写。
 
 ## 5.7.0
@@ -41,7 +60,7 @@
 
 ## 5.5.1
 
-- **修复：`getLoadedShare` / `pinLoadedShare` / `clearSessionState` 在 `/runtime` 与 `/react` 入口的类型与生成链缺口**——三个函数在内核（`dist/runtime.js`）实际导出且生成脚本向 `runtime-entry.js` 注入了 `clearSessionState`，但 `src/runtime-entry.ts` / `src/react.ts` 源码导出面未包含（发布包 d.ts 因此缺失，TS 消费者不可导入；`getLoadedShare`/`pinLoadedShare` 的 JS 入口导出也缺失）。现统一：源码、d.ts、生成脚本（`gen-runtime-entry.mjs`）三处一致，React 入口补齐同面；导出面守卫测试（`tests/runtime-entry-graph.test.ts`）批准清单同步。包内 `demo` 场景（`demo/shared` 卡片⑫）以真调用覆盖：getLoadedShare 与 loadShare 结果对象严格相等、pinLoadedShare 收敛、clearSessionState 后新代次 onSession 重跑。
+- **修复：`getLoadedShare` / `pinLoadedShare` / `clearSessionState` 在 `/runtime` 与 `/react` 入口的类型与生成链缺口**——三个函数在内核（`dist/runtime.js`）实际导出且生成脚本向 `runtime-entry.js` 注入了 `clearSessionState`，但 `src/runtime-entry.ts` / `src/react.ts` 源码导出面未包含（发布包 d.ts 因此缺失，TS 消费者不可导入；`getLoadedShare`/`pinLoadedShare` 的 JS 入口导出也缺失）。现统一：源码、d.ts、生成脚本（`gen-runtime-entry.mjs`）三处一致，React 入口补齐同面；导出面守卫测试（`tests/runtime-entry-graph.test.ts`）批准清单同步。包内 `demo` 场景（`examples/demos/shared` 卡片⑫）以真调用覆盖：getLoadedShare 与 loadShare 结果对象严格相等、pinLoadedShare 收敛、clearSessionState 后新代次 onSession 重跑。
 
 ## 5.5.0
 
@@ -111,7 +130,7 @@
   - 使用合同：桥接宿主必须同时安装 vue + react + react-dom 并将 shared 三键全部 singleton；纯 Vue / 纯 React 项目零对方依赖不受影响。
   - 修复：dev 跨源场景 react-refresh shim 的自引用顶层 await 死锁（无 @vitejs/plugin-react 的宿主消费 React 远程时页面永久挂起；shim 自身不再参与导入改写）；为无 plugin-react preamble 的宿主注入首个 http(s) dev 远程 origin 的 react-refresh preamble + 页面级单例发布。
   - 新增错误码后 gzip 门禁同步：`bridge-host-vue.js` / `bridge-host-react.js` 各 ≤ 4096B（zlib level9，框架外置）；`runtime.js` ≤ 9216B、`react-adapter.js` ≤ 4096B 维持不变（本轮内核零改动）。
-  - 示例：`examples/bridge/{vue-host,react-host,vue-remote,react-remote}` 四个独立工程（registry 正式包消费，双向各一对）。
+  - 示例：`examples/templates/{vue-host,react-host,vue-remote,react-remote}` 四个独立工程（registry 正式包消费，双向各一对）。
 
 ## 5.2.5
 
@@ -140,7 +159,7 @@
 - **修复：生产静态子依赖失败的用户恢复闭环（D2）**——浏览器 module map 缓存静态子依赖失败（同 URL 再 import 直接拒绝），同页重试无法穿透；默认占位的「刷新页面重试」给出确定的整页恢复路径。`prod B3c` 由「两种结果都能 PASS」改写为确定性门禁：占位双操作可见 → 同页重试（记录结果）→ 产品按钮触发导航（跨刷新标记证明，非测试脚本 reload）→ 目标业务页面真实恢复；新增 Vue 静态依赖生产用例（remote-a 静态依赖链 fixture + host-vue 页面）。
 - **修复：React 跨应用开发更新真实自动传播（D3）**——根因：react-refresh 运行时状态（helpersByRendererID/pending 队列）为模块私有，宿主页内第二份副本（远程 origin）刷新空转。修复：宿主 preamble 后注入发布脚本把页面级 react-refresh 单例发布到 globalThis；远程组件的 /@react-refresh 导入改写到插件 shim（dev），shim 优先委托页面单例、standalone 回退本源实例。R11 重写为「5 轮冷启动 × 3 次修改」零人工刷新热更新保活门禁 + R11b 普通 TS 依赖传播门禁（挂载宿主实际看到新值）。
 - **修复：Vite 5.x 双 client 错误覆盖层 IllegalConstructor（D4）**——Vite 5 客户端对 `vite-error-overlay` 的 define 有注册守卫，双 client 场景第二份客户端的本地 ErrorOverlay 类未注册，按 HTML 规范 new 未注册 HTMLElement 子类抛 IllegalConstructor，远程编译错误覆盖层无法显示。修复：把 Vite ≥6 的注册表构造修法前移到 Vite 5 客户端代码（fulgurjs:dev-client-compat，不改已安装 Vite 源码）；fault.spec 的 5.1.4 版本门控 skip 移除，支持矩阵内该用例全部真实执行（Vite 5.1.4 本地实测通过）。
-- **示例重构（D7）**：examples 按框架分组为 `examples/vue/{host,remote}`（5214/5213）与 `examples/react/{host,remote}`（5204/5203）四个完整可复制工程（npm + registry 精确正式包 + 独立 fulgurjs.config.ts + 完整入口/源码/README），每对演示远程可点击组件、普通 TS 模块调用、联邦首页/参数详情页、宿主导航懒加载、默认错误恢复；旧 `examples/{host,remote-a,react-host,react-remote}` 目录移除。中英文 examples 总入口与 GitHub 根 README 同步。
+- **示例重构（D7）**：examples 按框架分组为 `examples/templates/vue-vue/{host,remote}`（5214/5213）与 `examples/templates/react-react/{host,remote}`（5204/5203）四个完整可复制工程（npm + registry 精确正式包 + 独立 fulgurjs.config.ts + 完整入口/源码/README），每对演示远程可点击组件、普通 TS 模块调用、联邦首页/参数详情页、宿主导航懒加载、默认错误恢复；旧 `examples/{host,remote-a,react-host,react-remote}` 目录移除。中英文 examples 总入口与 GitHub 根 README 同步。
 - **文档（D5）**：中英文 README 与恢复/HMR 实际行为对齐；「失败 dynamic import 绝对不会再次访问网络」等表述限定到真实浏览器边界；支持矩阵与恢复操作口径统一。
 
 ## 5.1.4

package/DESIGN.md

@@ -1,5 +1,8 @@
 # @fulgurjs/federation 设计方案 v0.2（全量对齐 Webpack MF 版）
 
+> **当前状态索引（2026-10-03，5.7.1）**：本文是历史设计，早期“100% 配置/行为对齐”和里程碑状态不作为当前兼容承诺。当前为浏览器端 Vue 3 / React 18–19、子应用桥接及可选 URL 同步；能力和明确差异以 [当前对照表](docs/webpack-mf-对照与缺口.md) 与 [README](README.md) 为准。
+
+
 > **品牌**：fulgurjs，拉丁语「闪电 · 辉光」，取自作者名中「烨」字的意译。
 > 系列规划：`@fulgurjs/federation`（模块联邦）→ `@fulgurjs/micro`、`@fulgurjs/dts` …
 > 内外命名统一 `fulgurjs`（`virtual:fulgurjs-*` 虚拟模块、`window.__FULGURJS_*` 调试出口、`FgError` / MFU 错误码）。