@anov/cic-standard-sdk 0.0.20 → 0.0.21

package/dist/sdk/CICSDK.d.ts

@@ -2,6 +2,7 @@ import type { CICConfig, ComponentInstance } from '../types';
 import { CICInstance } from './CICInstance';
 import { createBareLoader, createDependencyLoader, getDependencyLoaderSingleton } from './depsLoader';
 import { Render } from './render';
+import { createManifestLoader, resolveManifest } from './manifestLoader';
 export * from '../types';
 export type { Result as GeneratorResult } from './core';
 /**
@@ -55,4 +56,8 @@ export declare class CICSDK extends CICInstance {
     static getDependencyLoaderSingleton: typeof getDependencyLoaderSingleton;
     /** 渲染 */
     static Render: typeof Render;
+    /** 解析供需清单 */
+    static resolveManifest: typeof resolveManifest;
+    /** 创建 manifest 加载器 */
+    static createManifestLoader: typeof createManifestLoader;
 }

package/dist/sdk/manifestLoader/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @file sdk/manifestLoader/index.ts
+ * @description Manifest 供需匹配核心实现
+ *
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  职责                                                                │
+ * │  1. resolveManifest()  —— 纯函数，供需匹配 + 合并，不依赖网络/DOM    │
+ * │  2. createManifestLoader() —— 工厂函数，远程加载 JSON 后调用         │
+ * │     resolveManifest，并将结果写入 globalThis                         │
+ * │                                                                     │
+ * │  设计约束：                                                          │
+ * │  - resolveManifest 是纯函数，可在 Node.js / 浏览器 / 测试中运行      │
+ * │  - createManifestLoader 依赖 fetch API，仅面向浏览器环境             │
+ * │  - 两者均不依赖 DOM importMap 注入（由 manifest-loader.js 负责）     │
+ * └─────────────────────────────────────────────────────────────────────┘
+ *
+ * 数据流：
+ *   RuntimeManifest (JSON)  ──┐
+ *                              ├─ resolveManifest() ──→ ResolvedManifest
+ *   CICManifest     (JSON)  ──┘                              │
+ *                                                            ▼
+ *                                               window.__MANIFEST__
+ *                                               window.__ENV__
+ *                                               window.__manifestReady
+ */
+import type { CICManifest } from '../../types/manifest/cic.manifest';
+import type { LoaderOptions, ResolvedManifest, RuntimeManifest } from '../../types/manifest/runtime.manifest';
+/**
+ * 供需匹配核心函数：将 RuntimeManifest（供给）与 CICManifest（需求）合并
+ *
+ * 输入：
+ *   runtime —— 宿主供给表（RuntimeManifest），描述能提供什么
+ *   cic     —— 应用需求表（CICManifest），描述需要什么
+ *
+ * 输出：ResolvedManifest，包含：
+ *   importMap —— 三方合并后的完整 importMap（可直接注入浏览器）
+ *   env       —— 合并后的环境变量（runtime.env 被 cic.env 覆盖）
+ *   report    —— 每条依赖的决策过程记录（可观测性）
+ *
+ * importMap 合并优先级（低 → 高）：
+ *   importsRuntime（runtime.importMap.imports）
+ *     < importsGenerated（供需匹配生成：direct-esm URL + shimB data:URL）
+ *     < importsAlias（alias 展开）
+ *     < cic.modules.importMap.imports（应用显式声明，最高优先级）
+ *
+ * ⚠️ 纯函数，无副作用，无 DOM 操作，可在 Node.js / 测试环境安全调用。
+ * ⚠️ 此函数不负责 importMap 注入（由 manifest-loader.js 调用 injectImportMap 完成）。
+ */
+export declare function resolveManifest(runtime: RuntimeManifest, cic: CICManifest): ResolvedManifest;
+/**
+ * 创建 manifest loader 实例（面向浏览器环境）
+ *
+ * 职责：
+ *   1. 并行 fetch runtime.manifest.json 和 cic.manifest.json
+ *   2. 调用 resolveManifest 完成供需匹配
+ *   3. 将结果写入 globalThis 的三个全局变量
+ *
+ * 与 manifest-loader.js（浏览器脚本）的分工：
+ *   manifest-loader.js —— 负责 importMap DOM 注入、modulepreload 插入、
+ *                          script 加载（shimB/globalTask）、import(entry)
+ *   createManifestLoader —— 负责 JSON 加载和供需逻辑，不操作 DOM
+ *
+ * 使用示例：
+ *   const loader = createManifestLoader({ runtimeUrl: '/runtime.manifest.json' })
+ *   const resolved = await loader.load()
+ *   console.log(resolved.report.entries)
+ *
+ * @param options LoaderOptions（所有字段可选，提供合理默认值）
+ */
+export declare function createManifestLoader(options?: LoaderOptions): {
+    /**
+     * 加载并解析 manifest，写入全局状态
+     *
+     * 写入的全局变量：
+     *   globalThis.__MANIFEST__      ResolvedManifest 完整结果
+     *   globalThis.__ENV__           合并后的环境变量（快捷访问）
+     *   globalThis.__manifestReady   已 resolve 的 Promise（兼容 await 语法）
+     *
+     * 注意：此方法写入的 __manifestReady 是 Promise.resolve(resolved)，
+     *       已经 resolve，不是 manifest-loader.js 中的 pending Promise。
+     *       两者在不同使用场景下使用，不要混淆。
+     *
+     * @throws 网络请求失败（HTTP 非 2xx）
+     * @throws resolveManifest 内部的版本/依赖校验错误
+     */
+    load(): Promise<ResolvedManifest>;
+};

