@webskill/sdk 0.3.0 → 0.4.0

package/dist/{openUiLibrary-B8-Cvou9-BbpNTXS3.js → openUiLibrary-YLS-cxyT-C96jWDQq.js}

@@ -1,5 +1,5 @@
-import { ft as uiCatalog } from "./dist-ZKaM8j06.js";
-import { n as catalogComponentImpls } from "./catalogComponents-C_V39rbF-BOHveMWa.js";
+import { q as uiCatalog } from "./dist-D9Lcn5Pp.js";
+import { t as CatalogNode } from "./catalogComponents-KsujmL4b-Clx1kCnU.js";
 import { z } from "zod";
 import { Component, Fragment, createContext, useCallback, useContext, useEffect, useInsertionEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -3761,7 +3761,7 @@ function Renderer({ response, library, isStreaming = false, onAction, onStateUpd
 const FormValidationContext = createContext(null);
 
 //#endregion
-//#region ../ui-react/dist/openUiLibrary-B8-Cvou9.js
+//#region ../ui-react/dist/openUiLibrary-YLS-cxyT.js
 const propsFor = (props, container) => container ? props.extend({ children: z.array(z.any()).optional() }) : props;
 /**
 * catalog 的 OpenUI 投影：`defineComponent` 复用同一份 zod schema 与描述，
@@ -3773,10 +3773,11 @@ const webskillOpenUiLibrary = createLibrary({
 		name: def.name,
 		description: def.description,
 		props: propsFor(def.props, def.children !== void 0),
-		component: ((input) => catalogComponentImpls[def.name]?.({
+		component: ((input) => /* @__PURE__ */ jsx(CatalogNode, {
+			name: def.name,
 			props: input.props,
 			children: input.renderNode(input.props["children"])
-		}) ?? null)
+		}))
 	}))
 });
 const OPEN_UI_COMPONENTS = Object.keys(webskillOpenUiLibrary.components);

package/dist/{skillVersionStore-DOEI9ptb-BxbYL70B.d.ts → skillVersionStore-uyefLPR1-DXOzbksv.d.ts}

@@ -1,5 +1,5 @@
-import { P as FileSystemProvider, X as SkillCatalogEntry, rt as SkillManifest } from "./types-AmKCKJn_-VGabeXK4.js";
-//#region ../governance/dist/skillVersionStore-DOEI9ptb.d.ts
+import { N as FileSystemProvider, R as Page, Z as SkillCatalogEntry, it as SkillManifest, z as PageQuery } from "./types-7Wcg--Vh-1YlQ4jF9.js";
+//#region ../governance/dist/skillVersionStore-uyefLPR1.d.ts
 //#region src/types.d.ts
 type CandidateStatus = 'draft' | 'pending-review' | 'approved' | 'published' | 'rejected';
 type CandidateSource = 'runtime-miss' | 'document' | 'manual';
@@ -35,16 +35,32 @@ interface AuditEvent {
   /** 本事件规范化载荷 + prevHash 的 sha256 */
   hash?: string;
 }
