@axewo/fin-micro 0.0.0-stage → 1.0.0

package/dist/types/iframe/index.d.ts

@@ -0,0 +1,77 @@
+/** 独立跨窗口 RPC；不导入 Vue，不自动序列化 AppBridge、导航或函数守卫。 */
+export type IframeRpcErrorCode = 'TIMEOUT' | 'CANCELLED' | 'DISPOSED' | 'LIMIT_EXCEEDED' | 'UNKNOWN_METHOD' | 'HANDLER_FAILED' | 'SERIALIZATION_FAILED';
+/** 公开错误只包含稳定错误码，不传递远端堆栈、cause 或业务消息。 */
+export declare class IframeRpcError extends Error {
+    readonly code: IframeRpcErrorCode;
+    constructor(code: IframeRpcErrorCode);
+}
+export interface IframeRequestOptions {
+    /** 本次请求超时毫秒数，覆盖连接默认值；必须为不超过 2^31−1 的有限正数。 */
+    timeoutMs?: number;
+    /** 预取消时不发送请求；发送后取消会通知对端，但不保证业务副作用回滚。 */
+    signal?: AbortSignal;
+}
+export interface IframeHandlerContext {
+    /** 请求取消、入站超时或连接释放时触发；handler 需自行协作停止异步工作。 */
+    readonly signal: AbortSignal;
+}
+/** 参数和成功结果均须支持 structured clone；异常仅映射为稳定错误码，不跨窗口透传。 */
+export type IframeRpcHandler = (args: unknown[], context: IframeHandlerContext) => unknown | Promise<unknown>;
+export interface IframeRpc {
+    /**
+     * 调用对端显式开放的方法；方法名为 1 至 128 字符，参数必须为可结构化克隆的数组。
+     * @returns 对端结果；泛型 T 仅为调用方类型声明，不提供运行时结果校验。
+     * @throws Promise 拒绝：参数非法为 TypeError；超时、取消、释放、限额及远端失败为 IframeRpcError。
+     */
+    request<T = unknown>(method: string, args: unknown[], options?: IframeRequestOptions): Promise<T>;
+    /**
+     * 注册一个方法的唯一 handler；方法名为 1 至 128 字符。
+     * @returns 本次注册专属的幂等注销函数；不取消已经开始执行的请求。
+     * @throws 方法非法、重复注册或 handler 非函数时抛 TypeError；连接释放后抛 IframeRpcError。
+     */
+    expose(method: string, handler: IframeRpcHandler): () => void;
+    /** 清理本端 pending/监听与入站 signal；无断连握手，对端尚在等待本端响应的请求由其 timeout 兜底。 */
+    dispose(): void;
+}
+export interface IframeRpcOptions {
+    /** 显式传入窗口，模块本身不访问全局 window。 */
+    localWindow: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+    /** 固定的对端窗口；接收时同时核对 event.source，不能仅凭 origin 接受同源其他窗口。 */
+    remoteWindow: Pick<Window, 'postMessage'>;
+    /** 必须为精确 HTTP(S) origin，不接受 *、null、路径、query 或 hash。 */
+    remoteOrigin: string;
+    /** 双方约定的通道名，长度为 1 至 128 字符。 */
+    channel: string;
+    /** 双方预先共享，每次连接生命周期使用新的 sessionId；不是认证密钥。 */
+    sessionId: string;
+    /** 出站默认超时毫秒数，默认 30000；必须为不超过 2^31−1 的有限正数。 */
+    timeoutMs?: number;
+    /** 入站 handler 最长期限，默认使用 timeoutMs；到期 abort 并回收槽位，不强制终止用户 Promise。 */
+    handlerTimeoutMs?: number;
+    /** 同时限制出站 pending 与入站执行；默认 100。防重放高水位为常量空间。 */
+    maxPending?: number;
+}
+/**
+ * 双方都需显式配置 source/origin/channel/sessionId，无自动发现或通配握手。
+ * 同一窗口对/channel/session 只创建一对端点；requestId 为单调递增的正安全整数十进制字符串，重复或旧序号忽略。
+ * 取消仅通知 handler 的 signal；忽略 signal 的业务副作用不会自动回滚。
+ * @param options 可信窗口引用、精确来源、共享通道/会话及超时/并发限制；不会自动开放任何方法。
+ * @returns 已监听 message 的独立端点；持有方必须调用 dispose 清理监听、定时器及待处理请求。
+ * @throws origin、标识、超时或数量限制非法时抛 TypeError；窗口适配器的监听注册异常原样抛出。
+ * @remarks source/origin 校验只约束窗口身份，不等同于业务授权；expose 的 handler 仍须校验参数与权限。
+ */
+export declare function createIframeRpc(options: IframeRpcOptions): IframeRpc;
+/**
+ * 仅暴露宿主明确允许的能力名；bridge 必须由宿主可信闭包选定，不读取消息中的 appId。
+ * 子端通过 rpc.request(name, args) 调用。不是 AppBridge 的透明远程代理。
+ * @param rpc 注册宿主能力的端点，应已绑定可信的子窗口和会话。
+ * @param bridge 宿主预先绑定身份的桥接实例；入站取消 signal 会传递给能力调用。
+ * @param allowedNames 明确允许远程调用的能力名；重复名称只注册一次，不默认开放令牌等敏感能力。
+ * @returns 幂等注销所有本次注册方法的函数；部分注册失败时先回滚已注册方法，再原样抛错。
+ * @throws rpc.expose 的非法名称、重复注册或连接释放等异常原样抛出。
+ */
+export declare function exposeHostCapabilities(rpc: IframeRpc, bridge: {
+    callHostWithOptions(name: string, options: {
+        signal?: AbortSignal;
+    }, ...args: any[]): Promise<unknown>;
+}, allowedNames: readonly string[]): () => void;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+/** 全集入口，包含 Vue 适配器及其运行时依赖；非 Vue 子应用应从 /sdk 导入纯 TypeScript 协议。 */
+export * from './sdk';
+export * from './core';
+export * from './runtime';
+export * from './vue';
+export * from './browser';

package/dist/types/runtime/index.d.ts

@@ -0,0 +1,21 @@
+import { MicroHost } from '../core';
+export { setupWujieLifecycle, isMicroFrontend } from './lifecycle';
+export type { WujieLifecycleOptions } from './lifecycle';
+/** 应用级运行时接口；只管理挂载实例，不拥有页签状态或页面缓存。所有操作使用 Promise 报告失败。 */
+export interface MicroRuntime {
+    /** 挂载 appId 到 element；同应用同容器复用 ready，容器冲突/未知应用/已销毁/加载失败时拒绝。 */
+    mount(appId: string, element: HTMLElement): Promise<void>;
+    /** 中断挂起加载并卸载 appId；不存在时成功，重复卸载复用同一 Promise。 */
+    unmount(appId: string): Promise<void>;
+    /** 禁止新挂载并等待全部实例清理；重复调用复用结果，任一失败在全部清理结束后拒绝。不销毁 host。 */
+    dispose(): Promise<void>;
+}
+export interface WujieRuntimeOptions {
+    /** 单次挂载等待上限（毫秒），默认 30000；有效范围为 (0, 2147483647]。 */
+    mountTimeoutMs?: number;
+}
+/**
+ * 为 host 创建 Wujie 运行时；Wujie 仅首次 mount 时动态加载，导入入口不会访问 DOM。
+ * 同应用清理串行执行；每次尝试使用独立沙箱名，迟到的启动/销毁不能操作新实例。
+ */
+export declare function createWujieRuntime(host: Pick<MicroHost, 'apps' | 'bridge'>, options?: WujieRuntimeOptions): MicroRuntime;

package/dist/types/runtime/lifecycle.d.ts

@@ -0,0 +1,23 @@
+/** Wujie 与独立运行共用的应用生命周期。 */
+export interface WujieLifecycleOptions {
+    /** 初始化应用；允许同步完成或返回 Promise，同一轮重复挂载复用结果。 */
+    mount(): void | Promise<void>;
+    /** 释放本轮资源；必须同步失效 bootstrap 自身的 generation，阻止异步初始化晚到后挂载。 */
+    unmount(): void | Promise<void>;
+}
+/**
+ * 判断当前窗口是否处于本库支持的 Wujie 微前端运行环境。
+ * @returns 存在有效的 Wujie 宿主挂载入口时为 true；独立运行、SSR 为 false。
+ * 不通过 top/self 或自注册的 __WUJIE_MOUNT 判断，避免把普通 iframe 或独立应用误判。
+ * 这只是环境标识，不保证 bridge 已连接，不代表登录或业务授权，也不用于安全校验。
+ */
+export declare function isMicroFrontend(): boolean;
+/**
+ * 注册 Wujie 全局回调和 unload 清理；嵌入时通知 Wujie，独立时自动挂载。
+ * 重复 setup 释放旧注册；返回的 dispose 幂等，可交给 import.meta.hot.dispose。
+ * 错误通过 console.error 报告（Wujie 可能忽略返回值），显式全局调用也可等待 Promise 接收失败。
+ * 卸载不等待挂起的 mount；新挂载等待上轮 unmount，旧 mount 的迟到结果不再触发清理。
+ * bootstrap 必须自行取消旧初始化（含其内部 catch/重试），本封装不能撤销回调内部的副作用。
+ * 无 window 时不注册、不挂载，返回可安全调用的空清理函数。
+ */
+export declare function setupWujieLifecycle(options: WujieLifecycleOptions): () => Promise<void>;

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

