@fulgurjs/federation 5.8.0 → 5.9.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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 成员图 + 首错栈定位出三层叠加根因，全部修复：
@@ -19,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
@@ -50,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
 
@@ -120,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
 
@@ -149,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/README.en.md

@@ -1,25 +1,27 @@
 # @fulgurjs/federation
 
-[简体中文](./README.md) | [English](./README.en.md)
+**[All templates and demos](examples/README.en.md)**: Example catalog and run guide.
+
+[简体中文](README.md) | [English](README.en.md)
 
 **Use components, pages and functions from another Vite application.**
 
 For example, a main application can load a separately deployed approval page, a Vue host can embed a React sub-app, or several applications can use the same utility module. Each application can live in its own repository and build and deploy separately.
 
-This is the usage guide, with examples for **5.7.1**. Signatures, defaults and execution rules are in the [API reference](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md).
+This is the usage guide. Examples and templates are written against **5.8.0** (the exact version in each project's `package.json` is what gets installed). Signatures, defaults and execution rules are in the [API reference](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md).
 
 ## Choose what you need
 
 | Goal | Use | Example |
 |---|---|---|
-| Load a Vue component in Vue | `remoteComponent` | [Vue examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/vue) |
-| Load a React component in React | `remoteComponent` from `/react` | [React examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/react) |
+| Load a Vue component in Vue | `remoteComponent` | [Vue examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/vue-vue) |
+| Load a React component in React | `remoteComponent` from `/react` | [React examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/react-react) |
 | Call a remote JS/TS function | `loadRemote`; React also has `useLoadRemote` | Quick start below |
-| Map several host routes to remote pages | `createHostPages` (Vue) / `createReactHostPages` (React) | [Page demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/pages-cli) |
-| Embed Vue in React, or React in Vue | `defineBridgeApp` + a host bridge component | [Bridge examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/bridge) |
-| Restore a sub-app detail route after refresh | Enable bridge URL sync | [Router demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/bridge-router) |
+| Map several host routes to remote pages | `createHostPages` (Vue) / `createReactHostPages` (React) | [Page demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/demos/pages-cli) |
+| Embed Vue in React, or React in Vue | `defineBridgeApp` + a host bridge component | [Bridge examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates) |
+| Restore a sub-app detail route after refresh | Enable bridge URL sync | [Router demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/showcase) |
 | Provide user data or run remote initialization | `AppContext`, optional `setup`/`onSession` | Initialization below |
-| Run React 18 and 19 on the same page | Separate dependency groups and consumers using `shareScope` | [Version isolation demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/react-versions) |
+| Run React 18 and 19 on the same page | Separate dependency groups and consumers using `shareScope` | [Version isolation demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/demos/react-versions) |
 
 Combine these features as needed. **A simple remote component does not require a bridge, page table or login lifecycle.**
 
@@ -54,6 +56,19 @@ pnpm add -D @fulgurjs/federation
 - Set the build target to `es2022` or newer. Chrome 108+ is the browser baseline; other browsers need corresponding ESM, dynamic import and top-level await support.
 - A pure Vue application needs Vue; a pure React application needs React and react-dom. A cross-framework bridge host installs both frameworks as explained below.
 
+## Starting fresh: create a complete project
+
+Without an existing project, scaffold from a complete template with the CLI (Node ≥ 20 and pnpm ≥ 9 required):
+
+```bash
+npx @fulgurjs/federation create            # interactive; or explicit:
+npx @fulgurjs/federation create vue-vue --dir my-federation
+```
+
+Five templates cover Vue×Vue, React×React, a Vue host embedding a React child app, a React host embedding a Vue child app, and the bidirectional bridge + URL sync showcase. `create` copies a runnable workspace (lockfile and startup script included) and runs a frozen install by default, then prints the commands to enter, start and build. For an **existing** project skip this and use the quick start below plus `fulgurjs init`.
+
+Template sources live in [examples/templates/](examples/templates/README.md); no manual wiring is needed unless you change names/ports (fixed checklist in the template guide).
+
 ## Quick start: two Vue applications
 
 These steps add federation to **existing Vite + Vue projects**, which retain their own HTML and application entry files.
@@ -186,7 +201,7 @@ npm run dev -- --port 5173 --strictPort
 
 Open `http://localhost:5173`. The remote button should count clicks, and the calculation should display `3`. pnpm projects can use `pnpm dev` instead.
 
-Complete projects and deployment configuration: [Vue examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/vue).
+Complete projects and deployment configuration: [Vue examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/vue-vue).
 
 ## React setup
 
@@ -229,7 +244,7 @@ export default function App() {
 }
 ```
 
-React also imports `loadRemote` and `useLoadRemote` from `/react` for ordinary modules. Complete projects: [React examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/react).
+React also imports `loadRemote` and `useLoadRemote` from `/react` for ordinary modules. Complete projects: [React examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/react-react).
 
 ## Embed Vue and React in each other
 
@@ -265,13 +280,30 @@ A cross-framework host installs and shares `vue`, `react` and `react-dom`. The c
 
 In the other direction, use `createReactBridgeApp` in the React host. The Vue child uses `defineBridgeApp` from `/runtime` and returns a `createApp(...)` application.
 
-Remember:
+### The shortest bridge mental model
 
-- `appProps` is a snapshot taken at mount. Replacing top-level fields later does not update the child. Pass stable callbacks/shared stores for live data, or change the component `key` to remount.
-- Separate component trees do not inherit Context, provide/inject or routers. Pass or install what is needed explicitly.
-- Use `remoteComponent` for a same-framework component; use a bridge for a sub-app.
+| Question | Answer |
+|---|---|
+| Which frameworks does each side install? | The bridge host installs and shares `vue` + `react` + `react-dom` (all three `singleton: true`); the child installs and shares only its own framework. This contract is mandatory — a missing key produces double instances (Invalid hook call / broken state) |
+| What do `shared` / `singleton` do here? | They make host and child use the **same** framework instance; `singleton` converges instances but does not make incompatible majors compatible |
+| How does the child export its entry? | The `./bridge` expose file **default-exports** the value returned by `defineBridgeApp(...)`; missing `mount`/`unmount` fails with MFU-015 |
+| How does the host mount it? | `createVueBridgeApp('remote/bridge')` / `createReactBridgeApp(...)` return a component: render to mount, remove to unmount; pass `appProps` and optional `sessionKey` |
+| When is URL sync needed? | Only when refresh/share/back-forward must restore the child's internal page (`routing` + `basePath`, configured on both ends). Without it, child navigation not touching the host URL is normal behavior |
+| How do sessions and unmount work? | Login generations use `sessionKey` (new generation re-runs `onSession`; logout → `null` unmounts and empties). Unmount is driven by the host component lifecycle; a child cleanup throw blocks that container until a full page reload |
+
+### `appProps` is a mount-time snapshot, not reactive props
 
-Complete bidirectional setup and login/cleanup flows: [bridge examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/bridge).
+Top-level fields are shallow-copied at mount; later host-side replacements do **not** update the child. Three channels for live data:
+
+| Situation | Use | Cost |
+|---|---|---|
+| Child needs current host values (token, user name…) | Pass a **stable callback** (`getToken: () => store.token`) — calls read the latest value | No remount; good for "reads" |
+| Both sides share one state | Pass the host store instance via `appProps` or AppContext; both subscribe to the same instance | Reactivity does not cross roots; the child subscribes explicitly |
+| Must re-initialize with new props | Change the bridge component's `key` to remount explicitly (full unload → reload chain) | All state resets; do not trigger frequently |
+
+This differs from ordinary component props on purpose — it is a structural property of cross-root mounting, not a bug. Separate component trees do not inherit Context, provide/inject or routers. Pass or install what is needed explicitly. Use `remoteComponent` for a same-framework component; use a bridge for a sub-app.
+
+Complete bidirectional setup and login/cleanup flows: [bridge examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates).
 
 ## Keep child routes in the browser URL
 
@@ -290,7 +322,7 @@ Configure both sides:
 
 Vue uses `createVueBridgeNavigation` / `connectVueBridgeRouter`; React uses `createReactBridgeNavigation` / `createReactBridgeRouter`. React hosts need a data router (`createBrowserRouter` or `createHashRouter`), not `BrowserRouter`. Built-in adapters support Vue Router 4 and React Router ≥6.11.
 
-Refresh, shared links and browser history restore the route, **not form contents or business data**. See [routing API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#url-sync) and the runnable [router demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/bridge-router).
+Refresh, shared links and browser history restore the route, **not form contents or business data**. See [routing API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#url-sync) and the runnable [router demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/showcase).
 
 ## User data and remote initialization
 
@@ -318,7 +350,7 @@ Maintain a page table and pass it to `createHostPages` (Vue) or `createReactHost
 
 The table records the host `route` and the remote expose `spec` (omit `./` and do not repeat the remote name); `remotePrefixes` selects the remote. For example, `/shop/home`, `spec: 'pages/Home'` and `remotePrefixes: { '/shop': 'shop' }` resolve to `shop/pages/Home`. Vue can use KeepAlive for component state; React has no equivalent keep-alive promise here.
 
-See [page API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#pages) and [page demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/pages-cli).
+See [page API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#pages) and [page demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/demos/pages-cli).
 
 ## Build and deploy
 
@@ -332,7 +364,7 @@ Check these settings:
 - Cross-origin deployments need production CORS headers; dev settings do not configure the production server.
 - Keep chunks still referenced by old pages available during releases, or use a deployment flow that avoids mixed versions.
 
-Deployment examples: [Vue](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/vue/README.md) / [React](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/react/README.md).
+Deployment examples: [Vue](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/templates/vue-vue/README.md) / [React](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/templates/react-react/README.md).
 
 ## Handle failures
 
@@ -366,7 +398,11 @@ See the [capability comparison](https://github.com/chenmingye/fulgurjs-federatio
 Run in the application directory:
 
 ```bash
-npx fulgurjs init
+# No existing project: create a complete project from a template (see "Starting fresh")
+npx @fulgurjs/federation create
+
+# Existing project: generate a federation config starter file
+npx fulgurjs init                        # --template <path> sets the output path (a path, not a template id)
 npx fulgurjs explain
 
 # Optional: validate a configured host page table
@@ -376,9 +412,9 @@ npx fulgurjs check-pages --site http://localhost:5173
 npx fulgurjs doctor --base https://your-site.example --apps remote-vue
 ```
 
-For `doctor`, `--base` is the site URL and `--apps` lists deployment subdirectories: the example checks `/remote-vue/`. It does not infer a different development port from a container name.
+For `doctor`, `--base` is the site URL and `--apps` lists **deployment subdirectories** (a remote deployed under `/remote-vue/` is `remote-vue`): the example checks `https://your-site.example/remote-vue/`. It does not infer a different development port from a container name.
 
-`init` creates a federation config template, not a full application, router or Nginx configuration. `check-pages` compares the page table with remote exposes; an unreachable remote is reported as unverified.
+`init` creates a federation config template, not a full application, router or Nginx configuration (use `create` for a new complete project). `check-pages` compares the page table with remote exposes; an unreachable remote is reported as unverified.
 
 Remote dev types are generated by default. Accessible source provides more precise mapping; inaccessible source produces `any` declarations without precise checks/completion. Set `dts: false` to disable generation. See the reference for details.
 
@@ -400,8 +436,8 @@ Specify the framework, whether you need a component or sub-app, remote URLs/expo
 
 ## Documentation
 
-- [Demo catalog](https://github.com/chenmingye/fulgurjs-federation/blob/master/demo/README.md): setup and runnable scenarios.
-- [Copy-and-run templates](https://github.com/chenmingye/fulgurjs-federation/tree/master/templates): five pnpm-workspace templates (Vue×Vue, React×React, both cross-framework bridge directions, and a full showcase). Copy a folder, then `pnpm install && pnpm dev`.
+- [Demo catalog](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/demos/README.md): setup and runnable scenarios.
+- [Copy-and-run templates](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates): five pnpm-workspace examples/templates (Vue×Vue, React×React, both cross-framework bridge directions, and a full showcase). Copy a folder, then `pnpm install && pnpm dev`.
 - [Migration guide](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/迁移指南.md).
 - [CHANGELOG](https://github.com/chenmingye/fulgurjs-federation/blob/master/CHANGELOG.md): changes and migration requirements.
 - [Acceptance records](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/整夜全量验收报告-20261004.md): overnight acceptance on two real MES business projects (fresh SVN copies), covering dev, production, fault recovery and HMR, plus production-build notes for large Vite 6 apps (that round required disabling `manualChunks`; **fixed in 5.8.0 — keep your own `manualChunks`, shared bodies are isolated into `fulgurjs-provider-*` chunks automatically**). Historical record: [20261002 demo acceptance](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/完整Demo展示与全面复测-验收报告-20261002.md) — historical results are not a substitute for testing your application.
@@ -420,4 +456,4 @@ See [CONTRIBUTING](https://github.com/chenmingye/fulgurjs-federation/blob/master
 
 ## License
 
-[MIT](./LICENSE) © chenmingye (Jason)
+[MIT](LICENSE) © chenmingye (Jason)

package/README.md

@@ -1,25 +1,27 @@
 # @fulgurjs/federation
 
-[简体中文](./README.md) | [English](./README.en.md)
+**[所有模板与 Demo 统一入口](examples/README.md)**：示例选择与运行指南。
+
+[简体中文](README.md) | [English](README.en.md)
 
 **让一个 Vite 应用使用另一个应用提供的组件、页面或函数。**
 
 例如：主系统加载独立部署的审批页面，Vue 页面中嵌入一个 React 子应用，或者多个应用共用同一套工具函数。提供方和使用方可以放在不同仓库，各自构建和部署。
 
-本文是使用指南，示例按 **5.7.1** 编写。完整参数、默认值和执行规则在 [API 手册](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.md)。
+本文是使用指南，示例与模板按 **5.8.0** 编写（各工程 `package.json` 声明的精确版本即实际安装版本）。完整参数、默认值和执行规则在 [API 手册](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.md)。
 
 ## 先看你要做什么
 
 | 你的需求 | 使用方法 | 示例 |
 |---|---|---|
-| Vue 加载另一个应用的 Vue 组件 | `remoteComponent` | [Vue 示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/vue) |
-| React 加载另一个应用的 React 组件 | `/react` 的 `remoteComponent` | [React 示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/react) |
+| Vue 加载另一个应用的 Vue 组件 | `remoteComponent` | [Vue 示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/vue-vue) |
+| React 加载另一个应用的 React 组件 | `/react` 的 `remoteComponent` | [React 示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/react-react) |
 | 加载远程 JS/TS 函数 | `loadRemote`；React 也可用 `useLoadRemote` | 见下方快速开始 |
-| 一批宿主路由对应远程页面 | Vue 用 `createHostPages`；React 用 `createReactHostPages` | [页面接入示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/pages-cli) |
-| Vue 嵌 React，或 React 嵌 Vue | 子应用桥接：`defineBridgeApp` + 宿主桥接组件 | [双向嵌套示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/bridge) |
-| 刷新后仍打开子应用的详情页 | 在桥接上开启 URL 同步 | [路由同步示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/bridge-router) |
+| 一批宿主路由对应远程页面 | Vue 用 `createHostPages`；React 用 `createReactHostPages` | [页面接入示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/demos/pages-cli) |
+| Vue 嵌 React，或 React 嵌 Vue | 子应用桥接：`defineBridgeApp` + 宿主桥接组件 | [双向嵌套示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates) |
+| 刷新后仍打开子应用的详情页 | 在桥接上开启 URL 同步 | [路由同步示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/showcase) |
 | 远程页面需要用户、token 或初始化 | `AppContext` + 可选 `setup`/`onSession` | 见下方业务初始化 |
-| 同页使用 React 18 和 React 19 | 将两组依赖和使用方放入不同 `shareScope` | [版本隔离示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/react-versions) |
+| 同页使用 React 18 和 React 19 | 将两组依赖和使用方放入不同 `shareScope` | [版本隔离示例](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/demos/react-versions) |
 
 这些功能按需组合。**加载一个普通组件，不需要先配置桥接、页面表或登录初始化。**
 
@@ -54,6 +56,19 @@ pnpm add -D @fulgurjs/federation
 - 构建目标使用 `es2022` 或更新；浏览器基线为 Chrome 108+，其他浏览器需要相应的 ESM、动态导入和顶层 await 支持。
 - 普通 Vue 项目安装 Vue 即可；普通 React 项目安装 React 和 react-dom 即可。双向跨框架桥接的宿主按下面说明安装两个框架。
 
+## 从零开始：创建一个完整工程
+
+没有可接入的存量项目时，用 CLI 从完整模板创建（需要 Node ≥ 20 和 pnpm ≥ 9）：
+
+```bash
+npx @fulgurjs/federation create          # 交互选择场景；也可显式指定：
+npx @fulgurjs/federation create vue-vue --dir my-federation
+```
+
+五个模板覆盖：Vue×Vue、React×React、Vue 宿主嵌 React 子应用、React 宿主嵌 Vue 子应用、双向桥接+URL 同步 showcase。`create` 复制完整可运行的 workspace（含锁文件与启动脚本）并默认执行冻结安装，完成后打印进入目录、启动和构建命令。要接入**已有**项目时跳过这步，用下面的快速开始 + `fulgurjs init`。
+
+模板源码在仓库 [examples/templates/](examples/templates/README.md)；不改名称/端口时无需任何手工配置。改端口的固定修改点见模板指南。
+
 ## 快速开始：两个 Vue 应用
 
 下面是在**已有 Vite + Vue 项目**中增加联邦功能。每个项目仍保留自己的 `index.html`、入口文件和原有插件。
@@ -196,7 +211,7 @@ npm run dev -- --port 5173 --strictPort
 
 打开 `http://localhost:5173`，应看到能增加计数的远程按钮；点击计算按钮应显示 `3`。使用 pnpm 的项目也可用 `pnpm dev` 启动。
 
-完整工程与生产部署配置见 [Vue examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/vue)。
+完整工程与生产部署配置见 [Vue examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/vue-vue)。
 
 ## React 怎么接入
 
@@ -241,7 +256,7 @@ export default function App() {
 }
 ```
 
-React 加载普通 TS 模块时可以使用 `loadRemote` 或 `useLoadRemote`，都从 `/react` 导入。完整工程见 [React examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/react)。
+React 加载普通 TS 模块时可以使用 `loadRemote` 或 `useLoadRemote`，都从 `/react` 导入。完整工程见 [React examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/react-react)。
 
 ## Vue 和 React 怎么互相嵌套
 
@@ -282,13 +297,30 @@ const RemoteApp = createVueBridgeApp<{ message: string }>('remote-react/bridge')
 
 反方向用 React 宿主的 `createReactBridgeApp`，Vue 子应用用 `/runtime` 的 `defineBridgeApp` 返回 `createApp(...)` 创建的应用。
 
-需要记住三点：
+### 跨框架桥接的最短理解
 
-- `appProps` 在挂载时取得快照。之后替换顶层字段不会自动更新子应用；实时数据可传稳定回调或共享 store，需要重新挂载时使用组件 `key`。
-- 两个组件树不会自动共用 Context、provide/inject 或路由，需要显式传递或在子应用安装。
-- 普通组件加载用 `remoteComponent`；整个子应用嵌套用桥接工厂。Vue 不能直接用 Vue 的 `remoteComponent` 渲染 React 组件。
+| 问题 | 答案 |
+|---|---|
+| 宿主和子应用各装什么框架？ | 桥接宿主装并共享 `vue` + `react` + `react-dom`（三键全 `singleton: true`）；子应用只装并共享自己的框架。这是硬性合同，缺一键就会出现双实例（Invalid hook call / 状态不互通） |
+| `shared` 与 `singleton` 在这里的作用？ | 让宿主与子应用拿到**同一个**框架实例；`singleton` 只是收敛实例，不把不兼容的大版本变成兼容 |
+| 子应用入口怎么导出？ | `exposes: { './bridge': … }` 指向的文件**默认导出** `defineBridgeApp(...)` 的返回值；缺 `mount/unmount` 会报 MFU-015 |
+| 宿主怎么挂载？ | `createVueBridgeApp('远程名/bridge')` / `createReactBridgeApp(...)` 返回一个组件，渲染它即挂载、移除即卸载；传 `appProps` 与可选 `sessionKey` |
+| URL 同步什么时候需要？ | 只有「刷新/分享/前进后退要恢复子应用内部页面」时才开（`routing` + `basePath`，两端都要配置）；不开发同步时子应用内部跳转不影响宿主地址，这是正常行为 |
+| 会话切换与卸载怎么处理？ | 登录代次用 `sessionKey`（换号→新代次重跑 `onSession`；登出→`null` 即卸载清空）；卸载由宿主组件生命周期驱动，子应用清理逻辑抛错会封锁该容器（只能整页刷新） |
+
+### `appProps` 是挂载快照，不是响应式 props
 
-双向配置、登录切换和卸载示例见 [bridge examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/bridge)。
+挂载时顶层字段做浅拷贝传入；之后宿主替换字段**不会**自动更新子应用。三种实时数据通道按需选择：
+
+| 场景 | 用什么 | 代价 |
+|---|---|---|
+| 子应用需要宿主的实时值（token、用户名等） | 传**稳定回调**（如 `getToken: () => store.token`），子应用调用时取到最新值 | 无重挂；适合“读” |
+| 两边共享一块状态 | 把宿主 store 实例经 `appProps` 或 AppContext 传过去，双方订阅同一实例 | 框架响应式不跨 root，子应用需自行订阅 |
+| 必须以新 props 重新初始化 | 宿主给桥接组件换 `key` 显式重挂（卸载→重新走完整加载链） | 全部状态重置；不要频繁触发 |
+
+这与普通 Vue/React 组件的 props 语义不同，是跨 root 挂载的结构限制，不是 bug。两个组件树也不会自动共用 Context、provide/inject 或路由，需要显式传递或在子应用安装。普通组件加载用 `remoteComponent`；整个子应用嵌套用桥接工厂。Vue 不能直接用 Vue 的 `remoteComponent` 渲染 React 组件。
+
+双向配置、登录切换和卸载示例见 [bridge examples](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates)。
 
 ## 子应用路由和浏览器地址怎么同步
 
@@ -309,7 +341,7 @@ const RemoteApp = createVueBridgeApp<{ message: string }>('remote-react/bridge')
 
 Vue 使用 `createVueBridgeNavigation` / `connectVueBridgeRouter`；React 使用 `createReactBridgeNavigation` / `createReactBridgeRouter`。React 宿主需要 data router（`createBrowserRouter` 或 `createHashRouter`），不能直接换成 `BrowserRouter`。内置适配支持 Vue Router 4、React Router ≥6.11。
 
-这样刷新、分享链接、前进后退能恢复路由位置；**不会自动保存表单内容或业务数据**。详细步骤见 [URL 同步 API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.md#url-sync)，可运行工程见 [bridge-router Demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/bridge-router)。
+这样刷新、分享链接、前进后退能恢复路由位置；**不会自动保存表单内容或业务数据**。详细步骤见 [URL 同步 API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.md#url-sync)，可运行工程见 [bridge-router Demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates/showcase)。
 
 ## 远程业务页需要用户信息或初始化时
 
@@ -337,7 +369,7 @@ Vue 使用 `createVueBridgeNavigation` / `connectVueBridgeRouter`；React 使用
 
 页面表里 `route` 是宿主路径，`spec` 是远程的 exposes 键（通常省略 `./`，不要重复加远程名）；`remotePrefixes` 指定这批路径属于哪个远程。例如 `/shop/home` + `spec: 'pages/Home'` + `remotePrefixes: { '/shop': 'shop' }`，最终加载的是 `shop/pages/Home`。Vue 可结合 KeepAlive 保存组件状态；React 不提供相同的保活承诺。
 
-完整配置见 [页面 API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.md#pages) 和 [pages-cli Demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/demo/pages-cli)。
+完整配置见 [页面 API](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.md#pages) 和 [pages-cli Demo](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/demos/pages-cli)。
 
 ## 构建与部署
 
@@ -357,7 +389,7 @@ npm run build
 - **跨域允许访问**：不同域名时，远程服务器要正确提供 CORS 响应头；开发配置不会自动替你修改生产服务器。
 - **避免旧文件突然失效**：发布期间保留仍被旧页面引用的 chunk，或使用能避免版本混搭的部署流程。
 
-生产部署样例见 [Vue 部署说明](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/vue/README.md) 与 [React 部署说明](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/react/README.md)。
+生产部署样例见 [Vue 部署说明](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/templates/vue-vue/README.md) 与 [React 部署说明](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/templates/react-react/README.md)。
 
 ## 加载失败时怎么办
 
@@ -391,7 +423,11 @@ npm run build
 在应用根目录运行：
 
 ```bash
-npx fulgurjs init                        # 创建联邦配置起步文件
+# 没有存量项目：从模板创建完整工程（见「从零开始」一节）
+npx @fulgurjs/federation create
+
+# 已有项目：生成联邦配置起步文件
+npx fulgurjs init                        # --template <路径> 指定输出路径（是路径，不是模板编号）
 npx fulgurjs explain                     # 查看当前应用的联邦配置
 
 # 使用页面表时，核对宿主页面声明：
@@ -401,9 +437,9 @@ npx fulgurjs check-pages --site http://localhost:5173
 npx fulgurjs doctor --base https://your-site.example --apps remote-vue
 ```
 
-`doctor` 的 `--base` 是站点地址，`--apps` 是要检查的部署子目录；上例检查 `/remote-vue/`。它不会从容器名自动猜测另一个开发端口。
+`doctor` 的 `--base` 是站点地址，`--apps` 是要检查的**部署子目录**（远程部署在 `/remote-vue/` 就写 `remote-vue`）；上例检查 `https://your-site.example/remote-vue/`。它不会从容器名自动猜测另一个开发端口。
 
-`init` 只生成联邦配置模板，不替你创建完整应用、路由或 Nginx 配置。`check-pages` 核对页面表与远程模块声明；远程不可达会报告无法验证，不代表通过。
+`init` 只生成联邦配置模板，不替你创建完整应用、路由或 Nginx 配置（新建完整工程用 `create`）。`check-pages` 核对页面表与远程模块声明；远程不可达会报告无法验证，不代表通过。
 
 开发类型默认开启：插件为远程模块生成类型声明。能访问远程源码时可获得更精确的提示；不能访问时生成 `any` 声明，表示可以导入但没有准确类型。需要关闭时设 `dts: false`。详细规则见 API 手册。
 
@@ -430,8 +466,8 @@ npx fulgurjs doctor --base https://your-site.example --apps remote-vue
 
 ## 文档
 
-- [完整 Demo 与运行步骤](https://github.com/chenmingye/fulgurjs-federation/blob/master/demo/README.md)：基础加载、双向嵌套、URL 同步、版本隔离和 Jeecg 场景。
-- [可复制运行模板](https://github.com/chenmingye/fulgurjs-federation/tree/master/templates)：Vue×Vue、React×React、双向跨框架桥接与完整 showcase，五个 pnpm workspace 模板，复制后 `pnpm install && pnpm dev` 即可运行。
+- [完整 Demo 与运行步骤](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/demos/README.md)：基础加载、双向嵌套、URL 同步、版本隔离和 Jeecg 场景。
+- [可复制运行模板](https://github.com/chenmingye/fulgurjs-federation/tree/master/examples/templates)：Vue×Vue、React×React、双向跨框架桥接与完整 showcase，五个 pnpm workspace 模板，复制后 `pnpm install && pnpm dev` 即可运行。
 - [迁移指南](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/迁移指南.md)：从已有微前端方案接入。
 - [CHANGELOG](https://github.com/chenmingye/fulgurjs-federation/blob/master/CHANGELOG.md)：版本变化与迁移说明。
 - [验收报告](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/整夜全量验收报告-20261004.md)：真实 MES 业务项目（两个 SVN 项目全新副本）接入验收：dev/生产/故障恢复/HMR（历史记录：该轮曾要求大型应用停用 manualChunks，**5.8.0 起已修复，可保留业务 manualChunks**——共享本体自动隔离进 `fulgurjs-provider-*` 组，不受用户分组影响）。
@@ -451,4 +487,4 @@ pnpm test:unit
 
 ## License
 
-[MIT](./LICENSE) © chenmingye (Jason)
+[MIT](LICENSE) © chenmingye (Jason)