@fulgurjs/federation 5.9.3 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 6.1.0
+
+**组件联邦的全局注册组件安装（setup `globalComponents` 契约）。** 修复一类真实缺陷：远程组件模板内的字符串标签（如 `<a-divider>`）按**消费方 app** 的全局注册表解析——提供方 app 里的 `app.use(X)` 全局注册不随组件走，消费方没注册就渲染成无样式的字面自定义元素（真实业务实测：流程内嵌表单的分节线/选人控件/上传按钮全部退化为死元素）。此前 setup 的注册目标 `hostApp` 在「宿主 → 桥接子应用 → 子应用内再消费远程表单」的嵌套场景拿不到真正渲染表单的子应用 app，本版本补齐该链路。
+
+### 新增
+
+- **`RemoteSetupModule.globalComponents`**（setup 模块可选具名导出，`Record<注册名, 组件>`）：提供方声明其暴露面依赖的全局注册组件。运行时在**每次 `loadRemote`** 时把它们幂等注册到当次消费方 app（`app.component` 同名覆盖天然幂等）——按次而非按 setup 一次执行，桥接子应用每次挂载新建 app 实例也能拿到注册。非法导出类型（数组/非对象）按 MFU-011 三段式报错并支持重试。无声明、无消费方 app（手动 `loadRemote`）、或消费方 app 无 `component` 方法时零行为、零副作用。
+- **`LoadRemoteOptions.consumerApp`**（可选）：发起本次加载的消费方应用实例。由框架适配器自动传入（Vue 的 `remoteComponent` 在异步包装组件 setup 内同步捕获当前渲染 app），业务代码不需要手填；运行时只在当次调用内消费，不保存、不感知具体框架类型。React 无全局组件注册表，不参与该机制。
+- **`globalComponents` 值支持零参 loader（`() => import('…')`，推荐形态）**：setup 模块自身保持零组件依赖，组件只在本框架消费方真实渲染时才加载——Vue 适配器注册时自动包 `defineAsyncComponent`。静态组件值仍支持（同框架消费一步到位）。实测教训（fixtures R12 回归拦截）：setup 若静态 import 框架组件，会把框架依赖图拖进**任意**加载该远程模块的页面（含跨框架纯 TS 消费方），dev 下模块内根相对 URL 在跨源页面解析断链。
+- 单测：`tests/global-components.test.ts`（注册/换 app 重注册/幂等/跳过/MFU-011/失败清缓存/无声明零行为）+ `tests/vue.test.ts` V-9/V-10（jsdom 全链路：远程模板字符串标签经 globalComponents 解析为真实 DOM；loader 形态惰性加载真实执行）。
+
+### 修复
+
+- **修复（文档）：`createReactBridgeRouter` 返回值合同文档缺失 `routerReady` 与 `dispose`**——6.0.0 新增的 `routerReady` 就绪合同（fast 路径同步已 resolve；slow 路径惰性接线完成时 resolve、缺依赖 reject）只存在于源码与类型，公开 API 文档未覆盖。现已在 docs/zh 与 docs/en 的 API 参考/URL 同步指南补齐完整语义（返回类型、等待时机、成功/失败、与 element 的关系、调用顺序、卸载行为）。
+
+## 6.0.0
+
+**破坏性版本：公共入口统一为四类。** 应用开发者先选框架，再从同一个入口导入全部能力；内部 bridge/router/context 分层不再是用户必学的路径规则。
+
+### 破坏性变化（迁移指南：docs/zh/migration.md / docs/en/migration.md）
+
+- **公共入口收敛**：`/bridge`、`/bridge/vue`、`/bridge/react`、`/bridge/router/vue`、`/bridge/router/react` 公共入口移除。新合同：
+  - Vite 配置与插件类型 → `@fulgurjs/federation`（包根，不变）；
+  - Vue 应用代码 → `@fulgurjs/federation/vue`（运行时全量 + remoteComponent/createHostPages + defineBridgeApp/createVueBridgeApp + createVueBridgeNavigation/connectVueBridgeRouter）；
+  - React 应用代码 → `@fulgurjs/federation/react`（运行时全量 + React 适配 + defineBridgeApp/createReactBridgeApp + createReactBridgeNavigation/createReactBridgeRouter）；
+  - 框架无关浏览器模块 → `@fulgurjs/federation/runtime`（**不再导出** Vue 的 remoteComponent/createHostPages/defineBridgeApp——迁移到 /vue）。
+  - 桥接宿主与路由同步实现转为 `/internal/*`（bridge-host-{vue,react}.js、bridge-router-{core,vue,react}.js 新增 internal 导出；internal 不供应用代码导入，dev 门面引用所需）。
+- **`/runtime` 回归真正框架无关**：静态导入图零 vue/react/框架 router（runtime-entry-graph 测试守护）；此前 /runtime 实际携带 Vue 适配层。
+- **init `--template` 更名 `--out`**（与 create 的模板概念同名不同义；本轮仍接受 --template 并提示更名，后续版本移除）。
+
+### 可选依赖边界（统一入口不制造新负担）
+
+- **未安装 vue-router 的纯 Vue 组件工程**导入 /vue：dev、build、skipLibCheck:false 类型检查全部通过。bridge-router-vue 对 vue-router 仅类型导入（宿主导航端口参数为结构化 VueRouterLike，真实 Router 结构兼容可赋值）；cancelled 导航失败判定以内联常量等价（vue-router 4.x/5.x 公开枚举一致，回归以真实 vue-router 覆盖）。
+- **未安装 react-router-dom 的纯 React 组件工程**导入 /react：dev（Vite optional-peer-dep 干净拒绝）、build（Vite 8/rolldown throw-stub chunk）、类型检查全部通过。bridge-router-react 对 react-router-dom 仅类型导入 + 模块级按需预热（形状校验兜底空 chunk）；就绪时行为与历史逐行一致（含 element.props.router 同步内省），未就绪走惰性宿主（首次渲染等待，缺依赖在首次渲染时以清晰合同内错误暴露）。gzip 预算 4096→4352B（合同增量，实测 4143B）。
+- peerDependenciesMeta 五项（vue/react/react-dom/vue-router/react-router-dom）全部 optional（延续），不自动安装。
+
+### 修复
+
+- **修复（插件）：dev 桥接门面误绑 `{ createVueBridgeApp }`**——internal/bridge-host-vue.js 实际只导出 `createVueBridgeAppWithLoader`（绑定发生在 dist 生成壳）。5.9.x 的旧 /bridge 桥接门面存在同一误写，因 expose 目标从不导入宿主工厂而从未触发；6.0.0 /vue 门面承载完整入口面后被 dev 预构建放大为 MFU-001（ MESZC 实测）。修复为取 WithLoader 名并就地绑定 loadRemote；新增 tests/api-facade-bindings.test.ts 以 dist 真实导出面逐名核对门面导入（防回归）。
+- **doctor 不再猜默认应用**：`--apps` 必填（缺省 main 的静默行为移除）；支持 `.`（站点根）、完整 URL 条目（多 origin）；新增 `--entry <文件名>`（自定义入口）、`--no-entry`（纯宿主）、`--no-manifest`（合法关闭）、`--no-html`；`--json` 输出实际检查目标 mode。
+- **create 环境校验前置**：按模板真实 `engines.node`（>=20.19.0）与 pnpm 存在性在**写入前**校验，不满足即失败并给升级方法（此前在复制/安装后才警告）；输出 `cd` 路径加引号（空格/中文路径）；宿主入口按 dev.config.json 的 host 标记列出**全部**宿主（showcase 双宿主不再只显示一个）。
+
+### 新增
+
+- **CLI `fulgurjs port <应用> <新端口> [--write]`**：模板工程端口一处变更，默认预览（计划列出四个受影响文件与命中数），`--write` 才写入；词边界替换不误伤其他端口；README 端口表一并更新。
+- **init 按场景生成最小有效配置**：框架从 package.json 依赖判断（判断不了要求显式 `--framework vue|react`，TTY 询问）；`--role consumer|provider|dual` 区分纯消费/纯提供/双角色；shared 只列项目实际安装并跨应用共享的库，不再默认塞 vue-router/pinia/示例业务页。
+- **接入核对清单按角色生成**（UX-03）：expose 分类说明（普通组件/函数可直接 expose）、消费方式按需选择（普通组件不需要页面表/桥接）、独立 Router/store 的隔离设计明确为合法；explain/check-pages/doctor/create/help 输出同一合同。
+
+### 文档
+
+- **统一文档中心**（docs/README.md）：docs/zh/（guide×8 + reference×4 + troubleshooting×2 + migration）、docs/en/（逐文件镜像）、docs/maintainers/（architecture/testing/releasing + 通用技术文档）。API/配置/CLI/错误码（48 码）逐项对齐 6.0.0 实现；私有业务资料、任务书与验收记录全部移出公开文档（Git 历史/历史发布不改动，风险自察）。
+- 错误码防漂移门禁改读 docs/zh/reference/errors.md（节标题不变，48 码三方一致校验保持）。
+- npm 包携带文档更新为 zh/en reference（api/errors/migration）+ maintainers 技术文档；根 README 收敛为产品介绍 + 快速开始 + 文档中心导航。
+
+### 模板
+
+- 五模板全部改为统一入口用法（/vue、/react）；插件依赖钉 **6.0.0**（同批发布）；根 package.json 声明 `engines.node >=20.19.0`；dev.config.json 应用条目新增 host 标记（create 宿主入口展示的数据源）；vue-vue 模板远程 Router 记录从页面表派生（route+spec 唯一来源）。
+- showcase vue-host 的 routing.ts 使用公开导出的 `BridgeHostRouting` 类型（移除历史替代类型）。
+- 锁文件在 6.0.0 上 registry 后单阶段重生成（发布流程既定步骤）。
+
+### 质量
+
+- 插件单测 683/683（新增 api-facade-bindings、port、入口导出面/导入图守护更新）；test:examples 15/15；干净消费者验证（无 vue-router 的 Vue 工程、无 react-router-dom 的 React 工程 × Vite 6/8 dev+build+tsc）通过。
+- 版本 5.9.3 → 6.0.0。
+
+
 ## 5.9.3
 
 - **修复：hostPages keepAlive 页在 Vue 3.5 下永不缓存**——Vue 3.5 的 KeepAlive 对「已解析的异步组件」按 `__asyncResolved.name`（内层组件自身的 name）做 include 匹配，而 createHostPages 的保活白名单给的是包装名（`Fulgurjs_<remote>_<spec>`）：解析后两名不一致 → 白名单永不命中 → keepAlive 页每次进出都重挂（数据看板计数/表单输入丢失；pages-cli 实测 100% 复现）。修复：keepAlive 页的 loader 对解析结果做**浅克隆独立命名副本**（name 与包装一致，不改写共享模块导出对象——多页共享同一导出时改写会串名；非选项组件保持原样退化为旧行为）。回归：解析后内层与包装同名、共享模块导出保持原样、非 keepAlive 页不受影响（host-pages.test.ts 13/13，全量 675/675）。

package/README.en.md

@@ -1,459 +1,100 @@
 # @fulgurjs/federation
 
-**[All templates and demos](examples/README.en.md)**: Example catalog and run guide.
+**Let one Vite app use components, pages, functions — or entire sub apps — provided by another.**
 
-[简体中文](README.md) | [English](README.en.md)
+For example: a main system loads an independently deployed approval page, a Vue page embeds a React sub app, or several apps share one copy of a dependency. Providers and consumers can live in separate repos and build/deploy independently. Supports Vue 3 and React 18/19 on Vite 5.1–8.
 
-**Use components, pages and functions from another Vite application.**
+[简体中文](README.md) ｜ **[Documentation center](docs/README.md)** (Chinese [docs/zh](docs/zh/README.md) · English [docs/en](docs/en/README.md))
 
-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.
+## Quick start
 
-This is the usage guide. Examples and templates are written against **5.9.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/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/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/examples/demos/react-versions) |
-
-Combine these features as needed. **A simple remote component does not require a bridge, page table or login lifecycle.**
-
-## Terms in plain language
-
-| Term | Meaning |
-|---|---|
-| Host | The application displaying remote content |
-| Remote | The application providing a module |
-| `exposes` | Files the remote allows other applications to load |
-| `remotes` | The remote names and addresses the host uses |
-| `shared` | Dependencies that participate in sharing, such as Vue or React |
-| `singleton` | Adopt one dependency instance within a share scope; this does not make incompatible major versions compatible |
-| `shareScope` | A group of shared dependencies; separate groups can use separate versions |
-| Bridge | A DOM container in which a sub-app manages its own rendering and cleanup |
-| URL sync | Record the sub-app route in the host URL so refresh, sharing and history navigation can restore it |
-
-An application can both expose and consume modules.
-
-## Install
-
-Install in every participating Vite project:
+**New project** (recommended): scaffold a fully runnable federation workspace from a template:
 
 ```bash
-pnpm add -D @fulgurjs/federation
-# npm projects: npm install -D @fulgurjs/federation
-```
-
-- Supports browser applications using Vue 3, React 18/19, and plain JS/TS modules.
-- Supports Vite 5.1+ within the Vite 5/6/7/8 series. Your framework plugins must also support your chosen Vite version.
-- The plugin requires Node.js ≥18, but **Vite 7/8 require Node.js 20.19+ or 22.12+**. Meet both requirements.
-- 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
+cd my-federation
+pnpm dev
 ```
 
-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.
-
-```text
-remote-vue/     Provides a button and add() function; dev port 5174
-host-vue/       Loads them; dev port 5173
-```
-
-### 1. Declare remote files
-
-`remote-vue/fulgurjs.config.ts`:
-
-```ts
-import type { FederationOptions } from '@fulgurjs/federation'
-
-export default {
-  name: 'remote-vue',
-  exposes: {
-    './Button': './src/Button.vue',
-    './math': './src/math.ts',
-  },
-  shared: { vue: { singleton: true, strictVersion: true } },
-} satisfies FederationOptions
-```
-
-`remote-vue/src/Button.vue`:
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-defineProps<{ label: string }>()
-const count = ref(0)
-</script>
-
-<template>
-  <button @click="count++">{{ label }}: {{ count }}</button>
-</template>
-```
-
-`remote-vue/src/math.ts`:
-
-```ts
-export function add(a: number, b: number): number {
-  return a + b
-}
-```
-
-### 2. Declare the address in the host
+**Existing project**: install the package, register the plugin in `vite.config.ts`, and import from the unified entry for your framework:
 
-`host-vue/fulgurjs.config.ts`:
-
-```ts
-import type { FederationOptions } from '@fulgurjs/federation'
-
-export default {
-  name: 'host-vue',
-  remotes: {
-    'remote-vue': {
-      dev: 'http://localhost:5174',
-      prod: '/remote-vue',
-    },
-  },
-  shared: { vue: { singleton: true, strictVersion: true } },
-} satisfies FederationOptions
+```bash
+npm add @fulgurjs/federation
 ```
 
-`dev` is the development URL. `prod` is the deployed URL; `/remote-vue` refers to a path on the host origin, not a local filesystem folder.
-
-### 3. Register the plugin in both applications
-
-Each project's `vite.config.ts` imports its own federation config:
-
 ```ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
+// vite.config.ts — build config uses the package root
 import federation from '@fulgurjs/federation'
-import fulgurjsConfig from './fulgurjs.config'
-
-export default defineConfig({
-  plugins: [vue(), federation(fulgurjsConfig)],
-  build: { target: 'es2022' },
-})
-```
 
-Keep existing aliases, proxies and other settings. Install compatible Vue versions in both applications; `strictVersion` rejects incompatible shared versions.
-
-### 4. Display and call the remote modules
-
-`host-vue/src/App.vue`:
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { loadRemote, remoteComponent } from '@fulgurjs/federation/runtime'
-
-const RemoteButton = remoteComponent('remote-vue/Button')
-const result = ref('Not calculated yet')
-
-async function calculate() {
-  try {
-    const math = await loadRemote<{ add(a: number, b: number): number }>('remote-vue/math')
-    result.value = String(math.add(1, 2))
-  } catch (error) {
-    result.value = error instanceof Error ? error.message : String(error)
-  }
+export default {
+  plugins: [federation({
+    name: 'my-app',
+    // exposes / remotes / shared as needed — see "Adopting in an existing project"
+  })],
 }
-</script>
-
-<template>
-  <RemoteButton label="Remote button" />
-  <button @click="calculate">Call remote add()</button>
-  <p>{{ result }}</p>
-</template>
 ```
 
-In `remote-vue/Button`, `remote-vue` matches the host's `remotes` key and `Button` matches the remote's `./Button` expose key. The `./` can be omitted when loading it.
-
-`loadRemote` returns module exports. You still need to call `math.add()` to perform the calculation.
-
-### 5. Run both applications
-
-```bash
-# Terminal one, inside remote-vue
-npm run dev -- --port 5174 --strictPort
-
-# Terminal two, inside host-vue
-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/templates/vue-vue).
-
-## React setup
-
-Use the same configuration structure with these changes:
-
-1. Use `@vitejs/plugin-react` in `vite.config.ts`, followed by `federation(fulgurjsConfig)`.
-2. Expose `./Button` from `./src/Button.tsx`; configure the remote's address in the host.
-3. Both applications use compatible React/renderer versions and share:
-
 ```ts
-shared: {
-  react: { singleton: true, strictVersion: true },
-  'react-dom': { singleton: true, strictVersion: true },
-}
+// Vue app code imports from @fulgurjs/federation/vue
+import { loadRemote, remoteComponent } from '@fulgurjs/federation/vue'
+const RemoteButton = remoteComponent('remote-a/Button')
+const math = await loadRemote<{ add(a: number, b: number): number }>('remote-a/math')
 ```
 
-Remote `src/Button.tsx`:
-
 ```tsx