package/dist/sdk/render/index.d.ts

@@ -1,11 +1,73 @@
-import type { CICConfig, CICManifest, Adapter, CreateContextOptions } from '../../types';
+/**
+ * @file sdk/render/index.ts
+ * @description Render 渲染协调器
+ *
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  职责                                                                │
+ * │  Render 是 ResolvedManifest 与 Adapter 之间的"协调层"。              │
+ * │  它不关心框架细节，只负责按正确顺序调用 Adapter 生命周期。            │
+ * │                                                                     │
+ * │  职责分工：                                                          │
+ * │    resolveManifest() —— 供需匹配，产出 ResolvedManifest             │
+ * │    Render             —— 消费 ResolvedManifest，驱动 Adapter 生命周期│
+ * │    Adapter            —— 框架具体实现（Vue3/React 等）               │
+ * └─────────────────────────────────────────────────────────────────────┘
+ *
+ * 生命周期调用顺序（render 方法内）：
+ *   supports()      —— 校验适配器是否支持当前 manifest
+ *   createContext() —— 创建贯穿生命周期的执行上下文
+ *   prepare()       —— 可选，预处理（框架实例初始化、异步资源准备）
+ *   register()      —— 必须，组件/插件注册
+ *   mount()         —— 可选，挂载到 DOM 容器
+ *
+ * 扩展能力（当前未封装，由调用方直接使用 adapter）：
+ *   update()  —— 热更新 props/配置
+ *   unmount() —— 卸载并清理
+ *
+ * 使用示例：
+ *   const resolved = await window.__manifestReady
+ *   const render   = new Render(resolved, new Vue3Adapter())
+ *   await render.render(document.getElementById('app'))
+ */
+import type { Adapter, ResolvedManifest } from '../../types';
 export declare class Render {
-    config: CICConfig;
-    manifest: CICManifest;
+    /**
+     * 合并后的完整 manifest，包含供需匹配结果、importMap、env、report。
+     * Adapter 生命周期方法通过 AdapterContext.manifest 访问此对象。
+     */
+    manifest: ResolvedManifest;
+    /**
+     * 平台执行器实例。
+     * 使用无泛型参数的 Adapter（TContainer=unknown, TInstance=unknown），
+     * 允许接收任意平台的 Adapter 实现，由具体 Adapter 内部做类型断言。
+     *
+     * 若需要类型安全的泛型版本，可将 Render 改为泛型类：
+     *   class Render<TContainer, TInstance> {
+     *     adapter: Adapter<TContainer, TInstance>
+     *   }
+     */
     adapter: Adapter;
-    constructor(config: CICConfig, manifest: CICManifest, adapter: Adapter);
     /**
-     * 渲染页面
+     * @param manifest 由 resolveManifest() 产出的合并结果
+     * @param adapter  目标平台的 Adapter 实现（如 Vue3Adapter）
+     */
+    constructor(manifest: ResolvedManifest, adapter: Adapter);
+    /**
+     * 执行完整的渲染装配流程
+     *
+     * 内部按顺序调用：supports → createContext → prepare? → register → mount?
+     *
+     * 错误处理策略（当前版本）：
+     *   - 任意阶段抛出错误，render() 直接向上传播，不做 onError 路由
+     *   - 需要 onError 支持（abort/skip/retry）时，由调用方包裹 try/catch，
+     *     或扩展 Render 类，在各阶段调用 adapter.onError 决策后续行为
+     *
+     * @param container 挂载目标容器
+     *   Web 场景：HTMLElement（如 document.getElementById('app')）
+     *   类型为 unknown，与 Adapter<TContainer=unknown> 保持一致
+     *
+     * @throws Error  adapter.supports() 返回 false
+     * @throws Error  adapter 生命周期方法内部抛出的任意错误
      */
-    render(options: CreateContextOptions): Promise<void>;
+    render(container: unknown): Promise<void>;
 }

