@webskill/sdk 0.2.6 → 0.2.8

package/dist/index-7DVaZJU7.d.ts

@@ -0,0 +1,597 @@
+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-AmKCKJn_-BogJPQHU.js";
+import { y as ExternalToolSource } from "./index-QrHtAudz.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
+/** catalog 里单个组件的最小可见面（A2UI `LitComponentApi` 的结构子集） */
+interface A2uiCatalogComponent {
+  readonly name: string;
+  readonly tagName: string;
+  readonly schema: unknown;
+}
+/**
+ * A2UI catalog 句柄的最小结构契约。
+ *
+ * 与 optionalPeers/openUiRuntime.ts 同一约定：**不引用** `@a2ui/*` 的包类型。
+ * 它们是 optional peer，写进签名后会原样进入已发布的 `.d.ts`，
+ * 未安装 A2UI 的消费方 `tsc --noEmit` 会撞 TS2307（install-smoke 的类型探针实测）。
+ */
+interface A2uiCatalogHandle {
+  readonly id: string;
+  readonly components: ReadonlyMap<string, A2uiCatalogComponent>;
+}
+/**
+ * BYOC Lit 元素的加载入口。
+ *
+ * 元素模块静态依赖 `lit` 与 `@a2ui/*`（三者都是 optional peer），
+ * 因此只能经动态 import 进来：未用 A2UI 档的应用不为这段体积买单，
+ * 缺依赖时给出带安装提示的 `UI_UNAVAILABLE`，而不是一个空白 surface。
+ */
+declare function loadWebSkillLitCatalog(): Promise<A2uiCatalogHandle>;
+//#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 { WEBSKILL_SURFACE_ACTION as $, SurfaceRendererProvenance as A, toA2uiSurfaceAction as At, UiSpecNode as B, toVercelToolInvocation as Bt, OPENUI_AUTHORIZE_ACTION as C, renderBlocks as Ct, OpenUiRendererProps as D, shapeInteractionValue as Dt, OPENUI_SURFACE_ACTION as E, renderRenderResult as Et, UiCatalogInput as F, toOpenUiSurfaceLang as Ft, VERCEL_INTERACTION_TOOL_NAME as G, UiSpecValidation as H, UiCatalogPromptOptions as I, toSurface as It, VercelSurfaceDataPart as J, VERCEL_SURFACE_ACTION_DATA_PART_TYPE as K, UiCatalogToolSourceOptions as L, toUiSurfaceActionDispatch as Lt, UI_SPEC_COMPONENT as M, toJsonRenderSpec as Mt, UiActionDef as N, toOpenUiLang as Nt, OpenUiRuntime as O, toA2uiMessages as Ot, UiCatalog as P, toOpenUiSpecLang as Pt, WEBSKILL_STYLES_CSS as Q, UiComponentDef as R, toUiSurfaceDescriptor as Rt, LoadedOpenUiPeers as S, loadWebSkillLitCatalog as St, OPENUI_SUBMIT_ACTION as T, renderMiniMarkdown as Tt, UiSurfaceActionDispatch as U, UiSpecSurfaceProps as V, uiCatalog as Vt, UiSurfaceDescriptor as W, VercelUiBridge as X, VercelToolInvocation as Y, WEBSKILL_A2UI_CATALOG_ID as Z, CollectedValues as _, fromVercelSurfaceAction as _t, A2UI_SPEC_FORM_PATH as a, chartToTable as at, JsonRenderSpec as b, isUiSpecSurface as bt, A2UI_VERSION as c, decodeInteractionResponse as ct, A2uiCatalogHandle as d, fromA2uiAction as dt, WebFormBridge as et, A2uiComponentShape as f, fromA2uiSpecAction as ft, CHART_PALETTE as g, fromUiSurfaceActionDispatch as gt, A2uiSpecMessageOptions as h, fromOpenUiSurfaceAction as ht, A2UI_SPEC_ACTION as i, buildA2uiCatalogDefinition as it, UI_CATALOG_GROUPS as j, toA2uiSurfaceMessages as jt, RENDER_UI_TOOL as k, toA2uiSpecMessages as kt, A2uiCatalogComponent as l, defineUiCatalog as lt, A2uiSpecActionEvent as m, fromOpenUiAction as mt, A2UI_CANCEL_ACTION as n, a2uiComponentSchema as nt, A2UI_SUBMIT_ACTION as o, collectValues as ot, A2uiMessage as p, fromA2uiSurfaceAction as pt, VERCEL_SURFACE_DATA_PART_TYPE as q, A2UI_COMMON_TYPES as r, a2uiComponentShapes as rt, A2UI_SURFACE_ACTION as s, createUiCatalogToolSource as st, A2UI_BASIC_CATALOG_ID as t, ZodRuntime as tt, A2uiCatalogDefinition as u, ensureStyles as ut, ControlModel as v, fromVercelToolResult as vt, OPENUI_CANCEL_ACTION as w, renderMiniChart as wt, LitRendererBridge as x, loadOpenUiPeers as xt, FormModel as y, interactionToFormModel as yt, UiSpecIssue as z, toVercelSurfaceDataPart as zt };