@fulgurjs/federation 3.0.0 → 4.0.0

package/docs//350/277/201/347/247/273/346/214/207/345/215/227.md

@@ -12,7 +12,9 @@
 | 主子应用 window 隔离/沙箱 | 无沙箱：同 realm 直渲染（`window.xxx` 全局桥自然可用） |
 | props 传递（qiankun 传参） | 组件 props（路由通道 = params+query 合并；弹窗通道 = 显式 v-bind） |
 | 公共依赖 externals/主应用共享 | `shared`（singleton 协商，"已加载优先"） |
-| `qiankun` 运行时 + single-spa | `virtual:fulgurjs-runtime`（15KB 级，无 single-spa） |
+| `qiankun` 运行时 + single-spa | `@fulgurjs/federation/runtime`（运行时内核 15KB 级，无 single-spa） |
+
+应用代码统一从 `@fulgurjs/federation/runtime` 导入。Vite 配置继续从 `@fulgurjs/federation` 导入插件。升级自 3.x 时，将 `virtual:fulgurjs-api` 替换为物理子路径；`remoteSchema` 仍按具名导入，开发态由插件填充，构建态为空清单。
 
 ## 二、迁移步骤（真实案例顺序）
 
@@ -36,7 +38,7 @@
 - [ ] 零兜底：联邦不可用显式报错（杀 remote 故障注入）
 - [ ] 装后可用：npm pack → 干净项目 dev+prod（e2e/h7-install-test.sh）
 
-> **目录约定说明**：联邦相关产物统一收在 **`src/fulgurjs/`** 一个文件夹（每个应用一份，内附 README 说明归属）——`types/`（插件每次 dev 自动生成的类型直连与运行时类型垫片，**勿手改**；src 布局 tsconfig 零配置生效，无 src 布局回退根目录 `.fulgurjs/types/`）与按角色划分的代码子目录：远程应用为 `exposes/`（联邦启动引导 federatedBoot + 供外部加载的组件），宿主应用为 `host/`（桥接 bridge.ts + 页面路由表 pages.ts）。均为迁移工具脚手架约定而非插件要求，可按团队习惯重组，只要 vite `exposes` 映射与调用点跟着改。
+> **目录约定说明**：联邦相关产物统一收在 **`src/fulgurjs/`** 一个文件夹（每个应用一份，内附 README 说明归属）——`types/`（插件每次 dev 自动生成的远程 exposes 类型直连，**勿手改**；运行时类型由包的 `/runtime` 子路径直接解析；无 src 布局回退根目录 `.fulgurjs/types/`）与按角色划分的代码子目录：远程应用为 `exposes/`（联邦启动引导 federatedBoot + 供外部加载的组件），宿主应用为 `host/`（桥接 bridge.ts + 页面路由表 pages.ts）。均为迁移工具脚手架约定而非插件要求，可按团队习惯重组，只要 vite `exposes` 映射与调用点跟着改。
 
 ## 三B、首次使用避坑清单（真实迁移踩坑实录，全文见仓库 README「避坑指南」节）
 
@@ -51,24 +53,24 @@
 | 7 | 登录异步链未完成就断言 | e2e 偶发被弹回登录页 | 等「登录表单消失」而非固定秒数；后台慢链 ≥15s |
 | 8 | 多版本组件库 CSS | 后加载覆盖 `:root` 变量 | 主流版本变量一致则无感；升级时留意 |
 | 9 | 后端缺端点 | 404/401 资源报错 | 代理/NGINX 层加诚实空响应垫片（不伪造业务数据） |
-| 10 | 远程页面（exposes 目标文件）静态导入 `virtual:fulgurjs-runtime` | 直接静态导入 | 插件自动把该导入改写为惰性单例代理——远程页面写法与宿主完全一致（详见下节三B-1） |
+| 10 | 远程页面（exposes 目标文件）静态导入 `@fulgurjs/federation/runtime` | 直接静态导入 | 插件自动把该导入改写为惰性单例代理——远程页面写法与宿主完全一致（详见下节三B-1） |
 
 ### 三B-1、远程页面如何取宿主运行时
 
 exposes 目标文件（被宿主跨源加载的远程页面/组件）**可以直接静态导入**
-`virtual:fulgurjs-runtime`——插件自动把远程页面里的该导入改写为**惰性单例代理**：
+`@fulgurjs/federation/runtime`——插件自动把远程页面里的该导入改写为**惰性单例代理**：
 求值期零副作用、调用期转发页面级运行时单例。宿主与远程写法完全一致，无需区分。
 
 ```ts
 // 远程页面内，与宿主页面写法完全一致
-import { loadRemote } from 'virtual:fulgurjs-runtime'
+import { loadRemote } from '@fulgurjs/federation/runtime'
 ```
 
