@aiti-ai/aiti-draft-keeper 0.0.0-stage → 0.1.8

package/AGENTS.md

@@ -0,0 +1,28 @@
+# aiti-draft-keeper 扩展（部署目录直改指南）
+
+## 结构
+- 运行时文件平铺在本目录根（index.ts / core.cjs …，宿主 loader 按相对路径加载——**禁手改运行时平铺文件**，改 src/ 再 build）
+- `src/` 源码（client/src + 服务端 ts/cjs）· `dist/` 构建产物（禁手改）· `tools/` 构建/部署脚本
+- npm 包形态的扩展：本目录 package.json 含 version 与 aitiConfigs 声明
+
+## 小改现场流程（改文案/样式/小逻辑）
+1. 改 `src/` 下对应源码
+2. `node tools/build.mjs`（client 有构建产物的扩展；纯服务端改动跳过）
+3. `curl -X POST http://127.0.0.1:3001/api/extensions/reload`（dev；prod 3002；外部经 nginx 带 basePath：/dev、/mac、/mdev、/win、/wdev → `/xxx/api/extensions/reload`）
+4. 浏览器刷新页面验证
+
+## 大改回源码仓
+- 源码仓：`extensions/aiti-draft-keeper/`（git 管理，deploy 同步回本目录）
+- 改完在源码仓跑 `node tools/deploy.mjs`（或仓库根 `node scripts/deploy-all.mjs --only aiti-draft-keeper`）
+
+## 数据目录（数据分层：config / cache）
+- `ctx.configDir` 根级 = 配置与关键小状态（aiti-configs 备份范围；小、珍贵、人可读）
+- `ctx.cacheDir`（= `<configDir>/cache/`）= 可删缓存：db/venv/日志/大文件；rm -rf 后扩展下次访问自动重建
+- `ctx.dataDir` 已移除（访问即抛）——新代码禁用
+- 本扩展白名单（永不为 cache 的配置文件）见 package.json `aitiConfigs.configFiles`
+
+## 红线
+- 禁轮询（setInterval 拉取）；需要等待用事件/回调/SSE（桥的 SSE、aiti-event-bus topics）
+- 禁重启生产服务（pi-web 3002 等 restart 须用户明确同意）
+- 禁手改 dist/ 与运行时平铺文件；跨扩展通信走 ctx.services（禁 globalThis.__ext 直穿）
+- 服务端：SQLite 一律 WAL + 分批小事务（批间 setImmediate 让步）；禁 execFileSync 调 >1s 外部程序；>8MB 文件禁同步读

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiti-ai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# Draft Keeper（aiti-draft-keeper）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 来源 · Origin
+
+本包是 **aiti** 生态的组成部分——以 [pi](https://pi.dev) 为引擎的个人 AI 开发工作台与本地调试注入生态：**aiti-agent**（自托管 Web 工作台，基于开源项目 [pi-web](https://github.com/aiti-ai/pi-web) 构建，浏览器为主操作面）+ 各开发工具内的调试注入（aiti-devtools）+ 丰富的扩展体系。
+
+This package is part of the **aiti** ecosystem — a personal AI development workbench powered by [pi](https://pi.dev): **aiti-agent** (a self-hosted web workbench built on the open-source [pi-web](https://github.com/aiti-ai/pi-web)) plus debug injection into mainstream dev tools (aiti-devtools) and a rich extension system.
+
+**English**: Draft persistence and crash recovery for the composer — the sole owner of the composer draft state machine (v2 intent contract), shared slots across tabs, 7-day stale pruning.
+
+- 工作台 / workbench: <https://github.com/aiti-ai/pi-web>
+- 生态仓库 / monorepo: <https://github.com/aiti-ai/aiti-ai>
+- 官网 / site: <https://aiti.pw>
+
+
+草稿持久化 + 恢复接管扩展——pi-web 去 fork 化 P2 的产物（`docs/pi-web-defork-roadmap.md` §3.B）。
+core 的草稿逻辑（原 `lib/draft-store.ts` + ChatInput/ChatWindow 接线）已全部迁出，
+**core 零 draft-store 依赖**；core 经 `lib/composer/draft-api.ts` 注册表访问本扩展
+提供的存储 API，经 composer 增强契约广播 key/值变化。
+
+## 架构（v2：状态机唯一所有者）
+
+- `client/core.mjs` = **草稿状态机纯逻辑**（storage/timers/onRestore 注入可测，
+  `core.test.mjs` 17 用例钉死语义）；`client/aiti-draft-keeper-client.mjs` =
+  薄壳（window/localStorage 适配 + hydration 门控 + DraftApi 注册）。
+- **core（pi-web）唯一写入口是意图**（`applyDraftIntent`，见 pi-web
+  `docs/composer-enhancement-contract.md` v2 节）：
+  - `sessionCreated {provisionalKey, sessionId}`：promote 时 provisional 草稿
+    作废；promote 窗口（key prop 切换前）的新输入重定向落 sid 槽位；
+  - `rejected {key, text, images}`：发送失败合并回草稿，当前框则写回。
+- `slotKeyOf` 按**最后一个冒号**取 cwd 段——draftId 可能自身含冒号
+  （?cwd= 引导的 `initial:<cwd>` 形式），不得按首个冒号切分。
+- `pruneStale()`：启动一次性清理 >7 天未写入槽位（含旧 per-tab 残留、无 ts 旧格式）。
+- 已修「恢复即删」：scan 恢复后同一轮 onChange 直接返回（恢复把 known 指向
+  恢复值后，空快照继续走清空分支会在确认延时后删掉刚恢复的草稿）。
+
+## 模型（共享槽位 + 无贡献不回写）
+
+- **每会话一个共享槽位** `crashrestore-<key>`（无 tabId）——多标签同会话天然共享
+  同一份草稿；新建视图 = `crashrestore-new:<cwd>`（cwd 族自然 key，draftId 抖动无感）。
+- **known** = 本标签页最后显示/写入的值。
+- **onChange（真实输入才写）**：
+  - `snap === known` → **不写**（无贡献不回写★——防震荡的核心）；
+  - `snap === ""` → 清槽位（**清空/发走再清**★；延迟 300ms 确认，防陈旧实例
+    空快照误清；打开时空框不清）；
+  - 其他 → 写新值（有贡献才写；last-write-wins）。
+- **scan（只读，永不写 → 无震荡源）**：
+  - 框空 + 有存储 → 静默恢复进框（**恢复不清暂存**；known = 恢复值）；
+  - 框有内容 + 存储 ⊇ known（别的标签页扩展了草稿）→ 同步进框；
+  - 分叉 → 不动（写方写新值）。
+- **恢复等宿主水合完成**（`pi-web:hydrated` 信号 + stage 重放二道防线）——
+  水合前落框会被 hydration 失配重渲染按服务端 HTML（空框）抹掉。
+
+## 多标签语义
+
+共享草稿 + last-write-wins + 被动同步：
+- 两个标签同会话各自打字 → 各自刷新各自恢复（共享槽位，无 own/foreign 之分）；
+- 一个标签扩展了草稿 → 另一标签被动同步进框；
+- 同时打字 → last-write-wins（共享草稿语义的固有属性）；
+- 「正在输入本页最大」：框有内容时绝不弹框/恢复，包含关系自动分流
+  （框 ⊇ 草稿丢弃；草稿 ⊇ 框静默覆盖；互不包含等下次框空恢复）。
+
+## 契约依赖（core 侧，worktree defork/composer-contract 分支）
+
+- `ctx.registerComposerEnhancement`（值观测/key 切换/发送前钩子）
+- `ctx.restoreComposerDraft` / `ctx.writeComposerValue`（受控写值，tracker 同步）
+- `ctx.registerDraftApi`（core 经 `getDraftApi()` 访问存储：**applyIntent**/
+  getDraft/clearAllDrafts/flushAll 为 v2 面；saveDraft/clearDraft/rekeyDraft/
+  restoreSubmission 为 deprecated，仅供未升级旧 core 回退）
+- `window.__piWebHydrated` + `pi-web:hydrated` 事件（水合信号）
+- ChatInput 增强器集合变化补发（晚注册补偿）
+
+## 已知边界
+
+- extman 关掉 keeper（或重开后关闭）→ 草稿功能停（core 无兜底，keeper 是
+  唯一所有者；运行时开关立即生效）。
+- 双标签**同时**打字 = last-write-wins（共享草稿语义固有）。
+- 旧 per-tab 槽位（crashrestore-<key>-<tabId>）首次读取时自动迁移到共享槽位；
+  从未访问的会话的旧槽位残留（无害）。
+
+## 部署
+
+```bash
+node tools/deploy.mjs    # 免构建；拷贝到 ~/.pi/web{,-dev}/extensions/
+```
+生效：POST /api/extensions/reload；刷新页面即新 client。
+
+## 文档 · Documentation
+
+- 中文完整文档（aiti-docs）: <https://aiti.pw/extensions/aiti-draft-keeper.html>
+- English docs: <https://aiti.pw/en/extensions/aiti-draft-keeper.html>
+- 扩展注册表 / registry: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>

package/check-client.mjs

@@ -0,0 +1,273 @@
+/**
+ * check-client —— 扩展 client .mjs/.js 的 TS 残留 tripwire（零依赖，纯 node）。
+ *
+ * 背景：aiti-plan-review 事故（docs/aiti-ext-client-hardening-plan.md §1）——
+ * `useState<any>(null)` 解析为合法 JS 比较表达式 `useState < any > (null)`，
+ * node --check / TS 解析器 / babel 全不报错，只有运行时才炸。纯语法检查
+ * 原理性无效，只能启发式规则 + 渲染期错误边界兜底。
+ *
+ * 用法：
+ *   CLI    node check-client.mjs <file|dir>...        FAIL → exit 1
+ *   自测   node check-client.mjs --selftest           fixtures 全过 → exit 0
+ *   API    lintClientSource(src) → violations[]       { line, level, rule, text }
+ *          lintPath(path)        → { files, violations }（文件或目录，递归）
+ *          checkClientDir(dir,{log})                 FAIL → throw（deploy 脚本用）
+ *
+ * 词法：规则匹配前先剥离注释/字符串/模板字面量（${} 插值内代码保留检查）——
+ * aiti-editor 的 Monaco TS stub 模板串、JSDoc @return 都是合法内容，不剥全误报。
+ * 已知极限：regex 字面量含引号等 lexer 歧义允许漏报（tripwire 定位非编译器）。
+ *
+ * 豁免：目标行或其上一行含 `check-client:allow` 即跳过该行。
+ * 权威源：本文件；aiti-extman 部署副本由其 tools/deploy.mjs 拷贝（改动两处同步）。
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ── 规则（分级）──────────────────────────────────────────────────────────────
+
+const RULES = [
+  // FAIL：合法 JS 但运行时必炸 / 纯 TS 语法
+  { level: "FAIL", re: /\b(useState|useRef|useMemo|useCallback|useReducer|useImperativeHandle)\s*</, why: "React hook 泛型（运行时必炸）" },
+  // 注：含「any/unknown/string」字样的规则用字符串构 RegExp——本文件自身也
+  // 会被扫，正则字面量里的 (?:any 会被自己命中（词法器不处理 regex 字面量），
+  // 字符串字面量则会被词法遮蔽。
+  { level: "FAIL", re: new RegExp("\\bas\\s+(?:" + "any|unknown|const)\\b"), why: "as 断言" },
+  { level: "FAIL", re: new RegExp(":\\s*(?:" + "any|unknown)\\b"), why: ": any/: unknown 注解" },
+  { level: "FAIL", re: /\b(?:import|export)\s+type\s/, why: "import/export type" },
+  { level: "FAIL", re: /\b(?:interface|enum)\s+[A-Za-z_$]/, why: "interface/enum 声明" },
+  // warn：疑似残留，人工确认，不阻断
+  { level: "warn", re: new RegExp(":\\s*(?:" + "string|number|boolean|void)\\b(?!\\s*[._\\w])"), why: "疑似类型注解" },
+  { level: "warn", re: /\bsatisfies\s/, why: "satisfies" },
+  { level: "warn", re: /\b(?:Record|Partial|Readonly|Omit|Pick)\s*</, why: "TS 工具类型" },
+];
+
+// ── 词法剥离：注释/字符串/模板字面量 → 空格（保留换行，行号不漂移）─────────
+export function stripLiterals(src) {
+  const out = src.split("");
+  const n = src.length;
+  const mask = (from, to) => {
+    for (let k = from; k < to && k < n; k++) if (out[k] !== "\n") out[k] = " ";
+  };
+  let mode = "code";
+  let depth = 0;
+  const stack = []; // 模板 ${ 插值进入时的 brace 深度（支持嵌套模板）
+  let i = 0;
+  while (i < n) {
+    const c = src[i];
+    const d = i + 1 < n ? src[i + 1] : "";
+    if (mode === "code") {
+      if (c === "/" && d === "/") {
+        const j = src.indexOf("\n", i);
+        const end = j === -1 ? n : j;
+        mask(i, end);
+        i = end;
+      } else if (c === "/" && d === "*") {
+        const j = src.indexOf("*/", i + 2);
+        const end = j === -1 ? n : j + 2;
+        mask(i, end);
+        i = end;
+      } else if (c === "'" || c === '"') {
+        let j = i + 1;
+        while (j < n && src[j] !== c && src[j] !== "\n") j += src[j] === "\\" ? 2 : 1;
+        if (j < n && src[j] === c) {
+          mask(i, j + 1);
+          i = j + 1;
+        } else {
+          // 未闭合到行尾 → 可能是 regex 字面量歧义，只遮开引号，按代码继续
+          out[i] = " ";
+          i++;
+        }
+      } else if (c === "`") {
+        mode = "tpl";
+        out[i] = " ";
+        i++;
+      } else if (c === "{") {
+        depth++;
+        i++;
+      } else if (c === "}") {
+        if (stack.length && depth === stack[stack.length - 1]) {
+          stack.pop();
+          mode = "tpl"; // 插值结束回模板
+          out[i] = " ";
+        } else {
+          depth = Math.max(0, depth - 1);
+        }
+        i++;
+      } else i++;
+    } else if (mode === "tpl") {
+      if (c === "\\") {
+        mask(i, Math.min(i + 2, n));
+        i += 2;
+      } else if (c === "`") {
+        mode = "code";
+        out[i] = " ";
+        i++;
+      } else if (c === "$" && d === "{") {
+        stack.push(depth);
+        mode = "code";
+        mask(i, i + 2);
+        i += 2;
+      } else {
+        if (c !== "\n") out[i] = " ";
+        i++;
+      }
+    } else {
+      // 不可达：line/block/字符串均在 code 分支内联处理
+      i++;
+    }
+  }
+  return out.join("");
+}
+
+// ── 单源检查 ────────────────────────────────────────────────────────────────
+export function lintClientSource(src) {
+  const masked = stripLiterals(src);
+  const origLines = src.split("\n");
+  const maskedLines = masked.split("\n");
+  const violations = [];
+  for (let i = 0; i < maskedLines.length; i++) {
+    const prev = i > 0 ? origLines[i - 1] : "";
+    if (origLines[i].includes("check-client:allow") || prev.includes("check-client:allow")) continue;
+    for (const { level, re, why } of RULES) {
+      if (re.test(maskedLines[i])) {
+        violations.push({ line: i + 1, level, rule: why, text: origLines[i].trim().slice(0, 90) });
+      }
+    }
+  }
+  return violations;
+}
+
+// ── 文件/目录检查 ───────────────────────────────────────────────────────────
+const SKIP_DIR = new Set(["node_modules", ".git"]);
+/** 超过此体积视为 vendored bundle（如 Monaco ts.worker，合法含 interface 字样），不查。 */
+const MAX_BYTES = 512 * 1024;
+const isClientFile = (name) => /\.(mjs|js|cjs)$/.test(name) && !/\.min\./.test(name) && !/\.test\./.test(name);
+
+export function lintPath(p, out = { files: 0, violations: [] }) {
+  const st = statSync(p);
+  if (st.isDirectory()) {
+    for (const name of readdirSync(p)) {
+      if (SKIP_DIR.has(name)) continue;
+      lintPath(join(p, name), out);
+    }
+    return out;
+  }
+  const base = p.split("/").pop();
+  if (!isClientFile(base)) return out;
+  if (st.size > MAX_BYTES) return out; // vendored bundle 豁免
+  out.files++;
+  for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  return out;
+}
+
+export function formatViolations(violations) {
+  return violations
+    .map((v) => `  ${v.level} ${v.file}:${v.line} [${v.rule}] ${v.text}`)
+    .join("\n");
+}
+
+/** deploy 脚本用：检查目录，FAIL 抛错（消息含违规清单），warn 只打日志不阻断。 */
+export function checkClientDir(dir, { log = console.log } = {}) {
+  const { files, violations } = lintPath(resolve(dir));
+  const fails = violations.filter((v) => v.level === "FAIL");
+  const warns = violations.filter((v) => v.level === "warn");
+  if (warns.length) log(`[check-client] ${warns.length} 处疑似 TS 残留（不阻断，建议人工确认）：\n${formatViolations(warns)}`);
+  if (fails.length) {
+    throw new Error(
+      `client 检查未通过：${files} 个文件中 ${fails.length} 处 TS 残留（.mjs 里是合法 JS，语法检查不报，运行时必炸）。\n` +
+        formatViolations(fails) +
+        `\n修复或在该行加注释 // check-client:allow 豁免。详见 docs/aiti-ext-client-hardening-plan.md`,
+    );
+  }
+  if (files) log(`[check-client] ${files} 个 client 文件检查通过`);
+  return { files, fails: fails.length, warns: warns.length };
+}
+
+/**
+ * extman 安装用：扫整个扩展目录（含第三方，不遵循 client/ 约定）。
+ * 在 SKIP_DIR 之上额外跳过构建产物/vendored 目录（Monaco ts.worker、语言包等
+ * 合法包含 TS 字样，词法器对 minified 代码不提供保证）；体积上限同上。
+ */
+export function lintExtensionDir(dir) {
+  const out = { files: 0, violations: [] };
+  const walk = (p) => {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p)) {
+        if (SKIP_DIR.has(name) || VENDORED_DIRS.has(name)) continue;
+        walk(join(p, name));
+      }
+      return;
+    }
+    const base = p.split("/").pop();
+    if (!isClientFile(base) || st.size > MAX_BYTES) return;
+    out.files++;
+    for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  };
+  walk(resolve(dir));
+  return out;
+}
+const VENDORED_DIRS = new Set(["vendor", "monaco", "dist", "build", "assets", "static", "bundles", "chunks"]);
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+function selftest() {
+  const MUST_FAIL = [
+    "const [st, setSt] = useState<any>(null);",
+    "const r = useRef<number>(null);",
+    "const x = v as any;",
+    "function f(a: unknown) {}",
+    'import type { Foo } from "./x";',
+    "interface Foo { a: string }",
+    "enum Color { Red }",
+    "const y = v as const;",
+  ];
+  const MUST_WARN = [
+    "const opts = { mode: string };",
+    "x satisfies Y;",
+    "const m: Record<string, any> = {};",
+  ];
+  const MUST_PASS = [
+    'const REACT_TYPE_STUB = `\ndeclare module "react" {\n  export function useState<T>(init: T): [T];\n  export const Fragment: any;\n}\n`;',
+    "/** @return {{chars1: string, chars2: string}} */",
+    "const [s] = useState(null);",
+    "useState<any>(null); // check-client:allow",
+    "// check-client:allow\nuseState<never>(0);",
+    "const cmp = a < b && c > (d);",
+    "if (a // 注释里 as any 不算\n  ) run();",
+  ];
+  let bad = 0;
+  const check = (src, expect, desc) => {
+    const v = lintClientSource(src);
+    const fails = v.filter((x) => x.level === "FAIL");
+    const ok = expect === "FAIL" ? fails.length > 0 : expect === "PASS" ? v.length === 0 : v.length > 0 && fails.length === 0;
+    if (!ok) {
+      bad++;
+      console.log(`SELFTEST FAIL [${desc}] 期望 ${expect}，实际 ${JSON.stringify(v)}`);
+    }
+  };
+  MUST_FAIL.forEach((s) => check(s, "FAIL", s.slice(0, 40)));
+  MUST_WARN.forEach((s) => check(s, "WARN", s.slice(0, 40)));
+  MUST_PASS.forEach((s) => check(s, "PASS", s.replace(/\n/g, "⏎").slice(0, 40)));
+  if (bad) {
+    console.log(`selftest: ${bad} 处未过`);
+    process.exit(1);
+  }
+  console.log("selftest: 全部通过（8 FAIL / 3 WARN / 7 PASS）");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.filename)) {
+  if (process.argv.includes("--selftest")) {
+    selftest();
+  } else if (process.argv.length > 2) {
+    const all = { files: 0, violations: [] };
+    for (const p of process.argv.slice(2)) lintPath(resolve(p), all);
+    const fails = all.violations.filter((v) => v.level === "FAIL");
+    const warns = all.violations.filter((v) => v.level === "warn");
+    if (all.violations.length) console.log(formatViolations(all.violations));
+    console.log(`\n${all.files} 个文件：FAIL=${fails.length} warn=${warns.length}`);
+    process.exit(fails.length ? 1 : 0);
+  } else {
+    console.log("用法：node check-client.mjs <file|dir>... ｜ --selftest");
+    process.exit(2);
+  }
+}

