webloom-framework 0.3.0 → 0.4.1

package/README.md

@@ -1,8 +1,8 @@
 # WebLoom
 
-WebLoom 是一个只面向浏览器的插件 Runtime 框架。0.3.0 管理真实的
-`window-main` 和 `shared-worker` JavaScript realm、插件运行单元、实例、
-依赖图、ResourceScope、权限租约、服务桥和资源缓存；路由、存储、日志、
+WebLoom 是一个只面向浏览器的插件 Runtime 框架。0.4.1 管理真实的
+`window-main` 和 `shared-worker` JavaScript realm、插件运行单元、实例、依赖图、
+ResourceScope、权限租约、typed capability、服务桥和资源缓存；路由、存储、日志、
 国际化等产品能力由插件或下游应用注入。
 
 ## 安装
@@ -11,10 +11,11 @@ WebLoom 是一个只面向浏览器的插件 Runtime 框架。0.3.0 管理真实
 pnpm add webloom-framework
 ```
 
-WebLoom 是 ESM 单包，提供三个入口：
+WebLoom 是 ESM 单包，提供四个入口：
 
 - `webloom-framework`：浏览器核心，提供 Window/SharedWorker Runtime，不加载 React；
-- `webloom-framework/react`：Provider、capability、Host、Registry 和 Resource Hooks；
+- `webloom-framework/advanced`：Host、graph、peer、transport 和分阶段装配工具；
+- `webloom-framework/react`：Provider、typed capability、plugin 和 Resource Hooks；
 - `webloom-framework/testing`：无产品语义的假 Host、假传输和测试辅助。
 
 React 是可选 peer dependency。只使用 `webloom-framework` 时不需要安装 React。
@@ -22,27 +23,37 @@ React 是可选 peer dependency。只使用 `webloom-framework` 时不需要安
 ## 最小 Window Runtime
 
 ```ts
-import { createWindowApp, definePlugin } from "webloom-framework";
+import { defineCapability, createWindowApp, definePlugin } from "webloom-framework";
+
+const Hello = defineCapability<{ value: string }>({
+  kind: "local",
+  id: "hello.service",
+  version: "1",
+});
 
 const hello = definePlugin({
   id: "hello",
-  provides: ["hello.service"],
+  provides: [Hello] as const,
   setup(ctx) {
-    ctx.provide("hello.service", { value: "world" });
+    ctx.provide(Hello, { value: "world" });
   },
 });
 
 const app = await createWindowApp({ plugins: [hello] });
-const service = app.capability<{ value: string }>("hello.service");
+const service = app.capability(Hello);
 console.log(service.value); // world
 
 await app.dispose();
 ```
 
+`defineCapability()` 是 capability 的唯一身份入口。local capability 只在同一 realm
+提供和消费；RPC/stream capability 必须声明生产 `request`、`response` 或 `item`
+parser，调用参数与结果从契约对象自动推导。
+
 `createWindowApp()` 会固定创建一个 `window-main` Runtime、生成新的
 `runtimeInstanceId`、装配实现并等待初始插件启动。普通插件不需要手工创建
-Implementation Registry 或调用 `host.register()`；`definePlugin()` 返回的静态
-manifest 不包含 `setup` 函数。
+Implementation Registry 或调用 `host.register()`；静态 manifest 不包含 setup、parser
+或 transfer 函数。
 
 ## SharedWorker Runtime
 
@@ -50,28 +61,44 @@ Worker 入口只在 Worker realm 中装配插件：
 
 ```ts
 // coordinator.worker.ts
-import { definePlugin, startSharedWorkerApp } from "webloom-framework";
+import { defineCapability, definePlugin, startSharedWorkerApp } from "webloom-framework";
+
+const Health = defineCapability({
+  kind: "rpc",
+  id: "coordinator.health",
+  version: "1",
+  request: { parse(value: unknown): { type: string } {
+    if (!value || typeof value !== "object" || typeof (value as { type?: unknown }).type !== "string") {
+      throw new Error("invalid health request");
+    }
+    return value as { type: string };
+  } },
+  response: { parse(value: unknown): { type: string; instanceId: string } {
+    if (!value || typeof value !== "object") throw new Error("invalid health response");
+    const result = value as { type?: unknown; instanceId?: unknown };
+    if (typeof result.type !== "string" || typeof result.instanceId !== "string") throw new Error("invalid health response");
+    return value as { type: string; instanceId: string };
+  } },
+});
 
 const coordinator = definePlugin({
   id: "coordinator",
-  provides: ["coordinator.service"],
+  provides: [Health] as const,
   setup(ctx) {
-    ctx.provide("coordinator.service", {
-      handle(request: { type: string }) {
-        return { type: request.type, instanceId: ctx.instanceId };
-      },
-    });
+    ctx.handle(Health, (request) => ({
+      type: request.type,
+      instanceId: ctx.instanceId,
+    }));
   },
 });
 
-startSharedWorkerApp({ id: "coordinator", plugins: [coordinator] });
+startSharedWorkerApp({ id: "coordinator", plugins: [coordinator], expose: [Health] });
 ```
 
 Window 侧只连接 Worker，不创建第二套 Worker 插件生命周期：
 
 ```ts
 // Vite: this query emits a real, hashed JavaScript SharedWorker chunk.
-// Do not pass the source `.ts` URL to connectSharedWorker in a production build.
 import coordinatorWorkerUrl from "./coordinator.worker.ts?sharedworker&url";
 import { connectSharedWorker } from "webloom-framework";
 
@@ -79,27 +106,27 @@ const runtime = connectSharedWorker({
   id: "coordinator",
   url: coordinatorWorkerUrl,
 });
-const service = runtime.capability("coordinator.service");
+const service = runtime.capability(Health);
 await service.call({ type: "health" });
 ```
 
-`connectSharedWorker()` 同步返回本地句柄；Worker 通过完整 `RuntimeSnapshot` 发布
-状态和服务目录，代理的第一次 `call()` 在有限 deadline 内等待精确匹配。协议不兼容、
-断线、超时和服务撤销都从调用 Promise 返回；框架不自动重连或重放调用。旧代理不会
-静默换绑到新 Worker；Worker 重启后 `runtimeInstanceId`、服务的
-`serviceInstanceId` 和运行单元实例都会变化。
+`connectSharedWorker()` 同步返回本地句柄；Worker 通过完整 `RuntimeSnapshot` 发布状态和
+服务目录，代理的第一次 `call()` 在有限 deadline 内等待精确匹配。协议不兼容、断线、
+超时和服务撤销都从调用 Promise 返回；框架不自动重连或重放调用。旧代理不会静默换绑
+到新 Worker；Worker 重启后 `runtimeInstanceId`、服务的 `serviceInstanceId` 和运行单元
+实例都会变化。
 
-Vite 项目必须把 Worker 入口交给 Vite 的 Worker importer（例如
-`?sharedworker&url`），再把构建后导出的 URL 传给框架。框架内部的
-`new SharedWorker(url, { type: "module" })` 只负责运行时连接，不能替调用方的
-Bundler 发现源码 `.ts` 入口。其它 Bundler 应使用等价的独立 SharedWorker
-Rollup entry。仓库的 `pnpm run test:browser` 会先执行生产构建，再从 dist 启动
-真实浏览器验收。
+Vite 项目必须把 Worker 入口交给 Vite 的 Worker importer（例如 `?sharedworker&url`），
+再把构建后导出的 URL 传给框架。框架内部的 `new SharedWorker(url, { type: "module" })`
+只负责运行时连接，不能替调用方的 Bundler 发现源码 `.ts` 入口。其它 Bundler 应使用
+等价的独立 SharedWorker Rollup entry。仓库的 `pnpm run test:browser` 会先执行生产构建，
+再从 dist 启动真实浏览器验收。
 
-Window 插件依赖 Worker capability 时，把已连接的 `RuntimeHandle` 传给
-`createWindowApp({ remoteRuntime: runtime, plugins })`，并在 setup 中通过
-`ctx.serviceBridge.requireProxy()` 获取精确版本的远程代理。Worker 断线时，Window
-Host 会把相关单元置为 `blocked`；新的完整快照到达后按原启用意图重新协调。
+页面要向 Worker 暴露反向能力时，先创建本地 `WindowApp`，再通过
+`connectSharedWorker({ client: { app, expose } })` 绑定同一条私有端口。页面消费 Worker
+capability 时使用 `runtime.capability(C)`；需要分阶段把远程依赖装入已有页面 Host，则从
+`webloom-framework/advanced` 使用 `attachRemote()` 和 `registerPlugins()`。Worker 断线
+会撤销旧代理；框架不会自动重连或重放调用。
 
 ## 公共字段中文语义
 
@@ -113,8 +140,8 @@ Host 会把相关单元置为 `blocked`；新的完整快照到达后按原启
 | `serviceInstanceId` | 某个服务实例的不可复用身份；服务撤销或重建后必须变化。 |
 | `revision` | 完整 RuntimeSnapshot 的单调修订号；只用于观察和目录收敛。 |
 | `scopeId` | 本次生命周期 Scope 的唯一标识。 |
-| `capability` | 插件提供或依赖的服务契约标识。 |
-| `contractVersion` | capability 的精确契约版本。 |
+| `capability` | 插件提供或依赖的 typed 服务契约。 |
+| `contractVersion` | capability 的精确业务契约版本。 |
 | `permission` | 字符串形式的权限动作；具体集合由宿主批准。 |
 | `attributes` | 宿主绑定的只读扩展元数据，不包含私密材料。 |
 | `desiredEnabled` | 用户或控制面希望产品启用的持久意图。 |
@@ -127,6 +154,7 @@ Host 会把相关单元置为 `blocked`；新的完整快照到达后按原启
 pnpm install
 pnpm lint:boundaries
 pnpm typecheck
+pnpm test:types
 pnpm test
 pnpm build
 pnpm run pack:consumer
@@ -134,9 +162,9 @@ pnpm run pack:consumer
 pnpm run test:browser
 ```
 