package/dist/types/components.d.ts

@@ -1,10 +1,8 @@
 import { CICEventMap } from './events';
 import { Data } from './data';
 import { JSFormat } from './deps';
-/** 通用表达式（用于条件、模板等） */
-export type Expr = string;
-/** 样式值可以是静态或表达式 */
-export type StyleValue = string | number | Expr;
+/** 样式值 */
+export type StyleValue = any;
 /** component 引用：字符串或 object 描述 */
 export type ComponentRef = string | {
     type: 'id';

package/dist/types/index.d.ts

@@ -1,6 +1,4 @@
 /** AUTO-GENERATED BY generate-types.ts — DO NOT EDIT MANUALLY */
-export * from './adapter';
-export * from './cic.manifest';
 export * from './cic';
 export * from './components';
 export * from './data';
@@ -10,5 +8,7 @@ export * from './events';
 export * from './meta';
 export * from './page';
 export * from './registry';
-export * from './runtime.manifest';
 export * from './variables';
+export * from './manifest/adapter';
+export * from './manifest/cic.manifest';
+export * from './manifest/runtime.manifest';

package/dist/types/manifest/adapter.d.ts

@@ -0,0 +1,235 @@
+/**
+ * @file adapter.ts
+ * @description Adapter 执行器接口类型定义
+ *
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  职责定位                                                            │
+ * │  Adapter 是"第三元"：消费 ResolvedManifest，在目标平台执行装配。      │
+ * │                                                                     │
+ * │  与 Loader 的职责分工：                                              │
+ * │    Loader  —— 供需匹配、importMap 注入、依赖加载、shim 生成          │
+ * │    Adapter —— 框架实例创建、组件/插件注册、DOM 挂载、生命周期管理     │
+ * │                                                                     │
+ * │  Adapter 不关心依赖从哪里来，只关心"已就绪的 ResolvedManifest"        │
+ * │  如何被转化成一个可运行的框架应用实例。                               │
+ * └─────────────────────────────────────────────────────────────────────┘
+ *
+ * 生命周期顺序：
+ *   supports? → createContext → prepare? → register → mount → update* → unmount
+ *
+ * 实现示例（Vue3）：
+ *   class Vue3Adapter implements Adapter<Element, App<Element>> { ... }
+ */
+import type { ResolvedManifest } from './runtime.manifest';
+/**
+ * Adapter 生命周期阶段枚举
+ * 传入 onError 钩子，用于区分错误发生的阶段
+ *
+ *   prepare  —— 预处理阶段（资源初始化、异步准备）
+ *   register —— 注册阶段（组件/插件注册）
+ *   mount    —— 挂载阶段（框架实例挂载到 DOM）
+ *   update   —— 更新阶段（props/配置热更新）
+ *   unmount  —— 卸载阶段（实例销毁、资源清理）
+ */
+export type AdapterPhase = 'prepare' | 'register' | 'mount' | 'update' | 'unmount';
+/**
+ * 错误处置策略（onError 钩子的返回值）
+ *
+ *   'abort'  —— 抛出错误，中止整个装配流程（默认值）
+ *               适用：注册必需插件失败、挂载失败等不可恢复错误
+ *
+ *   'skip'   —— 跳过当前阶段，继续下一步
+ *               适用：prepare 阶段失败（非核心准备工作）、
+ *                     非必需组件注册失败
+ *
+ *   'retry'  —— 重试当前任务的网络加载（受 maxRetries 限制，默认 1 次）
+ *               ⚠️ 重试粒度是单个任务的网络加载，不是整个生命周期阶段
+ *               ⚠️ 禁止重试整个 register 阶段（防止 app.use 等副作用重复执行）
+ *               适用：临时网络抖动导致的资源加载失败
+ */
+export type ErrorDisposition = 'abort' | 'skip' | 'retry';
+/**
+ * register 阶段的执行结果报告
+ * 返回值结构化，便于上层（Loader 或测试）断言注册情况
+ */
+export interface RegisterResult {
+    /** 成功注册的组件/插件名称列表 */
+    registered: string[];
+    /**
+     * 被跳过的组件/插件名称列表（required=false 且失败，或 conflictPolicy='replace'）
+     * 跳过不代表错误，只是本次装配中未注册
+     */
+    skipped: string[];
+    /**
+     * 注册失败的条目列表
+     * name   —— 组件/插件标识符
+     * reason —— 失败原因描述（错误消息或人类可读原因）
+     *
+     * 注意：required=true 的失败通常会在 register 阶段直接 throw，
+     *       不会进入此列表，除非 onError 返回 'skip'。
+     */
+    failed: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+/**
+ * 适配器执行上下文（贯穿整个生命周期的状态容器）
+ *
+ * 泛型参数：
+ *   TContainer —— 挂载容器类型
+ *     Web 平台：Element（HTMLElement / document.body）
+ *     Electron：BrowserWindow 或自定义 host 对象
+ *     测试环境：DocumentFragment 或 mock 对象
+ *
+ *   TInstance —— 框架应用实例类型
+ *     Vue3：App<Element>（import('vue').App）
+ *     Vue2：Vue 构造函数实例
+ *     React：Root（ReactDOM.createRoot 返回值）
+ *     未初始化时为 undefined（prepare 阶段前）
+ *
+ * 生命周期中的状态变化：
+ *   createContext → instance=undefined
+ *   prepare       → instance 可能被赋值（框架初始化）
+ *   register      → instance 完成插件注册（app.use / app.component）
+ *   mount         → instance 挂载到 container（app.mount(container)）
+ *   update        → instance 响应 props 变化
+ *   unmount       → instance.unmount()，实例置为 undefined
+ */
+export interface AdapterContext<TContainer = unknown, TInstance = unknown> {
+    /** 合并后的完整 manifest，提供所有配置信息 */
+    manifest: ResolvedManifest;
+    /**
+     * 目标挂载容器。
+     * Web 场景：document.getElementById('app') 返回的 Element
+     * Adapter 在 mount 阶段将框架实例挂载到此容器上。
+     */
+    container: TContainer;
+    /**
+     * 平台框架应用实例（可选，由 prepare/register 阶段赋值）。
+     * 类型参数 TInstance 可具体化为对应框架的实例类型，
+     * 避免在实现中进行不安全的类型断言。
+     */
+    instance?: TInstance;
+}
+/**
+ * 平台执行器接口：消费 ResolvedManifest，完成框架装配与挂载
+ *
+ * 泛型参数与 AdapterContext 一致：
+ *   TContainer —— 挂载容器类型
+ *   TInstance  —— 框架应用实例类型
+ *
+ * 实现约定：
+ *   1. supports() 必须实现，用于多 Adapter 场景下的路由选择
+ *   2. createContext() 必须实现，是其他方法的前置条件
+ *   3. register() 必须实现，是注册组件的核心阶段
+ *   4. mount() 可选（某些场景由外部控制挂载时机）
+ *   5. prepare / update / unmount / onError 均可选
+ *
+ * 注册顺序（register 阶段内部）：
+ *   components.registry（静态，最先）
+ *     → components.adapters（按 dependencies 拓扑排序后顺序执行）
+ *     → conflictPolicy 处理同名冲突
+ */
+export interface Adapter<TContainer = unknown, TInstance = unknown> {
+    /**
+     * 判断当前适配器是否支持目标 manifest
+     *
+     * 典型检查项：
+     *   - manifest.runtime.engine.platform === 'web'
+     *   - manifest.runtime.engine.runtime  === 'vue3'
+     *   - manifest.runtime.engine.version  满足适配器要求的最低版本
+     *
+     * 多 Adapter 场景下（如同时注册 Vue3Adapter / ReactAdapter），
+     * Loader 遍历 adapters 列表，选择第一个 supports() 返回 true 的 Adapter。
+     */
+    supports(manifest: ResolvedManifest): boolean;
+    /**
+     * 创建执行上下文
+     *
+     * 此阶段应只做轻量的同步初始化（分配内存、设置初始状态），
+     * 不发起网络请求，不创建框架实例（在 prepare 中进行）。
+     *
+     * 返回的 ctx 对象贯穿整个生命周期，所有阶段共享同一个引用。
+     */
+    createContext(manifest: ResolvedManifest, container: TContainer): AdapterContext<TContainer, TInstance>;
+    /**
+     * 预处理阶段（可选）
+     *
+     * 适用场景：
+     *   - 创建框架应用实例（Vue: createApp / React: createRoot）
+     *   - 异步加载非 external 的内部资源（主题、图标字体）
+     *   - 建立与宿主环境的通信通道
+     *
+     * 失败处理：
+     *   prepare 失败通常不致命，onError 可返回 'skip' 继续 register。
+     *   若框架实例创建失败，则应返回 'abort'（无法继续注册）。
+     */
+    prepare?(ctx: AdapterContext<TContainer, TInstance>): Promise<void>;
+    /**
+     * 注册阶段（必须实现）
+     *
+     * 核心职责：
+     *   1. 按 components.registry 静态注册表注册组件（优先级最高）
+     *   2. 按 components.adapters 列表（拓扑排序后）注册插件/组件
+     *   3. 处理同名冲突（按 components.conflictPolicy）
+     *   4. 返回 RegisterResult 报告注册情况
+     *
+     * 注意：
+     *   - registry 与 adapters 同名冲突：registry 优先，记录 warning
+     *   - required=true 的注册失败：应直接 throw（不进入 failed 列表）
+     *   - required=false 的注册失败：进入 skipped 列表，继续执行
+     */
+    register(ctx: AdapterContext<TContainer, TInstance>): Promise<RegisterResult>;
+    /**
+     * 挂载阶段（可选，大多数场景需要实现）
+     *
+     * 将框架实例挂载到 ctx.container（Vue: app.mount(container)）。
+     * 可选的原因：某些微前端场景由宿主统一控制挂载时机。
+     *
+     * 失败处理：mount 失败通常是致命的，onError 默认返回 'abort'。
+     */
+    mount?(ctx: AdapterContext<TContainer, TInstance>): Promise<void>;
+    /**
+     * 更新阶段（可选，热更新/动态配置场景使用）
+     *
+     * 适用场景：
+     *   - 宿主下发新的运行配置（如切换主题、更新 locale）
+     *   - 微前端框架调用子应用更新 props
+     *
+     * 实现建议：通过 provide/inject 或全局 store 传递 props，
+     *           避免销毁重建实例（开销大，破坏状态）。
+     */
+    update?(ctx: AdapterContext<TContainer, TInstance>, props: unknown): Promise<void>;
+    /**
+     * 卸载阶段（可选）
+     *
+     * 职责：
+     *   - 调用框架实例的卸载方法（Vue: app.unmount()）
+     *   - 清理事件监听器、定时器等副作用
+     *   - 将 ctx.instance 置为 undefined
+     *
+     * 微前端场景（子应用切换）必须实现此方法，防止内存泄漏。
+     */
+    unmount?(ctx: AdapterContext<TContainer, TInstance>): Promise<void>;
+    /**
+     * 错误处理钩子（可选）
+     *
+     * 在各生命周期阶段抛出错误时被调用，返回错误处置策略。
+     * 未实现时默认返回 'abort'（中止整个装配流程）。
+     *
+     * 推荐实现：
+     *   onError(phase, err, ctx) {
+     *     if (phase === 'prepare') return 'skip'    // prepare 失败可跳过
+     *     if (phase === 'update')  return 'skip'    // 热更新失败不影响运行
+     *     return 'abort'                            // 其他阶段失败中止
+     *   }
+     *
+     * retry 注意事项：
+     *   - 重试粒度为单个任务的网络加载（script / import()），
+     *     不重试整个阶段（防止 app.use 等副作用重复执行）
+     *   - 受 LoaderOptions.maxRetries 限制（默认 1 次）
+     *   - 超过重试次数仍失败 → 降级为 'abort'
+     */
+    onError?(phase: AdapterPhase, err: Error, ctx: AdapterContext<TContainer, TInstance>): ErrorDisposition;
+}