package/client/src/aiti-draft-keeper-client.mjs

@@ -0,0 +1,128 @@
+/**
+ * Draft Keeper（aiti-draft-keeper）client 薄壳。
+ *
+ * 职责只剩装配：window/localStorage 适配、hydration 门控、ctx 接线、
+ * DraftApi 注册。全部草稿语义在 ./core.mjs 的状态机（唯一所有者）——
+ * core（pi-web）只发意图（applyIntent）或经 enhancement 回调喂快照，
+ * 不再直接 clearDraft/rekeyDraft（竞态源头已收敛进状态机）。
+ *
+ * 兼容：DraftApi 保留 v1 方法（saveDraft/clearDraft/rekeyDraft/restoreSubmission，
+ * 标记 deprecated）——部署顺序无关：旧 core + 新 keeper 仍可工作；新 core 的
+ * applyDraftIntent 检测 applyIntent 存在即走新路径。
+ */
+
+import { createKeeperCore } from "./core.mjs";
+
+const PREFIX = "crashrestore-";
+
+function dbg(msg) {
+  try {
+    if (localStorage.getItem("__keeperDebugOn") !== "1") return;
+    const logArr = JSON.parse(localStorage.getItem("__keeperDebug") || "[]");
+    logArr.push({ at: Math.round(performance.now()), msg: String(msg).slice(0, 140) });
+    localStorage.setItem("__keeperDebug", JSON.stringify(logArr.slice(-40)));
+  } catch { /* ignore */ }
+}
+
+/** 等宿主水合完成（pi-web AppShell 挂载后置 __piWebHydrated + 派发事件）。
+ *  水合前恢复进框会被 hydration 重渲染按服务端 HTML（空框）抹掉。8s 兜底放行。 */
+function whenHydrated(cb) {
+  if (typeof window === "undefined") { cb(); return; }
+  if (window.__piWebHydrated) { cb(); return; }
+  const h = () => { window.removeEventListener("pi-web:hydrated", h); cb(); };
+  window.addEventListener("pi-web:hydrated", h);
+  setTimeout(() => { window.removeEventListener("pi-web:hydrated", h); cb(); }, 8000);
+}
+
+export default function register(ctx) {
+  // 契约防御：宿主 core 缺少 composer 契约（未同步的旧 core）→ 不启用，避免崩溃
+  if (typeof ctx.registerComposerEnhancement !== "function") return;
+  // 接管语义：hydration 失配后扩展客户端会重新执行 → 旧实例状态过期。新实例先
+  // 解散旧实例，以全新状态接管；ChatInput 的增强器集合变化补发会让新实例追上。
+  if (typeof window !== "undefined" && window.__draftKeeperDisposer) {
+    try { window.__draftKeeperDisposer(); } catch { /* ignore */ }
+    window.__draftKeeperDisposer = null;
+  }
+  return setup(ctx);
+}
+
+function setup(ctx) {
+  const storage = {
+    getItem: (k) => localStorage.getItem(k),
+    setItem: (k, v) => localStorage.setItem(k, v),
+    removeItem: (k) => localStorage.removeItem(k),
+    keys: () => {
+      const out = [];
+      for (let i = localStorage.length - 1; i >= 0; i--) out.push(localStorage.key(i));
+      return out;
+    },
+  };
+
+  // 写框（hydration 门控内）：优先受控恢复（含图片），退化为纯文本写值
+  let hydrated = typeof window !== "undefined" && !!window.__piWebHydrated;
+  const writeBox = (draft) => {
+    let ok = false;
+    if (typeof ctx.restoreComposerDraft === "function") {
+      ok = ctx.restoreComposerDraft({ value: draft.value, images: draft.images }) === true;
+    } else if (typeof ctx.writeComposerValue === "function") {
+      ok = ctx.writeComposerValue(draft.value) === true;
+    }
+    return ok;
+  };
+  const onRestore = (draft) => {
+    if (hydrated) return writeBox(draft);
+    whenHydrated(() => { hydrated = true; writeBox(draft); });
+    return true; // 已受理（挂起等水合），staged 补偿由状态机经 onChange 快照负责
+  };
+
+  const core = createKeeperCore({ storage, onRestore, log: dbg });
+  core.pruneStale(); // 启动时一次性清理过期残留（非轮询）
+
+  // 页面关闭/隐藏前强制落盘未 debounce（300ms 内）的草稿
+  const flush = () => core.flushAll();
+  const onVisibility = () => { if (document.visibilityState === "hidden") flush(); };
+  if (typeof window !== "undefined") {
+    window.addEventListener("beforeunload", flush);
+    window.addEventListener("pagehide", flush);
+    document.addEventListener("visibilitychange", onVisibility);
+  }
+
+  const dispose = () => {
+    core.dispose();
+    if (typeof window !== "undefined") {
+      window.removeEventListener("beforeunload", flush);
+      window.removeEventListener("pagehide", flush);
+      document.removeEventListener("visibilitychange", onVisibility);
+    }
+    if (typeof ctx.registerDraftApi === "function") ctx.registerDraftApi(null);
+  };
+
+  const offEnh = ctx.registerComposerEnhancement({
+    id: "aiti-draft-keeper",
+    onChange: (snap) => {
+      try { core.onChange(snap); } catch (e) { console.error("[draft-keeper] onChange error:", e); }
+    },
+    onKeyChange: (prev, next) => {
+      try { core.onKeyChange(prev, next); } catch (e) { console.error("[draft-keeper] onKeyChange error:", e); }
+    },
+  });
+
+  // 草稿存储 API：core 经 getDraftApi() 访问。applyIntent 是唯一写入口；
+  // v1 方法 deprecated（部署顺序兼容，仅未升级的旧 core 会调）。
+  if (typeof ctx.registerDraftApi === "function") {
+    ctx.registerDraftApi({
+      getDraft: (key) => core.getDraft(key),
+      clearAllDrafts: (sid) => core.clearAllDrafts(sid),
+      flushAll: () => core.flushAll(),
+      applyIntent: (intent) => core.applyIntent(intent),
+      // ---- deprecated v1 ----
+      saveDraft: (key, draft) => core.saveDraft(key, draft),
+      clearDraft: (key) => core.clearDraft(key),
+      rekeyDraft: (prev, next, currentDraft) => core.rekeyDraft(prev, next, currentDraft),
+      restoreSubmission: (key, text, images) => core.restoreSubmission(key, text, images),
+    });
+  }
+
+  if (typeof window !== "undefined") window.__draftKeeperDisposer = dispose;
+  return dispose;
+}