-`pack:consumer` 会在不访问本仓库源码的临时项目中安装 tarball，分别执行
-core-only、React 和 Worker 消费者的 `tsc --noEmit` 与运行时 smoke，并检查
-发布文件白名单、体积、`.d.ts` 和 `.js.map` 的本地路径及产品字段。版本、发布身份
-与许可证确认属于发布责任人的操作，本仓库不自动执行发布。
+`pack:consumer` 会在不访问本仓库源码的临时项目中安装 tarball，分别执行 core-only、
+advanced、React 和 Worker 消费者的 `tsc --noEmit` 与运行时 smoke，并检查发布文件白名单、
+体积、`.d.ts` 和 `.js.map` 的本地路径及产品字段。版本、发布身份与许可证确认属于
+发布责任人的操作，本仓库不自动执行发布。
 
 详细 API 约束见 [`docs/api.md`](docs/api.md)。

package/dist/advanced.d.ts

@@ -0,0 +1,168 @@
+import { R as RuntimeKind, C as CapabilityDescriptor, P as PluginManifest, a as PluginGraph, b as RuntimeUnitDependency, c as PluginReverseDep, d as RuntimeUnitDescriptor, L as LifecycleScopeIdentity, e as PluginPermission, f as LifecycleScope, g as PermissionLease, S as ScopedTaskScheduler, h as CreateUpgradeGateOptions, U as UpgradeGate, i as ServiceReference, j as CapabilityPeer, k as ResourceStoreApi$1, W as WindowApp, l as RuntimeHandle } from './runtimeTypes-DquUCHz-.js';
+export { m as CapabilityRegistration, n as CapabilityRegistry, o as ContextExtensionInput, p as ContributionAdapter, q as ContributionAdapterInput, r as ContributionHandle, s as CreatePluginHostOptions, H as HostCapabilityRegistration, t as HostInspection, u as PermissionPolicyInput, v as PermissionPolicyResult, w as PluginConfigStore, x as PluginHost, y as RuntimeUnitAttributesInput, z as RuntimeUnitAvailabilityInput, A as RuntimeUnitParentScopeInput, B as RuntimeUnitSnapshot, D as StartupCapabilityError, E as StartupPluginError, F as createCapabilityRegistry, G as createInMemoryPluginConfigStore, I as createPluginHost, J as invokeCapabilityHandler } from './runtimeTypes-DquUCHz-.js';
+import { R as RuntimeCallMessage, M as MessagePortLike, a as RuntimeTransport } from './messagePortServiceTransport-BYprNvQY.js';
+export { C as CreateCapabilityBridgeOptions, b as CreatePluginIntentControllerOptions, c as RUNTIME_CALL_TYPE, d as RUNTIME_CANCEL_TYPE, e as RUNTIME_CREDIT_TYPE, f as RUNTIME_ERROR_MESSAGE_TYPE, g as RUNTIME_ERROR_TYPE, h as RUNTIME_NEXT_TYPE, i as RUNTIME_PROTOCOL_VERSION, j as RUNTIME_RESULT_TYPE, k as RUNTIME_SNAPSHOT_TYPE, l as RuntimeCancelMessage, m as RuntimeCreditMessage, n as RuntimeErrorMessage, o as RuntimeErrorResponseMessage, p as RuntimeMessageCodec, q as RuntimeNextMessage, r as RuntimeReceiveMetadata, s as RuntimeResultMessage, t as RuntimeSnapshotMessage, u as RuntimeSnapshotUnit, v as RuntimeStreamDoneMessage, w as RuntimeStreamReadyMessage, x as RuntimeUnaryResultMessage, y as RuntimeUnitImplementation, z as RuntimeWireMessage, A as createCapabilityBridge, B as createMessagePortRuntimeTransport, D as createPluginIntentController, E as createResourceRegistry, F as createRuntimeMessageCodec, G as createRuntimeUnitImplementationRegistry, H as isRuntimeSnapshot, I as registerOwnedResource, J as validateTransferables } from './messagePortServiceTransport-BYprNvQY.js';
+import { R as ReceivePortLedger, a as RuntimeLimitsInput, b as RuntimeBudget, c as RuntimePluginDefinition } from './sharedWorkerHost-KI7TIGdX.js';
+export { C as CreateResourceScopeOptions, P as PeerController, d as PeerExposureOptions, e as ResourceScopeOptions, S as SharedWorkerApp, f as StartSharedWorkerAppForTestingOptions, g as StartSharedWorkerAppOptions, h as bridgeForRuntimeHandle, i as createLifecycleScope, j as createResourceScope } from './sharedWorkerHost-KI7TIGdX.js';
+export { c as createWindowAppFromHost, h as hostForWindowApp } from './windowRuntime-BKkLPsAS.js';
+
+interface PluginGraphOptions {
+    /** 当前 Host 的 Runtime；未指定时只用于静态检查。 */
+    readonly runtime?: RuntimeKind;
+    /** 当前已经启用的插件，用于生成反向依赖状态。 */
+    readonly enabledPluginIds?: ReadonlySet<string>;
+    /** Host-owned 或远端已发布的 descriptor。 */
+    readonly builtinCapabilities?: ReadonlySet<CapabilityDescriptor | string>;
+    /** 是否允许尚未出现在本图中的跨 Runtime provider。 */
+    readonly externalRuntimeDependencies?: boolean;
+    /** registerAll 的调用阶段是否允许缺依赖。 */
+    readonly allowMissingDependencies?: boolean;
+}
+/** 选择一个插件在当前 Runtime 中的实现单元；多匹配必须显式消歧。 */
+declare function selectRuntimeUnit(manifest: PluginManifest, runtime: RuntimeKind | undefined): (RuntimeUnitDescriptor & {
+    id: string;
+    runtime: RuntimeKind;
+}) | undefined;
+declare function dependenciesOfManifest(manifest: PluginManifest, runtime?: RuntimeKind): readonly RuntimeUnitDependency[];
+declare function providesOfManifest(manifest: PluginManifest, runtime?: RuntimeKind): readonly CapabilityDescriptor[];
+/** 构建不可变图快照；结果顺序始终由 manifest 输入顺序和 descriptor 顺序决定。 */
+declare function buildPluginGraph(manifests: readonly PluginManifest[], options?: PluginGraphOptions): PluginGraph;
+/** 在注册/批量装配前验证 manifest 及其依赖闭包。 */
+declare function validatePluginGraph(manifests: readonly PluginManifest[], options?: PluginGraphOptions): void;
+/** 查询依赖某 provider 的已启用插件。 */
+declare function reverseDependentsOf(graph: PluginGraph, pluginId: string, enabledPluginIds?: ReadonlySet<string>): readonly PluginReverseDep[];
+
+interface CreatePermissionLeaseOptions {
+    /** 已由 Host 绑定的作用域身份；调用方不能从请求体自报。 */
+    identity: LifecycleScopeIdentity;
+    /** 插件 manifest 申请的权限。 */
+    requested?: readonly PluginPermission[];
+    /** 可信策略批准的权限。 */
+    approved?: readonly PluginPermission[];
+    /** 当前会话约束；存在时再与申请、批准求交集。 */
+    sessionConstraints?: readonly PluginPermission[];
+    /** 内置可信策略修订；策略变化后不能复用旧租约。 */
+    policyRevision?: number;
+    /** Connect 用户授权修订；内置插件可以省略。 */
+    grantRevision?: number;
+    /** Connect/外部授权的不可猜测授权标识；最终边界仍需查权威状态。 */
+    grantId?: string;
+    /** 可选作用域；撤权时自动撤销租约。 */
+    scope?: LifecycleScope;
+}
+/** 创建一个不可换绑的权限租约。 */
+declare function createPermissionLease(options: CreatePermissionLeaseOptions): PermissionLease;
+
+interface VerifyPermissionLeaseOptions {
+    /** 已由受信装配层创建的租约。 */
+    lease: PermissionLease;
+    /** 本次实际操作所需的最小权限。 */
+    permission: PluginPermission;
+    /** 从端口 / 当前会话权威取得的绑定值。 */
+    binding?: Parameters<PermissionLease["assertBinding"]>[0];
+}
+/** 在最终 RPC / I/O 边界执行一次 fail-closed 校验。 */
+declare function verifyPermissionLease(options: VerifyPermissionLeaseOptions): void;
+
+interface CreateScopedTaskSchedulerOptions {
+    /** 注册后是否先恢复运行一次；缺省为 false，由业务显式触发。 */
+    runOnRegister?: boolean;
+}
+/** 创建绑定到一个 lifecycle scope 的任务调度器。 */
+declare function createScopedTaskScheduler(scope: LifecycleScope, options?: CreateScopedTaskSchedulerOptions): ScopedTaskScheduler & {
+    dispose(): Promise<void>;
+};
+
+interface ScopedRegistryRegistration {
+    /** 注册方法名，例如 register / registerFeature。 */
+    method: string;
+    /** 从参数哪个位置读取带 id 的定义。 */
+    idArgument?: number;
+    /** 没有返回取消函数时使用的注销方法。 */
+    unregisterMethod?: string;
+    /** 注销方法的参数位置；默认使用 idArgument。 */
+    unregisterArgument?: number;
+    /** 含 ownerPluginId 参数的注册方法；由 Host 绑定当前插件身份。 */
+    bindPluginIdArgument?: number;
+    /** 定义对象中的 ownerPluginId 字段；存在时必须与当前插件一致。 */
+    ownerPluginIdProperty?: string;
+}
+interface CreateScopedRegistryFacadeOptions {
+    /** 日志和作用域资源中显示的注册表名。 */
+    name: string;
+    /** 注册方法规则；缺省只包装 register(item)。 */
+    registrations?: readonly ScopedRegistryRegistration[];
+}
+/** 创建一个只对当前插件实例开放的 Registry 视图。 */
+declare function createScopedRegistryFacade<T extends object>(target: T, scope: LifecycleScope, options: CreateScopedRegistryFacadeOptions): T;
+
+/** 创建一个绑定当前构建和接管世代的升级门禁。 */
+declare function createUpgradeGate(options: CreateUpgradeGateOptions): UpgradeGate;
+
+interface MessagePortServiceCallInput {
+    /** 已验证的 call message；request 已由生产 parser 规范化。 */
+    readonly message: RuntimeCallMessage;
+    /** parser 规范化后的请求。 */
+    readonly request: unknown;
+    /** 服务绑定身份。 */
+    readonly reference: ServiceReference;
+    /** 取消信号。 */
+    readonly signal: AbortSignal;
+    /** 本端以接收时钟计算的调用截止时间。 */
+    readonly deadlineAt: number;
+    /** 对端 peer 视图。 */
+    readonly peer?: CapabilityPeer;
+}
+interface PreparedRequest {
+    /** parser 规范化后的 DTO。 */
+    readonly value: unknown;
+    /** 契约声明的 transfer。 */
+    readonly transfer?: readonly Transferable[];
+    /** 可选的已计算计费值。 */
+    readonly budgetBytes?: number;
+}
+interface MessagePortServiceProviderOptions {
+    /** 兼容 standalone/testing 的当前 MessagePort；实际 Runtime 使用 shared transport。 */
+    readonly port?: MessagePortLike;
+    /** 当前物理 endpoint 的唯一 v4 transport。 */
+    readonly transport?: RuntimeTransport;
+    /** 当前可暴露的服务；返回空集合即拒绝新的调用。 */
+    readonly services: () => readonly ServiceReference[];
+    /** 调用 Host handler。 */
+    readonly handleCall: (input: MessagePortServiceCallInput) => unknown | Promise<unknown | AsyncIterable<unknown>>;
+    /** 当前 peer scope。 */
+    readonly peerScope?: LifecycleScope;
+    /** 默认 peer view；peerForCall 可按 handler 依赖进一步收窄。 */
+    readonly peer?: CapabilityPeer;
+    /** 当前 handler 所属插件允许观察的 peer view。 */
+    readonly peerForCall?: (call: RuntimeCallMessage, reference: ServiceReference) => CapabilityPeer | undefined;
+    /** 接收 request 的 parser/transfer 适配。 */
+    readonly prepareRequest?: (call: RuntimeCallMessage, ledger: ReceivePortLedger) => PreparedRequest;
+    /** 发送前验证/提取 unary response。 */
+    readonly prepareResult?: (value: unknown, call: RuntimeCallMessage) => PreparedRequest;
+    /** 发送前验证/提取 stream item。 */
+    readonly prepareItem?: (value: unknown, call: RuntimeCallMessage) => PreparedRequest;
+    /** 可信 Runtime/advanced 装配预算。 */
+    readonly limits?: RuntimeLimitsInput;
+    /** 可选的 Runtime 方向共享计数器。 */
+    readonly budget?: RuntimeBudget;
+}
+/** 创建一个严格 bounded 的 MessagePort provider。 */
+declare function createMessagePortServiceProvider(options: MessagePortServiceProviderOptions): {
+    setServices(): void;
+    dispose(): void;
+    pendingCount(): number;
+    executionCount(): number;
+    nonCooperativeExecutionCount(): number;
+    retainedPayloadBytes(): number;
+};
+
+/** Resource Store 的 advanced 类型出口；显式 alias 可被 dts bundler 保留。 */
+type ResourceStoreApi = ResourceStoreApi$1;
+
+/** 分阶段向已经拥有的 App 注册新的 typed plugin definitions。 */
+declare function registerPlugins(app: WindowApp, definitions: readonly RuntimePluginDefinition[]): Promise<void>;
+/** 把一个连接绑定到现有 WindowApp；替换时先撤销旧 bridge。 */
+declare function attachRemote(app: WindowApp, runtime: RuntimeHandle): Promise<() => void>;
+
+export { type CreatePermissionLeaseOptions, type CreateScopedRegistryFacadeOptions, type CreateScopedTaskSchedulerOptions, MessagePortLike, type MessagePortServiceCallInput, type MessagePortServiceProviderOptions, type PluginGraphOptions, type PreparedRequest, type ResourceStoreApi, RuntimeCallMessage, RuntimeTransport, type ScopedRegistryRegistration, type VerifyPermissionLeaseOptions, attachRemote, buildPluginGraph, createMessagePortServiceProvider, createPermissionLease, createScopedRegistryFacade, createScopedTaskScheduler, createUpgradeGate, dependenciesOfManifest, providesOfManifest, registerPlugins, reverseDependentsOf, selectRuntimeUnit, validatePluginGraph, verifyPermissionLease };