@webskill/sdk 0.2.5 → 0.2.7

package/dist/{index-CsDJvYGV.d.ts → index-BHL5FWGw.d.ts}

@@ -1,5 +1,5 @@
-import { B as SkillManifest, C as FileStat, G as SkillsLockfile, L as SkillInstallSource, T as JsonSchema, _ as RenderResultRequest, o as InteractionRequest, q as VerifyResult, s as InteractionResponse, v as UiBridge, w as FileSystemProvider, y as ArchiveLimits } from "./types-CKm5G_eQ-krKWW8WV.js";
-import { N as NetworkPolicy, Q as ScriptExecutor, X as SchemaInferer, Z as ScriptExecutionContext, b as FsArtifactStore, d as BridgeCapabilities, it as ToolResult, nt as ToolDefinition, u as ApprovalScope, x as FsMemoryStore } from "./index-DfINBEOy.js";
+import { K as SkillInstallSource, M as FileStat, N as FileSystemProvider, O as ArchiveLimits, P as JsonSchema, Y as SkillManifest, _ as RenderResultRequest, et as SkillsLockfile, nt as VerifyResult, o as InteractionRequest, s as InteractionResponse, v as UiBridge } from "./types-7fnqDVrf-BnRQjVU3.js";
+import { N as NetworkPolicy, Q as ScriptExecutor, X as SchemaInferer, Z as ScriptExecutionContext, b as FsArtifactStore, d as BridgeCapabilities, it as ToolResult, nt as ToolDefinition, u as ApprovalScope, x as FsMemoryStore } from "./index-BpIK7tJM.js";
 import { Readable, Writable } from "node:stream";
 //#region ../node/dist/index.d.ts
 //#region src/fs/nodeFs.d.ts

package/dist/index-BNQNSDKg.d.ts

@@ -0,0 +1,580 @@
+import { D as UiSurfaceSnapshot, P as JsonSchema, _ as RenderResultRequest, b as UiSurfaceAction, g as RenderBlock, o as InteractionRequest, r as ChartSpec, s as InteractionResponse, v as UiBridge, y as UiSurface } from "./types-7fnqDVrf-BnRQjVU3.js";
+import { y as ExternalToolSource } from "./index-BpIK7tJM.js";
+import { z } from "zod";
+import { ComponentType, ReactNode } from "react";
+//#region ../ui/dist/index.d.ts
+//#region src/model/formModel.d.ts
+interface FormModel {
+  kind: 'ask' | 'confirm' | 'form' | 'select' | 'authorize';
+  title?: string;
+  message?: string;
+  controls: ControlModel[];
+  submitLabel: string;
+  cancelLabel?: string;
+}
+interface ControlModel {
+  name: string;
+  label: string;
+  control: 'text' | 'number' | 'boolean' | 'select' | 'textarea';
+  required?: boolean;
+  description?: string;
+  defaultValue?: unknown;
+  options?: Array<{
+    label: string;
+    value: unknown;
+  }>;
+}
+/** 提交值按请求类型归形（WebFormBridge 与框架组件库共享单一来源） */
+declare function shapeInteractionValue(model: FormModel, values: Record<string, unknown>): unknown;
+/** 五类 InteractionRequest → 统一中间模型（框架无关） */
+declare function interactionToFormModel(request: InteractionRequest): FormModel;
+//#endregion
+//#region src/model/collectValues.d.ts
+interface CollectedValues {
+  values: Record<string, unknown>;
+  /** required 但为空的控件名（阻止提交） */
+  missingRequired: string[];
+}
+/**
+ * 严格类型化控件值收集：
+ * - number 空串 → undefined（非 0）；非数值输入（NaN）按缺失处理（required 时入 missingRequired）
+ * - select 用 option 值本身经 JSON 编码比对命中（对象值可正确命中）
+ * - required 空值列入 missingRequired（由调用方阻止提交并标记）
+ */
+declare function collectValues(controls: ControlModel[], container: ParentNode): CollectedValues;
+//#endregion
+//#region src/markdown/miniMarkdown.d.ts
+/**
+ * 最小子集 markdown → DOM：标题（#..###）、无序列表、代码块（```）、加粗、链接。
+ * 全部内容经 textContent 写入，用户内容天然转义防 HTML 注入。
+ */
+declare function renderMiniMarkdown(text: string, doc: Document): HTMLElement;
+//#endregion
+//#region src/chart/miniChart.d.ts
+/** 固定 8 色循环调色板 */
+declare const CHART_PALETTE: readonly ["#4e79a7", "#f28e2b", "#e15759", "#76b7b2", "#59a14f", "#edc948", "#b07aa1", "#ff9da7"];
+/**
+ * ChartSpec → SVG（bar 等宽柱 + 值标签；line 折线 + 点；pie 扇形 + 图例；空数据容错）
+ * @stable
+ */
+declare function renderMiniChart(chart: ChartSpec, doc: Document): SVGSVGElement;
+/** A2UI/OpenUI 降级：chart → table（labels 为首列，series 各为一列） */
+declare function chartToTable(chart: ChartSpec): {
+  type: 'table';
+  columns: string[];
+  rows: unknown[][];
+};
+//#endregion
+//#region src/web/webFormBridge.d.ts
+/**
+ * 框架无关原生 DOM 的 UiBridge：request 渲染表单并返回 Promise
+ * （提交 resolve / 取消 {cancelled:true}），完成后卸载 DOM。
+ * document 可注入（jsdom 测试）；BEM class 样式可覆写。
+ */
+declare class WebFormBridge implements UiBridge {
+  #private;
+  constructor(options: {
+    mount: HTMLElement;
+    document?: Document;
+    styles?: boolean;
+  });
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+  /** 尽力取消等待中的 request（超时后清理遗留表单） */
+  cancel(id: string): void;
+  renderResult(input: RenderResultRequest): Promise<void>;
+  progress(input: {
+    runId: string;
+    message: string;
+    value?: number;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/web/resultRenderer.d.ts
+/** RenderBlock → DOM（markdown/json/table/image/file/chart 六种） */
+declare function renderBlocks(container: HTMLElement, blocks: RenderBlock[], doc: Document): void;
+/** 完整 RenderResultRequest → DOM（summary 头 + blocks） */
+declare function renderRenderResult(request: RenderResultRequest, doc: Document): HTMLElement;
+//#endregion
+//#region src/web/styles.d.ts
+/** 最小样式（BEM class，应用可整体覆写） */
+declare const WEBSKILL_STYLES_CSS = "\n.webskill-form { display: block; padding: 12px; border: 1px solid #d0d0d0; border-radius: 8px; font-family: system-ui, sans-serif; max-width: 420px; }\n.webskill-form__title { margin: 0 0 8px; font-size: 15px; font-weight: 600; }\n.webskill-form__message { margin: 0 0 10px; font-size: 14px; }\n.webskill-form__control { margin-bottom: 10px; display: flex; flex-direction: column; gap: 4px; }\n.webskill-form__control--invalid .webskill-form__input { border-color: #d33; }\n.webskill-form__label { font-size: 13px; font-weight: 500; }\n.webskill-form__label-required::after { content: ' *'; color: #d33; }\n.webskill-form__description { font-size: 12px; color: #666; }\n.webskill-form__error { font-size: 12px; color: #d33; display: none; }\n.webskill-form__control--invalid .webskill-form__error { display: block; }\n.webskill-form__input { padding: 6px 8px; border: 1px solid #bbb; border-radius: 4px; font-size: 14px; font-family: inherit; }\n.webskill-form__actions { display: flex; gap: 8px; margin-top: 12px; }\n.webskill-form__button { padding: 6px 14px; border-radius: 4px; border: 1px solid #bbb; background: #fff; cursor: pointer; font-size: 14px; }\n.webskill-form__button--primary { background: #2563eb; border-color: #2563eb; color: #fff; }\n.webskill-form__button--ghost { background: transparent; }\n.webskill-result { font-family: system-ui, sans-serif; font-size: 14px; }\n.webskill-result__summary { font-size: 12px; color: #666; margin-bottom: 6px; }\n.webskill-result__json { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }\n.webskill-result__file { padding: 4px 0; font-size: 13px; }\n.webskill-md pre { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }\n.webskill-md h1, .webskill-md h2, .webskill-md h3 { margin: 8px 0 4px; }\n.webskill-md p { margin: 4px 0; }\n.webskill-md ul { margin: 4px 0; padding-left: 20px; }\n";
+/** 每个 document 只注入一次 */
+declare function ensureStyles(doc: Document): void;
+//#endregion
+//#region src/catalog/types.d.ts
+/** 声明式 UI 的节点：框架无关，技能脚本与 LLM 产出同一形状 */
+interface UiSpecNode {
+  /** catalog 中声明过的组件名 */
+  component: string;
+  props?: Record<string, unknown>;
+  children?: UiSpecNode[];
+  /** 稳定 id（回放与 action 关联用） */
+  id?: string;
+}
+interface UiComponentDef {
+  /** 声明里使用的组件名（PascalCase，全局唯一） */
+  name: string;
+  /** 给模型看的用途描述：一句话说清"什么时候用它" */
+  description: string;
+  /** props 的 zod schema */
+  props: z.ZodType<Record<string, unknown>>;
+  /** 允许的子节点组件名；省略表示叶子节点 */
+  children?: readonly string[] | 'any';
+  group: 'layout' | 'content' | 'data' | 'input' | 'feedback';
+  /** 给模型的额外约束 */
+  constraints?: readonly string[];
+  /** 最小示例（进 prompt，显著提升生成质量） */
+  example?: UiSpecNode;
+}
+interface UiActionDef {
+  name: string;
+  description: string;
+  params?: z.ZodType<Record<string, unknown>>;
+}
+interface UiSpecIssue {
+  /** 形如 `root.children[1].props.value` */
+  path: string;
+  message: string;
+}
+type UiSpecValidation = {
+  ok: true;
+} | {
+  ok: false;
+  issues: UiSpecIssue[];
+};
+interface UiCatalogPromptOptions {
+  /** tool-description 模式省略标题层级，直接作为工具描述使用 */
+  mode?: 'document' | 'tool-description';
+}
+interface UiCatalogInput {
+  id: string;
+  version: string;
+  title: string;
+  /** Markdown 设计准则，注入 prompt（对齐 A2UI catalog 的 instructions 字段） */
+  instructions: string;
+  components: readonly UiComponentDef[];
+  actions: readonly UiActionDef[];
+}
+interface UiCatalog extends UiCatalogInput {
+  readonly componentNames: readonly string[];
+  readonly actionNames: readonly string[];
+  component(name: string): UiComponentDef | undefined;
+  /** 整棵 spec 节点的 JSON Schema（组件按 `component` 判别） */
+  toJsonSchema(): JsonSchema;
+  /** Markdown 目录说明：组件签名 + 描述 + 约束 + 示例 */
+  toPrompt(options?: UiCatalogPromptOptions): string;
+  /** 运行时越界拒绝（安全边界） */
+  validate(spec: unknown): UiSpecValidation;
+}
+//#endregion
+//#region src/catalog/defineCatalog.d.ts
+/**
+ * 同一份定义派生出 JSON Schema / prompt / validator 三种投影，
+ * 不允许任何一方手写副本（21 号文档 §1）。
+ */
+declare function defineUiCatalog(input: UiCatalogInput): UiCatalog;
+//#endregion
+//#region src/catalog/uiCatalog.d.ts
+/**
+ * v3 首发 catalog：覆盖既有 `UiSurface` 六类的全部表达力，先窄后宽。
+ * 只依赖 zod —— 不 import 任何 UI framework（21 号文档 §5.1）。
+ */
+declare const uiCatalog: UiCatalog;
+/** prompt / 文档里引用的分组顺序（Console 展示同序） */
+declare const UI_CATALOG_GROUPS: {
+  readonly content: readonly ["Stack", "Card", "Separator", "Heading", "Text", "Markdown", "Badge"];
+  readonly data: readonly ["Metric", "Table", "Chart", "FileLink"];
+  readonly input: readonly ["Form", "Field", "Button"];
+};
+//#endregion
+//#region src/catalog/toSurface.d.ts
+/**
+ * 保留的 custom 组件名：catalog 声明树整棵挂在这个 surface 上。
+ * `UiSurface` 的六类联合表达不了通用节点树，改造它属破坏性变更（21 号文档 §7 已备案），
+ * 因此本轮用一个保留 component 名承载，四档 registry 各自识别它。
+ */
+declare const UI_SPEC_COMPONENT = "webskill.ui-spec";
+interface UiSpecSurfaceProps {
+  catalogId: string;
+  catalogVersion: string;
+  spec: UiSpecNode;
+  /** 声明树里出现过的 action 名（renderer 据此生成按钮能力） */
+  actions: string[];
+}
+/** 声明树 → `UiSurface`。id 缺省时由调用方给（工具源用 runtime 生成的 id）。 */
+declare function toSurface(catalog: UiCatalog, spec: UiSpecNode, id: string): UiSurface;
+/** surface 是否承载 catalog 声明树（四档 renderer 的分派入口） */
+declare function isUiSpecSurface(surface: UiSurface): boolean;
+//#endregion
+//#region src/catalog/toJsonRenderSpec.d.ts
+/** json-render 的扁平 spec：`elements` 以 key 索引，`children` 只存 key */
+interface JsonRenderSpec {
+  root: string;
+  elements: Record<string, {
+    type: string;
+    props: Record<string, unknown>;
+    children?: string[];
+  }>;
+}
+/**
+ * catalog 声明树 → json-render 扁平 spec。纯数据变换，不 import json-render
+ * （`@webskill/ui` 保持环境无关）。
+ */
+declare function toJsonRenderSpec(spec: UiSpecNode): JsonRenderSpec;
+//#endregion
+//#region src/catalog/uiCatalogToolSource.d.ts
+declare const RENDER_UI_TOOL = "render_ui";
+interface UiCatalogToolSourceOptions {
+  /** 默认使用 v1 catalog */
+  catalog?: UiCatalog;
+  /** surface id 生成（默认时间戳 + 随机后缀） */
+  newSurfaceId?: () => string;
+}
+/**
+ * 把 catalog 变成一个工具的入参 Schema，让模型直接生成声明式 UI（21 号文档 §3）：
+ * agentLoop / UiBridge / extractUiSurfaceEvents 全部零改动，装配处只多一个 externalTools 条目。
+ */
+declare function createUiCatalogToolSource(options?: UiCatalogToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/adapters/surface/surfaceDescriptor.d.ts
+declare const WEBSKILL_SURFACE_ACTION = "webskill:surface-action";
+type SurfaceRendererProvenance = 'a2ui-standard' | 'a2ui-extension' | 'openui-library' | 'openui-extension' | 'vercel-surface-host';
+/** Serializable surface state consumed by a renderer-specific host. @experimental */
+interface UiSurfaceDescriptor {
+  type: 'webskill-surface';
+  snapshot: UiSurfaceSnapshot;
+  provenance: SurfaceRendererProvenance;
+}
+/** Serializable renderer action. The Runtime validates nonce capability before resuming a run. @experimental */
+interface UiSurfaceActionDispatch {
+  runId?: string;
+  surfaceId: string;
+  actionId: string;
+  intent: UiSurfaceAction['intent'];
+  nonce?: string;
+  value?: Record<string, unknown>;
+  cancelled?: boolean;
+}
+declare function toUiSurfaceDescriptor(snapshot: UiSurfaceSnapshot, provenance: SurfaceRendererProvenance): UiSurfaceDescriptor;
+declare function toUiSurfaceActionDispatch(snapshot: UiSurfaceSnapshot, action: UiSurfaceAction, value?: Record<string, unknown>): UiSurfaceActionDispatch;
+/** Returns undefined for malformed or non-WebSkill renderer events. @experimental */
+declare function fromUiSurfaceActionDispatch(value: unknown): UiSurfaceActionDispatch | undefined;
+//#endregion
+//#region src/adapters/vercel/vercelPayload.d.ts
+/** Vercel AI SDK v7 ToolCallPart 兼容结构 */
+interface VercelToolInvocation {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+}
+declare const VERCEL_INTERACTION_TOOL_NAME = "webskill_interaction";
+declare const VERCEL_SURFACE_DATA_PART_TYPE = "data-webskill-surface";
+declare const VERCEL_SURFACE_ACTION_DATA_PART_TYPE = "webskill:surface-action";
+/** Vercel AI SDK-compatible data part consumed by a WebSkill SurfaceHost. @experimental */
+interface VercelSurfaceDataPart {
+  type: typeof VERCEL_SURFACE_DATA_PART_TYPE;
+  id: string;
+  data: ReturnType<typeof toUiSurfaceDescriptor>;
+}
+/** InteractionRequest → SDK tool UI 结构（应用聊天 UI 直接消费） */
+declare function toVercelToolInvocation(request: InteractionRequest): VercelToolInvocation;
+/** SDK 回传（tool result / output）→ InteractionResponse */
+declare function fromVercelToolResult(part: unknown): InteractionResponse;
+/** UiSurfaceSnapshot → AI SDK data part; the SurfaceHost owns renderer selection. @experimental */
+declare function toVercelSurfaceDataPart(snapshot: UiSurfaceSnapshot): VercelSurfaceDataPart;
+/** Decodes a nonce-bound action data part emitted by a Vercel SurfaceHost. @experimental */
+declare function fromVercelSurfaceAction(part: unknown): UiSurfaceActionDispatch | undefined;
+//#endregion
+//#region src/adapters/vercel/vercelUiBridge.d.ts
+/**
+ * 薄桥接类：request → SDK tool UI 结构 → 应用的聊天 UI（sendInteraction 回调实现）
+ * → SDK 回传 → InteractionResponse。
+ */
+declare class VercelUiBridge implements UiBridge {
+  #private;
+  constructor(deps: {
+    sendInteraction: (invocation: VercelToolInvocation) => Promise<unknown>;
+  });
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+}
+//#endregion
+//#region src/adapters/openui/openuiLang.d.ts
+/**
+ * InteractionRequest ↔ openui-lang 双向转换。
+ * openui-lang 语法（@openuidev/react-lang 实测）：
+ * - 每行一条语句 `identifier = Expression`，`root = Component(...)` 为入口
+ * - 组件调用参数为位置参数；字符串双引号反斜杠转义
+ * - 组件词汇（与应用 Library 约定）：Form(title, children)、
+ *   Text(content)（纯展示文本，authorize 的能力描述用）、
+ *   TextField(name, label, required?, defaultValue?)、NumberField、BooleanField(name, label, default?)、
+ *   SelectField(name, label, options)、SubmitButton(label, actionType, requestId)、
+ *   CancelButton(label, actionType, requestId)
+ */
+declare const OPENUI_SUBMIT_ACTION = "webskill:submit";
+declare const OPENUI_CANCEL_ACTION = "webskill:cancel";
+/** authorize 的 Allow 专用动作（提交即批准 → value:true；Deny 走 cancel → cancelled:true） */
+declare const OPENUI_AUTHORIZE_ACTION = "webskill:authorize";
+declare const OPENUI_SURFACE_ACTION = "webskill:surface-action";
+/** @experimental */
+declare function toOpenUiLang(request: InteractionRequest): string;
+/**
+ * UiSurfaceSnapshot → OpenUI library program. OpenUI applications provide WebSkillSurfaceHost;
+ * its descriptor tells the host whether it is a native extension rather than an OpenUI-native component.
+ * @experimental
+ */
+declare function toOpenUiSurfaceLang(snapshot: UiSurfaceSnapshot): string;
+/** Decodes a nonce-bound action emitted by an OpenUI WebSkillSurfaceHost. @experimental */
+declare function fromOpenUiSurfaceAction(action: unknown): UiSurfaceActionDispatch | undefined;
+/**
+ * OpenUI ActionEvent → InteractionResponse（formState 优先，取消单独分支）
+ * @experimental
+ */
+declare function fromOpenUiAction(action: unknown): InteractionResponse;
+//#endregion
+//#region src/adapters/openui/openUiSpecLang.d.ts
+/**
+ * catalog 声明树 → openui-lang 文本。语法为每行一条 `id = Component(位置参数…)`，
+ * `root = …` 为入口；容器组件的子节点作为最后一个参数传 id 数组。
+ */
+declare function toOpenUiSpecLang(spec: UiSpecNode, catalog?: UiCatalog): string;
+//#endregion
+//#region src/adapters/a2ui/a2uiMessages.d.ts
+/**
+ * InteractionRequest → A2UI 协议消息（v0.9.1，Basic Catalog）。
+ * 依据 https://a2ui.org/specification/v0.9-a2ui/：
+ * - 信封 {version, createSurface|updateComponents|updateDataModel|deleteSurface}
+ * - 组件为扁平邻接表（id 引用），root 必需
+ * - 输入组件与数据模型经 JSON Pointer 双向绑定；action.context 回传
+ * - createSurface.sendDataModel: true → 客户端动作时携带完整数据模型
+ *
+ * action 约定：submit → {name: 'webskill:submit', context: {requestId}}；
+ * cancel → {name: 'webskill:cancel', context: {requestId}}。
+ */
+declare const A2UI_VERSION = "v0.9.1";
+declare const A2UI_BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+declare const A2UI_SUBMIT_ACTION = "webskill:submit";
+declare const A2UI_CANCEL_ACTION = "webskill:cancel";
+declare const A2UI_SURFACE_ACTION = "webskill:surface-action";
+interface A2uiMessage {
+  version: string;
+  [key: string]: unknown;
+}
+/** @experimental */
+declare function toA2uiMessages(request: InteractionRequest): A2uiMessage[];
+/**
+ * UiSurfaceSnapshot → A2UI extension-host messages.
+ * Basic Catalog has no chart/table vocabulary, so a labelled WebSkill host owns these controlled renderers.
+ * @experimental
+ */
+declare function toA2uiSurfaceMessages(snapshot: UiSurfaceSnapshot): A2uiMessage[];
+/** Decodes a nonce-bound action emitted by a WebSkill A2UI extension host. @experimental */
+declare function fromA2uiSurfaceAction(event: unknown): UiSurfaceActionDispatch | undefined;
+/** Builds the A2UI event payload an extension host sends after a user action. @experimental */
+declare function toA2uiSurfaceAction(snapshot: UiSurfaceSnapshot, action: UiSurfaceAction, value?: Record<string, unknown>): {
+  name: string;
+  context: UiSurfaceActionDispatch;
+};
+/**
+ * 按 InteractionRequest.type 解码提交值（绑定模型原样回传的是表单对象）：
+ * confirm 仅 confirmed===true 批准；select 还原原始 option 值（非字符串值经 JSON 编码比对）；
+ * form 的 number 字段转 number（NaN 保留原值）；ask 取 answer；authorize 提交即批准。
+ * 纯转换器：任何直接使用 fromA2uiAction 的消费者都应经此拿到正确类型。
+ * @experimental
+ */
+declare function decodeInteractionResponse(request: InteractionRequest, response: InteractionResponse): InteractionResponse;
+/**
+ * A2UI client→server action 事件 → InteractionResponse。
+ * 传入 request 时按类型解码提交值（见 decodeInteractionResponse）。
+ * @experimental
+ */
+declare function fromA2uiAction(event: unknown, request?: InteractionRequest): InteractionResponse;
+//#endregion
+//#region src/adapters/a2ui/webskillCatalog.d.ts
+/** 自定义 catalog 的协议 id（对齐 https://a2ui.org/specification/v1_0/catalog_definition.json） */
+declare const WEBSKILL_A2UI_CATALOG_ID = "https://webskill.dev/a2ui/catalogs/v1/catalog.json";
+interface A2uiCatalogDefinition {
+  catalogId: string;
+  title: string;
+  description: string;
+  /** Markdown 设计准则；A2UI 侧的模型据此生成 */
+  instructions: string;
+  /** 组件名 → 该组件 props 的 JSON Schema */
+  components: Record<string, JsonSchema>;
+  /** 可被组件 action 引用的函数名 */
+  functions: Record<string, {
+    description: string;
+  }>;
+}
+/**
+ * WebSkill catalog → A2UI `catalog_definition.json`。
+ * 组件 schema 由 catalog 的 JSON Schema 投影经 `a2uiComponentShapes` 改写成 A2UI 线上形状
+ * （嵌套变 id 引用、action 名变协议信封），不手写第二份词汇表——
+ * Lit 元素的 zod API 也由同一份 shape 派生。
+ */
+declare function buildA2uiCatalogDefinition(catalog: UiCatalog): A2uiCatalogDefinition;
+//#endregion
+//#region src/adapters/a2ui/a2uiComponentShape.d.ts
+/**
+ * 声明树与 A2UI 线上形状只差三处，且三处都能从 catalog 定义机械推出：
+ *
+ * 1. 嵌套：声明树把子节点内联在 `node.children`；A2UI 要求组件是扁平邻接表，
+ *    子节点以 id 引用出现在 props 的 `children` 字段里。
+ * 2. 动作：catalog 的 `Button.action` 是一个 action 名（字符串）；
+ *    A2UI 用 `{event:{name, context}}` 信封表达"点击时做什么"。
+ * 3. 取值：表单控件（group=input 且声明了 `name`）在 A2UI 里靠 JSON Pointer
+ *    与数据模型双向绑定，因此多出一个 `value` 字段。
+ *
+ * 这份描述是 JSON `catalog_definition` 与 Lit 元素 zod API 的共同来源——
+ * 两边各自手写就会漂移（用例断言两者派生自同一份 shape）。
+ */
+interface A2uiComponentShape {
+  name: string;
+  description: string;
+  /** catalog 投影出的 props JSON Schema（未做 A2UI 改写） */
+  props: JsonSchema;
+  /** 原样透传的 props 字段名（键序取自 JSON Schema） */
+  staticProps: readonly string[];
+  /** 该组件接受子节点：props 里多出一个 A2UI ChildList 字段 */
+  childList: boolean;
+  /** children 字段的说明，承载 catalog 的子节点白名单约束 */
+  childListDescription?: string;
+  /** 需要换成 A2UI action 信封的 props 字段名 */
+  actionProps: readonly string[];
+  /** 与数据模型双向绑定的字段名（表单控件才有） */
+  valueProps: readonly string[];
+  /** 该组件自带提交按钮（props 里声明了提交标签） */
+  submitLabelProp?: string;
+  /** 该组件自带取消按钮 */
+  cancelLabelProp?: string;
+}
+/** A2UI 协议公共类型（与 @a2ui/web_core 的 common-types 同一套定义） */
+declare const A2UI_COMMON_TYPES = "https://a2ui.org/specification/v0_9/common_types.json";
+/** catalog → 每个组件的 A2UI 线上形状 */
+declare function a2uiComponentShapes(catalog: UiCatalog): A2uiComponentShape[];
+/** 单个组件的 A2UI props JSON Schema（协议要求每个组件是一份 schema） */
+declare function a2uiComponentSchema(shape: A2uiComponentShape): JsonSchema;
+//#endregion
+//#region src/adapters/a2ui/specToA2ui.d.ts
+/** 声明树里按钮触发的事件名（宿主据 context.actionId 回传 surface action） */
+declare const A2UI_SPEC_ACTION = "webskill:spec-action";
+/** 表单值在 A2UI 数据模型里的根路径 */
+declare const A2UI_SPEC_FORM_PATH = "/form";
+interface A2uiSpecMessageOptions {
+  surfaceId: string;
+  /** 缺省用 WebSkill BYOC catalog；传 Basic Catalog id 无意义（词汇表对不上） */
+  catalogId?: string;
+  /** 并入每个 action 的 context，宿主据此定位 surface */
+  context?: Record<string, unknown>;
+}
+/**
+ * catalog 声明树 → A2UI 消息序列。
+ *
+ * 协议要求组件是扁平邻接表且根节点 id 为 `root`，因此这里做树 → 邻接表的展开。
+ * 三处改写全部由 `a2uiComponentShapes` 决定，本函数不认识任何具体组件名：
+ * - 子节点变成 props.children 里的 id 引用
+ * - 表单控件的值经 JSON Pointer 与数据模型双向绑定
+ * - 自带提交/取消标签的组件（A2UI 没有表单提交事件）把按钮物化成 Button 子节点，
+ *   与 `toA2uiMessages` 对交互请求的处理同一手法
+ */
+declare function toA2uiSpecMessages(catalog: UiCatalog, spec: UiSpecNode, options: A2uiSpecMessageOptions): A2uiMessage[];
+interface A2uiSpecActionEvent {
+  actionId: string;
+  context: Record<string, unknown>;
+}
+/** A2UI action 事件 → 声明树 action（非本 catalog 的事件返回 undefined） */
+declare function fromA2uiSpecAction(event: unknown): A2uiSpecActionEvent | undefined;
+//#endregion
+//#region src/a2uiRuntime/litRendererBridge.d.ts
+/** @experimental */
+declare class LitRendererBridge implements UiBridge {
+  #private;
+  constructor(deps: {
+    mount: HTMLElement;
+    document?: Document;
+  });
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+  /** runtime 交互超时/取消：移除 surface 并以 cancelled resolve pending Promise（防悬挂 + DOM 残留） */
+  cancel(id: string): void;
+}
+//#endregion
+//#region src/a2uiRuntime/loadLitCatalog.d.ts
+/**
+ * BYOC Lit 元素的加载入口。
+ *
+ * 元素模块静态依赖 `lit` 与 `@a2ui/*`（三者都是 optional peer），
+ * 因此只能经动态 import 进来：未用 A2UI 档的应用不为这段体积买单，
+ * 缺依赖时给出带安装提示的 `UI_UNAVAILABLE`，而不是一个空白 surface。
+ */
+declare function loadWebSkillLitCatalog(): Promise<import('@a2ui/web_core/v0_9').Catalog<import('@a2ui/lit/v0_9').LitComponentApi>>;
+//#endregion
+//#region src/optionalPeers/openUiRuntime.d.ts
+/**
+ * Minimal structural contracts for the optional OpenUI peers (0.2.7 B4).
+ *
+ * `@openuidev/react-lang` and `zod` are optional peers loaded via dynamic import.
+ * The contracts below deliberately do NOT reference the peers' package types:
+ * tracing the react-lang/lang-core/zod type graph OOMs the dts build under the
+ * default heap (see packages/chatbot/src/react/OpenUiInteraction.tsx history).
+ *
+ * The `as unknown as` narrowing lives ONLY here (repository-wide single point):
+ * callers receive typed handles and never re-assert.
+ */
+interface OpenUiStateField<T> {
+  value: T;
+  setValue(value: T): void;
+}
+interface OpenUiRenderProps<P> {
+  props: P;
+  renderNode(value: unknown): ReactNode;
+}
+interface OpenUiRendererProps {
+  response: string | null;
+  library: unknown;
+  onAction?: (event: unknown) => void;
+}
+interface OpenUiRuntime {
+  /** The OpenUI Renderer component (structurally React's ComponentType). */
+  Renderer: ComponentType<OpenUiRendererProps>;
+  defineComponent<P>(config: {
+    name: string;
+    description: string;
+    props: unknown;
+    component: (renderProps: OpenUiRenderProps<P>) => ReactNode;
+  }): unknown;
+  createLibrary(definition: {
+    components: unknown[];
+    root?: string;
+  }): unknown;
+  useStateField<T>(name: string, value?: T): OpenUiStateField<T>;
+  useTriggerAction(): (userMessage: string, formName?: string, action?: {
+    type?: string;
+    params?: Record<string, unknown>;
+  }) => void | Promise<void>;
+}
+/** Minimal zod surface used to build OpenUI component props schemas at runtime. */
+interface ZodSchemaBuilder {
+  optional(): ZodSchemaBuilder;
+  nullable(): ZodSchemaBuilder;
+}
+interface ZodRuntime {
+  object(shape: Record<string, unknown>): ZodSchemaBuilder;
+  string(): ZodSchemaBuilder;
+  boolean(): ZodSchemaBuilder;
+  any(): ZodSchemaBuilder;
+  unknown(): ZodSchemaBuilder;
+  array(item: unknown): ZodSchemaBuilder;
+}
+interface LoadedOpenUiPeers {
+  openui: OpenUiRuntime;
+  z: ZodRuntime;
+}
+/**
+ * Loads the optional OpenUI peers (@openuidev/react-lang and zod) for the OpenUI
+ * interaction/surface paths. Throws a WebSkillError with code UI_UNAVAILABLE and an
+ * install hint when either peer is missing, so callers can fall back to native
+ * rendering instead of leaving a blank surface.
+ */
+declare function loadOpenUiPeers(): Promise<LoadedOpenUiPeers>;
+//#endregion
+export { ZodRuntime as $, UI_SPEC_COMPONENT as A, toJsonRenderSpec as At, UiSpecValidation as B, OPENUI_SUBMIT_ACTION as C, renderMiniMarkdown as Ct, RENDER_UI_TOOL as D, toA2uiSpecMessages as Dt, OpenUiRuntime as E, toA2uiMessages as Et, UiCatalogToolSourceOptions as F, toUiSurfaceActionDispatch as Ft, VERCEL_SURFACE_DATA_PART_TYPE as G, UiSurfaceDescriptor as H, UiComponentDef as I, toUiSurfaceDescriptor as It, VercelUiBridge as J, VercelSurfaceDataPart as K, UiSpecIssue as L, toVercelSurfaceDataPart as Lt, UiCatalog as M, toOpenUiSpecLang as Mt, UiCatalogInput as N, toOpenUiSurfaceLang as Nt, SurfaceRendererProvenance as O, toA2uiSurfaceAction as Ot, UiCatalogPromptOptions as P, toSurface as Pt, WebFormBridge as Q, UiSpecNode as R, toVercelToolInvocation as Rt, OPENUI_CANCEL_ACTION as S, renderMiniChart as St, OpenUiRendererProps as T, shapeInteractionValue as Tt, VERCEL_INTERACTION_TOOL_NAME as U, UiSurfaceActionDispatch as V, VERCEL_SURFACE_ACTION_DATA_PART_TYPE as W, WEBSKILL_STYLES_CSS as X, WEBSKILL_A2UI_CATALOG_ID as Y, WEBSKILL_SURFACE_ACTION as Z, FormModel as _, interactionToFormModel as _t, A2UI_SPEC_FORM_PATH as a, createUiCatalogToolSource as at, LoadedOpenUiPeers as b, loadWebSkillLitCatalog as bt, A2UI_VERSION as c, ensureStyles as ct, A2uiMessage as d, fromA2uiSurfaceAction as dt, a2uiComponentSchema as et, A2uiSpecActionEvent as f, fromOpenUiAction as ft, ControlModel as g, fromVercelToolResult as gt, CollectedValues as h, fromVercelSurfaceAction as ht, A2UI_SPEC_ACTION as i, collectValues as it, UiActionDef as j, toOpenUiLang as jt, UI_CATALOG_GROUPS as k, toA2uiSurfaceMessages as kt, A2uiCatalogDefinition as l, fromA2uiAction as lt, CHART_PALETTE as m, fromUiSurfaceActionDispatch as mt, A2UI_CANCEL_ACTION as n, buildA2uiCatalogDefinition as nt, A2UI_SUBMIT_ACTION as o, decodeInteractionResponse as ot, A2uiSpecMessageOptions as p, fromOpenUiSurfaceAction as pt, VercelToolInvocation as q, A2UI_COMMON_TYPES as r, chartToTable as rt, A2UI_SURFACE_ACTION as s, defineUiCatalog as st, A2UI_BASIC_CATALOG_ID as t, a2uiComponentShapes as tt, A2uiComponentShape as u, fromA2uiSpecAction as ut, JsonRenderSpec as v, isUiSpecSurface as vt, OPENUI_SURFACE_ACTION as w, renderRenderResult as wt, OPENUI_AUTHORIZE_ACTION as x, renderBlocks as xt, LitRendererBridge as y, loadOpenUiPeers as yt, UiSpecSurfaceProps as z, uiCatalog as zt };