webloom-framework 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-import { P as PluginExecution, a as PluginManifest, b as PluginGraph, c as PluginDependency, d as PluginReverseDep, M as MessageBus, L as LifecycleScope, e as LifecycleScopeIdentity, f as PluginPermission, g as PermissionLease, S as ScopedTaskScheduler, C as CreateUpgradeGateOptions, U as UpgradeGate, R as RemoteServiceHandshake, h as RemoteServiceSnapshot, i as RemoteServiceMessageCodec } from './createPluginHost-CcW9sPNs.js';
-export { j as CapabilityRegistry, k as ContextExtensionInput, l as ContributionAdapter, m as ContributionAdapterInput, n as ContributionHandle, o as CreatePluginHostOptions, D as DispatchOptions, E as EventHandler, H as HandlerOptions, p as HostListener, q as LIFECYCLE_ERROR_TEXT, r as LifecycleCleanup, s as LifecycleCleanupIssue, t as LifecycleCleanupPhase, u as LifecycleDisposeOptions, v as LifecycleDisposeResult, w as LifecycleResourceHandle, x as LifecycleResourceSnapshot, y as LifecycleScopeKind, z as LifecycleScopeRevokedError, A as LifecycleScopeState, B as Message, F as MessageBusSnapshot, G as MessageHandler, I as MessageMode, O as OwnedResourceDefinition, J as PermissionDeniedError, K as PermissionLeaseBinding, N as PermissionLeaseBindingExpectation, Q as PermissionLeaseRevokedError, T as PermissionPolicyInput, V as PermissionPolicyResult, W as PluginAttributes, X as PluginConfig, Y as PluginConfigStore, Z as PluginContext, _ as PluginContextExtension, $ as PluginContribution, a0 as PluginHost, a1 as PluginIntentCommand, a2 as PluginIntentCommandResult, a3 as PluginIntentController, a4 as PluginIntentCoordinator, a5 as PluginIntentSnapshot, a6 as PluginIntentSubmissionResult, a7 as PluginLifecycleState, a8 as PluginLifetime, a9 as PluginMeta, aa as PluginSetup, ab as PluginStartupMode, ac as PluginState, ad as PluginStateKind, ae as PluginTeardown, af as PluginUnitGraph, ag as PluginUnitState, ah as PublishOptions, ai as RESOURCE_OWNER, aj as RESOURCE_REGISTRY_CAPABILITY, ak as RUNTIME_MESSAGE_BUS, al as RemoteServiceBridge, am as RemoteServiceBridgeState, an as RemoteServiceCallContext, ao as RemoteServiceLookup, ap as RemoteServiceMessageKind, aq as RemoteServicePortControlMessage, ar as RemoteServiceProxy, as as RemoteServiceReference, at as RemoteServiceSnapshotResult, au as RemoteServiceTransport, av as RemoteServiceUnavailableError, aw as RequestOptions, ax as ResourceContext, ay as ResourceDefinition, az as ResourceKey, aA as ResourceRegistry, aB as ResourceSnapshot, aC as ResourceStatus, aD as ResourceStoreApi, aE as RuntimeUnitDependency, aF as RuntimeUnitDescriptor, aG as RuntimeUnitImplementationRegistry, aH as RuntimeUnitSnapshot, aI as SCOPED_TASK_SCHEDULER_CAPABILITY, aJ as ScopeResolution, aK as ScopeResolver, aL as ScopeResolverInput, aM as ScopedTaskDefinition, aN as ScopedTaskSnapshot, aO as StartupCapabilityError, aP as StartupCapabilityErrorDetails, aQ as StartupPluginError, aR as StartupPluginErrorDetails, aS as UpgradeDrainResult, aT as UpgradeGateRejectedError, aU as UpgradeGateState, aV as UpgradeHandshake, aW as UpgradeHandshakeResult, aX as UpgradeIoLease, aY as UpgradeMode, aZ as UpgradeSession, a_ as createCapabilityRegistry, a$ as createInMemoryPluginConfigStore, b0 as createPluginHost, b1 as createRemoteServiceMessageCodec, b2 as createResourceStore, b3 as defineRuntimeUnitDependencies, b4 as defineRuntimeUnitProvidedContracts, b5 as lifecycleErrorText, b6 as runtimeCapabilityContractVersion } from './createPluginHost-CcW9sPNs.js';
-import { R as RemoteServicePortCallMessage } from './resourceRegistry-BAnqKcp7.js';
-export { C as CreateMessagePortServiceTransportOptions, a as CreatePluginIntentControllerOptions, b as CreateResourceScopeOptions, c as CreateServiceBridgeOptions, d as RemoteServicePortCancelMessage, e as RemoteServicePortErrorMessage, f as RemoteServicePortResponseMessage, g as RemoteServicePortResultMessage, h as ResourceScopeOptions, i as RuntimeUnitImplementation, j as createLifecycleScope, k as createMessageBus, l as createMessagePortServiceTransport, m as createPluginIntentController, n as createRemoteServiceBridge, o as createResourceRegistry, p as createResourceScope, q as createRuntimeUnitImplementationRegistry, r as createServiceBridge, s as registerOwnedResource } from './resourceRegistry-BAnqKcp7.js';
+import { R as RuntimeKind, P as PluginManifest, a as PluginGraph, b as PluginDependency, c as PluginReverseDep, d as PluginContribution, e as PluginConfig, f as PluginContextExtension, g as PluginManifestInput, h as RuntimeUnitDescriptorInput, i as PluginSetup, j as RuntimeDependency, k as PluginPermission, l as PluginMeta, m as PluginStateKind, n as RemoteServiceReference, o as RemoteServiceMessageCodec, p as PluginUnitState, q as RemoteServiceBridge, r as RemoteServiceProxy, s as PluginHost, L as LifecycleDisposeResult, C as CreatePluginHostOptions, M as MessageBus, t as LifecycleScope, u as LifecycleScopeIdentity, v as PermissionLease, S as ScopedTaskScheduler, w as CreateUpgradeGateOptions, U as UpgradeGate, x as RemoteServiceHandshake, y as RemoteServiceSnapshot } from './createPluginHost-ChJNBTsX.js';
+export { z as CapabilityRegistry, A as ContextExtensionInput, B as ContributionAdapter, D as ContributionAdapterInput, E as ContributionHandle, F as DispatchOptions, G as EventHandler, H as HandlerOptions, I as HostListener, J as LIFECYCLE_ERROR_TEXT, K as LifecycleCleanup, N as LifecycleCleanupIssue, O as LifecycleCleanupPhase, Q as LifecycleDisposeOptions, T as LifecycleResourceHandle, V as LifecycleResourceSnapshot, W as LifecycleScopeKind, X as LifecycleScopeRevokedError, Y as LifecycleScopeState, Z as Message, _ as MessageBusSnapshot, $ as MessageHandler, a0 as MessageMode, a1 as OwnedResourceDefinition, a2 as PermissionDeniedError, a3 as PermissionLeaseBinding, a4 as PermissionLeaseBindingExpectation, a5 as PermissionLeaseRevokedError, a6 as PermissionPolicyInput, a7 as PermissionPolicyResult, a8 as PluginAttributes, a9 as PluginConfigStore, aa as PluginContext, ab as PluginIntentCommand, ac as PluginIntentCommandResult, ad as PluginIntentController, ae as PluginIntentCoordinator, af as PluginIntentSnapshot, ag as PluginIntentSubmissionResult, ah as PluginLifecycleState, ai as PluginStartupMode, aj as PluginState, ak as PluginTeardown, al as PluginUnitGraph, am as PublishOptions, an as RESOURCE_OWNER, ao as RESOURCE_REGISTRY_CAPABILITY, ap as RUNTIME_MESSAGE_BUS, aq as RemoteServiceBridgeState, ar as RemoteServiceCallContext, as as RemoteServiceLookup, at as RemoteServiceMessageKind, au as RemoteServicePortControlMessage, av as RemoteServiceSnapshotResult, aw as RemoteServiceTransport, ax as RemoteServiceUnavailableError, ay as RequestOptions, az as ResourceContext, aA as ResourceDefinition, aB as ResourceKey, aC as ResourceRegistry, aD as ResourceSnapshot, aE as ResourceStatus, aF as ResourceStoreApi, aG as RuntimeUnitAttributesInput, aH as RuntimeUnitAvailabilityInput, aI as RuntimeUnitDependency, aJ as RuntimeUnitDependencyInput, aK as RuntimeUnitDescriptor, aL as RuntimeUnitImplementationRegistry, aM as RuntimeUnitParentScopeInput, aN as RuntimeUnitSnapshot, aO as SCOPED_TASK_SCHEDULER_CAPABILITY, aP as ScopedTaskDefinition, aQ as ScopedTaskSnapshot, aR as StartupCapabilityError, aS as StartupCapabilityErrorDetails, aT as StartupPluginError, aU as StartupPluginErrorDetails, aV as UpgradeDrainResult, aW as UpgradeGateRejectedError, aX as UpgradeGateState, aY as UpgradeHandshake, aZ as UpgradeHandshakeResult, a_ as UpgradeIoLease, a$ as UpgradeMode, b0 as UpgradeSession, b1 as createCapabilityRegistry, b2 as createInMemoryPluginConfigStore, b3 as createPluginHost, b4 as createRemoteServiceMessageCodec, b5 as createResourceStore, b6 as defineRuntimeUnitDependencies, b7 as defineRuntimeUnitProvidedContracts, b8 as lifecycleErrorText, b9 as runtimeCapabilityContractVersion } from './createPluginHost-ChJNBTsX.js';
+import { R as RemoteServicePortCallMessage } from './resourceRegistry-MNM1c7od.js';
+export { C as CreateMessagePortServiceTransportOptions, a as CreatePluginIntentControllerOptions, b as CreateResourceScopeOptions, c as CreateServiceBridgeOptions, d as RemoteServicePortCancelMessage, e as RemoteServicePortErrorMessage, f as RemoteServicePortResponseMessage, g as RemoteServicePortResultMessage, h as ResourceScopeOptions, i as RuntimeUnitImplementation, j as createLifecycleScope, k as createMessageBus, l as createMessagePortServiceTransport, m as createPluginIntentController, n as createRemoteServiceBridge, o as createResourceRegistry, p as createResourceScope, q as createRuntimeUnitImplementationRegistry, r as createServiceBridge, s as registerOwnedResource } from './resourceRegistry-MNM1c7od.js';
 
 interface BuildPluginGraphOptions {
     /** 当前真正运行的插件；不传时使用 manifest.meta.defaultEnabled。 */
     enabledPluginIds?: ReadonlySet<string>;
-    /** 当前 Host 实际执行环境；未选中的 Worker/Window 单元不会进入图。 */
-    execution?: PluginExecution;
+    /** 当前 Host 的真实 Runtime；未选中的 Window/Worker 单元不会进入图。 */
+    runtime?: RuntimeKind;
 }
 interface ValidatePluginGraphOptions extends BuildPluginGraphOptions {
     /** 平台内建 capability，不需要由某个 manifest 提供。 */
@@ -16,10 +16,15 @@ interface ValidatePluginGraphOptions extends BuildPluginGraphOptions {
     multiProviderCapabilities?: ReadonlySet<string>;
     /** Host 分批注册时允许 provider 尚未注册；真正装配前仍会进入 blocked。 */
     allowMissingDependencies?: boolean;
+    /**
+     * 允许依赖当前图之外的另一个真实 Runtime；实际是否 ready 由运行时
+     * snapshot 和 RemoteServiceBridge 在 Host reconcile 时决定。
+     */
+    externalRuntimeDependencies?: boolean;
 }
 interface PluginGraphDiagnostic {
     /** 稳定诊断码。 */
-    code: "plugin.duplicate_id" | "capability.duplicate_provider" | "plugin.missing_dependency" | "plugin.dependency_cycle" | "plugin.dependency_contract_invalid" | "plugin.dependency_contract_unavailable" | "plugin.runtime_declaration_at_product_level";
+    code: "plugin.duplicate_id" | "capability.duplicate_provider" | "plugin.missing_dependency" | "plugin.dependency_cycle" | "plugin.dependency_contract_invalid" | "plugin.dependency_contract_unavailable" | "plugin.runtime_invalid" | "plugin.runtime_declaration_at_product_level";
     /** 相关插件或 capability。 */
     ids: string[];
     /** 中文诊断原因，供设置页直接显示或再做 i18n 映射。 */
@@ -43,9 +48,9 @@ declare function validateRuntimeUnitDependencyContracts(manifests: readonly Plug
  * 返回当前执行环境的依赖；显式运行单元不会继承产品级依赖。
  * 只有没有 units 的简单插件才读取历史 product-level dependencies。
  */
-declare function dependenciesOfManifest(manifest: PluginManifest, execution?: PluginExecution): PluginDependency[];
+declare function dependenciesOfManifest(manifest: PluginManifest, runtime?: RuntimeKind): PluginDependency[];
 /** 返回当前执行环境提供的 capability；显式单元不会继承产品级摘要。 */
-declare function providesOfManifest(manifest: PluginManifest, execution?: PluginExecution): string[];
+declare function providesOfManifest(manifest: PluginManifest, runtime?: RuntimeKind): string[];
 /** 从 manifest 列表构造依赖、提供者和反向依赖。 */
 declare function buildPluginGraph(manifests: PluginManifest[], options?: BuildPluginGraphOptions): PluginGraph;
 /** 在任何 setup 前校验重复提供、缺失硬依赖和硬依赖环。 */
@@ -53,6 +58,291 @@ declare function validatePluginGraph(manifests: readonly PluginManifest[], optio
 /** 查询当前启用的逆依赖者；禁用提供者时应按此集合先停止消费者。 */
 declare function reverseDependentsOf(graph: PluginGraph, pluginId: string, enabledSet: ReadonlySet<string>): PluginReverseDep[];
 
+interface DefinePluginOptions<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> {
+    /** 全局稳定插件标识。 */
+    id: string;
+    /** 默认展示名称。 */
+    name?: string;
+    /** 可选诊断描述。 */
+    description?: string;
+    /** 普通插件的可执行实现；不会进入静态 descriptor。 */
+    setup: PluginSetup<TConfig, TExtension>;
+    /** 默认目标 Runtime；普通 Window 插件通常省略，由 App 注入。 */
+    runtime?: RuntimeKind;
+    /** 默认 unit id；省略时使用插件 id。 */
+    unitId?: string;
+    /** 插件依赖；helper 会为本地依赖补齐 v1 契约版本。 */
+    dependencies?: readonly (RuntimeDependency | PluginDependency)[];
+    /** 本单元提供的 capability。 */
+    provides?: readonly string[];
+    /** 跨 Runtime 时可显式覆盖 capability 契约版本。 */
+    providedContracts?: Readonly<Record<string, string>>;
+    /** 请求的权限集合。 */
+    permissions?: readonly PluginPermission[];
+    /** 单元只读配置。 */
+    config?: TConfig;
+    /** 产品贡献；不会被框架解释。 */
+    contribution?: TContribution;
+    /** 是否默认启用；默认为 true。 */
+    defaultEnabled?: boolean;
+    /** 是否允许控制面停用；默认为 true。 */
+    canDisable?: boolean;
+    /** required 插件在 App 初始启动时必须成功。 */
+    required?: boolean;
+    /** 显式启动模式；required=true 时不能覆盖为 optional。 */
+    startup?: "required" | "optional";
+    /** 仅用于兼容低层消费方的静态 meta 扩展；WebLoom 不解释分类字段。 */
+    meta?: Partial<PluginMeta>;
+}
+/** 静态 descriptor 与当前 realm 的实现函数分离。 */
+interface PluginDefinition<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> {
+    readonly manifest: PluginManifestInput<TContribution, TConfig, TExtension>;
+    readonly descriptor: RuntimeUnitDescriptorInput<TContribution, TConfig>;
+    readonly setup: PluginSetup<TConfig, TExtension>;
+}
+/**
+ * 声明一个插件。
+ *
+ * 该函数不创建 Host，也不启动 setup；真正的启动边界由
+ * createWindowApp()/startSharedWorkerApp() 拥有。
+ */
+declare function definePlugin<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension>(options: DefinePluginOptions<TContribution, TConfig, TExtension>): PluginDefinition<TContribution, TConfig, TExtension>;
+
+type RuntimePluginDefinition = PluginDefinition<any, any, any> | {
+    readonly manifest: PluginManifest | PluginManifestInput;
+    readonly setup: PluginSetup<any, any>;
+    /** 多 unit manifest 中 setup 所实现的目标 unit；单一匹配 unit 可省略。 */
+    readonly unitId?: string;
+};
+interface MaterializedPluginDefinition {
+    readonly manifest: PluginManifest;
+    /** 当前 Runtime 中由 setup 实现的 unit。 */
+    readonly unitId: string;
+    readonly setup: PluginSetup;
+}
+/** 将作者定义绑定到真实 Runtime；不把 setup 复制进 manifest。 */
+declare function materializePluginDefinition(input: RuntimePluginDefinition, runtime: RuntimeKind): MaterializedPluginDefinition;
+declare function materializePluginDefinitions(inputs: readonly RuntimePluginDefinition[], runtime: RuntimeKind): MaterializedPluginDefinition[];
+
+declare const RUNTIME_PROTOCOL_VERSION = "webloom.runtime.v1";
+declare const RUNTIME_HELLO_TYPE = "webloom.runtime.hello";
+declare const RUNTIME_SNAPSHOT_TYPE = "webloom.runtime.snapshot";
+declare const RUNTIME_RESYNC_TYPE = "webloom.runtime.resync";
+declare const RUNTIME_ERROR_TYPE = "webloom.runtime.error";
+interface RuntimeHelloMessage {
+    type: typeof RUNTIME_HELLO_TYPE;
+    protocolVersion: string;
+    connectionId: string;
+    runtimeId: string;
+}
+interface RuntimeResyncMessage {
+    type: typeof RUNTIME_RESYNC_TYPE;
+    connectionId: string;
+}
+interface RuntimeErrorMessage {
+    type: typeof RUNTIME_ERROR_TYPE;
+    protocolVersion: string;
+    code: "runtime.protocol_mismatch" | "runtime.initialization_failed" | "runtime.invalid_connection";
+    message: string;
+    pluginId?: string;
+    unitId?: string;
+    phase?: string;
+}
+interface RuntimeSnapshot {
+    type: typeof RUNTIME_SNAPSHOT_TYPE;
+    protocolVersion: string;
+    runtimeId: string;
+    runtimeKind: RuntimeKind;
+    runtimeInstanceId: string;
+    connectionId: string;
+    snapshotRevision: number;
+    baseline: boolean;
+    state: "starting" | "ready" | "stopping" | "failed" | "disposed";
+    units: readonly RuntimeSnapshotUnit[];
+    services: readonly RemoteServiceReference[];
+}
+interface RuntimeSnapshotUnit {
+    pluginId: string;
+    unitId: string;
+    runtime: RuntimeKind;
+    instanceId?: string;
+    state: PluginStateKind;
+}
+declare function createRuntimeMessageCodec(): RemoteServiceMessageCodec;
+declare function isRuntimeHello(input: unknown): input is RuntimeHelloMessage;
+declare function isRuntimeResync(input: unknown): input is RuntimeResyncMessage;
+declare function isRuntimeSnapshot(input: unknown): input is RuntimeSnapshot;
+declare function isRuntimeError(input: unknown): input is RuntimeErrorMessage;
+/** 将 Host 的 PluginUnitState 映射成不会泄露领域配置的运行时快照。 */
+declare function unitSnapshotFromState(state: PluginUnitState, runtime: RuntimeKind): RuntimeSnapshotUnit;
+
+type RuntimeAppState = "starting" | "ready" | "stopping" | "failed" | "disposed" | "connecting" | "disconnected";
+interface RuntimeStatusSnapshot {
+    runtimeId: string;
+    runtimeKind: RuntimeKind;
+    runtimeInstanceId: string;
+    state: RuntimeAppState;
+    snapshotRevision: number;
+    connectionId?: string;
+    units: readonly RuntimeSnapshotUnit[];
+    services: readonly RemoteServiceReference[];
+    error?: string;
+}
+type RuntimeStatusListener = (snapshot: RuntimeStatusSnapshot) => void;
+interface WindowApp {
+    readonly runtimeKind: "window-main";
+    readonly runtimeId: string;
+    readonly runtimeInstanceId: string;
+    /** 已由 createWindowApp 装配并注册完成的本地 Host。 */
+    readonly host: PluginHost;
+    state(): RuntimeStatusSnapshot;
+    /** 获取当前本地 capability；停止或销毁后同步抛错。 */
+    capability<T>(capabilityId: string): T;
+    subscribe(listener: RuntimeStatusListener): () => void;
+    dispose(reason?: string): Promise<LifecycleDisposeResult>;
+}
+interface RuntimeHandle {
+    readonly runtimeKind: "shared-worker";
+    readonly runtimeId: string;
+    /** 当前连接绑定的 Worker 启动身份；未握手时为 undefined。 */
+    readonly runtimeInstanceId?: string;
+    /** 当前物理连接身份；未握手时为 undefined。 */
+    readonly connectionId?: string;
+    /** 当前连接已校验的服务桥；不暴露原始 MessagePort。 */
+    readonly serviceBridge: RemoteServiceBridge;
+    state(): RuntimeStatusSnapshot;
+    ready(): Promise<void>;
+    capability<T = unknown>(capabilityId: string, options?: {
+        contractVersion?: string;
+    }): RemoteServiceProxy & {
+        readonly serviceType?: T;
+    };
+    subscribe(listener: RuntimeStatusListener): () => void;
+    dispose(reason?: string): Promise<void>;
+}
+/** 跨 realm 初始化失败；不把 required 插件错误包装成成功状态。 */
+interface RuntimeInitializationErrorDetails {
+    pluginId?: string;
+    unitId?: string;
+    phase: "validate" | "register" | "startup" | "snapshot" | "handshake";
+    error: string;
+}
+declare class RuntimeInitializationError extends Error {
+    readonly code: "runtime.initialization_failed";
+    readonly details: RuntimeInitializationErrorDetails;
+    constructor(details: RuntimeInitializationErrorDetails);
+}
+declare class RuntimeUnavailableError extends Error {
+    readonly code: "runtime.unavailable";
+    constructor(message?: string);
+}
+
+interface CreateWindowAppOptions extends Omit<CreatePluginHostOptions, "runtime" | "runtimeUnitImplementationRegistry"> {
+    /** 逻辑 Runtime 标识；同一页面通常只创建一个 App。 */
+    id?: string;
+    /** 当前 Window 的插件定义；setup 只在当前 Window realm 执行。 */
+    plugins: readonly RuntimePluginDefinition[];
+    /**
+     * 供领域适配层接管分阶段注册时复用已经创建的 Window Host。
+     * 普通插件应省略该字段；传入后由调用方负责后续 register，App 仍负责
+     * Window Runtime 快照、远端投影和最终 dispose。
+     */
+    host?: PluginHost;
+    /** 可选的 SharedWorker Runtime；Window 单元只投影其状态，不创建 Worker 假实例。 */
+    remoteRuntime?: RuntimeHandle;
+}
+/** 创建当前 Window 的唯一 window-main Runtime。 */
+declare function createWindowApp(options: CreateWindowAppOptions): Promise<WindowApp>;
+
+interface SharedWorkerScopeLike {
+    onconnect: ((event: {
+        ports: MessagePort[];
+    }) => void) | null;
+}
+interface StartSharedWorkerAppOptions extends Omit<CreatePluginHostOptions, "runtime" | "runtimeUnitImplementationRegistry"> {
+    /** SharedWorker 的逻辑稳定标识。 */
+    id: string;
+    /** 只在 SharedWorker realm 执行的插件定义。 */
+    plugins: readonly RuntimePluginDefinition[];
+    /** 测试 fixture 可注入结构等价的 SharedWorkerGlobalScope。 */
+    globalScope?: SharedWorkerScopeLike;
+    /**
+     * 复用已有领域 Worker 入口的 onconnect 装配。回调只负责安装领域协议
+     * listener；WebLoom 仍在同一端口上安装自己的 Runtime listener，不会创建
+     * 第二个 Worker 或第二条物理连接。
+     */
+    onPortConnect?: (event: {
+        ports: MessagePort[];
+    }) => void;
+}
+interface SharedWorkerApp {
+    readonly runtimeKind: "shared-worker";
+    readonly runtimeId: string;
+    readonly runtimeInstanceId: string;
+    ready(): Promise<void>;
+    /** 重新按当前外部身份/意图对账运行单元；不会创建第二个 Worker。 */
+    reconcile(): Promise<void>;
+    state(): RuntimeStatusSnapshot;
+    subscribe(listener: RuntimeStatusListener): () => void;
+    dispose(reason?: string): Promise<LifecycleDisposeResult>;
+}
+/** 在当前 SharedWorkerGlobalScope 中安装唯一的 Worker Runtime。 */
+declare function startSharedWorkerApp(options: StartSharedWorkerAppOptions): SharedWorkerApp;
+
+interface SharedWorkerLike {
+    readonly port: MessagePort;
+    onerror?: (event: Event) => void;
+    /** 浏览器 SharedWorker 的错误事件；测试 fake 可省略。 */
+    addEventListener?(type: "error", listener: (event: Event) => void): void;
+    removeEventListener?(type: "error", listener: (event: Event) => void): void;
+}
+type SharedWorkerFactory = (url: string | URL, options: {
+    type: "module";
+    name?: string;
+}) => SharedWorkerLike;
+/**
+ * 供仍需在同一物理连接上承载产品 RPC 的装配层使用。
+ *
+ * 普通调用方不需要这个接缝；它们只使用 RuntimeHandle 的状态和
+ * serviceBridge。已有大量领域 RPC 的应用迁移时可以先把
+ * Runtime 握手与旧 RPC 复用同一 MessagePort，再逐步把领域调用收敛到
+ * capability service，而不会偷偷创建第二个 SharedWorker 连接。
+ */
+interface SharedWorkerConnectionContext {
+    readonly worker: SharedWorkerLike;
+    readonly port: MessagePort;
+    readonly connectionId: string;
+}
+interface ConnectSharedWorkerOptions {
+    /** Worker 入口的逻辑 Runtime 标识。 */
+    id: string;
+    /** module SharedWorker URL；默认直接传给 new SharedWorker。 */
+    url: string | URL;
+    /** 可选的浏览器 SharedWorker name；不传时由 URL 参与实例隔离。 */
+    name?: string;
+    /** 断线后是否建立新连接；旧代理仍永久失效。默认为 true。 */
+    autoReconnect?: boolean;
+    /** 自动重连等待毫秒数。 */
+    reconnectDelayMs?: number;
+    /** 首个 runtime snapshot 到达前的握手超时；默认 10000ms。 */
+    handshakeTimeoutMs?: number;
+    /** 测试 fixture 使用；生产默认使用 globalThis.SharedWorker。 */
+    workerFactory?: SharedWorkerFactory;
+    /**
+     * 每次建立实际物理连接时调用一次；自动重连会再次调用。
+     * 回调可以在同一端口上安装产品协议，但不得替换 Runtime 的消息
+     * 监听器，也不得把旧端口保存为可重用连接。
+     */
+    onConnection?: (context: SharedWorkerConnectionContext) => void | Promise<void>;
+}
+/**
+ * 从 Window 连接真实 module SharedWorker。
+ *
+ * Promise 只在首个完整 baseline 快照到达后成功；调用方得到的代理均绑定
+ * 当前 connection/runtime/provider/revision，断线或重启不会静默换绑旧代理。
+ */
+declare function connectSharedWorker(options: ConnectSharedWorkerOptions): Promise<RuntimeHandle>;
+
 /** 创建绑定到指定插件实例的 MessageBus 视图。 */
 declare function createScopedMessageBus(base: MessageBus, scope: LifecycleScope): MessageBus;
 
@@ -156,4 +446,4 @@ interface MessagePortServiceProvider {
 /** 创建一个只服务于一条实际 MessagePort 连接的 Provider 端点。 */
 declare function createMessagePortServiceProvider(options: CreateMessagePortServiceProviderOptions): MessagePortServiceProvider;
 
-export { type BuildPluginGraphOptions, type CreateMessagePortServiceProviderOptions, type CreatePermissionLeaseOptions, type CreateScopedRegistryFacadeOptions, type CreateScopedTaskSchedulerOptions, CreateUpgradeGateOptions, LifecycleScope, LifecycleScopeIdentity, MessageBus, type MessagePortServiceCallInput, type MessagePortServiceProvider, PermissionLease, PluginDependency, PluginExecution, PluginGraph, type PluginGraphDiagnostic, PluginGraphValidationError, PluginManifest, PluginPermission, PluginReverseDep, RemoteServiceHandshake, RemoteServiceMessageCodec, RemoteServicePortCallMessage, RemoteServiceSnapshot, type ScopedRegistryRegistration, ScopedTaskScheduler, UpgradeGate, type ValidatePluginGraphOptions, type VerifyPermissionLeaseOptions, buildPluginGraph, createMessagePortServiceProvider, createPermissionLease, createScopedMessageBus, createScopedRegistryFacade, createScopedTaskScheduler, createUpgradeGate, dependenciesOfManifest, providesOfManifest, reverseDependentsOf, validatePluginGraph, validateRuntimeUnitDependencyContracts, verifyPermissionLease };
+export { type BuildPluginGraphOptions, type ConnectSharedWorkerOptions, type CreateMessagePortServiceProviderOptions, type CreatePermissionLeaseOptions, CreatePluginHostOptions, type CreateScopedRegistryFacadeOptions, type CreateScopedTaskSchedulerOptions, CreateUpgradeGateOptions, type CreateWindowAppOptions, type DefinePluginOptions, LifecycleDisposeResult, LifecycleScope, LifecycleScopeIdentity, type MaterializedPluginDefinition, MessageBus, type MessagePortServiceCallInput, type MessagePortServiceProvider, PermissionLease, PluginConfig, PluginContextExtension, PluginContribution, type PluginDefinition, PluginDependency, PluginGraph, type PluginGraphDiagnostic, PluginGraphValidationError, PluginHost, PluginManifest, PluginManifestInput, PluginMeta, PluginPermission, PluginReverseDep, PluginSetup, PluginStateKind, PluginUnitState, RUNTIME_ERROR_TYPE, RUNTIME_HELLO_TYPE, RUNTIME_PROTOCOL_VERSION, RUNTIME_RESYNC_TYPE, RUNTIME_SNAPSHOT_TYPE, RemoteServiceBridge, RemoteServiceHandshake, RemoteServiceMessageCodec, RemoteServicePortCallMessage, RemoteServiceProxy, RemoteServiceReference, RemoteServiceSnapshot, type RuntimeAppState, RuntimeDependency, type RuntimeErrorMessage, type RuntimeHandle, type RuntimeHelloMessage, RuntimeInitializationError, type RuntimeInitializationErrorDetails, RuntimeKind, type RuntimePluginDefinition, type RuntimeResyncMessage, type RuntimeSnapshot, type RuntimeSnapshotUnit, type RuntimeStatusListener, type RuntimeStatusSnapshot, RuntimeUnavailableError, RuntimeUnitDescriptorInput, type ScopedRegistryRegistration, ScopedTaskScheduler, type SharedWorkerApp, type SharedWorkerConnectionContext, type SharedWorkerFactory, type SharedWorkerLike, type SharedWorkerScopeLike, type StartSharedWorkerAppOptions, UpgradeGate, type ValidatePluginGraphOptions, type VerifyPermissionLeaseOptions, type WindowApp, buildPluginGraph, connectSharedWorker, createMessagePortServiceProvider, createPermissionLease, createRuntimeMessageCodec, createScopedMessageBus, createScopedRegistryFacade, createScopedTaskScheduler, createUpgradeGate, createWindowApp, definePlugin, dependenciesOfManifest, isRuntimeError, isRuntimeHello, isRuntimeResync, isRuntimeSnapshot, materializePluginDefinition, materializePluginDefinitions, providesOfManifest, reverseDependentsOf, startSharedWorkerApp, unitSnapshotFromState, validatePluginGraph, validateRuntimeUnitDependencyContracts, verifyPermissionLease };