-组件直渲染推荐用 `@fulgurjs/federation/vue` 子路径的 `remoteComponent`——
+组件直渲染推荐用 `@fulgurjs/federation/runtime` 子路径的 `remoteComponent`——
 `defineAsyncComponent + loadRemote` 的标准封装，加载失败显式错误占位（错误码+根因+修法），无任何兜底：
 
 ```ts
-import { remoteComponent } from '@fulgurjs/federation/vue'
+import { remoteComponent } from '@fulgurjs/federation/runtime'
 const FederatedBusinessForm = remoteComponent('demo-host/FormRouterPage')
 ```
 
@@ -81,7 +83,7 @@ realm 检测等特殊场景，常规集成无需使用。
 
 ```ts
 // 宿主桥（admin/src/fulgurjs/host/bridge.ts）——登录完成后一次性提供
-import { provideAppContext } from '@fulgurjs/federation/context'
+import { provideAppContext } from '@fulgurjs/federation/runtime'
 provideAppContext({
   user, getToken, store, hostApp, locale,   // 只传有真实消费的键（token 一律 getToken() 拉取）
   events: { main: mainEvents },       // 方法池：宿主提供 main.*，子应用反向注册 bpm.* / lowcode.*
@@ -89,12 +91,12 @@ provideAppContext({
 })
 
 // 远程启动引导（xxx/src/fulgurjs/exposes/federatedBoot.ts）——显式校验消费
-import { requireAppContext } from '@fulgurjs/federation/context'
+import { requireAppContext } from '@fulgurjs/federation/runtime'
 const { store, user, hostApp } = requireAppContext('store', 'user', 'hostApp')
 // 缺键 → [fulgurjs:CC-001]（三段式，指向宿主桥）；独立直开远程页 → [fulgurjs:CC-002]
 
 // 页面读点（替代 window.mainAppProps?.xxx）
-import { getAppContext } from '@fulgurjs/federation/context'
+import { getAppContext } from '@fulgurjs/federation/runtime'
 const dict = getAppContext().events?.main?.getDictItems?.('sex')
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulgurjs/federation",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "Vite Module Federation with full Webpack MF parity. Dev & production, no compromise.",
   "license": "MIT",
@@ -18,8 +18,9 @@
       "import": "./dist/config.js",
       "require": "./dist/config.cjs"
     },
-    "./client": {
-      "types": "./client.d.ts"
+    "./runtime": {
+      "types": "./dist/runtime-entry.d.ts",
+      "import": "./dist/runtime-entry.js"
     },
     "./package.json": "./package.json",
     "./internal/context.js": {
@@ -36,18 +37,25 @@
       "types": "./dist/vue.d.ts",
       "import": "./dist/vue.js",
       "require": "./dist/vue.cjs"
+    },
+    "./internal/vue-adapter.js": {
+      "types": "./dist/vue-adapter.d.ts",
+      "import": "./dist/vue-adapter.js",
+      "require": "./dist/vue-adapter.cjs"
     }
   },
   "typesVersions": {
     "*": {
       "config": [
         "dist/config.d.ts"
+      ],
+      "runtime": [
+        "dist/runtime-entry.d.ts"
       ]
     }
   },
   "files": [
     "dist",
-    "client.d.ts",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -59,7 +67,7 @@
     "docs/P5-vite7-8兼容矩阵.md"
   ],
   "scripts": {
-    "build": "cp ../../README.md README.md && mkdir -p docs && cp ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md docs/ && cp ../../CHANGELOG.md CHANGELOG.md && cp ../../DESIGN.md DESIGN.md && rm -rf examples && cp -r ../../examples examples && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime.mjs && tsup src/index.ts src/pages.ts src/config.ts src/vue.ts src/context.ts --format esm,cjs --dts --external vite --target node18 --clean && esbuild src/cli.ts --bundle --format=esm --target=node18 --platform=node --outfile=dist/cli.js && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/check-gzip.mjs && node scripts/check-manual-codes.mjs",
+    "build": "cp ../../README.md README.md && mkdir -p docs && cp ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md docs/ && cp ../../CHANGELOG.md CHANGELOG.md && cp ../../DESIGN.md DESIGN.md && rm -rf examples && cp -r ../../examples examples && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime.mjs && tsup src/index.ts src/pages.ts src/config.ts src/vue.ts src/vue-adapter.ts src/context.ts --format esm,cjs --dts --external vite --target node18 --clean && tsup src/runtime-entry.ts --format esm --dts --external vite,vue --target node18 && esbuild src/cli.ts --bundle --format=esm --target=node18 --platform=node --outfile=dist/cli.js && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime-entry.mjs && node scripts/check-gzip.mjs && node scripts/check-manual-codes.mjs",
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",

package/client.d.ts

@@ -1,180 +0,0 @@
-/**
- * virtual:fulgurjs-api 客户端类型声明（3.0.0 起唯一公开运行时入口）。
- *
- * 应用代码的一切联邦导入——runtime 函数、context 三函数（provideAppContext/
- * getAppContext/requireAppContext）、definePages/validatePages、remoteSchema、
- * remoteComponent——全部来自 'virtual:fulgurjs-api'。旧入口
- * （virtual:fulgurjs-runtime、@fulgurjs/federation/{context,pages,vue}）已删除。
- * 类型由本声明聚合（script 文件：顶层无 import/export，环境模块声明才生效）。
- *
- * 用法（二选一）：
- * 1. dev 启动后插件自动在类型目录（默认 src/fulgurjs/types/，无 src 布局回退 .fulgurjs/types/）
- *    生成 fulgurjs-runtime.d.ts 加载垫片——只要 tsconfig include 了该目录
- *    （远程模块类型直连本就要求），运行时类型零配置生效；
- * 2. tsconfig.json → compilerOptions.types 加 "@fulgurjs/federation/client"（对齐 vite/client 模式）。
- *
- * ⚠️ 本文件必须是 script 形态（顶层不得出现 import/export）——环境模块声明
- * （declare module）住在 module 文件里会退化为 augmentation 被静默忽略。
- * 与 dist/runtime.js 的导出面一一对应（tests/client-types.test.ts 守漂移）。
- * 对外类型（LoadRemoteOptions 等）经 'virtual:fulgurjs-runtime' 模块本身导出，
- * 用法：import type { LoadRemoteOptions } from 'virtual:fulgurjs-runtime'。
- */
-declare module 'virtual:fulgurjs-api' {
-  /** shared 协商条目（window.__FULGURJS_SCOPE__ 内的形态） */
-  export interface ShareEntry {
-    version: string
-    get: () => Promise<any>
-    from: string
-    eager: boolean
-    loaded?: boolean
-  }
-
-  /** 远程注册配置（federation({ remotes }) 对象形态的运行时等价物） */
-  export interface RemoteInput {
-    name: string
-    entry: string
-    shareScope?: string
-    timeout?: number
-    retries?: number
-    fallback?: string[]
-    breaker?: { threshold: number; resetMs: number }
-    manifestUrl?: string
-    container?: unknown
-    containerPromise?: Promise<unknown>
-  }
-
-  export interface LoadRemoteOptions {
-    /** 单次调用级重试覆盖（缺省用远程注册值，默认 2） */
-    retries?: number
-    /** 显式降级：加载失败时返回该模块（错误事件仍显式发出，绝不静默兜底） */
-    fallbackModule?: () => Promise<any> | any
-  }
-
-  export interface PreloadRemoteOptions {
-    /** preload = 立即高优先级；prefetch = 空闲时低优先级 */
-    mode?: 'preload' | 'prefetch'
-  }
-
-  export interface LoadShareOptions {
-    shareScope?: string
-    shareKey?: string
-    requiredVersion?: string | false
-    singleton?: boolean
-    strictVersion?: boolean
-    fallback?: () => Promise<any>
-  }
-
-  /**
-   * 跨应用上下文标准字段表见 README §9。token 快照 / formUrl / baseUrl 不在默认 provide 内——
-   * 取 token 用 getToken()（拉取式不过期），其余按项目需要经扩展位自定。
-   * 值 API 在 '@fulgurjs/federation/context' 子路径（runtime.js 不导出 context 函数，
-   * 此处仅类型随虚拟模块声明供 type-only import）；读写约定：宿主桥先写标准字段，
-   * 远程 boot 只增不改宿主键；嵌套对象（如 events）引用共享。
-   */
-  export interface AppContext {
-    /** 宿主登录用户原始形态（只读约定） */
-    user: Record<string, any>
-    /** 取最新 token（拉取式防过期；0.8.2 起 bridge 不再传一次性 token 快照） */
-    getToken?: () => string | undefined
-    /** 宿主 pinia 实例：子应用 useUserStore(ctx.store) 拿共享响应式状态 */
-    store?: unknown
-    /** 宿主 Vue App 实例（同 realm 直引用）：全局组件/指令注册目标 */
-    hostApp?: unknown
-    /** EP locale 等 UI 配置（原 W4 字段） */
-    locale?: unknown
-    /** 事件/方法池：events.main.* 宿主提供、events.bpm.* / events.lowcode.* 子应用反向注册 */
-    events?: Record<string, any>
-    /** 项目扩展位（formUrl/baseUrl 等自定义键，按需自行提供） */
-    [key: string]: unknown
-  }
-
-  /** 运行时单例（与 globalThis.__FULGURJS_RUNTIME__ 同一实例，方法面冻结） */
-  export interface FgRuntime {
-    shareScopeMap: Record<string, Record<string, Record<string, ShareEntry>>>
-    initSharing(scopeName?: string): FgRuntime['shareScopeMap']
-    registerShare(
-      scopeName: string,
-      name: string,
-      version: string,
-      get: () => Promise<any>,
-      opts?: { from?: string; eager?: boolean; loaded?: boolean },
-    ): void
-    registerRemotes(remotes: RemoteInput[]): void
-    registerRemote(remote: RemoteInput): void
-    registerPlugins(plugins: unknown[]): void
-    loadShare<T = any>(name: string, opts?: LoadShareOptions): Promise<T>
-    loadRemote<T = Record<string, any>>(spec: string, opts?: LoadRemoteOptions): Promise<T>
-    getContainer(name: string): Promise<{ name: string; init: (scope: unknown) => void | Promise<void>; get: (module: string) => Promise<any> }>
-    preloadRemote(spec: string, opts?: PreloadRemoteOptions): Promise<void>
-    parseSpec(spec: string): { remote: string; module: string }
-  }
-
-  export const version: string
-  export const runtime: FgRuntime
-  export const shareScopeMap: FgRuntime['shareScopeMap']
-  export function getRuntime(): FgRuntime
-  export function initSharing(scopeName?: string): FgRuntime['shareScopeMap']
-  export function registerShare(
-    scopeName: string,
-    name: string,
-    version: string,
-    get: () => Promise<any>,
-    opts?: { from?: string; eager?: boolean; loaded?: boolean },
-  ): void
-  export function registerRemotes(remotes: RemoteInput[]): void
-  export function registerRemote(remote: RemoteInput): void
-  export function registerPlugins(plugins: unknown[]): void
-  export function loadShare<T = any>(name: string, opts?: LoadShareOptions): Promise<T>
-  export function loadRemote<T = Record<string, any>>(spec: string, opts?: LoadRemoteOptions): Promise<T>
-  export function getContainer(
-    name: string,
-  ): Promise<{ name: string; init: (scope: unknown) => void | Promise<void>; get: (module: string) => Promise<any> }>
-  export function preloadRemote(spec: string, opts?: PreloadRemoteOptions): Promise<void>
-  export function parseSpec(spec: string): { remote: string; module: string }
-  /** 兜底解包：命名空间有 default 取 default，否则原样返回 */
-  export function unwrapDefault<T>(ns: { default?: T } | T): T
-  /** 与 globalThis.__FULGURJS_RUNTIME__ 同一实例（方法面冻结） */
-  const runtimeDefault: FgRuntime
-  export default runtimeDefault
-
-  // ── 跨应用上下文（原 @fulgurjs/federation/context，3.0.0 并入）──
-  export function provideAppContext(config: Partial<AppContext> & Record<string, unknown>): void
-  export function getAppContext(): AppContext
-  export function requireAppContext(...keys: string[]): AppContext
-
-  // ── 页面路由表（原 @fulgurjs/federation/pages，3.0.0 并入）──
-  export interface PageRouteLike {
-    route: string
-    name?: string
-    spec?: string
-    title?: string
-    keepAlive?: boolean
-  }
-  export interface PagesOptions {
-    pages: PageRouteLike[]
-    remoteSchema?: { [remoteKey: string]: { exposes: string[]; exists: boolean } }
-    remoteNameOf?: (route: string) => string
-    exposeOf?: (route: string, remoteName: string) => string
-  }
-  export interface PageViolation {
-    level: 'ERROR' | 'WARN'
-    route: string
-    reason: string
-  }
-  export function validatePages(pages: PageRouteLike[], opts?: PagesOptions): PageViolation[]
-  export function definePages<P extends PageRouteLike[]>(pages: P, opts?: PagesOptions): P
-
-  // ── Vue 远程组件直渲染（原 @fulgurjs/federation/vue，3.0.0 并入）──
-  export interface RemoteComponentOptions {
-    loadingComponent?: unknown
-    errorComponent?: unknown
-    retries?: number
-    delay?: number
-    timeout?: number
-  }
-  export function remoteComponent(spec: string, opts?: RemoteComponentOptions): unknown
-
-  // ── 远程 exposes 清单（dev 异步 probe；build 为空表，路由校验按 R3 降级）──
-  export const remoteSchema: { [remoteKey: string]: { exposes: string[]; exists: boolean } }
-}
-