@@ -0,0 +1,338 @@
+/** 框架无关的子应用协议：无 Vue、Wujie、core 运行时依赖；不提供页面缓存或跨窗口 RPC。 */
+/** 递归菜单；分组只配置 children，可导航叶节点只配置 target，menuId 在同一应用内唯一。 */
+export interface MicroMenu {
+    /** 应用内菜单标识；不同应用可以使用相同标识。 */
+    menuId: string;
+    /** 菜单展示名称，同时作为入口页签的默认标题。 */
+    name: string;
+    /** 子菜单；分组不允许同时配置 target。 */
+    children?: readonly MicroMenu[];
+    /** 入口导航信息；tabId 仍须在整个宿主唯一。 */
+    target?: {
+        tabId: string;
+        route: string;
+    };
+}
+/** 页面归属规则；只影响菜单高亮，不决定应用加载、页签身份或访问权限。 */
+export interface MicroMenuRoute {
+    /** 应用内路径前缀，不带 query/hash，按路径段边界进行最长匹配。 */
+    pathPrefix: string;
+    /** 该应用内可导航叶节点的 menuId。 */
+    menuId: string;
+}
+/** 宿主登记的应用元信息；entry 必须为 HTTP(S) 地址，菜单配置在创建宿主时递归复制冻结。 */
+export interface MicroApp {
+    appId: string;
+    name: string;
+    entry: string;
+    /** 可选多级菜单；不配置时保持原有无菜单导航行为。 */
+    menus?: readonly MicroMenu[];
+    /** 隐藏页面的菜单归属规则；入口 target 路径也自动参与匹配。 */
+    menuRoutes?: readonly MicroMenuRoute[];
+}
+/** 打开页面的导航元信息；tabId 在宿主内唯一，route 为应用内绝对路径，不应存放敏感信息。 */
+export interface OpenTab {
+    appId: string;
+    tabId: string;
+    title: string;
+    route: string;
+    /** 显式指定本应用的可导航叶节点；省略则按 route 自动归属，不作为权限或加载依据。 */
+    activeMenuId?: string;
+}
+/** 已打开页面；key 区分同 tabId 关闭重开后的不同生命周期。 */
+export interface MicroTab extends OpenTab {
+    readonly key: string;
+}
+/** 宿主状态快照；调用者不应修改页签数据。 */
+export interface MicroState {
+    tabs: readonly MicroTab[];
+    activeTabId: string | null;
+}
+/** 幂等取消订阅函数。 */
+export type Unsubscribe = () => void;
+/** 业务事件契约；广播与有响应的宿主函数调用相互独立。 */
+export interface BusinessEvents {
+    'record:saved': {
+        appId: string;
+        id: string;
+    };
+}
+/** 宿主生成的事件来源；不从业务负载推断身份，同窗口桥不是安全沙箱。 */
+export interface BusinessEventMetadata {
+    readonly source: 'host' | 'app';
+    readonly appId?: string;
+    readonly tabKey?: string;
+}
+/** 宿主业务事件总线；第二参数始终由宿主生成，兼容只接收负载的监听器。 */
+export interface BusinessEventBus {
+    on<K extends keyof BusinessEvents>(event: K, handler: (payload: BusinessEvents[K], metadata: BusinessEventMetadata) => void): Unsubscribe;
+    emit<K extends keyof BusinessEvents>(event: K, payload: BusinessEvents[K]): void;
+    clear(): void;
+}
+/** 单次宿主调用选项；不自动重试，不承诺撤销已经发生的业务副作用。 */
+export interface HostCallOptions {
+    /** 正有限毫秒数，最大2147483647，防止原生计时器溢出。 */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** 仅包含可公开认证与权限信息的会话；不允许携带 Token、凭据或任意扩展字段。 */
+export interface SessionInput {
+    readonly authenticated: boolean;
+    readonly user?: {
+        readonly id: string;
+        readonly name?: string;
+    };
+    readonly permissions: readonly string[];
+}
+export interface SessionSnapshot extends SessionInput {
+    readonly revision: number;
+}
+/** 当前桥可调用的能力名称仅来自注册表和应用白名单，不暴露处理器。 */
+export interface MicroProtocol {
+    readonly version: '1.0';
+    readonly capabilities: readonly string[];
+    readonly features: readonly string[];
+}
+export interface ProtocolRequirement {
+    version?: string;
+    capabilities?: readonly string[];
+}
+export interface ProtocolNegotiation {
+    readonly compatible: boolean;
+    readonly protocol: MicroProtocol;
+    readonly missingCapabilities: readonly string[];
+}
+/** 同步进程内事件总线，不承担权限验证或请求响应。 */
+export interface NotificationBus<Events extends object> {
+    /** 订阅 event；handler 接收事件负载，返回取消订阅函数。 */
+    on<K extends keyof Events>(event: K, handler: (payload: Events[K]) => void): Unsubscribe;
+    /** 同步广播 payload；本轮新增监听下次生效，取消或 clear 立即停止对应交付；监听异常传播给调用者。 */
+    emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+    /** 清空全部监听器；已有取消订阅函数仍可安全调用。 */
+    clear(): void;
+}
+/** 创建独立事件总线；无全局单例，使用方负责 clear。此低层总线原样传播同步监听异常；宿主业务 bus 才通过 onError 隔离。 */
+export declare function createNotificationBus<Events extends object>(): NotificationBus<Events>;
+/** 未提供业务契约时的宽泛默认类型；业务应用应显式指定具体函数接口。 */
+export type HostCapabilities = Record<string, (...args: any[]) => unknown>;
+/** 对具体键逐项约束为函数，兼容没有 string 索引签名的 interface。 */
+export type CapabilityContract<C> = {
+    [K in keyof C]: (...args: any[]) => unknown;
+};
+/** 从能力契约提取参数元组；不替代宿主 handler 的运行时输入校验。 */
+export type CapabilityArgs<C, K extends keyof C> = C[K] extends (...args: infer A) => unknown ? A : never;
+/** 提取并展开异步结果，确保 callHost 始终返回单层 Promise。 */
+export type CapabilityResult<C, K extends keyof C> = C[K] extends (...args: never[]) => infer R ? Awaited<R> : never;
+/** 宿主闭包生成的可信上下文；不会从子应用 payload 读取身份，不是对恶意同窗口代码的安全沙箱。 */
+export interface HostCallContext {
+    /** 发起调用的已注册应用身份。 */
+    readonly appId: string;
+    /** 超时、主动取消及上下文释放时中止；handler 应将其传给可取消业务请求。 */
+    readonly signal: AbortSignal;
+    /** 页级调用的冻结快照；应用级调用为 undefined，非当前活动页的动态引用。 */
+    readonly tab?: MicroTab;
+    /** 返回本次调用的宿主/bridge/页面是否尚有效；不表示该页是当前选中页。异步 handler 应在副作用前主动检查。 */
+    isActive(): boolean;
+}
+/** 可判别调用失败原因；handler 原始异常不会透传给子应用。 */
+export type HostCallErrorCode = 'UNKNOWN_CAPABILITY' | 'FORBIDDEN' | 'PAGE_RELEASED' | 'BRIDGE_RELEASED' | 'HOST_DISPOSED' | 'HANDLER_FAILED' | 'TIMEOUT' | 'CANCELLED';
+/** 宿主调用公开错误；不透传 handler 原始 cause、堆栈或业务敏感字段；本 Error 自身仍有正常 stack。 */
+export declare class HostCallError extends Error {
+    readonly code: HostCallErrorCode;
+    /** 使用稳定 code 与对外 message 创建错误。 */
+    constructor(code: HostCallErrorCode, message: string);
+}
+/** 页签生命周期引用；key 省略时宿主在调用瞬间捕获，不会在排队后误操作同 id 的新页面。 */
+export interface TabRef {
+    tabId: string;
+    key?: string;
+}
+/** 导航命令。signal 仅取消尚未提交的导航；已发生的业务副作用不在回滚范围内。 */
+export type NavigationOperation = 
+/** 同应用同 id 异路由时经旧页守卫原位替换为新 key；跨应用 id 冲突拒绝，同位置同路由复用。 */
+({
+    type: 'open';
+    input: OpenTab;
+} | {
+    type: 'activate' | 'refresh' | 'close';
+    target: TabRef;
+} | {
+    type: 'closeMany';
+    scope: 'all' | 'others' | 'left' | 'right';
+    anchor?: TabRef;
+    /**
+     * 从本次批量集合中排除指定生命周期；适用于宿主固定工作台等不可批量关闭入口。
+     * 调用时复制并冻结数组和引用，省略 key 时立即捕获当时存在的 key；不存在或旧 key 不匹配不排除新页面。
+     * 排除项不参与关闭确认，不会扩大页面 SDK 的应用权限；省略时完全保持原有范围选择行为。
+     */
+    exclude?: readonly TabRef[];
+} | {
+    type: 'back';
+    target?: TabRef;
+    fallback?: OpenTab;
+}) & {
+    signal?: AbortSignal;
+};
+/** 导航事务结果；affected 为实际变动的生命周期引用，拒绝、过期和无操作均为空。tab 是提交后的目标页。 */
+export interface NavigationResult {
+    status: 'committed' | 'cancelled' | 'noop' | 'stale';
+    affected: TabRef[];
+    tab?: MicroTab;
+}
+/** 离页守卫收到调用时复制的命令与被确认页。返回 false 取消整个事务；抛错统一转 GUARD_FAILED。 */
+export type BeforeLeaveGuard = (context: {
+    operation: NavigationOperation;
+    tab: MicroTab;
+}) => boolean | void | Promise<boolean | void>;
+/** 导航稳定错误码；不暴露守卫原始异常或业务敏感信息。 */
+export type NavigationErrorCode = 'INVALID_OPERATION' | 'FORBIDDEN' | 'PAGE_RELEASED' | 'HOST_DISPOSED' | 'GUARD_FAILED' | 'CANCELLED' | 'STALE';
+/** 导航异常；调用方通过 code 区分失败，不依赖中文提示文本或原始异常堆栈。 */
+export declare class NavigationError extends Error {
+    readonly code: NavigationErrorCode;
+    /** 创建公开错误。message 只包含稳定描述，不传递守卫原始 cause。 */
+    constructor(code: NavigationErrorCode, message: string);
+}
+/** 绑定某一 tab.key 的页面 SDK；页面卸载时 dispose，不能按点击瞬间的活动页重建。 */
+export interface PageSDK<C extends CapabilityContract<C> = HostCapabilities> {
+    /** 调用显式注册的 name，args 仅为业务参数；返回异步结果。未知/禁用/释放/销毁/handler异常均拒绝；不会自动取消已发生副作用。 */
+    callHost<K extends keyof C & string>(name: K, ...args: CapabilityArgs<C, K>): Promise<CapabilityResult<C, K>>;
+    /** 带超时与协作取消的调用；省略 timeoutMs 使用宿主默认值（默认30秒）。 */
+    callHostWithOptions<K extends keyof C & string>(name: K, options: HostCallOptions, ...args: CapabilityArgs<C, K>): Promise<CapabilityResult<C, K>>;
+    /** 页面存在时读取最新元信息；页签关闭后回退到该 SDK 创建时捕获的快照，而非最后一次更新快照。 */
+    readonly tab: MicroTab;
+    /** 打开 input 指定的页签并激活；返回页签，非法导航或上下文失效时拒绝。 */
+    openTab(input: OpenTab): Promise<MicroTab>;
+    /**
+     * 通过宿主策略打开并激活目标，允许显式授权的跨应用导航；不会关闭来源页。
+     * 同应用无需跨应用授权；跨应用默认拒绝，且仍检查目标页面准入与离页守卫。
+     * @param input 仅复制 OpenTab 公开字段；来源身份及生命周期由宿主在调用时捕获，不从目标参数推断。
+     * @param options signal 只取消未提交事务；取消返回 status=stale，不中断守卫业务或回滚副作用。
+     * @returns 守卫保护的串行 open 事务结果；拒绝守卫返回 cancelled，相同目标无变化返回 noop，过期返回 stale。
+     * @throws FORBIDDEN 策略拒绝；INVALID_OPERATION 参数无效；PAGE_RELEASED 来源释放或关闭重开；
+     * HOST_DISPOSED 宿主销毁；GUARD_FAILED 离页守卫异常。异常统一为公开 NavigationError，不泄漏策略原始错误。
+     * @remarks 排队及异步守卫通过后复核来源与权限；仅开放 open，不扩大 openTab/operate 权限或建立跨应用 back 来源关系。
+     */
+    navigateTo(input: OpenTab, options?: {
+        signal?: AbortSignal;
+    }): Promise<NavigationResult>;
+    /** 关闭捕获 key 的原页签。dispose 后仍允许异步保存完成关闭原页；已关闭、同 id 重开或宿主销毁返回 false。 */
+    closeCurrent(): Promise<boolean>;
+    /**
+     * 注册当前 key 的离页确认，关闭、刷新及活动页切换前串行执行。
+     * @param guard 返回 false 取消整批事务；异常统一拒绝为 GUARD_FAILED，不泄露原始业务错误。
+     * @returns 幂等取消函数；页面移除或 SDK.dispose 自动清理，不影响同 tabId 的新生命周期。
+     * @throws 页面释放或宿主销毁时同步抛错。守卫等待期间的同步写入使事务 stale，不重复确认。
+     * @remarks 守卫只执行确认、保存并返回布尔；不可 await 同宿主的 operate/openTab/navigateTo/closeCurrent 等导航，否则串行队列自等待。
+     * signal 取消会立即放行导航队列，但不会中断守卫业务 Promise、保存请求或回滚已发生的副作用。
+     */
+    beforeLeave(guard: BeforeLeaveGuard): Unsubscribe;
+    /**
+     * 原位刷新 SDK 绑定页，而非点击时的活动页，保留 tabId、标题、路由、菜单及顺序并生成新 key。
+     * @returns 守卫保护的事务结果；成功 tab 为新生命周期，旧 SDK 立即失效，但最后一页刷新不会释放应用桥。
+     * @throws 释放上下文或守卫异常时 Promise 拒绝；拒绝或 stale 时不销毁旧页面。
+     */
+    refreshCurrent(): Promise<NavigationResult>;
+    /**
+     * 原子关闭本页并激活仍存活的来源 key；来源仅保存在当前宿主内存，不写持久化快照。
+     * @param fallback 来源不存在时可打开的本应用入口；省略时按当前位置选择本应用邻页，最后一页可关闭为空。
+     * @returns 单次发布的事务结果；不调用 history.back，不跨应用激活来源，不会重新确认过期意图。
+     * @throws 跨应用 fallback、已释放 SDK 或守卫异常时拒绝，状态保持原样。
+     */
+    back(fallback?: OpenTab): Promise<NavigationResult>;
+    /**
+     * 在当前应用范围内发起异步导航；目标 key、批量集合及调用来源在调用时复制捕获。
+     * @param operation 导航命令。closeMany 默认只选择本应用，跨应用目标拒绝；全局批量操作仅宿主可执行。
+     * @returns 串行事务结果；守卫全部通过后仅发布一次，cancelled、noop、stale 的 affected 为空。
+     * @throws 参数非法、越权、SDK 释放或守卫异常时拒绝；dispose 后仅 closeCurrent 是允许的写操作。
+     */
+    operate(operation: NavigationOperation): Promise<NavigationResult>;
+    /** 同步广播事件；上下文释放时抛错，payload 不提供可信身份保证，来源应读取 handler 第二参数。 */
+    emit<K extends keyof BusinessEvents>(event: K, payload: BusinessEvents[K]): void;
+    /** 订阅业务事件并返回取消函数；页面释放自动清理，失效上下文抛错。 */
+    on<K extends keyof BusinessEvents>(event: K, handler: (payload: BusinessEvents[K], metadata: BusinessEventMetadata) => void): Unsubscribe;
+    /** 幂等释放本 SDK 与订阅；不关闭页签，closeCurrent 是释放后的唯一写操作特例。 */
+    dispose(): void;
+}
+/** 宿主注入某应用的进程内桥；默认拒绝未注册能力，白名单是工程约束而非安全隔离。 */
+export interface AppBridge<C extends CapabilityContract<C> = HostCapabilities> {
+    /** 应用级能力调用，context 无 tab；返回 Promise，错误规则同 PageSDK.callHost。 */
+    callHost<K extends keyof C & string>(name: K, ...args: CapabilityArgs<C, K>): Promise<CapabilityResult<C, K>>;
+    /** 带超时与协作取消的调用；省略 timeoutMs 使用宿主默认值（默认30秒）。 */
+    callHostWithOptions<K extends keyof C & string>(name: K, options: HostCallOptions, ...args: CapabilityArgs<C, K>): Promise<CapabilityResult<C, K>>;
+    /** 返回当前桥的版本与已授权能力；释放后抛错。 */
+    protocol(): MicroProtocol;
+    /** 精确版本匹配与必需能力检查；不自动降级或调用能力。 */
+    negotiate(requirement?: ProtocolRequirement): ProtocolNegotiation;
+    /** 读取不含凭据的冻结会话快照；释放后抛错。 */
+    getSession(): SessionSnapshot;
+    /** 立即重放当前会话，后续更新同步通知；异常通过宿主 onError 隔离，释放自动取消。 */
+    subscribeSession(handler: (session: SessionSnapshot) => void): Unsubscribe;
+    /** 宿主绑定的应用标识。 */
+    readonly appId: string;
+    /** 返回宿主导航快照；不返回宿主对象、处理器或配置。 */
+    getState(): MicroState;
+    /** 订阅宿主状态，返回取消函数；最后应用页关闭或宿主销毁时自动释放，旧桥订阅抛错。 */
+    subscribe(handler: (state: MicroState) => void): Unsubscribe;
+    /** 通过本应用 tabId 绑定当前生命周期；不存在或跨应用时抛错。 */
+    bindPage(tabId: string): PageSDK<C>;
+    /** 通过稳定 tabKey 绑定页面；旧 key、跨应用、已释放桥或宿主销毁时抛错。 */
+    page(tabKey: string): PageSDK<C>;
+    /** 立即同步本应用活动页并持续通知 navigate，返回取消函数；首次回调异常传播，后续通知异常由宿主 onError 隔离，加载前导航不会丢失。 */
+    ready(navigate: (tab: MicroTab) => void): Unsubscribe;
+}
+/** Token 只通过按需能力返回，绝不写入公开会话或广播。null 表示已登录的 Cookie 模式。 */
+export type TokenResult = {
+    status: 'authenticated';
+    token: string | null;
+} | {
+    status: 'unauthenticated' | 'session-changed';
+};
+export interface TokenCapabilities {
+    getToken(): TokenResult | Promise<TokenResult>;
+}
+export type TokenErrorCode = 'NO_BRIDGE' | 'UNAUTHENTICATED' | 'SESSION_CHANGED' | 'INVALID_RESULT';
+/** 公开错误不包含后台返回值、凭据或原始 cause。 */
+export declare class TokenError extends Error {
+    readonly code: TokenErrorCode;
+    constructor(code: TokenErrorCode);
+}
+/**
+ * 按需通过宿主能力读取最新凭据，不缓存、不刷新、不持久化，也不自动重放业务请求。
+ * @param options bridge 为当前挂载的应用桥；省略时读取当前 Wujie 注入桥，独立运行不会创建假宿主。
+ * signal 将取消传入现有 RPC；timeoutMs 沿用宿主调用的正有限毫秒约定。
+ * @returns 最新 Token；null 仅表示已登录但使用 Cookie 等不暴露 Token 的认证方式。
+ * @throws TokenError：无桥、未认证、会话在读取期间变化或返回格式无效。
+ * HostCallError：能力未注册/未授权、超时、取消及上下文释放；不把失败降级为无凭据请求。
+ * @remarks 只向可信 API 使用返回值，不输出日志、放入 URL、公开会话或广播。
+ */
+export declare function getToken(options?: HostCallOptions & {
+    bridge?: AppBridge<TokenCapabilities>;
+}): Promise<string | null>;
+/**
+ * 构造基座 getToken 能力配置，复用 core 白名单与调用生命周期，不建立第二套 RPC。
+ * @param options apps 为完全可信应用的显式白名单，复制后冻结；空数组不授权任何应用。
+ * getSession 每次返回当前认证状态与 revision，登录、退出、用户切换及凭据更新必须递增版本；
+ * provider 接收宿主生成的 appId/signal，可读取私有内存或调用可取消后台，不能缓存初始 Token。
+ * @returns 可直接注册到 capabilities.getToken 的 apps/handler；Cookie 模式允许 provider 返回 null。
+ * @throws provider 异常、非法 Token 或越权直接调用 handler 时拒绝；经过 core 调用时统一脱敏。
+ * @remarks 异步后复查会话版本、认证和调用存活，退出或切换不交付旧凭据；
+ * 已交付的 Token 无法撤回，服务端仍须鉴权。同窗口白名单不构成恶意代码隔离沙箱。
+ */
+export declare function createTokenCapability(options: {
+    apps: readonly string[];
+    getSession(): SessionSnapshot;
+    provider(context: HostCallContext): string | null | Promise<string | null>;
+}): {
+    apps: readonly string[];
+    handler(context: HostCallContext): Promise<TokenResult>;
+};
+/** Wujie 注入约定；可显式传入测试窗口，SDK 本身不导入 Wujie。 */
+export interface MicroWindow extends Window {
+    $wujie?: {
+        props?: {
+            finMicro?: AppBridge;
+        };
+    };
+}
+/** 获取 target 上的桥；默认浏览器 window，独立运行或 Node/SSR 无 window 时返回 undefined，不创建宿主。 */
+export declare function getMicroBridge<C extends CapabilityContract<C> = HostCapabilities>(target?: MicroWindow): AppBridge<C> | undefined;

package/dist/types/vue/index.d.ts

@@ -0,0 +1,91 @@
+import { PropType } from 'vue';
+import { MicroHost } from '../core';
+import { MicroRuntime } from '../runtime';
+import { AppBridge, MicroTab, PageSDK, CapabilityContract } from '../sdk';
+export { useMicroTab } from './tab-context';
+export { MicroRouteView, type MicroRouteErrorCode } from './router-view';
+/** 应用共享容器：appId 对应一个 runtime 实例；挂载失败显示错误，组件卸载触发异步 unmount。不是页级缓存组件，不应在每次切 tab 时销毁。 */
+export declare const MicroAppContainer: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    appId: {
+        type: StringConstructor;
+        required: true;
+    };
+    runtime: {
+        type: PropType<MicroRuntime>;
+        required: true;
+    };
+    retryDisabled: BooleanConstructor;
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    appId: {
+        type: StringConstructor;
+        required: true;
+    };
+    runtime: {
+        type: PropType<MicroRuntime>;
+        required: true;
+    };
+    retryDisabled: BooleanConstructor;
+}>> & Readonly<{}>, {
+    retryDisabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+/** 在 Vue setup 中订阅 host 导航状态，返回 shallowRef；卸载自动取消，已销毁宿主订阅抛错。只依赖状态接口，不限制业务能力泛型。 */
+export declare function useMicroHost(host: Pick<MicroHost, 'getState' | 'subscribe'>): import('vue').ShallowRef<import('..').MicroState, import('..').MicroState>;
+/**
+ * 页签级页面缓存。tabs 为本应用仍打开的页签，activeKey 为当前展示的 key；默认最多保留 20 页。
+ * 仅激活过的页签创建组件，切换触发 Vue activated/deactivated；关闭或 LRU 淘汰触发真正卸载，
+ * useMicroPage 因而释放 SDK。LRU 永不淘汰活动页，超限后再访问会重建页面，不关闭宿主页签。
+ * 默认插槽接收创建时的 tab；路由页面必须提供该 tab 的独立路由上下文，不能直接读全局活动路由。
+ * 同一 key 的 route 被视为页面创建快照；需要清除本页缓存时使用 SDK.refreshCurrent 或宿主 operate(refresh)，由 core 原位生成新 key。
+ * 缓存本身不执行离页守卫：导航确认由 core 事务负责；LRU 淘汰和组件树卸载不会等待 beforeLeave。
+ * 未保存业务数据不能仅依赖此内存缓存，重要草稿应由业务层另外持久化，整页刷新不会恢复组件实例。
+ */
+export declare const MicroTabCache: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    tabs: {
+        type: PropType<readonly MicroTab[]>;
+        required: true;
+    };
+    activeKey: StringConstructor;
+    max: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>[], {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    tabs: {
+        type: PropType<readonly MicroTab[]>;
+        required: true;
+    };
+    activeKey: StringConstructor;
+    max: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>> & Readonly<{}>, {
+    max: number;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+/** 最小路由适配契约；Vue Router 可直接适配，页面缓存可使用 MicroTabCache。 */
+export interface RouteAdapter {
+    /** 将应用内 route 应用到路由器，可使用 tab.key 关联页面身份；返回导航完成 Promise，拒绝交给 onError。 */
+    replace(route: string, tab?: MicroTab): Promise<unknown>;
+}
+/**
+ * 连接 bridge 与 router，立即读取最新活动页，避免子应用加载期间丢失导航。
+ * @param bridge 已注册应用桥，保留业务能力泛型。
+ * @param router 异步 replace 适配器；串行应用最新导航，不并发覆盖路由。
+ * @param onError 导航错误回调，默认 console.error；桥初始化错误直接抛出。
+ * @returns 停止订阅函数；不会取消已经进入 router.replace 的导航，也不实现页面缓存。
+ */
+export declare function connectMicroRouter<C extends CapabilityContract<C>>(bridge: AppBridge<C>, router: RouteAdapter, onError?: (error: unknown) => void): () => void;
+/**
+ * 在页面 setup 中按固定 tab.key 创建强类型 SDK，并随页面真正卸载自动 dispose。
+ * @param bridge 由宿主注入且属于当前应用的有效桥，不应在业务代码中伪造或跨应用共享。
+ * @param tab 缓存边界注入的页面身份快照；每个页面实例仅绑定一次，不能随活动页切换重建。
+ * @returns 页面级能力、导航和业务事件接口；非法、跨应用或已释放 key 在创建时抛错。
+ * @remarks 缓存停用不释放 SDK，故非活动脏页仍能参与批量关闭确认；关闭、刷新、LRU 淘汰均会真正卸载。
+ * dispose 会注销该 SDK 的事件及离页守卫，但不会关闭页签；卸载后的异步保存仍可调用 closeCurrent，
+ * 该特例始终使用原 key，不会关闭同 tabId 重开的页面。其余失效 SDK 操作不得继续提交。
+ */
+export declare function useMicroPage<C extends CapabilityContract<C>>(bridge: AppBridge<C>, tab: MicroTab): PageSDK<C>;

package/dist/types/vue/router-view-impl.d.ts

@@ -0,0 +1,41 @@
+import { SlotsType } from 'vue';
+import { MicroTab } from '../sdk';
+import { MicroRouteErrorCode } from './router-view';
+/**
+ * 页签内的 Vue Router 页面出口，必须位于 MicroTabCache 内，并已通过 app.use(router) 安装 Vue Router 4.5+。
+ * 固定使用创建时的 tab.key/route；支持路由 props、嵌套 RouterView、命名视图及 useRoute 独立上下文。
+ * loading 插槽接收 { tab }，error 插槽接收 { tab, code, retry }；不提供插槽时也会展示加载/错误与重试。
+ *
+ * 这里只解析与加载页面，不启动导航事务、不执行 Vue Router 导航守卫、不修改宿主页签和权限。
+ * redirect 不替代宿主 canOpen；业务必须保证重定向目标属于该应用已授权页面，鉴权仍由宿主/core 负责。
+ * 页面定位等价于从 START_LOCATION 发起解析：相对 redirect 以应用根为基准，函数 redirect 的 from 为 START_LOCATION。
+ * 建议 redirect 使用绝对 path 或 name；不会把其他页签的全局 currentRoute 当作本页的导航来源。
+ * 页面跳转和离页确认应使用页面 SDK；不要通过 RouterLink/router.push 把全局路由当作宿主页签导航。
+ * 懒加载无法取消网络请求；卸载后忽略迟到结果，不再写入组件状态。模块加载后的组件 setup/render 异常由 Vue 错误边界处理。
+ */
+export declare const MicroRouteViewImpl: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    name: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}> | import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>[], {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    name: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    name: string;
+}, SlotsType<{
+    loading: {
+        tab: MicroTab;
+    };
+    error: {
+        tab: MicroTab;
+        code: MicroRouteErrorCode;
+        retry: () => Promise<void>;
+    };
+}>, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/types/vue/router-view.d.ts

@@ -0,0 +1,42 @@
+import { SlotsType } from 'vue';
+import { MicroTab } from '../sdk';
+/** 稳定的脱敏错误分类；不包含模块地址、原始异常消息或堆栈。 */
+export type MicroRouteErrorCode = 'NOT_FOUND' | 'LOAD_FAILED' | 'REDIRECT_LOOP' | 'RESOLVE_FAILED';
+/**
+ * 固定页签的 Vue Router 页面出口，需放在 MicroTabCache 内，并已安装 Vue Router 4.5+。
+ * name 指定命名视图，默认 default；loading 插槽接收 { tab }，error 接收 { tab, code, retry }。
+ * 不提供插槽时仍显示加载、错误和重试按钮；retry 返回 Promise<void>，重复点击不会并发加载。
+ *
+ * 仅实际渲染本组件时才动态加载路由实现；旧的 /vue 缓存和 SDK 用户不必安装可选 vue-router peer。
+ * 内部组件以同步 setup 注入固定 tab 和路由上下文，不依赖 async setup 或 Suspense。
+ * 页面只解析与加载，不执行 router.push/replace 或导航守卫；导航、canOpen 和离页确认仍由宿主/core/SDK负责。
+ * redirect 不替代 canOpen，也不会更改宿主 tab.route；相对 redirect 与函数 from 均以 START_LOCATION 为来源。
+ * 支持 Composition API useRoute 的独立快照；Options API this.$route / 模板 $route 仍读全局路由，不支持页签隔离。
+ * 懒加载请求不可取消，卸载后忽略迟到结果；组件 setup/render 异常交由 Vue 错误边界处理。
+ */
+export declare const MicroRouteView: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    name: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}> | import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>[], {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    name: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    name: string;
+}, SlotsType<{
+    loading: {
+        tab: MicroTab;
+    };
+    error: {
+        tab: MicroTab;
+        code: MicroRouteErrorCode;
+        retry: () => Promise<void>;
+    };
+}>, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;