@webskill/chatbot 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,12 +1,19 @@
-import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, WebSkillErrorCode, diffUserProfile } from "@webskill/sdk";
+import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DataSourceInfo, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, PdfTextExtractor, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, WebSkillErrorCode, XlsxTextExtractor, diffUserProfile } from "@webskill/sdk";
 import { SandboxMode, TypeScriptSupportOptions } from "@webskill/sdk/browser";
 import { CustomSurfaceActionEvent, ReactBridgeState, SpecInteractionChannel, SurfaceRegistry, UiSurfaceActionEvent } from "@webskill/sdk/ui-react";
-import { PageActionPolicy, PagePerceptionPolicy, PerceptionRecord, SkillCandidateSink, TodoItem } from "@webskill/sdk/agent";
+import { DownloadedFileConsent, DownloadedFileReader, PageActionPolicy, PagePerceptionPolicy, PerceptionPagingBudget, PerceptionRecord, SkillCandidateSink, TodoItem } from "@webskill/sdk/agent";
 import "react";
 import "react/jsx-runtime";
 //#region ../ui-kit/src/i18n/types.d.ts
 /** @stable */
 type Locale = 'zh' | 'en';
+/**
+ * 宿主 / 用户提供的、随界面语言切换的短文案（0.13.0 分册 21 FR-21.1）。
+ * SDK 自己的界面文案走 `createI18n` 字典，不用这个类型。
+ * 允许只填部分语种，缺的语种由 `resolveLocalizedText` 借用已填的。
+ * @experimental
+ */
+type LocalizedText = Partial<Record<Locale, string>>;
 /** 单语言词条：key → 文案（支持 {name} 占位插值） */
 type LocaleMessages = Record<string, string>;
 /** 双语字典：zh/en 两个 locale 的键集必须一致（见 assertDictionaryComplete） */
@@ -19,6 +26,37 @@ type InterpolationParams = Record<string, string | number>;
 /** t(key, params?)：查当前 locale 词条并做 {name} 插值 */
 type TranslateFn<D extends Dictionary = Dictionary> = (key: DictionaryKey<D>, params?: InterpolationParams) => string;
 //#endregion
+//#region ../core/src/attachment/kind.d.ts
+/**
+ * 附件类型判据与文本形态。0.14.0 分册 20 从 `@webskill/chatbot` 迁入：
+ * 「用户上传」与「读取下载目录」两条入口必须给出同一结论（AC-20.17）、
+ * 产出同一份文本（AC-20.6），而后者住在 `@webskill/agent`，chatbot 依赖 agent，
+ * 判据只能落在两者共同的下游。纯字符串运算，无环境依赖。
+ */
+/** 附件在模型侧的内容形态（0.6.0 FR-11.2） @experimental */
+type ChatAttachmentKind = 'text' | 'image' | 'file' | 'document-text';
+//#endregion
+//#region ../runtime/src/tools/types.d.ts
+/**
+ * 宿主声明的一个数据源的**可公开部分**（0.14.0 分册 19）。
+ *
+ * `target` 不在这里，且不得被加进来：这条通路的终点是模型上下文，
+ * 而「地址不由脚本提供」正是 0.11.0 分册 16 §2.2 授权面的全部依据。
+ * @experimental
+ */
+interface DataSourceInfo$1 {
+  id: string;
+  description: string;
+  /**
+   * 非宿主声明时的出处（0.14.0 分册 21）。缺省即宿主声明，不带标注。
+   *
+   * 有值意味着 `description` **来自页面**，模型看到的清单里必须随之出现「可能不准确」的标注，
+   * 否则一段由站点控制的文本会以宿主口吻进上下文。
+   * @experimental
+   */
+  provenance?: 'page-declared' | 'tool-projection';
+}
+//#endregion
 //#region ../runtime/src/sandbox/bridgeProtocol.d.ts
 /**
  * 能力模式：true 直通 / false 关闭（TOOL_UNSUPPORTED）/ 'require-approval' 调用前强制授权
@@ -40,6 +78,43 @@ type NetworkPolicy$1 = 'deny-all' | 'allow-all' | {
   allow: string[];
 };
 //#endregion
+//#region ../ui-kit/src/runtime-config/quickPrompts.d.ts
+/**
+ * 快捷指令可选图标名（0.12.0 分册 21）。
+ * 用受控枚举而不是让宿主传组件：SDK 的图标集不进公开契约，
+ * 换实现（lucide → 别的）时宿主代码不用动。
+ *
+ * 0.13.0 分册 17 FR-17.1：真值源从 `@webskill/chatbot` 迁到这里，
+ * 让 console 的配置界面也能用同一份枚举；`@webskill/chatbot` 原样 re-export，
+ * 公开面逐字不变。
+ * @experimental
+ */
+type QuickPromptIconName = 'chart' | 'document' | 'report' | 'search' | 'list' | 'bug' | 'test' | 'metric' | 'compare' | 'page' | 'run' | 'warn' | 'sparkles' | 'settings';
+/**
+ * 带图标的快捷指令（0.12.0 分册 21）。
+ * @experimental
+ */
+interface QuickPrompt {
+  /**
+   * 点击后发出的文本，同时作为按钮可见文案。
+   * 0.13.0 分册 21 FR-21.1：改为按语种取值，可只填部分语种。
+   */
+  text: LocalizedText;
+  /** 缺省或取值不在枚举内时按无图标渲染 */
+  icon?: QuickPromptIconName;
+}
+/**
+ * `RuntimeConfig` 里持久化的快捷指令条目（0.13.0 分册 17）。
+ * 比 `QuickPrompt` 多一个稳定 `id`：列表增删改需要它做定位，
+ * 用 `text` 当 key 在「两条同文案」时会塌陷。`id` 不进任何发给模型的字符串。
+ * @experimental
+ */
+interface RuntimeQuickPrompt {
+  id: string;
+  text: LocalizedText;
+  icon?: QuickPromptIconName;
+}
+//#endregion
 //#region ../ui-kit/src/runtime-config/types.d.ts
 /**
  * 运行环境配置模型（P2）：console Configure Tab 编辑、chatbot ChatEngine 装配应用，
@@ -73,6 +148,19 @@ interface RuntimeHooksConfig {
 }
 /** 浏览器宿主执行器档位；Node 宿主的 in-process/worker/process 由宿主侧扩展展示 */
 type RuntimeSandboxExecutor = 'auto' | 'blob-worker' | 'iframe-sandbox';
+/**
+ * 用户自己声明的取数源（0.14.0 分册 19）。
+ *
+ * 存在的理由：从别的宿主导出的技能会声明本宿主没有的源 id，没有这一段就永远跑不起来。
+ * 它不放宽任何闸门——`url` 照过 `sandbox.remoteUrl` 判定，取数照受 `capabilities.fetchData` 管，
+ * 变的只是「谁来写这个地址」：宿主开发者，还是宿主的使用者。
+ */
+interface RuntimeDataSourceEntry {
+  id: string;
+  /** 绝对 http(s) 地址 */
+  url: string;
+  description: string;
+}
 interface RuntimeSandboxConfig {
   executor: RuntimeSandboxExecutor;
   networkPolicy: NetworkPolicy$1;
@@ -94,6 +182,11 @@ interface RuntimeSandboxConfig {
    * 所以不受 `toolResultMaxBytes` 约束。
    */
   maxDataSourceBytes: number;
+  /**
+   * 用户声明的取数源（0.14.0 分册 19）；缺省空数组 = 只有宿主代码写死的那些。
+   * 与宿主源撞 id 时宿主的那条胜出——否则用户配置就能改写宿主的授权面。
+   */
+  dataSources: RuntimeDataSourceEntry[];
   /**
    * 出站 URL 准入策略（`RemoteUrlPolicy` 的可配置部分）：技能安装、MCP 端点连接
    * 这类由宿主发起的取数都按它判定。两项都默认关，即 https-only 且拒绝内网/环回。
@@ -101,6 +194,13 @@ interface RuntimeSandboxConfig {
   remoteUrl: RuntimeRemoteUrlConfig;
   /** 浏览器沙箱的 TypeScript 支持；关闭时 `.ts` 脚本按 `TOOL_UNSUPPORTED` 拒绝 */
   typescript: RuntimeTypeScriptConfig;
+  /**
+   * 读取用户下载的文件（0.14.0 分册 20）。缺省 `false`。
+   *
+   * **不放进 `capabilities`**：那张表的语义是三态 `CapabilityMode`（关 / 需批准 / 开），
+   * 而本能力的「需批准」是恒定的，放进去会凭空多出一个「开且不批准」的非法组合。
+   */
+  downloadedFiles: boolean;
 }
 /**
  * 只做类型擦除，不做类型检查。`esbuildUrl` 为绝对 http(s) 地址时按 `remoteUrl` 判定；
@@ -225,6 +325,11 @@ interface RuntimeMultimodalConfig {
   maxImageBytes: number;
   /** 附件与取像共用 */
   maxImagesPerMessage: number;
+  /**
+   * 页面取像时小于该面积（平方像素）的元素视作工具图标，不占名额（0.13.0 FR-20.4）。
+   * `0` 是合法值，意为关闭过滤；只作用于页面取像，不管用户上传的附件。
+   */
+  minImageArea: number;
 }
 /**
  * 用户画像配置（0.6.0 FR-19.6）。`enabled` 默认**关**（AC-G5）：
@@ -270,6 +375,19 @@ interface RuntimeConfig {
   documentSurface: RuntimeDocumentSurfaceConfig;
   userProfile: RuntimeUserProfileConfig;
   skillState: RuntimeSkillStateConfig;
+  /**
+   * 快捷指令的**唯一权威**（0.13.0 分册 21 FR-21.5）。
+   * `ChatbotConfig.quickPrompts` 降级为一次性种子源，不再参与渲染判断。
+   */
+  quickPrompts: readonly RuntimeQuickPrompt[];
+  /**
+   * 宿主种子是否已注入过（FR-21.6）。
+   * 不得用 `quickPrompts.length === 0` 推断：「从未配置」与「用户删光了」都是空数组，
+   * 靠数组本身分不开——这正是 D-17-3 当年绕不过去的地方。
+   */
+  quickPromptsSeeded: boolean;
+  /** 空态与动态指令条最多展示多少条；超出的部分截断。取值 1..{@link MAX_QUICK_PROMPT_LIMIT} */
+  quickPromptLimit: number;
   /** 被用户删掉的自动模型条目 id（FR-14.3）：删一次就不该再自己长回来 */
   dismissedAutoEntries: readonly string[];
 }