-import { useState } from 'react'
-
-export default function Button({ label }: { label: string }) {
-  const [count, setCount] = useState(0)
-  return <button onClick={() => setCount(count + 1)}>{label}: {count}</button>
-}
+// React app code imports from @fulgurjs/federation/react
+import { remoteComponent, useLoadRemote, RemoteErrorBoundary } from '@fulgurjs/federation/react'
 ```
 
-Host `src/App.tsx`, with a remote configured as `remote-react`:
-
-```tsx
-import { remoteComponent } from '@fulgurjs/federation/react'
-
-// Create once at module scope, not on every render.
-const RemoteButton = remoteComponent<{ label: string }>('remote-react/Button', {
-  fallback: <p>Loading…</p>,
-})
-
-export default function App() {
-  return <RemoteButton label="Remote React button" />
-}
-```
-
-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
-
-**A bridge embeds a sub-app with its own component tree. It does not convert a React component into a Vue component.**
-
-For a Vue host embedding React:
-
-1. React remote `src/bridge.tsx`:
-
-```tsx
-import { defineBridgeApp } from '@fulgurjs/federation/react'
-
-export default defineBridgeApp((props) => (
-  <section>React sub-app: {String(props.message ?? '')}</section>
-))
-```
-
-2. Add `exposes: { './bridge': './src/bridge.tsx' }` to the remote config.
-3. Configure the remote address in the Vue host, then use:
-
-```vue
-<script setup lang="ts">
-import { createVueBridgeApp } from '@fulgurjs/federation/bridge/vue'
-const RemoteApp = createVueBridgeApp<{ message: string }>('remote-react/bridge')
-</script>
-
-<template>
-  <RemoteApp :app-props="{ message: 'From Vue host' }" />
-</template>
+```ts
+// Framework-agnostic browser modules: @fulgurjs/federation/runtime (zero Vue/React)
+import { loadRemote, loadShare } from '@fulgurjs/federation/runtime'
 ```
 
-A cross-framework host installs and shares `vue`, `react` and `react-dom`. The child installs and shares its own framework. React and react-dom must be compatible; multiple React majors need separate dependency groups and consumers, as shown in the isolation demo.
+## Entries (6.0.0)
 
-In the other direction, use `createReactBridgeApp` in the React host. The Vue child uses `defineBridgeApp` from `/runtime` and returns a `createApp(...)` application.
-
-### The shortest bridge mental model
-
-| Question | Answer |
+| Where | Entry |
 |---|---|
-| 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
-
-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
-
-Bridging does not change the host URL by default. Enable URL sync to map:
-
-```text
-Host /approval/list        → Child /list
-Host /approval/detail/42   → Child /detail/42
-```
-
-Configure both sides:
-
-1. The host router must handle all child paths under `/approval` without unmounting the child on each detail navigation.
-2. Pass `routing` to the host bridge component, including `basePath: '/approval'` and the host navigation adapter.
-3. The child declares `defineBridgeApp(..., { routing: true })` and connects a controlled memory router.
-
-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/examples/templates/showcase).
-
-## User data and remote initialization
-
-These features are optional. A plain button or utility module does not need them.
-
-| Need | API | When |
-|---|---|---|
-| Provide user, token getter, store, etc. | `provideAppContext` | Host supplies them before loading business modules |
-| Read host values | `getAppContext` / `requireAppContext` | Called by remote business code |
-| Initialize a remote once | Default export in configured `setup` file | Before the first business `loadRemote('remote/module')` returns |
-| Synchronize permissions after login/account changes | Named `onSession` export in the same file | Deduplicated by `sessionKey` |
-| Clear account context on logout | `clearAppContext` | Host logout flow; host also removes private pages/caches |
-
-`sessionKey` identifies a login attempt; it is **not a token or authorization credential**. Generate a new value on login/account change; token refresh alone retains it.
-
-A bridge can read current data using `getContext`. Controlled `sessionKey: null` means logged out: unmount and stop loading. Omitting the key disables controlled session switching.
-
-Only a configured `setup` file participates in initialization. `preloadRemote` fetches resources without running setup/onSession. Async initialization must check `context.signal.aborted` before writing state, so late responses do not restore old-account data.
-
-See the [API reference](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#context).
+| Vite config, `FederationOptions` types | `@fulgurjs/federation` |
+| Vue app code (components/pages/bridge/router sync) | `@fulgurjs/federation/vue` |
+| React app code (components/pages/bridge/router sync) | `@fulgurjs/federation/react` |
+| Framework-agnostic browser modules | `@fulgurjs/federation/runtime` |
 
-## Several remote pages
+Since 6.0.0 the legacy entries `/bridge`, `/bridge/vue`, `/bridge/react` and `/bridge/router/{vue,react}` are removed; their features live in `/vue` and `/react`. See the [migration guide](docs/en/migration.md).
 
-Maintain a page table and pass it to `createHostPages` (Vue) or `createReactHostPages` (React). These helpers resolve modules, cache loading components and provide loading/error states. **They do not create your host Router.**
+## Capabilities
 
-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/examples/demos/pages-cli).
-
-## Build and deploy
-
-Build each application separately with its own `npm run build`. The remote produces `fulgurjs-remoteEntry.js` and `fulgurjs-manifest.json` by default. The host locates them through `prod`.
-
-Check these settings:
-
-- Remote deployment `/remote-vue/` → remote Vite `base: '/remote-vue/'` and host `prod: '/remote-vue'`.
-- HTML, remoteEntry and manifest use `Cache-Control: no-cache`; content-hashed chunks can use long-lived caching.
-- SPA routes support refresh; missing resource URLs return 404 rather than HTML.
-- 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/templates/vue-vue/README.md) / [React](https://github.com/chenmingye/fulgurjs-federation/blob/master/examples/templates/react-react/README.md).
-
-## Handle failures
-
-| Symptom | Check | Recovery |
-|---|---|---|
-| Remote unavailable | Server, address, CORS | Timeout/retry/error UI; optional backup entry or fallback module |
-| Module missing | remotes name and exposes key | Fix the name and retry |
-| Shared version incompatible | Installed versions, requiredVersion, strictVersion, scope | Align or isolate versions |
-| Static dependency remains failed after service recovery | Browser may retain the failed dependency URL | User-initiated refresh preserves the current address |
-| Child unmount fails | Child cleanup, timers and subscriptions | Container stays blocked; refresh and fix cleanup |
-
-`remoteComponent` and bridge components provide default error UI. Direct `loadRemote` calls and React `useLoadRemote` require application error handling. An explicit `fallbackModule` does not repair the original remote.
-
-Errors include a code, cause and fix. See [error codes](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#error-codes).
-
-## Vite 8 and support boundaries
-
-**Supports Vite 8 development and production. The earlier large-application startup hang has been fixed and relevant regression tests pass.**
-
-Two practical details:
-
-- A first dev visit may reload while Vite prepares newly discovered dependencies. Wait for optimization before judging stable behavior. This is not a production behavior on every visit.
-- Some shared scenarios fetch an unused local library copy. One singleton scope still uses one instance; explicitly isolated React 18/19 scopes may use one each. Downloaded file count and active instance count are different.
-
-Not provided: SSR/RSC, Node-side federation, React Native, automatic JS/CSS isolation, webpack `script/var` artifact interoperability, component-type conversion, automatic multi-level bridge routing proxies or cross-window route sync. Global CSS/variables can affect the host; children need their own internal error handling.
-
-See the [capability comparison](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/webpack-mf-对照与缺口.md) for detailed boundaries and differences from webpack.
-
-## Debugging, types and CLI
-
-Run in the application directory:
-
-```bash
-# 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
-npx fulgurjs check-pages --site http://localhost:5173
-
-# After deployment under /remote-vue/, substitute your actual site:
-npx fulgurjs doctor --base https://your-site.example --apps remote-vue
-```
-
-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 (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.
-
-Advanced diagnostics use `window.__FULGURJS_SCOPE__`, `window.__FULGURJS_INFO__` and `FULGURJS_DEBUG`. Normal integration does not require editing these objects.
-
-## API reference
-
-Use the current reference rather than guessing signatures from old task documents:
-
-- [Plugin options and defaults](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#plugin-options)
-- [Runtime loading, registration and hooks](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#runtime)
-- [Bridge props, sessions and cleanup](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#bridge)
-- [URL sync and navigation](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.en.md#url-sync)
-- [Chinese API reference](https://github.com/chenmingye/fulgurjs-federation/blob/master/docs/API.md)
-
-### When an AI implements your integration
-
-Specify the framework, whether you need a component or sub-app, remote URLs/expose names, and whether login switching or URL sync is required. Have it read the guide and relevant API section first, preserve the existing Vite configuration, check installed versions and use the correct browser entry. It should not invent configuration fields. Verify mounting, interaction and error handling; URL sync also needs deep-link refresh, history and cancellation checks.
+- **Components & modules**: `remoteComponent` (Vue/React), `useLoadRemote`, `RemoteErrorBoundary`, `loadRemote` — explicit retryable error states, no silent fallbacks.
+- **Per-page pages**: `definePages` + `createHostPages` (host route table → remote pages) with CLI `check-pages` contract checks.
+- **Full sub app bridge**: `defineBridgeApp` (child) + `createVueBridgeApp` / `createReactBridgeApp` (host); mount/unmount, session epochs, unmount-failure quarantine.
+- **URL sync**: `createVueBridgeNavigation` / `createReactBridgeNavigation` (host) + `connectVueBridgeRouter` / `createReactBridgeRouter` (child); deep-link refresh, guard cancellation, query/hash preservation.
+- **Shared dependencies**: singleton / requiredVersion / strictVersion / shareScope / eager, sync & async negotiation, React 18/19 multi-version isolation.
+- **CLI**: `create` / `init` / `explain` / `check-pages` / `doctor` / `port`.
 
 ## Documentation
 
-- [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.
+| Need | Entry |
+|---|---|
+| New project / existing project | [Getting started](docs/en/guide/getting-started.md) |
+| Vue/React components & plain modules | [Components & modules](docs/en/guide/components-and-modules.md) |
+| Full sub apps / cross-framework nesting | [App bridge](docs/en/guide/app-bridge.md) |
+| Router sync / deep links | [URL sync](docs/en/guide/url-sync.md) |
+| All options & defaults | [Configuration](docs/en/reference/configuration.md) |
+| Full API signatures & semantics | [API reference](docs/en/reference/api.md) |
+| CLI commands & exit codes | [CLI reference](docs/en/reference/cli.md) |
+| Error codes (symptom/cause/fix) | [Error code table](docs/en/reference/errors.md) |
+| Troubleshooting / compatibility | [Troubleshooting](docs/en/troubleshooting/README.md) |
+| Templates & demos | [Examples overview](examples/README.md) |
 
-## Development and testing
+## Examples
 
-These commands develop **this plugin repository**; ordinary consumers do not need them:
+Five complete templates (`vue-vue` / `react-react` / `vue-host-react-remote` / `react-host-vue-remote` / `showcase`) plus feature demos live in [examples/](examples/README.md). Each can be copied out and installed standalone.
 
-```bash
-pnpm --dir packages/plugin install
-pnpm --dir packages/plugin build
-pnpm test:unit
-```
+## Contributing & security
 
-See [CONTRIBUTING](https://github.com/chenmingye/fulgurjs-federation/blob/master/CONTRIBUTING.md) for fixture installation and browser test prerequisites. CI checks builds, types, unit tests, installed packages and browser scenarios across multiple Vite versions. Counts come from the corresponding run.
+- See [CONTRIBUTING.md](CONTRIBUTING.md); architecture and release process live in [docs/maintainers/](docs/maintainers/README.md).
+- Please report security issues privately via [SECURITY.md](SECURITY.md).
 
 ## License
 
-[MIT](LICENSE) © chenmingye (Jason)
+[MIT](LICENSE)