+/**
+ * 审计查询的筛选条件。刻意是**具名字段**而不是谓词函数：
+ * 谓词无法被存储层用索引优化，下推一个谓词等于把 `.filter()` 换了个位置。
+ * @stable
+ */
+interface AuditQueryFilter {
+  target?: string;
+  type?: string;
+  actor?: string;
+  /** 含端点（`ts >= since`） */
+  since?: string;
+  /** 含端点（`ts <= until`） */
+  until?: string;
+}
 interface AuditLog {
   append(event: Omit<AuditEvent, 'id' | 'ts'> & {
     id?: string;
     ts?: string;
   }): Promise<AuditEvent>;
-  query(filter: {
-    target?: string;
-    type?: string;
-    since?: string;
-  }): Promise<AuditEvent[]>;
+  /**
+   * 分页查询。方向与会话消息一致：无游标给**最新**一页，`nextCursor` 指向更早的历史。
+   *
+   * 分页是性能优化，不是绕过完整性检查的通道：本页范围内的 hash 链断裂
+   * 必须以 `GOVERNANCE_FAILED` 报出，不得安静地把那一页返回。
+   */
+  query(filter?: AuditQueryFilter & PageQuery): Promise<Page<AuditEvent>>;
 }
 interface SkillVersion {
   versionId: string;
@@ -59,6 +75,8 @@ interface SkillVersion {
 type SkillState = 'active' | 'quarantined' | 'deprecated' | 'disabled';
 //#endregion
 //#region src/candidate/candidateStore.d.ts
+/** 候选列表的缺省页长。缺省属于实现，不属于调用方 */
+declare const CANDIDATE_PAGE_SIZE = 50;
 /** 逐文件持久化的候选存储：<managedRoot>/.webskill/candidates/<id>.json */
 declare class CandidateStore {
   #private;
@@ -68,7 +86,14 @@ declare class CandidateStore {
   });
   save(candidate: CandidateSkill): Promise<void>;
   get(id: string): Promise<CandidateSkill>;
-  list(): Promise<CandidateSkill[]>;
+  /**
+   * 候选（= 审批队列）分页。`status` 是端口参数而不是上层 `.filter()`：
+   * 审批页面只看 `pending-review`，没理由把已发布的候选全部拉过端口。
+   * 目录扫描仍是逐文件读（备案 D25），但返回量已由 `limit` 封顶。
+   */
+  list(options?: {
+    status?: CandidateStatus;
+  } & PageQuery): Promise<Page<CandidateSkill>>;
   updateStatus(id: string, status: CandidateStatus, now?: string): Promise<CandidateSkill>;
 }
 /** 硬门禁：仅 published 可转换为 Catalog 条目，否则 APPROVAL_REQUIRED */
@@ -94,6 +119,8 @@ declare class CompositeApprovalPolicy implements ApprovalPolicy {
 }
 //#endregion
 //#region src/versioning/skillVersionStore.d.ts
+/** 版本列表的缺省页长。缺省属于实现，不属于调用方 */
+declare const SKILL_VERSION_PAGE_SIZE = 20;
 /** 版本存储：manifest 快照 + parentVersionId 链；回滚 = 追加新版本（谱系不断）。
  *  保留策略：maxArchivesPerSkill（默认 5）超出时清理最旧版本（json + zip 归档一并删除）。 */
 declare class SkillVersionStore {
@@ -115,7 +142,11 @@ declare class SkillVersionStore {
   }): Promise<SkillVersion>;
   /** 读取版本归档字节（applyRollback 用；未捕获归档的旧版本 → GOVERNANCE_FAILED） */
   readArchive(skillName: string, versionId: string): Promise<Uint8Array>;
-  list(skillName: string): Promise<SkillVersion[]>;
+  /**
+   * 版本列表分页（方向同 C1：无游标给**最新**一页）。
+   * 保留策略与谱系构建走 `#readAll`：它们必须看到全量，不能被分页截断。
+   */
+  list(skillName: string, options?: PageQuery): Promise<Page<SkillVersion>>;
   get(skillName: string, versionId: string): Promise<SkillVersion>;
   /** 回滚：基于旧 manifest 追加新版本 + skill.rolled_back 审计 */
   rollback(skillName: string, targetVersionId: string, input: {
@@ -124,4 +155,4 @@ declare class SkillVersionStore {
   }): Promise<SkillVersion>;
 }
 //#endregion
-export { AuditLog as a, CandidateSkill as c, CandidateStore as d, CompositeApprovalPolicy as f, candidateToCatalogEntry as g, SkillVersionStore as h, AuditEvent as i, CandidateSource as l, SkillVersion as m, ApprovalDecision as n, CandidateFile as o, SkillState as p, ApprovalPolicy as r, CandidateRisk as s, AlwaysHumanApprovalPolicy as t, CandidateStatus as u };
+export { SkillVersion as _, AuditLog as a, CandidateFile as c, CandidateSource as d, CandidateStatus as f, SkillState as g, SKILL_VERSION_PAGE_SIZE as h, AuditEvent as i, CandidateRisk as l, CompositeApprovalPolicy as m, ApprovalDecision as n, AuditQueryFilter as o, CandidateStore as p, ApprovalPolicy as r, CANDIDATE_PAGE_SIZE as s, AlwaysHumanApprovalPolicy as t, CandidateSkill as u, SkillVersionStore as v, candidateToCatalogEntry as y };

package/dist/{testing-CsrG3XLz.js → testing-DDCJWvgA.js}

@@ -1,4 +1,5 @@
 import { m as WebSkillError } from "./dist-8oQRa8Xz.js";
+import { i as textParts, n as partsToText } from "./memoryArtifactStore-BtOeB_hm-tj3fC5ip.js";
 
 //#region ../runtime/dist/testing.js
 /**
@@ -27,7 +28,7 @@ var MockLlmClient = class {
 			else if (event.type === "tool-calls") toolCalls = event.toolCalls;
 			else if (event.type === "done" && event.content !== void 0) content = event.content;
 			return {
-				content,
+				content: content === "" ? void 0 : textParts(content),
 				toolCalls
 			};
 		}
@@ -43,11 +44,12 @@ var MockLlmClient = class {
 			return;
 		}
 		const response = typeof next === "function" ? await next(input) : next;
-		if (response.content) {
-			const chunkSize = Math.max(1, Math.ceil(response.content.length / 3));
-			for (let i = 0; i < response.content.length; i += chunkSize) yield {
+		const text = partsToText(response.content);
+		if (text !== "") {
+			const chunkSize = Math.max(1, Math.ceil(text.length / 3));
+			for (let i = 0; i < text.length; i += chunkSize) yield {
 				type: "text-delta",
-				delta: response.content.slice(i, i + chunkSize)
+				delta: text.slice(i, i + chunkSize)
 			};
 		}
 		if (response.toolCalls?.length) yield {

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { c as LlmClient, d as LlmResponse, f as LlmStreamEvent, h as MemoryStore, l as LlmCompleteInput, n as ArtifactStore, o as InteractionRequest, s as InteractionResponse, t as Artifact, v as UiBridge } from "./types-AmKCKJn_-VGabeXK4.js";
+import { c as LlmClient, f as LlmResponse, g as MemoryStore, l as LlmCompleteInput, n as ArtifactStore, o as InteractionRequest, p as LlmStreamEvent, s as InteractionResponse, t as Artifact, y as UiBridge } from "./types-7Wcg--Vh-1YlQ4jF9.js";
 import { a as loadGoogleConfigFromEnv, i as loadAnthropicConfigFromEnv, n as LlmEnvConfig, o as loadLlmConfigFromEnv, r as ProviderEnvConfig } from "./env-BPUBZCwJ-4jat_SVG.js";
 //#region ../runtime/dist/testing.d.ts
 //#region src/llm/mockLlmClient.d.ts

package/dist/testing.js

@@ -1,5 +1,5 @@
-import { t as MemoryArtifactStore } from "./memoryArtifactStore-C9lFVqPF-yFz6yJj0.js";
+import { t as MemoryArtifactStore } from "./memoryArtifactStore-BtOeB_hm-tj3fC5ip.js";
 import { n as loadGoogleConfigFromEnv, r as loadLlmConfigFromEnv, t as loadAnthropicConfigFromEnv } from "./env--jJB-TSX-04klhTYi.js";
-import { n as MockLlmClient, r as MockUiBridge, t as InMemoryStore } from "./testing-CsrG3XLz.js";
+import { n as MockLlmClient, r as MockUiBridge, t as InMemoryStore } from "./testing-DDCJWvgA.js";
 
 export { InMemoryStore, MemoryArtifactStore, MockLlmClient, MockUiBridge, loadAnthropicConfigFromEnv, loadGoogleConfigFromEnv, loadLlmConfigFromEnv };

package/dist/{types-AmKCKJn_-VGabeXK4.d.ts → types-7Wcg--Vh-1YlQ4jF9.d.ts}

@@ -1,6 +1,6 @@
 //#region ../core/dist/index.d.ts
 //#region src/errors.d.ts
-type WebSkillErrorCode = 'FS_NOT_FOUND' | 'FS_PATH_OUTSIDE_ROOT' | 'SKILL_NOT_FOUND' | 'SKILL_INVALID_METADATA' | 'SKILL_INVALID_NAME' | 'SKILL_DUPLICATE_NAME' | 'SKILL_UNSUPPORTED_SCRIPT' | 'VALIDATION_FAILED' | 'TOOL_NOT_FOUND' | 'TOOL_EXECUTION_FAILED' | 'NETWORK_BLOCKED' | 'TOOL_UNSUPPORTED' | 'TOOL_SCHEMA_UNAVAILABLE' | 'RUN_TIMEOUT' | 'RUN_MAX_TURNS_EXCEEDED' | 'RUN_FAILED' | 'RUN_CANCELLED' | 'RUN_INTERACTION_TIMEOUT' | 'UI_UNAVAILABLE' | 'LLM_UNAVAILABLE' | 'LLM_REQUEST_FAILED' | 'INSTALL_FAILED' | 'UNINSTALL_FAILED' | 'EXPORT_FAILED' | 'INTEGRITY_FAILED' | 'FS_PERMISSION_DENIED' | 'MCP_ENDPOINT_UNAVAILABLE' | 'MCP_TOOL_NOT_FOUND' | 'CANDIDATE_INVALID' | 'APPROVAL_REQUIRED' | 'SKILL_QUARANTINED' | 'SKILL_DISABLED' | 'SKILL_UNKNOWN_ALLOWED_TOOL' | 'SKILL_UNKNOWN_DEPENDENCY' | 'SKILL_CIRCULAR_DEPENDENCY' | 'GOVERNANCE_FAILED' | 'RUN_SNAPSHOT_NOT_FOUND' | 'RUN_SNAPSHOT_EXPIRED' | 'RUN_SNAPSHOT_INCOMPATIBLE' | 'RUN_TRACE_INCOMPATIBLE' | 'SESSION_INCOMPATIBLE' | 'SIGNATURE_MISSING' | 'SIGNATURE_MALFORMED' | 'SIGNATURE_UNTRUSTED_KEY' | 'SIGNATURE_MISMATCH' | 'SIGNATURE_UNSUPPORTED' | 'MCP_STDIO_SPAWN_FAILED' | 'MCP_STDIO_EXITED' | 'MCP_STDIO_TIMEOUT';
+type WebSkillErrorCode = 'FS_NOT_FOUND' | 'FS_PATH_OUTSIDE_ROOT' | 'SKILL_NOT_FOUND' | 'SKILL_INVALID_METADATA' | 'SKILL_INVALID_NAME' | 'SKILL_DUPLICATE_NAME' | 'SKILL_UNSUPPORTED_SCRIPT' | 'VALIDATION_FAILED' | 'TOOL_NOT_FOUND' | 'TOOL_EXECUTION_FAILED' | 'NETWORK_BLOCKED' | 'TOOL_UNSUPPORTED' | 'TOOL_NOT_ALLOWED' | 'TOOL_SCHEMA_UNAVAILABLE' | 'RUN_TIMEOUT' | 'RUN_MAX_TURNS_EXCEEDED' | 'RUN_FAILED' | 'RUN_CANCELLED' | 'RUN_INTERACTION_TIMEOUT' | 'UI_UNAVAILABLE' | 'LLM_UNAVAILABLE' | 'LLM_REQUEST_FAILED' | 'INSTALL_FAILED' | 'UNINSTALL_FAILED' | 'EXPORT_FAILED' | 'INTEGRITY_FAILED' | 'FS_PERMISSION_DENIED' | 'MCP_ENDPOINT_UNAVAILABLE' | 'MCP_TOOL_NOT_FOUND' | 'CANDIDATE_INVALID' | 'APPROVAL_REQUIRED' | 'SKILL_QUARANTINED' | 'SKILL_DISABLED' | 'SKILL_UNKNOWN_ALLOWED_TOOL' | 'SKILL_UNKNOWN_DEPENDENCY' | 'SKILL_CIRCULAR_DEPENDENCY' | 'GOVERNANCE_FAILED' | 'RUN_SNAPSHOT_NOT_FOUND' | 'RUN_SNAPSHOT_EXPIRED' | 'RUN_SNAPSHOT_INCOMPATIBLE' | 'RUN_SNAPSHOT_SCHEMA_UNSUPPORTED' | 'RUN_TRACE_INCOMPATIBLE' | 'SESSION_INCOMPATIBLE' | 'SIGNATURE_MISSING' | 'SIGNATURE_MALFORMED' | 'SIGNATURE_UNTRUSTED_KEY' | 'SIGNATURE_MISMATCH' | 'SIGNATURE_UNSUPPORTED' | 'MCP_STDIO_SPAWN_FAILED' | 'MCP_STDIO_EXITED' | 'MCP_STDIO_TIMEOUT';
 /**
  * 所有公开 API 抛出的结构化错误，code 供上层可编程处理
  * @stable
@@ -29,6 +29,27 @@ interface JsonSchema {
   [key: string]: unknown;
 }
 //#endregion
+//#region src/contracts/pagination.d.ts
+/**
+ * 全仓统一的游标分页形状。会话、消息、治理列表共用同一套，
+ * 不为每个存储端口各造一种（形状一多，调用方就得为每个端口重写一遍翻页逻辑）。
+ */
+interface PageQuery {
+  /**
+   * 不透明续读位置，只能来自上一页的 `nextCursor`。
+   * 刻意不是数字 offset：追加型存储上并发追加会让 offset 错位，
+   * 而不透明串让实现方自己决定编码。
+   */
+  cursor?: string;
+  /** 本页最多返回多少条；缺省值由**存储实现**决定，不由调用方兜底 */
+  limit?: number;
+}
+/** 一页结果。`nextCursor` 缺席即已到末页，不用额外的 `hasMore` 布尔 */
+interface Page<T> {
+  items: T[];
+  nextCursor?: string;
+}
+//#endregion
 //#region src/skill/manifest.d.ts
 type SkillInstallSource = {
   type: 'local';
@@ -181,7 +202,12 @@ interface SkillSignature {
   signature: string;
   signedAt: string;
 }
-/** 未签名包的处置策略；0.3.0 默认 `warn`，0.4.0 与 D10 一起收紧 */
+/**
+ * 未签名包的处置策略。默认是 `warn`，0.4.0（D2）复核后维持不变：
+ * 默认信任库是空的，`deny` 之下未签名包报 `SIGNATURE_MISSING`、签名再正确也报
+ * `SIGNATURE_UNTRUSTED_KEY`——接受集为空，那不是更严的默认值而是恒失败的安装。
+ * `deny` 必须与装配好的 `TrustedKeyStore` 成对启用。
+ */
 type UnsignedPolicy = 'allow' | 'warn' | 'deny';
 interface TrustedKey {
   keyId: string;
@@ -342,6 +368,22 @@ interface RemoteUrlPolicy {
  */
 declare function assertRemoteUrlAllowed(rawUrl: string, policy?: RemoteUrlPolicy): URL;
 //#endregion
+//#region src/ui/types.d.ts
+/**
+ * 声明式 UI 的节点：框架无关，技能脚本与 LLM 产出同一形状。
+ *
+ * 定义放在 core 而不是 ui/runtime：runtime 要用它做结构校验，ui 要用它做 catalog
+ * 语义校验，两者互不依赖。`@webskill/ui` 以同名 re-export，公开名不变。
+ */
+interface UiSpecNode {
+  /** catalog 中声明过的组件名 */
+  component: string;
+  props?: Record<string, unknown>;
+  children?: UiSpecNode[];
+  /** 稳定 id（回放与 action 关联用；交互节点以此作为 actionId） */
+  id?: string;
+}
+//#endregion
 //#region src/skill/types.d.ts
 type SkillSource = 'local' | 'mcp' | 'generated' | 'installed';
 /**
@@ -540,7 +582,7 @@ declare function escapeXml(text: string): string;
 declare function renderAvailableSkillsXml(catalog: SkillCatalog): string;
 declare const xmlRenderer: CatalogRenderer;
 //#endregion
-//#region ../runtime/dist/types-AmKCKJn_.d.ts
+//#region ../runtime/dist/types-7Wcg--Vh.d.ts
 //#region src/llm/streamTypes.d.ts
 /** 流式 LLM 事件（OpenAI SSE / Vercel fullStream 统一映射） */
 type LlmStreamEvent = {
@@ -555,9 +597,26 @@ type LlmStreamEvent = {
 };
 //#endregion
 //#region src/llm/types.d.ts
+/**
+ * 消息内容分片。二进制一律 base64 内联：引用形态（URL / 句柄）需要生命周期管理，
+ * 不属于本批。代价是快照体积。
+ */
+type LlmContentPart = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'image';
+  mimeType: string;
+  data: string;
+} | {
+  type: 'file';
+  mimeType: string;
+  data: string;
+  name?: string;
+};
 interface LlmMessage {
   role: 'system' | 'user' | 'assistant' | 'tool';
-  content: string;
+  content: LlmContentPart[];
   /** role=tool 时必填 */
   toolCallId?: string;
   /** role=assistant 发起工具调用时携带 */
@@ -576,7 +635,7 @@ interface LlmToolCall {
   argumentsParseError?: string;
 }
 interface LlmResponse {
-  content?: string;
+  content?: LlmContentPart[];
   toolCalls?: LlmToolCall[];
   raw?: unknown;
 }
@@ -703,14 +762,16 @@ interface RenderResultRequest {
   artifacts?: Artifact[];
 }
 /** A user action exposed by a generative UI surface. @experimental */
-interface UiSurfaceAction {
+interface UiSpecActionCapability {
+  /** Matches the `id` of the interactive node that declares the action. */
   id: string;
-  label: string;
   intent: 'submit' | 'cancel' | 'select' | 'download' | 'refresh';
-  disabled?: boolean;
   /** Requests that the producing run waits for this action before continuing. @experimental */
   awaitResponse?: boolean;
-  /** Runtime-generated action capability; model-provided values are never trusted. @experimental */
+  /**
+   * Runtime-generated action capability. Kept out of the node tree on purpose:
+   * the tree is model-writable, so a nonce carried inside it would be forgeable.
+   */
   nonce?: string;
 }
 /** A runtime-owned request for a user action on a rendered UI surface. @experimental */
@@ -718,7 +779,7 @@ interface UiSurfaceActionRequest {
   runId: string;
   surfaceId: string;
   actionId: string;
-  intent: UiSurfaceAction['intent'];
+  intent: UiSpecActionCapability['intent'];
   nonce: string;
 }
 /** A structured action returned by a renderer to the waiting run. @experimental */
@@ -727,75 +788,26 @@ interface UiSurfaceActionResponse extends UiSurfaceActionRequest {
   cancelled?: boolean;
 }
 /** Serializable draft values for forms that belong to one interrupted run. @experimental */
-type UiSurfaceDrafts = Record<string, Record<string, unknown>>;
-/** A structured form field rendered inside a generative UI surface. @experimental */
-interface UiSurfaceFormField {
-  name: string;
-  label: string;
-  type: 'text' | 'number' | 'date' | 'textarea' | 'select' | 'multi-select' | 'toggle' | 'file';
-  required?: boolean;
-  description?: string;
-  defaultValue?: unknown;
-  options?: Array<{
-    label: string;
-    value: unknown;
-  }>;
-}
-/** Framework-neutral generative UI surface. @experimental */
-type UiSurface = {
-  kind: 'form';
-  id: string;
-  title?: string;
-  fields: UiSurfaceFormField[];
-  actions: UiSurfaceAction[];
-} | {
-  kind: 'chart';
-  id: string;
-  chart: ChartSpec;
-  actions?: UiSurfaceAction[];
-} | {
-  kind: 'table';
-  id: string;
-  columns: string[];
-  rows: unknown[][];
-  actions?: UiSurfaceAction[];
-} | {
-  kind: 'metric';
-  id: string;
-  label: string;
-  value: string | number;
-  trend?: 'up' | 'down' | 'neutral';
-} | {
-  kind: 'file';
-  id: string;
-  path: string;
-  mimeType?: string;
-  size?: number;
-  actions?: UiSurfaceAction[];
-} | {
-  kind: 'custom';
-  id: string;
-  component: string;
-  props: unknown;
-  actions?: UiSurfaceAction[];
-};
-/** A bounded mutation applied to an existing UI surface. @experimental */
-interface UiSurfacePatch {
+type UiSpecDrafts = Record<string, Record<string, unknown>>;
+/** A bounded mutation applied to an existing UI spec tree. @experimental */
+interface UiSpecPatch {
   op: 'replace' | 'merge' | 'append';
   path: string;
   value: unknown;
 }
 /** Incremental lifecycle event for a framework-neutral generative UI surface. @experimental */
-type UiSurfaceEvent = {
+type UiSpecEvent = {
   runId?: string;
 } & ({
   type: 'open';
-  surface: UiSurface;
+  id: string;
+  node: UiSpecNode;
+  actions?: UiSpecActionCapability[];
 } | {
   type: 'patch';
   id: string;
   revision: number;
-  operations: UiSurfacePatch[];
+  operations: UiSpecPatch[];
 } | {
   type: 'complete';
   id: string;
@@ -810,8 +822,10 @@ type UiSurfaceEvent = {
   id: string;
 });
 /** Persisted state of a generative UI surface. @experimental */
-interface UiSurfaceSnapshot {
-  surface: UiSurface;
+interface UiSpecSnapshot {
+  id: string;
+  node: UiSpecNode;
+  actions?: UiSpecActionCapability[];
   revision: number;
   status: 'active' | 'complete' | 'error' | 'cancelled';
   /** Immutable producing run; supplied on open to support session persistence and replay. */
@@ -834,7 +848,7 @@ interface UiBridge {
   /** 定义即可，阶段 7 消费 */
   renderResult?(input: RenderResultRequest): Promise<void>;
   /** Framework-neutral generative UI surface stream. @experimental */
-  renderSurface?(event: UiSurfaceEvent): Promise<void>;
+  renderSurface?(event: UiSpecEvent): Promise<void>;
   /** Waits for an action declared with awaitResponse; optional for compatibility with legacy bridges. @experimental */
   requestSurfaceAction?(input: UiSurfaceActionRequest): Promise<UiSurfaceActionResponse>;
   /** Best-effort cleanup when a surface action wait times out or is cancelled. @experimental */
@@ -878,4 +892,4 @@ interface MemoryStore {
   transaction?<T>(scope: string, fn: (inner: MemoryStore) => Promise<T>): Promise<T>;
 }
 //#endregion
-export { SkillInstallSource as $, CryptoKeyLike as A, messageOf as At, SIGNATURE_SCHEMA_VERSION as B, signSkill as Bt, UiSurfaceDrafts as C, checkSkillRules as Ct, UiSurfaceSnapshot as D, isValidSkillName as Dt, UiSurfacePatch as E, exportSkills as Et, FsTrustedKeyStore as F, readSkillSignature as Ft, SKILL_PACK_FILE as G, verifySkillSignature as Gt, SKILL_MANIFEST_FILE as H, unzipWithLimits as Ht, JsonSchema as I, renderAvailableSkillsXml as It, SignatureVerdict as J, SKILL_SIGNATURE_FILE as K, xmlRenderer as Kt, MANIFEST_EXCLUDED_FILES as L, renderCatalogJson as Lt, DiscoveryResult as M, parseSkillMarkdown as Mt, FileStat as N, parseSkillPackManifest as Nt, ArchiveLimits as O, jsonRenderer as Ot, FileSystemProvider as P, readResponseWithLimit as Pt, SkillDocument as Q, MemoryFS as R, resolveArchiveLimits as Rt, UiSurfaceActionResponse as S, checkDependencyCycles as St, UiSurfaceFormField as T, escapeXml as Tt, SKILL_NAME_MAX_LENGTH as U, validateSkills as Ut, SKILLS_LOCKFILE as V, signaturePayloadBytes as Vt, SKILL_NAME_PATTERN as W, verifyManifest as Wt, SkillCatalogEntry as X, SkillCatalog as Y, SkillDiscovery as Z, RenderResultRequest as _, assertRemoteUrlAllowed as _t, InteractionPolicy as a, SkillPackManifest as at, UiSurfaceAction as b, buildCatalog as bt, LlmClient as c, SkillSource as ct, LlmResponse as d, TrustedKeyStore as dt, SkillIssue as et, LlmStreamEvent as f, UnsignedPolicy as ft, RenderBlock as g, WebSkillErrorCode as gt, MemoryStore as h, WebSkillError as ht, FormField as i, SkillMetadata as it, DEFAULT_ARCHIVE_LIMITS as j, normalizePath as jt, CatalogRenderer as k, keyIdOf as kt, LlmCompleteInput as l, SkillsLockfile as lt, LlmToolSpec as m, VerifyResult as mt, ArtifactStore as n, SkillManagerPort as nt, InteractionRequest as o, SkillReader as ot, LlmToolCall as p, ValidationReport as pt, SignatureAuditSink as q, ChartSpec as r, SkillManifest as rt, InteractionResponse as s, SkillSignature as st, Artifact as t, SkillLocation as tt, LlmMessage as u, TrustedKey as ut, UiBridge as v, assertSafePathSegment as vt, UiSurfaceEvent as w, computeDigest as wt, UiSurfaceActionRequest as x, buildManifest as xt, UiSurface as y, atomicWriteText as yt, RemoteUrlPolicy as z, resolveInsideRoot as zt };
+export { SkillDocument as $, DEFAULT_ARCHIVE_LIMITS as A, jsonRenderer as At, RemoteUrlPolicy as B, resolveArchiveLimits as Bt, UiSpecPatch as C, buildManifest as Ct, ArchiveLimits as D, escapeXml as Dt, UiSurfaceActionResponse as E, computeDigest as Et, JsonSchema as F, parseSkillPackManifest as Ft, SKILL_NAME_PATTERN as G, validateSkills as Gt, SKILLS_LOCKFILE as H, signSkill as Ht, MANIFEST_EXCLUDED_FILES as I, readResponseWithLimit as It, SignatureAuditSink as J, xmlRenderer as Jt, SKILL_PACK_FILE as K, verifyManifest as Kt, MemoryFS as L, readSkillSignature as Lt, FileStat as M, messageOf as Mt, FileSystemProvider as N, normalizePath as Nt, CatalogRenderer as O, exportSkills as Ot, FsTrustedKeyStore as P, parseSkillMarkdown as Pt, SkillDiscovery as Q, Page as R, renderAvailableSkillsXml as Rt, UiSpecEvent as S, buildCatalog as St, UiSurfaceActionRequest as T, checkSkillRules as Tt, SKILL_MANIFEST_FILE as U, signaturePayloadBytes as Ut, SIGNATURE_SCHEMA_VERSION as V, resolveInsideRoot as Vt, SKILL_NAME_MAX_LENGTH as W, unzipWithLimits as Wt, SkillCatalog as X, SignatureVerdict as Y, SkillCatalogEntry as Z, RenderBlock as _, WebSkillError as _t, InteractionPolicy as a, SkillMetadata as at, UiSpecActionCapability as b, assertSafePathSegment as bt, LlmClient as c, SkillSignature as ct, LlmMessage as d, TrustedKey as dt, SkillInstallSource as et, LlmResponse as f, TrustedKeyStore as ft, MemoryStore as g, VerifyResult as gt, LlmToolSpec as h, ValidationReport as ht, FormField as i, SkillManifest as it, DiscoveryResult as j, keyIdOf as jt, CryptoKeyLike as k, isValidSkillName as kt, LlmCompleteInput as l, SkillSource as lt, LlmToolCall as m, UnsignedPolicy as mt, ArtifactStore as n, SkillLocation as nt, InteractionRequest as o, SkillPackManifest as ot, LlmStreamEvent as p, UiSpecNode as pt, SKILL_SIGNATURE_FILE as q, verifySkillSignature as qt, ChartSpec as r, SkillManagerPort as rt, InteractionResponse as s, SkillReader as st, Artifact as t, SkillIssue as tt, LlmContentPart as u, SkillsLockfile as ut, RenderResultRequest as v, WebSkillErrorCode as vt, UiSpecSnapshot as w, checkDependencyCycles as wt, UiSpecDrafts as x, atomicWriteText as xt, UiBridge as y, assertRemoteUrlAllowed as yt, PageQuery as z, renderCatalogJson as zt };