@@ -316,144 +434,457 @@ declare function createLocalStorageRuntimeConfigStore(options?: LocalStorageRunt
 /** 内存实现：测试、SSR、以及宿主明确不想持久化时使用。 @experimental */
 declare function createMemoryRuntimeConfigStore(initial?: Partial<RuntimeConfig>): RuntimeConfigStore;
 //#endregion
-//#region src/core/attachmentKind.d.ts
-/** 附件在模型侧的内容形态（0.6.0 FR-11.2） @experimental */
-type ChatAttachmentKind = 'text' | 'image' | 'file' | 'document-text';
-//#endregion
-//#region src/core/types.d.ts
+//#region src/core/hostAdapter.d.ts
 /**
- * 治理 port 集合（F1）：宿主把 `SkillStatePolicy` 的适配器交给 chatbot，
- * 由它接到内部装配的 `WebSkillRuntime` 上。字段名与 `WebSkillRuntimeDeps` 逐个对齐，
- * 不做重命名：中间多一层映射只会让宿主多记一套名字。
- * @experimental
+ * 宿主装配口：chatbot 不感知环境（浏览器/Node），全部能力经此注入。
+ * 页面动态技能来源同时是外部工具来源与外部技能提供者（同一对象两个 port）。
+ * LLM 配置不在这里——它统一由 `RuntimeConfigStore` 承载（0.5.0 起）。
+ * @stable
  */
-interface ChatbotGovernancePorts {
-  /** `SkillStatePolicy.toSkillStateGuard()`：read/activate/execute 三入口拦截 */
-  skillStateGuard?: SkillStateGuard;
-  /** `SkillStatePolicy.toSkillIntegrityGuard(verify)`：激活期验签，失败即隔离 */
-  skillIntegrityGuard?: SkillIntegrityGuard;
-  /** `SkillStatePolicy.toSkillOutcomeReporter()`：执行失败计数，达阈值即隔离 */
-  skillOutcomeReporter?: SkillOutcomeReporter;
-  /** `SkillStatePolicy.catalogFilter()`：非 active 技能不进路由候选集 */
-  catalogFilter?: (entries: SkillCatalogEntry[]) => SkillCatalogEntry[] | Promise<SkillCatalogEntry[]>;
+interface ChatbotHostAdapter {
+  storage: FileSystemProvider;
+  skillRoots: string[];
+  pageSkillSource?: ExternalToolSource & ExternalSkillProvider;
+  navigation: {
+    openConsole(): void;
+    /** 跳 console Traces 面板并定位该 run（v1.1；缺省时消息不渲染 View trace 入口） */
+    openConsoleTrace?(runId: string): void;
+    /** 打开治理面的审批队列并定位该候选（FR-24.2）；宿主未接治理面时不提供，入口随之不渲染 */
+    openConsoleCandidate?(candidateId: string): void;
+  };
+  /** 缺省 BrowserWorkerScriptExecutor（@webskill/browser）；Node 宿主可注入自己的执行器 */
+  executor?: ScriptExecutor;
   /**
-   * run 未激活任何技能时的钩子（如 `createMissHook`）。
+   * 页面只读感知策略（需求 10）。**只能在这里注入**：启用与否是宿主侧配置，
+   * 设置抽屉里没有也不会有开关（FR-10.1）——风险由部署方承担，
+   * 不应交给终端用户随手勾选。
+   * @experimental
+   */
+  pagePerception?: PagePerceptionPolicy;
+  /**
+   * 感知结果的分段预算（0.14.0 分册 22 FR-22.4 / FR-22.8）。
    *
-   * 开关存在 `GovernanceFacade.missHook`（属 console），chatbot 读不到也不该依赖它；
-   * 所以读开关是**宿主**的责任。宿主应传一个**每次触发时才读开关**的闭包，
-   * 而不是装配时把布尔值算好——`#assemble()` 不是每次 run 都跑，
-   * 算好了会导致「开着启动 → 中途关闭」不生效（AC-17.11）。
+   * 与 `pagePerception` 同一条装配规矩：只能在这里给，设置抽屉里没有开关。
+   * **不给即不分段，但地板照样生效**——不开启不等于允许引擎盲切，
+   * 超预算时仍然是「读到预算为止 + 一条原位说明」，只是没有续读的入口。
+   * @experimental
    */
-  onSkillMiss?: (input: {
-    prompt: string;
-    run: RuntimeRun;
-  }) => Promise<void>;
-}
-/** 分配式交叉：直接写 `信封 & LifecycleEventInit` 会把联合压成一个对象，`phase` 的判别性就没了 */
-type WithChatMeta<T> = T extends unknown ? {
-  type: 'lifecycle';
-  runId: string;
-  at: number;
-} & T : never;
-/**
- * 生命周期步进事件：`data` 随 `phase` 判别，与 runtime 的 `LifecycleEvent` 同一套契约。
- * 旧的 `Record<string, unknown>` 等于没有契约：消费方只能硬编码键名。
- */
-type LifecycleChatEvent = WithChatMeta<LifecycleEventInit>;
-/**
- * 交互渲染框架档位：native（React InteractionCard）/ a2ui（@a2ui/lit Lit 渲染）/
- * openui（@openuidev/react-lang Renderer，ui-kit Library）/ vercel（@json-render/react
- * Registry 渲染 catalog 声明树）
- * @experimental
- */
-type RendererKind = 'native' | 'a2ui' | 'openui' | 'vercel';
-/** assistant 消息所属 run 的一次工具调用（终态：completed/failed） @stable */
-interface ChatToolCall {
-  callId: string;
-  name: string;
-  status: 'completed' | 'failed';
-  /** 参数摘要（JSON 截断 100 字符；trace 重放无 args 时留空，卡片展开详情有则显示） */
-  args?: string;
-  /** 执行耗时（trace completed/failed 回填；live 由 started→终态计时） */
-  durationMs?: number;
+  pagePerceptionPaging?: PerceptionPagingBudget;
   /**
-   * 开始时刻（epoch ms，0.10.0 UI-UX5 #32）。与思考段按时间穿插需要共同时钟；
-   * 旧会话消息没有该字段时工具卡片保持原有相对顺序。
+   * 页面操作能力（需求 23）。**不注入即完全关闭**，与 `pagePerception` 分开：
+   * 可读不等于可操作。同样只能在这里注入——给终端用户一个「打开代操作」的开关
+   * 等于把安全边界交给最不了解它的人。
+   * @experimental
    */
-  at?: number;
+  pageActions?: PageActionPolicy;
   /**
-   * failed 时的结构化错误码（如 `TOOL_NOT_ALLOWED`）。
-   * 「被策略拒绝」与「执行失败」在 UI 上是两回事，靠错误码区分而不是解析文案。
+   * 读页面链接指向的文档（分册 22）。实现住在 `@webskill/browser`，
+   * 而 chatbot 不依赖它 —— 与 `pagePerception` 同一条装配规矩：宿主注入。
+   * 不注入即 `read_linked_document` 不注册。
    */
-  errorCode?: string;
-  /** failed 时的错误说明（拒绝时即「被哪条策略拒绝」） */
-  errorMessage?: string;
-}
-/** 已落盘的待发送附件（composer 附件适配器产出） @experimental */
-interface ChatAttachmentInput {
-  id: string;
-  name: string;
-  contentType: string;
-  /** 相对 `attachmentsRoot` 的路径 */
-  path: string;
-  size: number;
-  /** 注入模型的内容形态；决定 send 时读文本还是读二进制 */
-  kind: ChatAttachmentKind;
-  /** 图片经压缩时的原始字节数，供 UI 显示「3.2 MB → 1.8 MB」（FR-11.3） */
-  originalSize?: number;
+  linkedDocuments?: LinkedDocumentReader;
+  /** docx → 文本（`extractDocxText`）；不注入即 Word 文档明确报「本环境不支持」 */
+  docxExtractor?: DocxTextExtractor;
+  /** xlsx → 文本（`extractXlsxText`）；不注入即 Excel 工作簿明确报「本环境不支持」 */
+  xlsxExtractor?: XlsxTextExtractor;
+  /**
+   * PDF → 文本；**只用于直传被端点拒后的回退**（0.13.0 FR-22.1）。
+   * PDF 仍然默认直传，能读的端点拿到的还是原件；不注入即没有回退能力。
+   */
+  pdfExtractor?: PdfTextExtractor;
+  /** 文档读取留痕出口（FR-22.6） */
+  documentAudit?: {
+    append(event: {
+      type: string;
+      target: string;
+      data?: Record<string, unknown>;
+    }): Promise<unknown>;
+  };
+  /**
+   * 读用户本机下载的文件（0.14.0 分册 20）。**不注入即两个工具都不注册**，
+   * 与 `sandbox.downloadedFiles` 开关是「与」的关系：宿主没接通路，用户开了也没用。
+   *
+   * 只收端口，不收策略：授权卡出口、能力开关、模型读图能力、docx/xlsx 抽取器
+   * 全在引擎这一侧，宿主自己拼一个策略必然要重复这四项判断。
+   * @experimental
+   */
+  downloads?: {
+    reader: DownloadedFileReader;
+    /** 「不再询问」的记忆端口；不注入即每次都问 */
+    consent?: DownloadedFileConsent;
+  };
 }
-/** 随消息持久化的附件元数据 @experimental */
-type ChatAttachmentMeta = ChatAttachmentInput;
+//#endregion
+//#region src/core/chatEngine.d.ts
 /**
- * 归并后的显示相位。进行中通道与历史通道共用这一个结构：
- * 各存一份正是「运行细节首轮后消失」的根因（需求 17 条目 10-6）。
+ * 条目能否真的发请求：云端要有端点或密钥，浏览器内置两者都不需要。
+ *
+ * 导出给 UI：选择器不用同一份判据的话，用户能选中一个空配置条目，
+ * 而引擎静默回退到另一条——界面说在用 A、实际跑的是 B（UI-UX8 D1）。
  * @experimental
  */
-interface ChatRunPhase {
-  phase: RuntimePhase;
-  at: number;
-  /** 下一个步进到达时回填 */
-  endedAt?: number;
-  /** 由结构化 `LifecycleEvent.data` 派生的一句摘要 */
-  note?: string;
-  /** fail 相位的具体说明：`reason` 只有七种取值，说不出「哪个上限、哪个模型」 */
-  detail?: string;
-}
-/** 本轮发生的一次已提交交互（FR-17.8：提交后表单保留所填值） @experimental */
-interface ChatInteractionRecord {
-  id: string;
-  request: InteractionRequest;
-  /** 提交时的表单值；文件类字段已在引擎侧脱敏 */
-  submittedValues?: unknown;
-}
+declare const isLlmEntryUsable: (entry: RuntimeLlmEntry) => boolean;
 /**
- * 该 run 内模型产出的一段思考正文（0.10.0 UI-UX5 #32）。
- * 每次模型调用的思考算一段；随消息持久化，重开会话仍能看到。
- * 模型不支持思考输出时整个数组缺省——不产空壳卡片。
+ * 选中条目 → 默认条目 → 首条；命中不可用条目时**回退到下一个可用条目**
+ * （0.10.0 复核：选中项失效时宁可静默换用可用模型，也不能把 UI 锁死成
+ * 「未配置」死胡同——引擎与 UI 共用同一判据，两边必须同进退）。
+ * 全部不可用才 undefined（引擎走内置演示）。
+ *
+ * 导出给 UI 复用同一判据：composer 的「未配置模型」引导判定必须与引擎的
+ * 实际挑选结果一致，否则会出现「UI 说有模型、引擎却走演示档」的错位（0.10.0 UI-UX5 #49-1）。
  * @experimental
  */
-interface ChatThinking {
-  text: string;
-  /** 首个思考增量到达时刻（epoch ms；与工具卡片按时间穿插的排序依据） */
-  at: number;
+declare function pickUsableLlmEntry(entries: readonly RuntimeLlmEntry[], defaultId: string | undefined, selectedId: string | undefined): RuntimeLlmEntry | undefined;
+/** 默认沙箱执行器的构造参数（adapter.executor 未注入时；executorFactory 替换点可见同一形状） @stable */
+interface SandboxExecutorDeps {
+  fs: FileSystemProvider;
+  sandbox?: SandboxMode;
+  networkPolicy?: NetworkPolicy;
+  capabilities?: BridgeCapabilities;
+  approvalScope?: ApprovalScope;
+  uiBridge?: UiBridge;
+  /** 缺省时 `.ts` 脚本按 `TOOL_UNSUPPORTED` 拒绝 */
+  typescript?: TypeScriptSupportOptions;
 }
 /**
- * 该 run 的大模型用量（0.10.0 UI-UX5 #47）：随消息持久化，重开会话仍可见。
- * 上游不回报 token 用量时整个字段缺省——不显示假数据。
- * @experimental
+ * 装配时（而非执行时）把 `sandbox.typescript` 转成执行器参数，让配置错误早暴露。
+ * 只对绝对 URL 走 `RemoteUrlPolicy`：同源相对路径与打包器 specifier 不是出站请求。
  */
-interface ChatTokenUsage {
-  inputTokens: number;
-  outputTokens: number;
-  /** 本 run 向大模型发送请求的次数（模型调用轮数） */
-  llmCalls: number;
-}
 /**
- * 助手消息的有序内容段（分册 17 FR-17.1）：文字与 surface / 结果块按生成顺序排列。
- * 冗余记账——删掉本字段消息内容不缺失，只退化成「正文在上、扩展在下」（FR-17.11）。
- * @experimental
- */
-type ChatContentPart = {
+ * 由 `RuntimeConfig` 装出沙箱执行器依赖。
+ *
+ * 主链路与**评估链路**共用这一处（T-17-H）：此前评估侧只传 `fs`，
+ * 于是评估里跑的技能不受沙箱、网络策略、能力与授权范围约束——
+ * 那比「.ts 跑不了」严重得多（设计 17 §1.1a）。
+ *
+ * @experimental
+ */
+declare function sandboxExecutorDeps(fs: FileSystemProvider, rc?: RuntimeConfig, uiBridge?: SandboxExecutorDeps['uiBridge']): SandboxExecutorDeps;
+/** @stable */
+interface ChatEngineOptions {
+  llm?: LlmClient;
+  loopConfig?: AgentLoopConfig;
+  chatRoot?: string;
+  /** 运行环境配置存储（P2）：#ensureReady 装配时 load()（默认值兜底）并按映射应用 */
+  runtimeConfig?: RuntimeConfigStore;
+  /** 初始渲染框架档（默认 'native'；运行中可 setRenderer 热切换） */
+  renderer?: RendererKind;
+  /**
+   * 注入 `render_ui` 工具，让模型面向 AI Component Catalog 生成声明式 UI。
+   *
+   * 注入了 `runtimeConfig` 时**以 `RuntimeConfig.agentCapabilities.generativeUi` 为准**，
+   * 本字段只在未接配置存储的宿主上生效（否则设置面板里的开关点了不算数）。
+   */
+  generativeUi?: boolean;
+  /** 沙箱执行器替换点（测试注入 spy 断言构造参数；缺省 BrowserWorkerScriptExecutor） */
+  executorFactory?: (deps: SandboxExecutorDeps) => ScriptExecutor;
+  /**
+   * 宿主声明的数据源取数入口（分册 16）。不注入即脚本上下文没有 `fetchData` 这个键。
+   *
+   * 装配点必须在宿主：策略本体 `DataSourcePolicy` 住在 `@webskill/agent`，
+   * 而数据源的目标地址是宿主自己的业务知识，chatbot 无从代为声明。
+   * 能力开关 `sandbox.capabilities.fetchData` 缺省关，注入了也还要宿主在配置里打开。
+   */
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
+  /**
+   * 宿主声明的数据源清单（0.14.0 分册 19），取自 `DataSourcePolicy.publicSources`。
+   * 技能声明了本宿主没有的源时，引擎在激活回执里说明缺什么；不注入即不说。
+   */
+  dataSources?: readonly DataSourceInfo$1[] | (() => readonly DataSourceInfo$1[]);
+  /**
+   * 会话落盘替换点（缺省 `FsSessionStore`，落在 `<chatRoot>/sessions`）。
+   * 宕主换自己的实现（如 IndexedDB）与测试统计端口读写量都走这里。
+   */
+  sessionStore?: SessionStore<ChatMessage>;
+  /**
+   * 宿主已注册好钩子的执行器；装配时把 `RuntimeConfig.hooks` 应用到它再交给 runtime。
+   * 不注入即不挂钩子（与 0.0.2 行为一致）。
+   */
+  hooks?: HookRunner;
+  /**
+   * 治理 port 注入（F1）：把 `SkillStatePolicy` 的三个适配器接到本引擎装配的 runtime 上。
+   *
+   * 不注入即完全关闭，行为与 0.0.2 一致。装配点必须在宿主：chatbot 不能依赖
+   * `@webskill/governance`（它是可选治理层，且要求宿主提供治理根与审计存储）。
+   *
+   * 三个一起给才形成闭环——只给 `skillOutcomeReporter` 会把技能标成 `quarantined`
+   * 却仍旧照常路由和执行，降级形同虚设。
+   */
+  governance?: ChatbotGovernancePorts;
+  /**
+   * 技能自动生成的候选收货端（需求 12 号）。与 `governance` 同理，装配点在宿主：
+   * `@webskill/governance` 的 `createCandidateSink()` 是现成实现。
+   *
+   * 开关另在 `RuntimeConfig.agentCapabilities.skillGeneration`（默认关）；
+   * 开关开但未注入本端口时，工具会把 `SKILL_GENERATION_DISABLED` 回给模型。
+   */
+  skillCandidates?: SkillCandidateSink;
+}
+/**
+ * 对话框引擎：装配 WebSkillRuntime + 会话持久化 + 事件分发。
+ * RuntimeConfig 的 load() 是异步的，runtime 在首次 send 前懒装配（#ensureReady）。
+ * @stable
+ */
+declare class ChatEngine {
+  #private;
+  readonly bridge: ReactBridgeState;
+  constructor(adapter: ChatbotHostAdapter, options?: ChatEngineOptions);
+  /** 当前待办清单快照（宿主可直读；实时更新订阅 `todo-changed` 事件） */
+  get todos(): readonly TodoItem[];
+  /** 当前渲染框架档 */
+  get renderer(): RendererKind;
+  /** 当前会话选中的模型条目 id；未显式切换过时为 undefined（走 `RuntimeConfig.llm.defaultId`） */
+  get modelId(): string | undefined;
+  /**
+   * 切换本会话后续消息使用的模型条目（需求 4）。传 `undefined` 回到配置里的默认项。
+   * 重装配 runtime 以换掉客户端；已落盘的消息不受影响。
+   */
+  setModel(entryId: string | undefined): void;
+  /** 会话文件所在目录：「存储未初始化」提示要把路径写给用户看 @experimental */
+  get sessionsRoot(): string;
+  /** 渲染框架热切换：复合桥按档分发，无需重装配 runtime（会话句柄保留） */
+  setRenderer(renderer: RendererKind): void;
+  /** 非 native 三档共用的交互通道（Chatbot 的 SpecInteraction 订阅/attach；core 只产出 catalog 节点树） */
+  get interactionChannel(): SpecInteractionChannel;
+  /** 探测 @a2ui/lit 是否安装（Appearance/设置区 A2UI 档置灰判定） */
+  probeA2uiAvailability(): Promise<boolean>;
+  onEvent(listener: (event: ChatEvent) => void): () => void;
+  /**
+   * 配置源变更后调用（LLM 设置 / RuntimeConfigStore 内容变化）：丢弃缓存的
+   * runtime/llm/会话句柄，下次 send 重新装配（RuntimeConfig 重新 load() 应用）
+   */
+  reloadConfig(): void;
+  /**
+   * 技能仓变更后调用（安装/卸载/发布）：作废 runtime 缓存的技能目录，下次 send 重新扫描。
+   *
+   * 比 `reloadConfig()` 轻，因为它不清 `#handles`——那会连带丢掉每个会话的模型上下文。
+   * 装技能的界面与对话不在同一个页面时（如扩展的 options 页 vs side panel），
+   * 宿主必须自己把变更通知过来，否则新技能要等页面重载才出现在 catalog 里。
+   * @experimental
+   */
+  invalidateSkills(): void;
+  /**
+   * 会话列表页。归档会话也返回：UI 自己分区展示。
+   * `limit` 不给默认值——缺省属于 `SessionStore` 实现，在这里兜底就等于只下推了一半。
+   */
+  listSessions(options?: PageQuery): Promise<ChatSessionListResult>;
+  /** `title` 缺省时会话先无标题，首条消息发出时再按内容补（FR-21.8） */
+  createSession(options?: {
+    title?: string;
+  }): Promise<ChatSessionMeta>;
+  /**
+   * 选中会话并取**最新**一页历史（页内时间升序）。
+   * 返回全量 `ChatMessage[]` 的旧签名已移除：长会话下它强迫每个调用方拿全量。
+   */
+  selectSession(id: string, options?: PageQuery): Promise<Page<ChatMessage>>;
+  /** 向历史方向再取一页；`cursor` 只能来自上一页的 `nextCursor` */
+  loadMoreMessages(cursor: string, options?: {
+    limit?: number;
+  }): Promise<Page<ChatMessage>>;
+  deleteSession(id: string): Promise<void>;
+  /** 重命名会话：写入 title 并锁定（后续 send 不再用首条消息覆盖） */
+  renameSession(id: string, title: string): Promise<void>;
+  /** 归档会话（仅标记，消息与 trace 不动） */
+  archiveSession(id: string): Promise<void>;
+  /** 取消归档 */
+  unarchiveSession(id: string): Promise<void>;
+  /** 重发语义：取该 user 消息文本重新 send（assistant 应答新起一轮；不重写历史） */
+  retry(messageId: string): Promise<void>;
+  /**
+   * 编辑重发：截断该 user 消息（含自身）之后的持久化历史，再用新文本重跑一轮。
+   * runtime session 句柄自带的对话历史不受影响（与 retry 同口径）。
+   */
+  editAndResend(messageId: string, text: string): Promise<void>;
+  /** 从当前会话消息列表删除指定消息并持久化（消息不存在/无当前会话时静默跳过） */
+  deleteMessage(messageId: string): Promise<void>;
+  /**
+   * 驱动当前 session 的一轮 run。同 session 并发由 runtime session handle 内部
+   * 队列串行化（此处直接 await）；UI 层应在 send 期间禁用输入。
+   * 附件按 `attachmentsRoot` 内的路径读回并构造 `LlmContentPart[]`（FR-11.2）。
+   */
+  send(text: string, attachments?: readonly ChatAttachmentInput[]): Promise<void>;
+  /** 附件落盘根目录（composer 附件适配器写入，send 时读回） */
+  get attachmentsRoot(): string;
+  /** 取消进行中的 run（Composer Stop 按钮）；run 未找到/已结束返回 false */
+  cancel(runId: string): boolean;
+  /**
+   * 释放引擎：取消进行中的 run、退订全部事件、丢弃装配缓存。
+   * 宿主重挂组件时用它收尾；只是换配置的话用 `reloadConfig()`，不要 dispose。
+   */
+  dispose(): Promise<void>;
+  /** 列出 interrupted run（InterruptedBanner 数据源）；版本不受支持的项带 unsupported 标记 */
+  listInterrupted(): Promise<RunSnapshotListEntry[]>;
+  /**
+   * 恢复 interrupted run：等待中的交互重新进入 bridge.pending（UI 复用 InteractionForm），
+   * 完成后与 send 同路径（assistant 消息持久化 + run-completed + trace 落盘）。
+   */
+  resume(runId: string): Promise<void>;
+  /** 读取当前画像（FR-19.3：可见） @experimental */
+  readUserProfile(): Promise<UserProfile>;
+  /** 已记录的行为条数；设置面板用它告诉用户「清除」会删掉什么 @experimental */
+  countBehaviorRecords(): Promise<number>;
+  /** 删除单条画像结论（FR-19.3：可编辑可删除） @experimental */
+  deleteUserProfileEntry(id: string): Promise<UserProfile>;
+  /** 清除全部行为记录（FR-19.8）。与清除画像是两个独立操作 @experimental */
+  clearBehaviorRecords(): Promise<void>;
+  /** 清除提炼出的画像（FR-19.8） @experimental */
+  clearUserProfile(): Promise<void>;
+  /**
+   * 一并清除记录与画像，并销毁加密密钥（FR-19.8：关闭总开关时的「一并清除」）。
+   * 密钥留着就等于给残留密文留了一把能解开的钥匙。
+   * @experimental
+   */
+  clearUserProfileData(): Promise<void>;
+  /**
+   * 手动提炼（FR-19.3）。与会话结束后的自动提炼同一条路径，
+   * 区别只在于这里的失败会抛给调用方——用户点了按钮就该看到结果。
+   * @experimental
+   */
+  refineUserProfile(): Promise<UserProfile>;
+  /** 导出画像（FR-19.7）。`excludeIds` 来自导出前的审阅界面 @experimental */
+  exportUserProfile(excludeIds?: readonly string[]): Promise<UserProfileExport>;
+  /** 导入前的差异（FR-19.7）：由 UI 展示并确认后才调用 `applyUserProfileImport` @experimental */
+  diffUserProfileImport(incoming: UserProfileExport): Promise<ReturnType<typeof diffUserProfile> & {
+    origin: string;
+  }>;
+  /** 确认后落库（FR-19.7） @experimental */
+  applyUserProfileImport(incoming: UserProfileExport): Promise<UserProfile>;
+}
+//#endregion
+//#region src/core/types.d.ts
+/**
+ * 治理 port 集合（F1）：宿主把 `SkillStatePolicy` 的适配器交给 chatbot，
+ * 由它接到内部装配的 `WebSkillRuntime` 上。字段名与 `WebSkillRuntimeDeps` 逐个对齐，
+ * 不做重命名：中间多一层映射只会让宿主多记一套名字。
+ * @experimental
+ */
+interface ChatbotGovernancePorts {
+  /** `SkillStatePolicy.toSkillStateGuard()`：read/activate/execute 三入口拦截 */
+  skillStateGuard?: SkillStateGuard;
+  /** `SkillStatePolicy.toSkillIntegrityGuard(verify)`：激活期验签，失败即隔离 */
+  skillIntegrityGuard?: SkillIntegrityGuard;
+  /** `SkillStatePolicy.toSkillOutcomeReporter()`：执行失败计数，达阈值即隔离 */
+  skillOutcomeReporter?: SkillOutcomeReporter;
+  /** `SkillStatePolicy.catalogFilter()`：非 active 技能不进路由候选集 */
+  catalogFilter?: (entries: SkillCatalogEntry[]) => SkillCatalogEntry[] | Promise<SkillCatalogEntry[]>;
+  /**
+   * run 未激活任何技能时的钩子（如 `createMissHook`）。
+   *
+   * 开关存在 `GovernanceFacade.missHook`（属 console），chatbot 读不到也不该依赖它；
+   * 所以读开关是**宿主**的责任。宿主应传一个**每次触发时才读开关**的闭包，
+   * 而不是装配时把布尔值算好——`#assemble()` 不是每次 run 都跑，
+   * 算好了会导致「开着启动 → 中途关闭」不生效（AC-17.11）。
+   */
+  onSkillMiss?: (input: {
+    prompt: string;
+    run: RuntimeRun;
+  }) => Promise<void>;
+}
+/** 分配式交叉：直接写 `信封 & LifecycleEventInit` 会把联合压成一个对象，`phase` 的判别性就没了 */
+type WithChatMeta<T> = T extends unknown ? {
+  type: 'lifecycle';
+  runId: string;
+  at: number;
+} & T : never;
+/**
+ * 生命周期步进事件：`data` 随 `phase` 判别，与 runtime 的 `LifecycleEvent` 同一套契约。
+ * 旧的 `Record<string, unknown>` 等于没有契约：消费方只能硬编码键名。
+ */
+type LifecycleChatEvent = WithChatMeta<LifecycleEventInit>;
+/**
+ * 交互渲染框架档位：native（React InteractionCard）/ a2ui（@a2ui/lit Lit 渲染）/
+ * openui（@openuidev/react-lang Renderer，ui-kit Library）/ vercel（@json-render/react
+ * Registry 渲染 catalog 声明树）
+ * @experimental
+ */
+type RendererKind = 'native' | 'a2ui' | 'openui' | 'vercel';
+/** assistant 消息所属 run 的一次工具调用（终态：completed/failed） @stable */
+interface ChatToolCall {
+  callId: string;
+  name: string;
+  status: 'completed' | 'failed';
+  /** 参数摘要（JSON 截断 100 字符；trace 重放无 args 时留空，卡片展开详情有则显示） */
+  args?: string;
+  /** 执行耗时（trace completed/failed 回填；live 由 started→终态计时） */
+  durationMs?: number;
+  /**
+   * 开始时刻（epoch ms，0.10.0 UI-UX5 #32）。与思考段按时间穿插需要共同时钟；
+   * 旧会话消息没有该字段时工具卡片保持原有相对顺序。
+   */
+  at?: number;
+  /**
+   * failed 时的结构化错误码（如 `TOOL_NOT_ALLOWED`）。
+   * 「被策略拒绝」与「执行失败」在 UI 上是两回事，靠错误码区分而不是解析文案。
+   */
+  errorCode?: string;
+  /** failed 时的错误说明（拒绝时即「被哪条策略拒绝」） */
+  errorMessage?: string;
+}
+/** 已落盘的待发送附件（composer 附件适配器产出） @experimental */
+interface ChatAttachmentInput {
+  id: string;
+  name: string;
+  contentType: string;
+  /** 相对 `attachmentsRoot` 的路径 */
+  path: string;
+  size: number;
+  /** 注入模型的内容形态；决定 send 时读文本还是读二进制 */
+  kind: ChatAttachmentKind;
+  /** 图片经压缩时的原始字节数，供 UI 显示「3.2 MB → 1.8 MB」（FR-11.3） */
+  originalSize?: number;
+}
+/** 随消息持久化的附件元数据 @experimental */
+type ChatAttachmentMeta = ChatAttachmentInput;
+/**
+ * 归并后的显示相位。进行中通道与历史通道共用这一个结构：
+ * 各存一份正是「运行细节首轮后消失」的根因（需求 17 条目 10-6）。
+ * @experimental
+ */
+interface ChatRunPhase {
+  phase: RuntimePhase;
+  at: number;
+  /** 下一个步进到达时回填 */
+  endedAt?: number;
+  /** 由结构化 `LifecycleEvent.data` 派生的一句摘要 */
+  note?: string;
+  /** fail 相位的具体说明：`reason` 只有七种取值，说不出「哪个上限、哪个模型」 */
+  detail?: string;
+}
+/** 本轮发生的一次已提交交互（FR-17.8：提交后表单保留所填值） @experimental */
+interface ChatInteractionRecord {
+  id: string;
+  request: InteractionRequest;
+  /** 提交时的表单值；文件类字段已在引擎侧脱敏 */
+  submittedValues?: unknown;
+}
+/**
+ * 该 run 内模型产出的一段思考正文（0.10.0 UI-UX5 #32）。
+ * 每次模型调用的思考算一段；随消息持久化，重开会话仍能看到。
+ * 模型不支持思考输出时整个数组缺省——不产空壳卡片。
+ * @experimental
+ */
+interface ChatThinking {
+  text: string;
+  /** 首个思考增量到达时刻（epoch ms；与工具卡片按时间穿插的排序依据） */
+  at: number;
+}
+/**
+ * 该 run 的大模型用量（0.10.0 UI-UX5 #47）：随消息持久化，重开会话仍可见。
+ * 上游不回报 token 用量时整个字段缺省——不显示假数据。
+ * @experimental
+ */
+interface ChatTokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  /** 本 run 向大模型发送请求的次数（模型调用轮数） */
+  llmCalls: number;
+}
+/**
+ * 助手消息的有序内容段（分册 17 FR-17.1）：文字与 surface / 结果块按生成顺序排列。
+ * 冗余记账——删掉本字段消息内容不缺失，只退化成「正文在上、扩展在下」（FR-17.11）。
+ * @experimental
+ */
+type ChatContentPart = {
   type: 'text';
   text: string;
   at: number;
@@ -618,405 +1049,150 @@ type ChatEvent = {
   name: string;
   args?: string;
 } | {
-  type: 'tool-failed';
-  runId: string;
-  callId: string;
-  name: string;
-  args?: string;
-  errorCode?: string;
-} | {
-  type: 'run-completed';
-  runId: string;
-  status: 'completed' | 'failed' | 'cancelled';
-  output: string;
-  activeSkillNames: string[];
-  /** 终止原因对应的稳定错误码（仅非正常结束时）：UI 据此分类提示，不再压平为 RUN_FAILED */
-  code?: WebSkillErrorCode;
-} | {
-  type: 'todo-changed';
-  runId: string;
-  items: readonly TodoItem[];
-} | {
-  type: 'page-perceived';
-  runId: string;
-  record: PerceptionRecord;
-} | {
-  type: 'interaction-requested';
-  id: string;
-  requestType: InteractionRequest['type'];
-  /** 等待对象的可读名称（表单标题 / 问题正文）：等待指示器要说清在等什么（FR-21.3） */
-  label?: string;
-} | {
-  type: 'interaction-resolved';
-  id: string;
-  requestType: InteractionRequest['type'];
-  cancelled?: boolean;
-} | LifecycleChatEvent | {
-  type: 'session-updated';
-  session: ChatSessionMeta;
-} |
-/**
- * 会话结束（需求 19 FR-19.3）：切换、删除、归档、引擎释放各算一次。
- * 用户画像的自动提炼挂在这个事件上——没有它就只能靠定时器猜「聊完了没」。
- * @experimental
- */
-{
-  type: 'session-ended';
-  sessionId: string;
-  reason: 'switched' | 'deleted' | 'archived' | 'closed';
-} |
-/** 画像提炼完成（需求 19 FR-19.3）：设置面板据此刷新列表 @experimental */
-{
-  type: 'user-profile-updated';
-  profile: UserProfile;
-} | {
-  type: 'warning';
-  message: string;
-} | {
-  type: 'error';
-  message: string;
-  code?: string;
-};
-/**
- * 快捷指令可选图标名（0.12.0 分册 21）。
- * 用受控枚举而不是让宿主传组件：SDK 的图标集不进公开契约，
- * 换实现（lucide → 别的）时宿主代码不用动。
- * @experimental
- */
-type QuickPromptIconName = 'chart' | 'document' | 'report' | 'search' | 'list' | 'bug' | 'test' | 'metric' | 'compare' | 'page' | 'run' | 'warn' | 'sparkles' | 'settings';
-/**
- * 带图标的快捷指令（0.12.0 分册 21）。
- * @experimental
- */
-interface QuickPrompt {
-  /** 点击后发出的文本，同时作为按钮可见文案 */
-  text: string;
-  /** 缺省或取值不在枚举内时按无图标渲染 */
-  icon?: QuickPromptIconName;
-}
-/** @stable */
-interface ChatbotConfig {
-  /** header 标题，默认 'WebSkill Chat' */
-  title?: string;
-  /** 输入框占位文本 */
-  placeholder?: string;
-  /** 会话/trace/artifact 存储根，默认 '/chat' */
-  chatRoot?: string;
-  /** 覆盖 LLM（缺省走 `RuntimeConfig.llm` → 内置演示 LLM 的选择链） */
-  llm?: LlmClient;
-  /** AgentLoop 调参（maxTurns、超时等） */
-  loopConfig?: AgentLoopConfig;
-  /**
-   * 运行环境配置存储（P2）：装配时 load() 并应用 loop/interaction/router/streaming/
-   * renderResult/sandbox/llm 映射；与 console Configure Tab 共用同一 store（宿主接线）
-   */
-  runtimeConfig?: RuntimeConfigStore;
-  /** WelcomeScreen 快捷 prompt 覆盖（缺省用内置双语示例）；给字符串即无图标 */
-  quickPrompts?: readonly (string | QuickPrompt)[];
-  /**
-   * 开启后模型多一个 `render_ui` 工具，可面向 AI Component Catalog 直接生成声明式 UI。
-   * 默认关：工具描述 + 入参 schema 约 34 KB，会计入每一次请求。
-   * 数字的单一来源是 `@webskill/ui` 的 `catalog/budget.ts`（实测终态 12 744 + 21 470）。
-   *
-   * 接了 `runtimeConfig` 时以 `RuntimeConfig.agentCapabilities.generativeUi` 为准
-   * （设置抽屉里的开关就是它），本字段只在未接配置存储的宿主上生效。
-   */
-  generativeUi?: boolean;
-  /** 宿主注册好钩子的 `HookRunner`；执行策略（超时/严格模式）按 `RuntimeConfig.hooks` 应用 */
-  hooks?: HookRunner;
-  /**
-   * 治理 port 注入（F1）：透传给 `ChatEngineOptions.governance`。
-   * 不注入即完全关闭，行为与 0.0.2 一致。
-   */
-  governance?: ChatbotGovernancePorts;
-  /**
-   * 技能自动生成的候选收货端（需求 9）：透传给 `ChatEngineOptions.skillCandidates`。
-   * 开关只决定工具进不进列表，候选往哪存由宙主注入；不注入时工具返回
-   * `SKILL_GENERATION_DISABLED`，不弹确认框、不产生候选。
-   */
-  skillCandidates?: SkillCandidateSink;
-  /**
-   * 宿主声明的数据源取数入口（分册 16）：透传给 `ChatEngineOptions.fetchData`。
-   * 不注入即脚本上下文没有 `fetchData` 这个键。
-   *
-   * **必须是稳定引用**（模块级或 `useMemo`）：它进 `ChatEngine` 的 `useMemo`
-   * 依赖表，每次渲染新建一个箭头函数会把整个引擎重建掉。
-   */
-  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
-}
-//#endregion
-//#region src/core/hostAdapter.d.ts
-/**
- * 宿主装配口：chatbot 不感知环境（浏览器/Node），全部能力经此注入。
- * 页面动态技能来源同时是外部工具来源与外部技能提供者（同一对象两个 port）。
- * LLM 配置不在这里——它统一由 `RuntimeConfigStore` 承载（0.5.0 起）。
- * @stable
- */
-interface ChatbotHostAdapter {
-  storage: FileSystemProvider;
-  skillRoots: string[];
-  pageSkillSource?: ExternalToolSource & ExternalSkillProvider;
-  navigation: {
-    openConsole(): void;
-    /** 跳 console Traces 面板并定位该 run（v1.1；缺省时消息不渲染 View trace 入口） */
-    openConsoleTrace?(runId: string): void;
-    /** 打开治理面的审批队列并定位该候选（FR-24.2）；宿主未接治理面时不提供，入口随之不渲染 */
-    openConsoleCandidate?(candidateId: string): void;
-  };
-  /** 缺省 BrowserWorkerScriptExecutor（@webskill/browser）；Node 宿主可注入自己的执行器 */
-  executor?: ScriptExecutor;
-  /**
-   * 页面只读感知策略（需求 10）。**只能在这里注入**：启用与否是宿主侧配置，
-   * 设置抽屉里没有也不会有开关（FR-10.1）——风险由部署方承担，
-   * 不应交给终端用户随手勾选。
-   * @experimental
-   */
-  pagePerception?: PagePerceptionPolicy;
-  /**
-   * 页面操作能力（需求 23）。**不注入即完全关闭**，与 `pagePerception` 分开：
-   * 可读不等于可操作。同样只能在这里注入——给终端用户一个「打开代操作」的开关
-   * 等于把安全边界交给最不了解它的人。
-   * @experimental
-   */
-  pageActions?: PageActionPolicy;
-  /**
-   * 读页面链接指向的文档（分册 22）。实现住在 `@webskill/browser`，
-   * 而 chatbot 不依赖它 —— 与 `pagePerception` 同一条装配规矩：宿主注入。
-   * 不注入即 `read_linked_document` 不注册。
-   */
-  linkedDocuments?: LinkedDocumentReader;
-  /** docx → 文本（`extractDocxText`）；不注入即 Word 文档明确报「本环境不支持」 */
-  docxExtractor?: DocxTextExtractor;
-  /** 文档读取留痕出口（FR-22.6） */
-  documentAudit?: {
-    append(event: {
-      type: string;
-      target: string;
-      data?: Record<string, unknown>;
-    }): Promise<unknown>;
-  };
-}
-//#endregion
-//#region src/core/chatEngine.d.ts
-/**
- * 条目能否真的发请求：云端要有端点或密钥，浏览器内置两者都不需要。
- *
- * 导出给 UI：选择器不用同一份判据的话，用户能选中一个空配置条目，
- * 而引擎静默回退到另一条——界面说在用 A、实际跑的是 B（UI-UX8 D1）。
- * @experimental
- */
-declare const isLlmEntryUsable: (entry: RuntimeLlmEntry) => boolean;
-/**
- * 选中条目 → 默认条目 → 首条；命中不可用条目时**回退到下一个可用条目**
- * （0.10.0 复核：选中项失效时宁可静默换用可用模型，也不能把 UI 锁死成
- * 「未配置」死胡同——引擎与 UI 共用同一判据，两边必须同进退）。
- * 全部不可用才 undefined（引擎走内置演示）。
- *
- * 导出给 UI 复用同一判据：composer 的「未配置模型」引导判定必须与引擎的
- * 实际挑选结果一致，否则会出现「UI 说有模型、引擎却走演示档」的错位（0.10.0 UI-UX5 #49-1）。
- * @experimental
- */
-declare function pickUsableLlmEntry(entries: readonly RuntimeLlmEntry[], defaultId: string | undefined, selectedId: string | undefined): RuntimeLlmEntry | undefined;
-/** 默认沙箱执行器的构造参数（adapter.executor 未注入时；executorFactory 替换点可见同一形状） @stable */
-interface SandboxExecutorDeps {
-  fs: FileSystemProvider;
-  sandbox?: SandboxMode;
-  networkPolicy?: NetworkPolicy;
-  capabilities?: BridgeCapabilities;
-  approvalScope?: ApprovalScope;
-  uiBridge?: UiBridge;
-  /** 缺省时 `.ts` 脚本按 `TOOL_UNSUPPORTED` 拒绝 */
-  typescript?: TypeScriptSupportOptions;
-}
-/**
- * 装配时（而非执行时）把 `sandbox.typescript` 转成执行器参数，让配置错误早暴露。
- * 只对绝对 URL 走 `RemoteUrlPolicy`：同源相对路径与打包器 specifier 不是出站请求。
- */
+  type: 'tool-failed';
+  runId: string;
+  callId: string;
+  name: string;
+  args?: string;
+  errorCode?: string;
+} | {
+  type: 'run-completed';
+  runId: string;
+  status: 'completed' | 'failed' | 'cancelled';
+  output: string;
+  activeSkillNames: string[];
+  /** 终止原因对应的稳定错误码（仅非正常结束时）：UI 据此分类提示，不再压平为 RUN_FAILED */
+  code?: WebSkillErrorCode;
+} | {
+  type: 'todo-changed';
+  runId: string;
+  items: readonly TodoItem[];
+} | {
+  type: 'page-perceived';
+  runId: string;
+  record: PerceptionRecord;
+} | {
+  type: 'interaction-requested';
+  id: string;
+  requestType: InteractionRequest['type'];
+  /** 等待对象的可读名称（表单标题 / 问题正文）：等待指示器要说清在等什么（FR-21.3） */
+  label?: string;
+} | {
+  type: 'interaction-resolved';
+  id: string;
+  requestType: InteractionRequest['type'];
+  cancelled?: boolean;
+} | LifecycleChatEvent | {
+  type: 'session-updated';
+  session: ChatSessionMeta;
+} |
 /**
- * 由 `RuntimeConfig` 装出沙箱执行器依赖。
- *
- * 主链路与**评估链路**共用这一处（T-17-H）：此前评估侧只传 `fs`，
- * 于是评估里跑的技能不受沙箱、网络策略、能力与授权范围约束——
- * 那比「.ts 跑不了」严重得多（设计 17 §1.1a）。
- *
+ * 会话结束（需求 19 FR-19.3）：切换、删除、归档、引擎释放各算一次。
+ * 用户画像的自动提炼挂在这个事件上——没有它就只能靠定时器猜「聊完了没」。
  * @experimental
  */
-declare function sandboxExecutorDeps(fs: FileSystemProvider, rc?: RuntimeConfig, uiBridge?: SandboxExecutorDeps['uiBridge']): SandboxExecutorDeps;
+{
+  type: 'session-ended';
+  sessionId: string;
+  reason: 'switched' | 'deleted' | 'archived' | 'closed';
+} |
+/** 画像提炼完成（需求 19 FR-19.3）：设置面板据此刷新列表 @experimental */
+{
+  type: 'user-profile-updated';
+  profile: UserProfile;
+} | {
+  type: 'warning';
+  message: string;
+} | {
+  type: 'error';
+  message: string;
+  code?: string;
+};
 /** @stable */
-interface ChatEngineOptions {
+interface ChatbotConfig {
+  /** header 标题，默认 'WebSkill Chat' */
+  title?: string;
+  /** 输入框占位文本 */
+  placeholder?: string;
+  /** 会话/trace/artifact 存储根，默认 '/chat' */
+  chatRoot?: string;
+  /** 覆盖 LLM（缺省走 `RuntimeConfig.llm` → 内置演示 LLM 的选择链） */
   llm?: LlmClient;
+  /** AgentLoop 调参（maxTurns、超时等） */
   loopConfig?: AgentLoopConfig;
-  chatRoot?: string;
-  /** 运行环境配置存储（P2）：#ensureReady 装配时 load()（默认值兜底）并按映射应用 */
-  runtimeConfig?: RuntimeConfigStore;
-  /** 初始渲染框架档（默认 'native'；运行中可 setRenderer 热切换） */
-  renderer?: RendererKind;
   /**
-   * 注入 `render_ui` 工具，让模型面向 AI Component Catalog 生成声明式 UI。
-   *
-   * 注入了 `runtimeConfig` 时**以 `RuntimeConfig.agentCapabilities.generativeUi` 为准**，
-   * 本字段只在未接配置存储的宿主上生效（否则设置面板里的开关点了不算数）。
+   * 运行环境配置存储（P2）：装配时 load() 并应用 loop/interaction/router/streaming/
+   * renderResult/sandbox/llm 映射；与 console Configure Tab 共用同一 store（宿主接线）
    */
-  generativeUi?: boolean;
-  /** 沙箱执行器替换点（测试注入 spy 断言构造参数；缺省 BrowserWorkerScriptExecutor） */
-  executorFactory?: (deps: SandboxExecutorDeps) => ScriptExecutor;
+  runtimeConfig?: RuntimeConfigStore;
   /**
-   * 宿主声明的数据源取数入口（分册 16）。不注入即脚本上下文没有 `fetchData` 这个键。
+   * WelcomeScreen 快捷 prompt 的**一次性种子**（0.13.0 分册 21 FR-21.5）；给字符串即无图标、不分语种。
    *
-   * 装配点必须在宿主：策略本体 `DataSourcePolicy` 住在 `@webskill/agent`，
-   * 而数据源的目标地址是宿主自己的业务知识，chatbot 无从代为声明。
-   * 能力开关 `sandbox.capabilities.fetchData` 缺省关，注入了也还要宿主在配置里打开。
+   * 接了 `runtimeConfig` 时，本字段只在该存储**从未种子化过**时被注入一次
+   * （之后 `RuntimeConfig.quickPrompts` 是唯一权威，console 的「快捷指令」页改的就是它）；
+   * 用户在 console 里删光清单后本字段**不会**自行回填，除非用户点「恢复宿主默认」。
+   * 未接 `runtimeConfig` 的宿主上，本字段仍是直接的静态清单。
    */
-  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
+  quickPrompts?: readonly (string | QuickPrompt)[];
   /**
-   * 会话落盘替换点（缺省 `FsSessionStore`，落在 `<chatRoot>/sessions`）。
-   * 宕主换自己的实现（如 IndexedDB）与测试统计端口读写量都走这里。
+   * 按当前上下文动态下发的快捷指令（FR-17.4）。宿主可以随用户所在页面随时换一批。
+   *
+   * 与静态清单**拼接**而不是覆盖（动态在前，同文案去重）——用户在 console 里配的
+   * 不该被宿主惄惄吞掉。不同于静态清单，它在**对话进行中**也会渲染（FR-17.6）。
+   * @experimental
    */
-  sessionStore?: SessionStore<ChatMessage>;
+  dynamicQuickPrompts?: readonly (string | QuickPrompt)[];
   /**
-   * 宿主已注册好钩子的执行器；装配时把 `RuntimeConfig.hooks` 应用到它再交给 runtime。
-   * 不注入即不挂钩子（与 0.0.2 行为一致）。
+   * 开启后模型多一个 `render_ui` 工具，可面向 AI Component Catalog 直接生成声明式 UI。
+   * 默认关：工具描述 + 入参 schema 约 34 KB，会计入每一次请求。
+   * 数字的单一来源是 `@webskill/ui` 的 `catalog/budget.ts`（实测终态 12 744 + 21 470）。
+   *
+   * 接了 `runtimeConfig` 时以 `RuntimeConfig.agentCapabilities.generativeUi` 为准
+   * （设置抽屉里的开关就是它），本字段只在未接配置存储的宿主上生效。
    */
+  generativeUi?: boolean;
+  /** 宿主注册好钩子的 `HookRunner`；执行策略（超时/严格模式）按 `RuntimeConfig.hooks` 应用 */
   hooks?: HookRunner;
   /**
-   * 治理 port 注入（F1）：把 `SkillStatePolicy` 的三个适配器接到本引擎装配的 runtime 上。
-   *
-   * 不注入即完全关闭，行为与 0.0.2 一致。装配点必须在宿主：chatbot 不能依赖
-   * `@webskill/governance`（它是可选治理层，且要求宿主提供治理根与审计存储）。
-   *
-   * 三个一起给才形成闭环——只给 `skillOutcomeReporter` 会把技能标成 `quarantined`
-   * 却仍旧照常路由和执行，降级形同虚设。
+   * 治理 port 注入（F1）：透传给 `ChatEngineOptions.governance`。
+   * 不注入即完全关闭，行为与 0.0.2 一致。
    */
   governance?: ChatbotGovernancePorts;
   /**
-   * 技能自动生成的候选收货端（需求 12 号）。与 `governance` 同理，装配点在宿主：
-   * `@webskill/governance` 的 `createCandidateSink()` 是现成实现。
-   *
-   * 开关另在 `RuntimeConfig.agentCapabilities.skillGeneration`（默认关）；
-   * 开关开但未注入本端口时，工具会把 `SKILL_GENERATION_DISABLED` 回给模型。
+   * 技能自动生成的候选收货端（需求 9）：透传给 `ChatEngineOptions.skillCandidates`。
+   * 开关只决定工具进不进列表，候选往哪存由宙主注入；不注入时工具返回
+   * `SKILL_GENERATION_DISABLED`，不弹确认框、不产生候选。
    */
   skillCandidates?: SkillCandidateSink;
-}
-/**
- * 对话框引擎：装配 WebSkillRuntime + 会话持久化 + 事件分发。
- * RuntimeConfig 的 load() 是异步的，runtime 在首次 send 前懒装配（#ensureReady）。
- * @stable
- */
-declare class ChatEngine {
-  #private;
-  readonly bridge: ReactBridgeState;
-  constructor(adapter: ChatbotHostAdapter, options?: ChatEngineOptions);
-  /** 当前待办清单快照（宿主可直读；实时更新订阅 `todo-changed` 事件） */
-  get todos(): readonly TodoItem[];
-  /** 当前渲染框架档 */
-  get renderer(): RendererKind;
-  /** 当前会话选中的模型条目 id；未显式切换过时为 undefined（走 `RuntimeConfig.llm.defaultId`） */
-  get modelId(): string | undefined;
-  /**
-   * 切换本会话后续消息使用的模型条目（需求 4）。传 `undefined` 回到配置里的默认项。
-   * 重装配 runtime 以换掉客户端；已落盘的消息不受影响。
-   */
-  setModel(entryId: string | undefined): void;
-  /** 会话文件所在目录：「存储未初始化」提示要把路径写给用户看 @experimental */
-  get sessionsRoot(): string;
-  /** 渲染框架热切换：复合桥按档分发，无需重装配 runtime（会话句柄保留） */
-  setRenderer(renderer: RendererKind): void;
-  /** 非 native 三档共用的交互通道（Chatbot 的 SpecInteraction 订阅/attach；core 只产出 catalog 节点树） */
-  get interactionChannel(): SpecInteractionChannel;
-  /** 探测 @a2ui/lit 是否安装（Appearance/设置区 A2UI 档置灰判定） */
-  probeA2uiAvailability(): Promise<boolean>;
-  onEvent(listener: (event: ChatEvent) => void): () => void;
-  /**
-   * 配置源变更后调用（LLM 设置 / RuntimeConfigStore 内容变化）：丢弃缓存的
-   * runtime/llm/会话句柄，下次 send 重新装配（RuntimeConfig 重新 load() 应用）
-   */
-  reloadConfig(): void;
-  /**
-   * 会话列表页。归档会话也返回：UI 自己分区展示。
-   * `limit` 不给默认值——缺省属于 `SessionStore` 实现，在这里兜底就等于只下推了一半。
-   */
-  listSessions(options?: PageQuery): Promise<ChatSessionListResult>;
-  /** `title` 缺省时会话先无标题，首条消息发出时再按内容补（FR-21.8） */
-  createSession(options?: {
-    title?: string;
-  }): Promise<ChatSessionMeta>;
-  /**
-   * 选中会话并取**最新**一页历史（页内时间升序）。
-   * 返回全量 `ChatMessage[]` 的旧签名已移除：长会话下它强迫每个调用方拿全量。
-   */
-  selectSession(id: string, options?: PageQuery): Promise<Page<ChatMessage>>;
-  /** 向历史方向再取一页；`cursor` 只能来自上一页的 `nextCursor` */
-  loadMoreMessages(cursor: string, options?: {
-    limit?: number;
-  }): Promise<Page<ChatMessage>>;
-  deleteSession(id: string): Promise<void>;
-  /** 重命名会话：写入 title 并锁定（后续 send 不再用首条消息覆盖） */
-  renameSession(id: string, title: string): Promise<void>;
-  /** 归档会话（仅标记，消息与 trace 不动） */
-  archiveSession(id: string): Promise<void>;
-  /** 取消归档 */
-  unarchiveSession(id: string): Promise<void>;
-  /** 重发语义：取该 user 消息文本重新 send（assistant 应答新起一轮；不重写历史） */
-  retry(messageId: string): Promise<void>;
-  /**
-   * 编辑重发：截断该 user 消息（含自身）之后的持久化历史，再用新文本重跑一轮。
-   * runtime session 句柄自带的对话历史不受影响（与 retry 同口径）。
-   */
-  editAndResend(messageId: string, text: string): Promise<void>;
-  /** 从当前会话消息列表删除指定消息并持久化（消息不存在/无当前会话时静默跳过） */
-  deleteMessage(messageId: string): Promise<void>;
-  /**
-   * 驱动当前 session 的一轮 run。同 session 并发由 runtime session handle 内部
-   * 队列串行化（此处直接 await）；UI 层应在 send 期间禁用输入。
-   * 附件按 `attachmentsRoot` 内的路径读回并构造 `LlmContentPart[]`（FR-11.2）。
-   */
-  send(text: string, attachments?: readonly ChatAttachmentInput[]): Promise<void>;
-  /** 附件落盘根目录（composer 附件适配器写入，send 时读回） */
-  get attachmentsRoot(): string;
-  /** 取消进行中的 run（Composer Stop 按钮）；run 未找到/已结束返回 false */
-  cancel(runId: string): boolean;
-  /**
-   * 释放引擎：取消进行中的 run、退订全部事件、丢弃装配缓存。
-   * 宿主重挂组件时用它收尾；只是换配置的话用 `reloadConfig()`，不要 dispose。
-   */
-  dispose(): Promise<void>;
-  /** 列出 interrupted run（InterruptedBanner 数据源）；版本不受支持的项带 unsupported 标记 */
-  listInterrupted(): Promise<RunSnapshotListEntry[]>;
   /**
-   * 恢复 interrupted run：等待中的交互重新进入 bridge.pending（UI 复用 InteractionForm），
-   * 完成后与 send 同路径（assistant 消息持久化 + run-completed + trace 落盘）。
+   * 宿主声明的数据源取数入口（分册 16）：透传给 `ChatEngineOptions.fetchData`。
+   * 不注入即脚本上下文没有 `fetchData` 这个键。
+   *
+   * **必须是稳定引用**（模块级或 `useMemo`）：它进 `ChatEngine` 的 `useMemo`
+   * 依赖表，每次渲染新建一个箭头函数会把整个引擎重建掉。
    */
-  resume(runId: string): Promise<void>;
-  /** 读取当前画像（FR-19.3：可见） @experimental */
-  readUserProfile(): Promise<UserProfile>;
-  /** 已记录的行为条数；设置面板用它告诉用户「清除」会删掉什么 @experimental */
-  countBehaviorRecords(): Promise<number>;
-  /** 删除单条画像结论（FR-19.3：可编辑可删除） @experimental */
-  deleteUserProfileEntry(id: string): Promise<UserProfile>;
-  /** 清除全部行为记录（FR-19.8）。与清除画像是两个独立操作 @experimental */
-  clearBehaviorRecords(): Promise<void>;
-  /** 清除提炼出的画像（FR-19.8） @experimental */
-  clearUserProfile(): Promise<void>;
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
   /**
-   * 一并清除记录与画像，并销毁加密密钥（FR-19.8：关闭总开关时的「一并清除」）。
-   * 密钥留着就等于给残留密文留了一把能解开的钥匙。
-   * @experimental
+   * 宿主声明的数据源清单（0.14.0 分册 19）：透传给 `ChatEngineOptions.dataSources`。
+   * 用 `DataSourcePolicy.publicSources` 取，不要改传 `sources`——后者带 `target`，
+   * 结构子类型让这个赋值的类型检查能过，接口地址就静默进了模型上下文。
+   *
+   * **必须是稳定引用**（模块级或 `useMemo`）：同 `fetchData`，它进 `ChatEngine` 的依赖表。
+   * 源清单随用户配置变动的宿主传函数形式，引擎在每次激活时求值，改配置无须重建引擎。
    */
-  clearUserProfileData(): Promise<void>;
+  dataSources?: readonly DataSourceInfo[] | (() => readonly DataSourceInfo[]);
   /**
-   * 手动提炼（FR-19.3）。与会话结束后的自动提炼同一条路径，
-   * 区别只在于这里的失败会抛给调用方——用户点了按钮就该看到结果。
+   * 沙箱执行器替换点（分册 12）：透传给 `ChatEngineOptions.executorFactory`。
+   *
+   * 需要自定义执行器的宿主**必须走这里，而不是 `ChatbotHostAdapter.executor`**：
+   * 后者是一个构造期就定死的实例，装配时会整个跳过 `RuntimeConfig.sandbox` 映射，
+   * 于是设置面板里的能力开关、网络策略、TypeScript 与授权范围全部点了不算数。
+   * 本替换点拿到的 `deps` 已由引擎按当前配置算好，宿主只需覆盖自己要换的那几项。
+   *
+   * **必须是稳定引用**（模块级或 `useMemo`）：同 `fetchData`，它进 `ChatEngine` 的依赖表。
    * @experimental
    */
-  refineUserProfile(): Promise<UserProfile>;
-  /** 导出画像（FR-19.7）。`excludeIds` 来自导出前的审阅界面 @experimental */
-  exportUserProfile(excludeIds?: readonly string[]): Promise<UserProfileExport>;
-  /** 导入前的差异（FR-19.7）：由 UI 展示并确认后才调用 `applyUserProfileImport` @experimental */
-  diffUserProfileImport(incoming: UserProfileExport): Promise<ReturnType<typeof diffUserProfile> & {
-    origin: string;
-  }>;
-  /** 确认后落库（FR-19.7） @experimental */
-  applyUserProfileImport(incoming: UserProfileExport): Promise<UserProfile>;
+  executorFactory?: (deps: SandboxExecutorDeps) => ScriptExecutor;
 }
 //#endregion
 //#region src/core/interactionBridge.d.ts
@@ -1123,6 +1299,9 @@ declare const chatbotDictionary: {
     'app.title': string;
     'header.sessions': string;
     'header.settings': string;
+    'header.dock': string;
+    'header.undock': string;
+    'header.close': string;
     'header.console': string;
     'header.theme.light': string;
     'header.theme.dark': string;
@@ -1168,10 +1347,6 @@ declare const chatbotDictionary: {
     'welcome.capability.transparency.title': string;
     'welcome.capability.transparency.description': string;
     'welcome.quickPrompts': string;
-    'welcome.prompt.1': string;
-    'welcome.prompt.2': string;
-    'welcome.prompt.3': string;
-    'welcome.prompt.4': string;
     'message.copy': string;
     'message.copied': string;
     'message.retry': string;
@@ -1257,11 +1432,20 @@ declare const chatbotDictionary: {
     'interaction.pageAction.click': string;
     'interaction.pageAction.fill': string;
     'interaction.pageAction.submit': string;
+    'interaction.pageAction.select': string;
+    'interaction.pageAction.set': string;
+    'interaction.pageAction.attach': string;
     'interaction.pageAction.role.click': string;
     'interaction.pageAction.role.fill': string;
     'interaction.pageAction.role.submit': string;
+    'interaction.pageAction.role.select': string;
+    'interaction.pageAction.role.set': string;
+    'interaction.pageAction.role.attach': string;
+    'interaction.pageAction.remember': string;
     'interaction.pageAction.frame': string;
     'interaction.pageAction.elevated': string;
+    'interaction.downloadedFile.file': string;
+    'interaction.downloadedFile.remember': string;
     'interaction.traceEvidence.title': string;
     'interaction.traceEvidence.columnDraft': string;
     'interaction.traceEvidence.columnTrace': string;
@@ -1326,9 +1510,6 @@ declare const chatbotDictionary: {
     'composer.noModel.description': string;
     'composer.noModel.configure': string;
     'capability.group': string;
-    'composer.pageCapture': string;
-    'composer.pageCapture.disabled.setting': string;
-    'composer.pageCapture.disabled.model': string;
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
@@ -1479,6 +1660,9 @@ declare const chatbotDictionary: {
     'app.title': string;
     'header.sessions': string;
     'header.settings': string;
+    'header.dock': string;
+    'header.undock': string;
+    'header.close': string;
     'header.console': string;
     'header.theme.light': string;
     'header.theme.dark': string;
@@ -1524,10 +1708,6 @@ declare const chatbotDictionary: {
     'welcome.capability.transparency.title': string;
     'welcome.capability.transparency.description': string;
     'welcome.quickPrompts': string;
-    'welcome.prompt.1': string;
-    'welcome.prompt.2': string;
-    'welcome.prompt.3': string;
-    'welcome.prompt.4': string;
     'message.copy': string;
     'message.copied': string;
     'message.edit': string;
@@ -1613,11 +1793,20 @@ declare const chatbotDictionary: {
     'interaction.pageAction.click': string;
     'interaction.pageAction.fill': string;
     'interaction.pageAction.submit': string;
+    'interaction.pageAction.select': string;
+    'interaction.pageAction.set': string;
+    'interaction.pageAction.attach': string;
     'interaction.pageAction.role.click': string;
     'interaction.pageAction.role.fill': string;
     'interaction.pageAction.role.submit': string;
+    'interaction.pageAction.role.select': string;
+    'interaction.pageAction.role.set': string;
+    'interaction.pageAction.role.attach': string;
+    'interaction.pageAction.remember': string;
     'interaction.pageAction.frame': string;
     'interaction.pageAction.elevated': string;
+    'interaction.downloadedFile.file': string;
+    'interaction.downloadedFile.remember': string;
     'interaction.traceEvidence.title': string;
     'interaction.traceEvidence.columnDraft': string;
     'interaction.traceEvidence.columnTrace': string;
@@ -1682,9 +1871,6 @@ declare const chatbotDictionary: {
     'composer.noModel.description': string;
     'composer.noModel.configure': string;
     'capability.group': string;
-    'composer.pageCapture': string;
-    'composer.pageCapture.disabled.setting': string;
-    'composer.pageCapture.disabled.model': string;
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
@@ -1838,6 +2024,9 @@ declare const useT: () => TranslateFn<{
     'app.title': string;
     'header.sessions': string;
     'header.settings': string;
+    'header.dock': string;
+    'header.undock': string;
+    'header.close': string;
     'header.console': string;
     'header.theme.light': string;
     'header.theme.dark': string;
@@ -1883,10 +2072,6 @@ declare const useT: () => TranslateFn<{
     'welcome.capability.transparency.title': string;
     'welcome.capability.transparency.description': string;
     'welcome.quickPrompts': string;
-    'welcome.prompt.1': string;
-    'welcome.prompt.2': string;
-    'welcome.prompt.3': string;
-    'welcome.prompt.4': string;
     'message.copy': string;
     'message.copied': string;
     'message.retry': string;
@@ -1972,11 +2157,20 @@ declare const useT: () => TranslateFn<{
     'interaction.pageAction.click': string;
     'interaction.pageAction.fill': string;
     'interaction.pageAction.submit': string;
+    'interaction.pageAction.select': string;
+    'interaction.pageAction.set': string;
+    'interaction.pageAction.attach': string;
     'interaction.pageAction.role.click': string;
     'interaction.pageAction.role.fill': string;
     'interaction.pageAction.role.submit': string;
+    'interaction.pageAction.role.select': string;
+    'interaction.pageAction.role.set': string;
+    'interaction.pageAction.role.attach': string;
+    'interaction.pageAction.remember': string;
     'interaction.pageAction.frame': string;
     'interaction.pageAction.elevated': string;
+    'interaction.downloadedFile.file': string;
+    'interaction.downloadedFile.remember': string;
     'interaction.traceEvidence.title': string;
     'interaction.traceEvidence.columnDraft': string;
     'interaction.traceEvidence.columnTrace': string;
@@ -2041,9 +2235,6 @@ declare const useT: () => TranslateFn<{
     'composer.noModel.description': string;
     'composer.noModel.configure': string;
     'capability.group': string;
-    'composer.pageCapture': string;
-    'composer.pageCapture.disabled.setting': string;
-    'composer.pageCapture.disabled.model': string;
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
@@ -2194,6 +2385,9 @@ declare const useT: () => TranslateFn<{
     'app.title': string;
     'header.sessions': string;
     'header.settings': string;
+    'header.dock': string;
+    'header.undock': string;
+    'header.close': string;
     'header.console': string;
     'header.theme.light': string;
     'header.theme.dark': string;
@@ -2239,10 +2433,6 @@ declare const useT: () => TranslateFn<{
     'welcome.capability.transparency.title': string;
     'welcome.capability.transparency.description': string;
     'welcome.quickPrompts': string;
-    'welcome.prompt.1': string;
-    'welcome.prompt.2': string;
-    'welcome.prompt.3': string;
-    'welcome.prompt.4': string;
     'message.copy': string;
     'message.copied': string;
     'message.edit': string;
@@ -2328,11 +2518,20 @@ declare const useT: () => TranslateFn<{
     'interaction.pageAction.click': string;
     'interaction.pageAction.fill': string;
     'interaction.pageAction.submit': string;
+    'interaction.pageAction.select': string;
+    'interaction.pageAction.set': string;
+    'interaction.pageAction.attach': string;
     'interaction.pageAction.role.click': string;
     'interaction.pageAction.role.fill': string;
     'interaction.pageAction.role.submit': string;
+    'interaction.pageAction.role.select': string;
+    'interaction.pageAction.role.set': string;
+    'interaction.pageAction.role.attach': string;
+    'interaction.pageAction.remember': string;
     'interaction.pageAction.frame': string;
     'interaction.pageAction.elevated': string;
+    'interaction.downloadedFile.file': string;
+    'interaction.downloadedFile.remember': string;
     'interaction.traceEvidence.title': string;
     'interaction.traceEvidence.columnDraft': string;
     'interaction.traceEvidence.columnTrace': string;
@@ -2397,9 +2596,6 @@ declare const useT: () => TranslateFn<{
     'composer.noModel.description': string;
     'composer.noModel.configure': string;
     'capability.group': string;
-    'composer.pageCapture': string;
-    'composer.pageCapture.disabled.setting': string;
-    'composer.pageCapture.disabled.model': string;
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
@@ -2576,7 +2772,7 @@ interface AppearanceChange {
  * 不在其中（AC-20.7 按「无未覆盖的配置类 leaf」执行，见偏差 D-15）。
  * @experimental
  */
-type SettingsSectionId = 'settings.runtime' | 'settings.sandbox' | 'settings.genui' | 'settings.trust' | 'settings.privacy' | 'settings.appearance' | 'connections.models' | 'connections.webmcp' | 'connections.page' | 'connections.mcp';
+type SettingsSectionId = 'settings.runtime' | 'settings.sandbox' | 'settings.genui' | 'settings.prompts' | 'settings.trust' | 'settings.privacy' | 'settings.appearance' | 'connections.models' | 'connections.webmcp' | 'connections.page' | 'connections.mcp';
 //#endregion
 //#region src/react/useChatLayout.d.ts
 /** 宿主可指定的布局档；auto 按容器尺寸判定 @stable */
@@ -2613,6 +2809,21 @@ interface ChatbotProps {
    * `section` 可选（FR-16.5）：齿轮不带分区（→ Overview），带诉求的入口（错误卡等）才传分区。
    */
   onOpenSettings?(section?: SettingsSectionId): void;
+  /**
+   * 当前是否已「固定」到宿主页面（下沉占宽）。**受控**：SDK 只用它决定图标与
+   * `aria-pressed`，自身布局与样式一概不因它改变——悬浮/下沉的容器归宿主外壳（FR-16.2）。
+   */
+  docked?: boolean;
+  /**
+   * 用户请求切换固定态（FR-16.1）。宿主不接就不渲染这个按钮。
+   * 入参是用户**请求切换到**的目标态；宿主改完布局后把新的 `docked` 传回来。
+   */
+  onDock?(next: boolean): void;
+  /**
+   * 用户请求关闭对话框（FR-16.3）。宿主不接就不渲染这个按钮。
+   * SDK 只发出意图，不卸载自己、不清理任何状态。
+   */
+  onClose?(): void;
   /**
    * 装配完成后把引擎交给宿主，用于接线跨界面动作（例如 console 的快照恢复入口
    * 需要调 `engine.resume(runId)`）。每次重新装配都会再调一次。
@@ -2624,7 +2835,7 @@ interface ChatbotProps {
  * presentation shell and accessible thread primitives.
  * @stable
  */
-declare function Chatbot({ adapter, config, locale: localeProp, theme: themeProp, renderer: rendererProp, dictationLang: dictationLangProp, surfaceRegistry, layout, sessionList, onOpenSettings, onEngineReady }: ChatbotProps): import("react").JSX.Element;
+declare function Chatbot({ adapter, config, locale: localeProp, theme: themeProp, renderer: rendererProp, dictationLang: dictationLangProp, surfaceRegistry, layout, sessionList, onOpenSettings, docked, onDock, onClose, onEngineReady }: ChatbotProps): import("react").JSX.Element;
 //#endregion
 //#region src/react/A2uiSurfaceHost.d.ts
 /** @experimental */
@@ -2808,6 +3019,6 @@ declare function ErrorCard({ code, message, loopLimits, onOpenSettings, onDismis
  * Version of the published `@webskill/chatbot` package, injected at build time.
  * @stable
  */
-declare const CHATBOT_VERSION = "0.8.0";
+declare const CHATBOT_VERSION = "0.11.0";
 //#endregion
-export { A2uiSurfaceHost, type A2uiSurfaceHostProps, A2uiSurfaceSnapshotHost, type A2uiSurfaceSnapshotHostProps, type AppearanceChange, CHATBOT_VERSION, type ChatAttachmentInput, type ChatAttachmentMeta, type ChatContentPart, ChatEngine, type ChatEngineOptions, type ChatEvent, type ChatInteractionRecord, type ChatLayout, type ChatMessage, type ChatRunPhase, type ChatSessionListResult, type ChatSessionMeta, type ChatTheme, type ChatThinking, type ChatTokenUsage, type ChatToolCall, Chatbot, type ChatbotConfig, type ChatbotGovernancePorts, type ChatbotHostAdapter, type ChatbotProps, CompositeUiBridge, type CompositeUiBridgeDeps, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, type DownloadableFile, ErrorCard, type ErrorCardProps, InteractionCard, type InteractionCardProps, InterruptedBanner, type InterruptedBannerProps, type Locale, OpenUiSurfaceHost, type OpenUiSurfaceHostProps, OpenUiSurfaceSnapshotHost, type OpenUiSurfaceSnapshotHostProps, type QuickPrompt, type QuickPromptIconName, type RendererCapability, type RendererKind, type ResolvedChatLayout, ResultBlockList, type ResultBlockListProps, ResultBlocksPro, type ResultBlocksProProps, type RunSnapshot, type RuntimeAppearanceConfig, type RuntimeConfig, type RuntimeConfigStore, type RuntimeRendererId, type SandboxExecutorDeps, type SettingsSectionId, SkillBadges, SpecInteraction, type SpecInteractionProps, VercelPayloadPreview, type VercelPayloadPreviewProps, VercelSurfaceHost, type VercelSurfaceHostProps, VercelSurfaceSnapshotHost, type VercelSurfaceSnapshotHostProps, chatbotDictionary, configureA2uiMarkdown, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };
+export { A2uiSurfaceHost, type A2uiSurfaceHostProps, A2uiSurfaceSnapshotHost, type A2uiSurfaceSnapshotHostProps, type AppearanceChange, CHATBOT_VERSION, type ChatAttachmentInput, type ChatAttachmentMeta, type ChatContentPart, ChatEngine, type ChatEngineOptions, type ChatEvent, type ChatInteractionRecord, type ChatLayout, type ChatMessage, type ChatRunPhase, type ChatSessionListResult, type ChatSessionMeta, type ChatTheme, type ChatThinking, type ChatTokenUsage, type ChatToolCall, Chatbot, type ChatbotConfig, type ChatbotGovernancePorts, type ChatbotHostAdapter, type ChatbotProps, CompositeUiBridge, type CompositeUiBridgeDeps, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, type DownloadableFile, ErrorCard, type ErrorCardProps, InteractionCard, type InteractionCardProps, InterruptedBanner, type InterruptedBannerProps, type Locale, type LocalizedText, OpenUiSurfaceHost, type OpenUiSurfaceHostProps, OpenUiSurfaceSnapshotHost, type OpenUiSurfaceSnapshotHostProps, type QuickPrompt, type QuickPromptIconName, type RendererCapability, type RendererKind, type ResolvedChatLayout, ResultBlockList, type ResultBlockListProps, ResultBlocksPro, type ResultBlocksProProps, type RunSnapshot, type RuntimeAppearanceConfig, type RuntimeConfig, type RuntimeConfigStore, type RuntimeQuickPrompt, type RuntimeRendererId, type SandboxExecutorDeps, type SettingsSectionId, SkillBadges, SpecInteraction, type SpecInteractionProps, VercelPayloadPreview, type VercelPayloadPreviewProps, VercelSurfaceHost, type VercelSurfaceHostProps, VercelSurfaceSnapshotHost, type VercelSurfaceSnapshotHostProps, chatbotDictionary, configureA2uiMarkdown, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };