docs(runtime): clarify ledger authority and scheduler durability boundaries

Reviewed-on: #10

.env.example

@@ -1,2 +1,4 @@
+# Next 服务端访问 Foundry 的源站；本地代理从这里发起后端 HTTP 请求，不是浏览器页面地址。
 FOUNDRY_API_ORIGIN=https://api.foundry.entroia.com
+# 公开的项目路由标识，可进入浏览器构建；不是密码、会话令牌或授权凭证。
 NEXT_PUBLIC_FOUNDRY_PROJECT=endoleap

.gitignore

@@ -1,8 +1,15 @@
+# 安装依赖不入库；依赖版本由包清单与 lock 文件记录。
 node_modules/
+# Next 开发/生产构建缓存与产物，不作为源代码提交。
 .next/
+# 独立 headless ESM 包由 scripts/build-headless.mjs 重建。
 .headless-dist/
+# 忽略本机环境变量文件；下一条只放行可公开的示例模板。
 .env*
 !.env.example
+# TypeScript 增量检查缓存，由工具重新生成。
 *.tsbuildinfo
+# macOS Finder 的目录元数据。
 .DS_Store
+# 仓库根 docs 是本地研究/草案目录，当前约定不跟踪其中内容。
 /docs/

README.md

@@ -142,3 +142,73 @@ Core `subgraphs.member_positions` 能力启用时，最终落点（源画布局
 上传图片时立即在画布显示本地预览，并在后台上传原始文件；上传成功才把稳定附件引用加入快照。服务端预览加载完成前继续显示本地图片，避免网络等待期间空白。失败保留文件供重试/取消，重试沿用同一幂等键；本地 blob URL 不保存到服务端。
 
 上传中的图片也是正常本地节点，可立即选中、拖动、缩放、改名、删除和撤销；上传完成只补齐附件引用，不重置节点。上传前改变分区归属会先在本地完成，文件准备好后保存到当时的实际所属画布。临时上传标记和 blob 地址由传输层排除，不发送给 Core；文件仍未可用时，依赖服务端文件的 AI 生成需等待上传完成。
+
+
+## 配置与生成数据阅读说明
+
+本节为不适合内嵌注释的配置和严格 JSON 提供旁注；实际值仍以对应文件为准。源码、脚本和测试中的函数说明保留在各自文件内。包版本、TypeScript 输出目标、服务协议版本、文档格式版本和组件数据版本是不同概念。
+
+### 应用包与执行入口
+
+根 `package.json` 的 `private: true` 防止常规 npm 发布，`version: 0.1.0` 是应用包版本。`dependencies` 是应用运行/构建引用的库，`devDependencies` 包含编译器、类型声明和 Tailwind 工具；它们的精确版本及传递依赖由 `package-lock.json` 锁定。lock 文件由包管理器维护，不在其中手写说明或改某个嵌套版本。
+
+| scripts 项 | 执行内容与边界 |
+| --- | --- |
+| `dev` | 在 localhost:17321 启动 Next 开发服务器，会按需编译。 |
+| `build` / `start` | 前者执行 Next 生产构建，后者在 localhost:17321 运行已有构建。 |
+| `typecheck` | `tsc --noEmit` 检查类型，不生成应用 JS。 |
+| `test:headless` | 运行 `tests/headless/*.test.mjs`；不自动执行所有 `.integration.mjs` 或浏览器场景。 |
+| `test:headless:browser` | 浏览器存储、Worker 等适配器场景入口，环境装配见 `browser-storage.mjs`。 |
+| `test:headless:proxy` | Foundry 同源代理的隔离集成入口，启动与替身链路见 `proxy.integration.mjs`。 |
+| `test:headless:renderer` / `test:headless:performance` | 运行页面集成入口；后者附加 `--performance` 选择性能场景。 |
+| `build:headless` | 清理并重建 `.headless-dist` 的 ESM、声明和 Worker 引用，再复制包清单/文档。 |
+| `test:headless:package` | 构建、打包到隔离目录并运行消费方及浏览器验收，不是单纯语法检查。 |
+
+集成入口可能编译或启动本地进程，具体动作见各脚本模块注释；本节列出命令不表示这些检查已经运行或通过。
+
+### 应用 TypeScript 配置
+
+`tsconfig.json` 面向应用检查；以下选项共同作用，并非运行时开关：
+
+| 配置项 | 用途 |
+| --- | --- |
+| `target: ES2020` / `lib` | 声明语言输出目标和可用类型库；`dom`、`dom.iterable`、`esnext` 提供 API 类型，不会安装浏览器 polyfill。 |
+| `allowJs` / `skipLibCheck` | 允许 JS 进入项目；跳过声明文件内部的完整检查。它们不关闭项目 TS 源码的检查。 |
+| `strict` / `noEmit` | 启用严格类型检查，默认只检查而不生成 JS/声明。 |
+| `allowImportingTsExtensions` | 允许源码相对导入使用 `.ts` 等 TS 扩展名；独立包输出由另一配置重写扩展名。 |
+| `esModuleInterop` | 为 CommonJS/ESM 互操作提供 TypeScript 的兼容处理，不把整个项目改成 CommonJS。 |
+| `module: esnext` / `moduleResolution: bundler` | 使用 ESM 语法并按 bundler 模式解析依赖；应用最终交由 Next 构建链处理。 |
+| `resolveJsonModule` | 允许 TS 引用并推断 JSON 模块，例如图标 manifest。 |
+| `isolatedModules` / `jsx: react-jsx` | 按单文件转换约束检查源码，并使用 React 自动 JSX 转换形式。 |
+| `incremental` | 允许 TypeScript 使用增量检查缓存；生成的 `*.tsbuildinfo` 被忽略。 |
+| `paths` | `@/*` 在 TS 解析时指向 `src/*`，这不是把字符串路径写进业务文档。 |
+| `plugins` | 登记 Next TypeScript 插件供支持它的工具使用。 |
+| `include` / `exclude` | 纳入应用 TS/TSX、`next-env.d.ts` 与 Next 生成类型入口；排除依赖和独立包输出目录。由这些源码导入的依赖仍可参与类型解析。 |
+
+`next-env.d.ts` 是 Next 维护的类型入口，引用框架/图片和生成路由类型。其路径会随开发/构建环境变化，不在这个生成文件中追加维护注释。
+
+### 独立 headless 包
+
+`tsconfig.headless.json` 继承应用配置，显式覆盖输出部分：`target`/`module` 为 ES2022，`rootDir` 为 `src/lib`，`outDir` 为 `.headless-dist/modules`；`noEmit: false` 与 `declaration: true` 生成 JS 和 `.d.ts`。`incremental: false` 不使用这次编译的增量缓存，`rewriteRelativeImportExtensions` 将可重写的相对 TS 导入转成输出扩展名。`types: []` 和 `plugins: []` 清空自动纳入的类型包列表与继承插件条目，不禁止源码显式导入类型；未覆盖的 `lib` 等项仍继承。四组 `include` 从 core/runtime/service/bindings 的 `.ts` 入口收集源码，导入关系还会带入所需依赖。
+
+`headless/package.json` 是复制到产物根的包模板，源目录本身没有生成后的 `modules`。它的 `type: module` 声明 ESM，Node 引擎要求为 `>=22`。`exports` 为每个公开入口分别指定类型声明和 ESM 文件：根及 `/core` 指向 core，另有 `/runtime`、`/browser`、`/service`、`/bindings`、`/react-flow` 与 `/react`。这些是产物目录中的路径，不是指向 `src` 的别名，也没有声明 CommonJS `require` 入口。
+
+`files` 限定包收录的模块、消费示例和验收文档。React、React DOM、React Flow 以带版本范围的可选 peer 声明，供选择相关适配入口的宿主提供；“可选”不表示调用 UI 适配器时可以缺少它依赖的框架。便携入口的使用和依赖边界见 `headless/README.md`。`private: true` 保持预览包私有，不代表已经发布到 registry。
+
+### 组件生成器配置
+
+`components.json` 是 UI 组件生成器读取的配置，不是应用运行时组件 registry。`$schema` 指向配置的 schema；`style: new-york`、`tsx: true` 和 `rsc: false` 记录生成风格、TSX 和 RSC 选项，不改变整个 App Router 的路由/渲染模式。`tailwind.css` 指向 `src/styles/globals.css`，空 `tailwind.config` 没有指定独立配置路径，`baseColor: neutral` 与 `cssVariables: true` 是生成器的配色约定。`aliases` 指示生成文件的组件、工具、UI、lib 和 hooks 导入位置；其中 `@/hooks` 不保证已经存在对应目录。
+
+### 图标生成数据
+
+`src/components/canvas/icon-catalog-data.json` 是检索目录数组，每项包含 `name`（持久引用的图标 ID）、`slug`、`source`、`label`、`categories`、`common` 和 `keywords`；不包含 SVG 路径。`icon-catalog.ts` 用它构建名称 Map 并执行筛选，选择器的虚拟窗口另由 UI 控制。
+
+`src/lib/canvas-icon-assets.json` 保存 `root` URL 前缀与 `assets` 桶名到摘要文件名的映射。`iconAsset()` 对 Lucide 名称做 31 进制滚动散列并模 96，Tabler 名称统一使用 `tabler` 桶。`public/canvas-icons/<版本目录>/*.json` 每个分片以图标名索引 `[tag, props][]`，消费端 `validateIconShard()` 再检查支持的图形与属性。
+
+这三类数据由 `scripts/generate-canvas-icons.mjs` 同批生成，中文标注来自 `scripts/canvas-icon-labels.mjs`。文件名摘要是紧凑 JSON 内容的 SHA-256 前 12 位，写盘时另加换行；它与分桶散列用途不同。分片变更须同步目录/manifest 并更新摘要名；脚本不会自动删除旧分片。不要在 JSON 中插入注释或只手改其中一份，否则会破坏读取、引用或缓存命名约定。
+
+### 协议样例与忽略规则
+
+`tests/headless/fixtures/foundry-model-operation-v2.json` 是服务适配器单测的完整请求样例。协议 2 的 `request_id` 标识冻结请求，`expected_versions` 是参与 canvas 的已确认版本，`operations[].id` 是逻辑操作 ID。样例把第一代元素 `a` 的 `data.title` 从 `a` 改为 `renamed`；`beforePresent`/`afterPresent` 区分字段缺失与有值。字段旁注与断言在 `tests/headless/service.test.mjs`，静态样例不代表真实服务已执行。
+
+`.gitignore` 排除依赖、Next/headless 产物、环境变量、增量缓存和系统文件；仅放行 `.env.example` 作为模板。根 `/docs/` 当前作为本地研究目录忽略。忽略规则只影响未跟踪文件，不会把已经跟踪的文件自动移出 Git。`.env.example` 的公开项目标识与服务端源站说明写在模板内；实际凭据不应写进示例或公开构建变量。

scripts/generate-canvas-icons.mjs

@@ -80,6 +80,9 @@ for (const [key, nodes] of shards) {
   totalBytes += Buffer.byteLength(content);
 }
 // 两份生成JSON分别服务搜索目录与按需加载器；严格JSON不能内嵌注释，其结构与生成流程在本脚本说明。
+// catalog 每项是 name/slug/source/label/categories/common/keywords；不带 SVG node，搜索只读取这些元数据。
+// manifest.root 为公开 URL 前缀，assets 将 lucide-N 或 tabler 逻辑桶映射到带内容摘要的 JSON 文件名。
+// 分片对象按图标 name 索引 [tag, props][]；props 为可序列化 SVG 属性，消费端还会执行标签/属性校验。
 await writeFile("src/components/canvas/icon-catalog-data.json", JSON.stringify(catalog) + "\n");
 await writeFile("src/lib/canvas-icon-assets.json", JSON.stringify({ root: "/" + assetDir.replace(/^public\//, ""), assets }) + "\n");
 // 分发路径数据同时复制原包许可证；最后只打印资源统计，不启动应用或验证浏览器显示。

src/components/canvas/canvas.module.css

@@ -1,91 +1,124 @@
+/* 画布与节点的局部样式：React Flow 全局类通过 :global 组合，状态类由组件/手势控制器切换；CSS 只控制呈现和命中，不负责数据归属、提交或锁。 */
+/* 画布铺满定位父容器；随后覆盖 React Flow 背景、选中边框和 attribution 外观。 */
 .editor { position: absolute; inset: 0; width: 100%; height: 100%; background: #fffefb; }
 .editor :global(.react-flow) { --xy-background-color-default: #fffefb; --xy-node-border-selected-default: 1px solid #a47764; }
 .editor :global(.react-flow__attribution) { bottom: 5px; right: 5px; font-size: 9px; background: #fffefbc9; }
+/* 手形模式在 pane/节点上给 grab 光标，拖动 pane 时改为 grabbing。 */
 .handMode :global(.react-flow__pane), .handMode :global(.react-flow__node) { cursor: grab; }
 .handMode :global(.react-flow__pane.dragging) { cursor: grabbing; }
+/* 卡片基础边框/圆角/阴影，selectedNode 单独标记选择；标题绝对放在节点上方。 */
 .node { position: relative; padding: 0; border: 1px solid #ded7ce; border-radius: 10px; background: white; color: #37352f; box-shadow: 0 2px 5px #40302405; }
 .selectedNode { border-color: #a47764; box-shadow: 0 0 0 2px #a4776425; }
 .nodeHeading { position: absolute; left: 0; top: -26px; display: flex; align-items: center; gap: 6px; height: 20px; max-width: 100%; font-size: 11px; color: #92877c; white-space: nowrap; cursor: grab; }
+/* 文本填满 flex 容器，允许尺寸缩到零且关闭原生 resize；焦点时覆盖全局输入阴影，避免额外边框。 */
 .cardText, .plainText { box-sizing: border-box; display: block; width: 100%; height: 100%; min-height: 0; min-width: 0; flex: 1; padding: 14px; resize: none; border: 0; border-radius: inherit; background: transparent; outline: none; box-shadow: none; }
 .cardText:focus, .plainText:focus { outline: none; box-shadow: none; border-color: transparent !important; }
 .cardText::placeholder, .plainText::placeholder { color: #b2a99e; }
+/* 卡片图片保持原比例装入可用空间，不以图片固有尺寸撑开节点。 */
 .image { display: block; flex: 1; min-height: 0; width: 100%; height: 100%; max-width: 100%; border-radius: inherit; object-fit: contain; }
+/* 工具栏按 aria-pressed 高亮当前模式；disabled 光标不表示实际业务锁逻辑。 */
 .toolbar button[aria-pressed="true"] { background: #f1e6df; color: #78523f; }
 .toolbar button:disabled { cursor: not-allowed; }
+/* 右上工具条纵排；缩放值固定 48px 并使用等宽数字，避免百分比变化挤动旁边按钮。 */
 .topRight { position: absolute; top: 12px; right: 12px; z-index: 10; display: flex; flex-direction: column; align-items: flex-end; gap: 3px; }
 .toolbar .zoomValue { box-sizing: border-box; flex: 0 0 48px; width: 48px; height: var(--toolbar-control-height, 32px); padding: 0; border-radius: 5px; font: inherit; font-variant-numeric: tabular-nums; }
 .toolbar .zoomValue:hover { background: #e9e7e3; }
+/* 底部主工具栏相对画布居中；帮助、错误等浮层各自定位和设层级。 */
 .bottomToolbar { position: absolute; left: 50%; bottom: 12px; transform: translateX(-50%); z-index: 10; }
+/* 帮助面板固定在视口右下方，有宽高上限和内部滚动，长内容不溢出视口。 */
 .helpPopup { position: fixed; inset: auto 12px 62px auto; margin: 0; width: 330px; max-width: calc(100vw - 32px); max-height: calc(100dvh - 110px); overflow-y: auto; padding: 18px; border: 1px solid #e2dcd3; border-radius: 12px; background: white; color: #6d6054; box-shadow: 0 8px 30px #32251a14; font-size: 12px; line-height: 1.7; }
 .helpPopup strong { color: #49372e; font-size: 13px; }
 .helpPopup p { margin-top: 9px; }
+/* 画布错误在上方居中显示，宽度随视口收缩，不参与节点几何计算。 */
 .error { position: absolute; top: 78px; left: 50%; transform: translateX(-50%); max-width: min(500px, calc(100vw - 32px)); padding: 10px 14px; border: 1px solid #e5c7b8; border-radius: 8px; color: #a25439; background: #fff9f3; font-size: 12px; z-index: 15; }
 .helpToolbar { position: absolute; right: 12px; bottom: 12px; z-index: 10; }
+/* 迁移控制面板处于较高层级；按钮状态、是否允许迁移由组件判断。 */
 .migrationPanel { position: absolute; right: 12px; top: 64px; z-index: 220; display: flex; flex-wrap: wrap; gap: 8px; align-items: center; max-width: 360px; padding: 8px; border: 1px solid #ded7ce; border-radius: 7px; background: #fffefb; color: #78523f; font-size: 12px; }
 .migrationPanel button { border: 1px solid #ded7ce; border-radius: 5px; padding: 6px 9px; background: white; cursor: pointer; }
 .migrationPanel button:disabled { cursor: default; opacity: .5; }
+/* 旧/迁移画布表面铺满宿主，具体渲染内容由桥接组件决定。 */
 .migrationSurface { position: absolute; inset: 0; }
+/* 窄屏把右上工具条下移避让标题，底部工具条改左对齐并横向滚动，预留右侧帮助空间。 */
 @media (max-width: 700px) {
   .topRight { top: 62px; right: 12px; }
   .bottomToolbar { left: 12px; bottom: 12px; transform: none; max-width: calc(100vw - 92px); overflow-x: auto; overscroll-behavior-x: contain; }
 }
 
+/* 手形模式让文本/图片不拦截指针；右上工具条自身横向滚动以容纳窄视口。 */
 .handMode .node textarea, .handMode .node img { pointer-events: none; }
 
 .topRight .toolbar { max-width: calc(100vw - 24px); overflow-x: auto; }
 
+/* 隐藏旧 handle 且禁用命中，新的中心点交互在后续规则控制。 */
 .node :global(.react-flow__handle).legacyHandle { opacity: 0; pointer-events: none; }
 
+/* 变换容器以中心为 transform-origin，保留溢出给标题、handle 和提示；边框/阴影变化有短过渡。 */
 .transformFrame { position: relative; box-sizing: border-box; display: flex; flex-direction: column; transform-origin: center; overflow: visible; transition: border-color 160ms ease, box-shadow 160ms ease; }
+/* 纯内容 frame 默认透明边框，选中才显示；plainText 后置 padding 覆盖卡片文本的 14px。 */
 .plainFrame { padding: 0; border: 1px solid transparent; border-radius: 2px; background: transparent; box-shadow: none; }
 .plainFrame.selectedFrame { border-color: #a47764; }
 .plainText { padding: 4px; }
+/* 中心连接点默认透明且不响应指针；选中只改变可见性，connectionindicator 才开放命中。 */
 .node :global(.react-flow__handle).centerHandle { width: 10px; height: 10px; display: grid; place-items: center; background: #a47764; color: #78523f; border: 0; border-radius: 50%; z-index: 7; cursor: crosshair; touch-action: none; opacity: 0; pointer-events: none; transition: opacity 160ms ease, background 160ms ease, border-color 160ms ease; }
 .selectedNode :global(.react-flow__handle).centerHandle { opacity: 1; }
 .node :global(.react-flow__handle).centerHandle:global(.connectionindicator) { pointer-events: auto; }
 .node :global(.react-flow__handle).centerHandle:hover { border-color: #a47764; background: #f1e6df; }
+/* 右下缩放按钮单独命中、禁止触摸默认行为；旋转模式隐藏它，避免两种手势同时起动。 */
 .cornerResize { position: absolute; right: 2px; bottom: 2px; display: grid; place-items: center; width: 20px; height: 20px; padding: 0; border: 0; border-radius: 3px; color: #92877c; background: transparent; z-index: 8; cursor: nwse-resize; touch-action: none; opacity: 1; scale: 1; pointer-events: auto; transition: opacity 160ms ease, scale 160ms ease; }
 .selectedFrame .cornerResize { opacity: 1; scale: 1; pointer-events: auto; }
 .rotatingFrame .cornerResize { opacity: 0; pointer-events: none; }
+/* 旋转时由 frame 接收手势，文本和中心连接点让出指针。 */
 .rotatingFrame { cursor: grabbing; touch-action: none; }
 .rotatingFrame textarea, .node.rotatingFrame :global(.react-flow__handle).centerHandle { pointer-events: none; }
+/* 角度提示放在 frame 下方，禁止命中以免遮住正在进行的手势。 */
 .rotationHint { position: absolute; left: 50%; bottom: -30px; translate: -50% 0; display: flex; align-items: center; gap: 4px; white-space: nowrap; padding: 4px 7px; border-radius: 5px; background: #fffefbe8; color: #78523f; font-size: 10px; pointer-events: none; }
+/* 节点样式工具栏采用横排可滚动表面，按钮尺寸固定；数值/选择器共用高度。 */
 .styleToolbar { display: flex; align-items: center; gap: 3px; padding: 4px; border: 1px solid #ded7ce; border-radius: 8px; background: #fffefb; color: #49372e; box-shadow: 0 5px 20px #32251a12; max-width: calc(100vw - 24px); overflow-x: auto; }
 .styleToolbar button { display: grid; place-items: center; width: 28px; height: 28px; flex: 0 0 28px; padding: 0; border-radius: 4px; }
 .styleToolbar button:hover, .styleToolbar button[aria-pressed="true"] { background: #f1e6df; color: #78523f; }
 .styleToolbar select, .styleToolbar input[type="number"] { height: 28px; border: 0; border-radius: 3px; background: transparent; padding: 0 3px; font-size: 12px; }
 .styleToolbar input[type="number"] { width: 48px; }
+/* 可见圆点只显示颜色，透明原生 color input 覆盖整个点击区域。 */
 .colorPicker { position: relative; display: grid; place-items: center; width: 28px; height: 28px; flex: 0 0 28px; cursor: pointer; }
 .colorPicker span { width: 17px; height: 17px; border: 1px solid #bfb4aa; border-radius: 50%; }
 .colorPicker input { position: absolute; inset: 0; width: 100%; height: 100%; opacity: 0; cursor: pointer; }
+/* 分支菜单固定定位并高于普通工具条，菜单项整行点击；定位坐标由组件计算。 */
 .branchMenu { position: fixed; z-index: 60; width: 210px; padding: 7px; border: 1px solid #ded7ce; border-radius: 10px; background: #fffefb; color: #49372e; box-shadow: 0 8px 30px #32251a1a; }
 .branchMenu header { display: flex; align-items: center; justify-content: space-between; padding: 3px 6px 6px; color: #92877c; font-size: 11px; }
 .branchMenu header button { display: grid; place-items: center; width: 24px; height: 24px; }
 .branchMenu > button { display: flex; align-items: center; gap: 10px; width: 100%; min-height: 36px; padding: 8px; border-radius: 5px; font-size: 13px; text-align: left; }
 .branchMenu button:hover { background: #f1e6df; }
+/* 节点图标填满内容区域，SVG 自身不截获指针，事件交给外层节点。 */
 .iconContent { width: 100%; height: 100%; padding: 6px; border-radius: inherit; }
 .iconContent svg { pointer-events: none; }
+/* 图标选择器固定在左侧，可用高度限定并采用纵向 flex，头/搜索/分类与列表分区。 */
 .iconPicker { position: fixed; top: 70px; left: 12px; bottom: 70px; z-index: 60; display: flex; flex-direction: column; width: 272px; max-width: calc(100vw - 24px); max-height: 550px; padding: 14px; border: 1px solid #ded7ce; border-radius: 12px; background: #fffefb; color: #49372e; box-shadow: 0 8px 30px #32251a14; }
 .iconPicker header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 12px; font-size: 14px; }
 .iconPicker header button { width: 28px; height: 28px; display: grid; place-items: center; border-radius: 4px; }
 .iconPicker input { width: 100%; padding: 7px 9px; border: 1px solid #ded7ce; border-radius: 6px; font-size: 12px; margin-bottom: 12px; }
+/* 普通图标网格五列并内部滚动；后续 virtualIconGrid 是虚拟列表视口，窗口项目由 JS 定位。 */
 .iconGrid { display: grid; grid-template-columns: repeat(5, 1fr); gap: 6px; overflow-y: auto; }
 .iconGrid button { display: grid; place-items: center; aspect-ratio: 1; border-radius: 6px; color: #6d6054; }
 .iconGrid button:hover, .iconPicker header button:hover { background: #f1e6df; }
 .iconPicker footer { padding-top: 12px; color: #92877c; font-size: 10px; }
+/* 来源选择器限制宽度，分类按钮可换行并按 aria-pressed 显示当前筛选。 */
 .iconSource { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 10px; font-size: 11px; }
 .iconSource select { min-width: 0; max-width: 175px; padding: 4px; border: 1px solid #ded7ce; border-radius: 5px; background: transparent; }
 .iconCategories { display: flex; flex-wrap: wrap; gap: 4px; margin-bottom: 10px; }
 .iconCategories button { padding: 3px 6px; border-radius: 4px; color: #92877c; font-size: 10px; }
 .iconCategories button[aria-pressed="true"] { background: #f1e6df; color: #78523f; }
+/* flex:1 让列表吃剩余高度，overscroll contain 减少滚动传到外层；CSS 不负责裁剪数据窗口。 */
 .virtualIconGrid { flex: 1; min-height: 96px; overflow-y: auto; overscroll-behavior: contain; }
 .virtualIconGrid button { display: grid; place-items: center; border: 3px solid transparent; border-radius: 8px; background-clip: padding-box; color: #6d6054; }
 .virtualIconGrid button:hover { background-color: #f1e6df; }
 .virtualIconGrid button:focus-visible, .iconCategories button:focus-visible { outline: 2px solid #a47764; outline-offset: -2px; }
+/* 图标资源加载提示与选择器使用相近层级/起点。 */
 .iconLoading { position: absolute; left: 12px; top: 70px; z-index: 60; padding: 14px; border-radius: 10px; background: #fffefb; font-size: 12px; }
+/* 归属徽标放在节点下方，限制长名称且不参与命中；旋转时隐藏以减少遮挡。 */
 .membershipBadge { position: absolute; bottom: -25px; left: 0; display: flex; align-items: center; gap: 4px; max-width: 280px; padding: 3px 6px; border-radius: 4px; background: #e9f1e9; color: #3e684b; font-size: 10px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; pointer-events: none; }
 .rotatingFrame .membershipBadge { display: none; }
 .frameMemberCount { font-size: 10px; color: #92877c; white-space: nowrap; }
+/* 名称模式按钮宽度随文字，菜单固定定位且限制在视口内，勾选列保持对齐。 */
 .styleToolbar .frameModeTrigger { display: flex; align-items: center; justify-content: space-between; gap: 8px; width: auto; min-width: 96px; flex: 0 0 auto; padding: 0 7px; font-size: 12px; }
 .frameModeMenu { position: fixed; z-index: 120; width: 220px; max-width: calc(100vw - 16px); max-height: calc(100dvh - 16px); overflow-y: auto; padding: 5px; border: 1px solid #ded7ce; border-radius: 9px; background: #fffefb; color: #49372e; box-shadow: 0 8px 28px #32251a1f; }
 .frameModeMenu button { display: flex; align-items: center; gap: 8px; width: 100%; padding: 9px 7px; border-radius: 5px; text-align: left; }
@@ -94,33 +127,43 @@
 .frameModeCheck { display: grid; place-items: center; width: 15px; flex: 0 0 15px; }
 .frameModeMenu strong { display: block; font-size: 12px; font-weight: 500; }
 .frameModeMenu small { display: block; margin-top: 2px; color: #92877c; font-size: 10px; }
+/* 加入目标用绿色边框/光晕，移出预览改虚线；提示元素本身不拦截拖放。 */
 .frameNode.frameDropTarget { border-color: #538366; background: #5383660c; box-shadow: 0 0 0 3px #53836638; }
 .frameNode.frameDropExit { border-style: dashed; }
 .frameDropHint { position: absolute; top: 12px; left: 12px; transform-origin: top left; border: 1px solid #9db8a4; border-radius: 6px; padding: 6px 9px; background: #f3f8f3; color: #3e684b; font-size: 12px; white-space: nowrap; pointer-events: none; }
+/* 归属变更通知居中放在底部工具栏上方；空内容隐藏，非空也不接管指针。 */
 .membershipNotice { position: absolute; bottom: 70px; left: 50%; transform: translateX(-50%); z-index: 20; max-width: min(540px, calc(100vw - 32px)); padding: 8px 12px; border: 1px solid #c8d9ca; border-radius: 8px; background: #f3f8f3; color: #3e684b; font-size: 12px; pointer-events: none; }
 .membershipNotice:empty { display: none; }
+/* 手形模式统一关闭文本、缩放、中心点和样式工具条的编辑入口。 */
 .handMode .plainText { pointer-events: none; }
 .handMode .rotationHint, .handMode .centerHandle { visibility: hidden; }
 .handMode .cornerResize { pointer-events: none; opacity: 0.6; }
 .handMode .styleToolbar { display: none; }
+/* 第一组减少动态效果规则关闭 frame、角缩放和中心点的过渡；后面还有分段滑块/连线动画的关闭规则。 */
 @media (prefers-reduced-motion: reduce) {
   .transformFrame, .cornerResize, .node :global(.react-flow__handle).centerHandle { transition: none; }
 }
 
 
+/* 分区主体 pointer-events:none，让内部节点/画布继续接收事件；标签和四边命中条另行启用 pointer-events。 */
 .frameNode { border: 1px solid #c9b7a5; border-radius: 8px; background: transparent; pointer-events: none; }
 .frameNode.selectedFrame { border-color: #a47764; box-shadow: 0 0 0 2px #a477641a; }
+/* 名称放在分区顶部外侧并以左下角缩放；文字截断但标签自身可拖动。 */
 .frameLabel { position: absolute; bottom: calc(100% + 8px); left: 0; max-width: 400px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13px; font-weight: 500; line-height: 22px; color: #92806d; transform-origin: left bottom; pointer-events: auto; cursor: grab; }
+/* 四条 10px 命中带跨在视觉边框两侧，扩大拖动区域，不给整个分区内部铺点击层。 */
 .frameBorderHit { position: absolute; pointer-events: auto; cursor: grab; }
 .frameBorder_top { top: -5px; left: 0; right: 0; height: 10px; }
 .frameBorder_bottom { bottom: -5px; left: 0; right: 0; height: 10px; }
 .frameBorder_left { left: -5px; top: 0; bottom: 0; width: 10px; }
 .frameBorder_right { right: -5px; top: 0; bottom: 0; width: 10px; }
+/* 分区改名输入沿用工具栏高度；手形模式下标签和命中边框也不接管事件。 */
 .styleToolbar .frameNameInput { width: 150px; height: 28px; padding: 0 6px; border: 1px solid #ded7ce; border-radius: 4px; font-size: 12px; background: transparent; }
 .handMode .frameBorderHit, .handMode .frameLabel { pointer-events: none; }
+/* 同步错误提示在顶部居中并允许按钮换行，说明文字独占一行。 */
 .syncError { position: absolute; left: 50%; top: 70px; translate: -50% 0; z-index: 22; display: flex; flex-wrap: wrap; gap: 8px; max-width: min(580px, calc(100vw - 24px)); padding: 12px; border: 1px solid #e5c7b8; border-radius: 8px; background: #fff9f3; color: #a25439; font-size: 12px; }
 .syncError span { flex-basis: 100%; }
 
+/* 恢复对话框限制视口宽度并居中，backdrop 给遮罩色；模态焦点行为来自 dialog 而不是 CSS。 */
 .recoveryDialog { max-width: min(460px, calc(100vw - 32px)); padding: 24px; margin: auto; border: 1px solid #ded7ce; border-radius: 12px; background: #fffefb; color: #49372e; box-shadow: 0 12px 50px #32251a20; }
 .recoveryDialog::backdrop { background: #30251e33; }
 .recoveryDialog h2 { font-size: 16px; margin-bottom: 12px; }
@@ -128,24 +171,32 @@
 .recoveryDialog > div { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 20px; }
 .recoveryDialog button { padding: 8px 12px; border: 1px solid #cbb8a8; border-radius: 5px; }
 
+/* 文本编辑容器允许 flex 收缩；readonly textarea 让出指针，由上层选择层处理选择/拖动。 */
 .textEditor { position: relative; display: flex; flex: 1; min-width: 0; min-height: 0; width: 100%; height: 100%; border-radius: inherit; }
 .textEditor textarea[readonly] { pointer-events: none; }
+/* 透明选择层盖住内容区域，选中后给 grab 光标；手形模式取消该层命中。 */
 .textSelectLayer { position: absolute; inset: 0; border-radius: inherit; cursor: default; }
 .handMode .textSelectLayer { pointer-events: none; }
 
 .selectedFrame .textSelectLayer { cursor: grab; }
 .textSelectLayer:active { cursor: grabbing; }
+/* 纯图片没有卡片 padding，图片仅显示不接受选择/拖动，外层控制变换。 */
 .plainImageFrame { padding: 0; }
 .plainImage { width: 100%; height: 100%; display: block; object-fit: contain; pointer-events: none; user-select: none; }
+/* 标题省略与改名输入分开；输入固定目标宽度并继承字体。 */
 .nodeTitle { min-width: 0; overflow: hidden; text-overflow: ellipsis; }
 .nodeTitleInput { width: 180px; min-width: 0; height: 22px; padding: 0 4px; border: 1px solid #cbb8a8; border-radius: 4px; background: #fffefb; font: inherit; color: #78523f; }
 
+/* 三段图标选项用 isolation 建局部层叠，按钮在滑块上方，背景由滑块提供。 */
 .frameLabelSegments { position: relative; display: flex; padding: 3px; border-radius: 6px; background: #f1eee8; isolation: isolate; }
 .frameLabelSegments button { position: relative; z-index: 1; width: 28px; height: 28px; flex: 0 0 28px; background: transparent !important; color: #92877c; }
 .frameLabelSegments button[aria-checked="true"] { color: #78523f; }
+/* 滑块绝对定位并用 transform 做短过渡，实际位移由组件按选项设置。 */
 .frameLabelSlider { position: absolute; left: 3px; top: 3px; width: 28px; height: 28px; border-radius: 4px; background: #fffefb; box-shadow: 0 1px 4px #32251a16; transition: transform 160ms ease; }
+/* 八向缩放 handle 按中心锚定，pointer-events:auto 覆盖外层让出命中的行为；手形模式再禁用。 */
 .resizeHandle { position: absolute; width: 10px; height: 10px; transform: translate(-50%, -50%); border: 1px solid #a47764; border-radius: 2px; padding: 0; background: #fffefb; z-index: 12; touch-action: none; pointer-events: auto; }
 .handMode .resizeHandle { pointer-events: none; }
+/* 连线工具条可换行，数字、颜色、范围和选择器分别限宽，避免长表单撑出视口。 */
 .edgeToolbar { display: flex; align-items: end; flex-wrap: wrap; gap: 7px; max-width: min(680px, calc(100vw - 24px)); padding: 10px; border: 1px solid #ded7ce; border-radius: 9px; background: #fffefb; color: #49372e; box-shadow: 0 5px 20px #32251a14; }
 .edgeToolbar label { display: flex; align-items: center; gap: 4px; font-size: 10px; }
 .edgeToolbar input[type="number"] { width: 50px; }
@@ -156,17 +207,24 @@
 .edgeToolbar button:hover { background: #f1e6df; }
 .edgeToolbar button:disabled { opacity: .4; }
 .edgeToolbar small { width: 100%; color: #92877c; font-size: 10px; }
+/* 曲线控制点用 pointer-events:all 开放 SVG 命中，触摸默认行为关闭，拖动逻辑由事件处理器负责。 */
 .curveControl { cursor: move; touch-action: none; pointer-events: all; }
+/* 连线效果分别用 dashoffset 流动和 opacity 脉冲；是否附加动画类由执行状态/配置决定。 */
 .edgeDashAnimation { animation: edgeDash 1.6s linear infinite; }
 .edgePulseAnimation { animation: edgePulse 1.6s ease-in-out infinite; }
+/* 虚线一个周期移动 40 单位；脉冲从低透明到不透明再返回。 */
 @keyframes edgeDash { to { stroke-dashoffset: -40; } }
 @keyframes edgePulse { 0%, 100% { opacity: .1; } 50% { opacity: 1; } }
+/* 第二组减少动态效果规则关闭滑块过渡和两种连线动画。 */
 @media (prefers-reduced-motion: reduce) { .frameLabelSlider { transition: none; } .edgeDashAnimation, .edgePulseAnimation { animation: none; } }
+/* 全画布 busy 覆盖层是独立呈现态；成员局部同步使用后部 memberSync，不应从这个类推断所有任务都会锁画布。 */
 .canvasBusy { position: absolute; inset: 0; display: flex; align-items: start; justify-content: center; padding-top: 80px; z-index: 200; background: #fffefb35; cursor: progress; color: #78523f; font-size: 12px; }
+/* 子图显示比例输入窄排布；折叠子图的摘要占内部 inset 区域并可点击。 */
 .subgraphScale { display: flex; align-items: center; gap: 2px; font-size: 11px; }
 .subgraphScale input { width: 45px; }
 .collapsedSubgraph { position: absolute; inset: 15px; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 7px; color: #92877c; pointer-events: auto; font-size: 12px; }
 .collapsedSubgraph small { font-size: 10px; }
+/* 元素 AI 面板限制视口宽度；标题信息省略，提示词可纵向伸展，底部模型/传播/执行按钮横排。 */
 .aiPanel { width: min(440px, calc(100vw - 28px)); border: 1px solid #ded7ce; border-radius: 13px; padding: 14px; background: #fffefb; box-shadow: 0 8px 30px #32251a16; color: #49372e; }
 .aiPanel header { display: flex; align-items: center; gap: 6px; font-size: 12px; margin-bottom: 9px; }
 .aiPanel header span { margin-left: auto; color: #92877c; max-width: 160px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 10px; }
@@ -176,32 +234,40 @@
 .aiPanel footer label { display: flex; align-items: center; gap: 4px; font-size: 10px; white-space: nowrap; }
 .aiPanel footer button { width: 32px; height: 32px; flex: 0 0 32px; display: grid; place-items: center; border-radius: 8px; background: #78523f; color: white; }
 .aiPanel footer button:disabled { opacity: .35; }
+/* 普通提示与 role=alert 错误采用不同颜色；冲突候选区域独立滚动并保留预格式文本换行。 */
 .aiPanel p { margin: 7px 0 0; color: #92877c; font-size: 10px; }
 .aiPanel p[role="alert"] { color: #a25439; }
 .aiConflict { max-height: 180px; overflow: auto; padding: 8px; border-radius: 7px; background: #f4eee7; font-size: 11px; }
 .aiConflict pre { white-space: pre-wrap; }
 .aiConflict img { max-height: 100px; }
 .aiConflict button { padding: 6px; color: #78523f; }
+/* 对通用变换 frame 再声明中心 handle：默认不可见不可命中，选中显示、connectionindicator 开启命中。 */
 .transformFrame :global(.react-flow__handle).centerHandle { width: 10px; height: 10px; border: 0; background: #a47764; opacity: 0; pointer-events: none; }
 .selectedFrame :global(.react-flow__handle).centerHandle { opacity: 1; }
 .transformFrame :global(.react-flow__handle).centerHandle:global(.connectionindicator) { pointer-events: auto; }
+/* 端口先定义几何，再在下一条默认隐藏/禁用；选中只显示，是否可连仍由 connectionindicator 决定。 */
 .framePort { width: 8px; height: 8px; border: 1px solid #fffefb; background: #a47764; pointer-events: auto; }
 .framePort { opacity: 0; pointer-events: none; }
 .selectedFrame .framePort { opacity: 1; }
 .framePort:global(.connectionindicator) { pointer-events: auto; }
 .rotatingFrame :global(.react-flow__handle).centerHandle { pointer-events: none; }
+/* busy 状态中的恢复/重试按钮仍显示明确可点表面。 */
 .canvasBusy button { margin: 8px 5px; padding: 6px 9px; border: 1px solid #ded7ce; border-radius: 5px; background: #fffefb; cursor: pointer; }
 
+/* 图片上传状态浮在底部工具栏上方，宽度受容器限制，不作为节点持久数据。 */
 .imageUploadStatus { position: absolute; bottom: 88px; left: 50%; transform: translateX(-50%); z-index: 120; display: flex; align-items: center; gap: 12px; max-width: min(600px,90%); padding: 10px 14px; background: #fffdf9; border: 1px solid #ded5cb; border-radius: 10px; color: #796e63; font-size: 12px; box-shadow: 0 4px 18px #372f2410; }
 
+/* 成员同步只显示紧凑状态和下划线操作按钮，不使用全画布遮罩。 */
 .memberSync { padding: 5px 9px; border: 1px solid #ded7ce; border-radius: 7px; background: #fffefb; color: #796e63; font-size: 11px; box-shadow: 0 2px 8px #372f2410; }
 .memberSync button { margin-left: 6px; border: 0; background: transparent; color: #78523f; text-decoration: underline; cursor: pointer; }
 
+/* 导入状态面板位于右上，有宽高上限和内部滚动；summary 切换详情，任务之间用边线分隔。 */
 .importPanel { position: absolute; top: 84px; right: 12px; z-index: 12; width: max-content; max-width: min(310px, calc(100vw - 28px)); max-height: 45vh; overflow: auto; border: 1px solid #ded7ce; border-radius: 10px; padding: 6px 9px; background: #fffefb; box-shadow: 0 4px 18px #32251a10; color: #49372e; font-size: 11px; }
 .importPanel summary { cursor: pointer; padding: 5px 0; }
 .importPanel ul { padding-left: 16px; overflow-wrap: anywhere; }
 .importPanel p { margin: 5px 0; }
 .importPanel small { color: #92877c; }
 .importJob { border-top: 1px solid #eee7de; padding-top: 5px; margin-top: 5px; }
+/* 导入动作横排，其余任务按钮使用文字色与局部留白，任务状态由 runtime/组件决定。 */
 .importActions { display: flex; align-items: center; gap: 8px; }
 .importActions > button:not(:first-child), .importJob button { color: #78523f; padding: 4px 0; }

src/components/landing-page.module.css

@@ -1,95 +1,121 @@
+/* 当前 LandingPage 的局部配色、两栏首屏、可选预览卡片、功能区和响应式布局；预览交互由组件状态驱动，不使用真实画布模型。 */
+/* 页面作用域内定义墨色/弱文字/边线变量，局部规则覆盖全局品牌类时使用 :global。 */
 .page { --ink: #21221f; --muted: #797b73; --line: #e5e6df; background: #fff; color: var(--ink); font-family: Inter, -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; }
+/* 移除触摸高亮并保留明确的键盘可见焦点描边。 */
 .page a, .page button { -webkit-tap-highlight-color: transparent; }
 .page a:focus-visible, .page button:focus-visible { outline: 2px solid #6879c2; outline-offset: 4px; }
+/* 导航内容限制最大宽度，品牌、导航链接和右侧操作区横排。 */
 .nav { display: flex; align-items: center; gap: 40px; height: 88px; max-width: 1320px; padding: 0 48px; margin: auto; }
 .page :global(.brand) { color: var(--ink); gap: 8px; font-size: 19px; letter-spacing: -0.6px; }
 .page :global(.brand img) { width: 30px; height: 30px; }
 .page :global(.brand small) { color: #92958c; font-size: 11px; font-weight: 400; letter-spacing: 0; }
 .nav nav { display: flex; gap: 28px; font-size: 13px; color: #72766c; }
 .nav nav a:hover { color: var(--ink); }
+/* margin-left:auto 将登录和小 CTA 推到最右侧，hover 只改变表面色。 */
 .navActions { margin-left: auto; display: flex; align-items: center; gap: 24px; font-size: 13px; }
 .smallCta { display: inline-flex; align-items: center; gap: 12px; padding: 10px 15px; border: 1px solid #cfd2c8; border-radius: 5px; }
 .smallCta:hover { background: #f5f6f0; }
+/* 桌面首屏文案/预览用接近等宽的两列；clamp 让标题在边界内随视口缩放。 */
 .hero { max-width: 1320px; margin: auto; padding: 82px 48px 90px; display: grid; grid-template-columns: 1fr 1.04fr; align-items: center; gap: 46px; }
 .eyebrow { font: 10px/1.6 ui-monospace, "SFMono-Regular", monospace; letter-spacing: 1.25px; color: #90958a; }
 .heroCopy .eyebrow { display: flex; align-items: center; gap: 8px; white-space: nowrap; }
 .statusDot { width: 5px; height: 5px; background: #83966c; border-radius: 50%; }
 .hero h1 { font-size: clamp(38px, 4.4vw, 61px); font-weight: 600; line-height: 1.23; letter-spacing: -3px; margin: 22px 0; }
 .hero h1 > span { position: relative; white-space: nowrap; }
+/* 标题装饰线通过伪元素绘制，不增加实际文本或影响行内宽度。 */
 .hero h1 > span::after { content: ""; position: absolute; left: 0; bottom: -3px; width: 100%; height: 5px; border-bottom: 2px solid #b9c87c; border-radius: 50%; rotate: -2deg; }
 .heroCopy > p { color: #6f7369; font-size: 15px; line-height: 1.9; font-weight: 400; }
+/* CTA 可换行，主按钮悬停上移 1px；旁边文字链接保持次级视觉权重。 */
 .heroActions { display: flex; flex-wrap: wrap; align-items: center; gap: 22px; margin-top: 30px; }
 .primary { display: inline-flex; align-items: center; justify-content: center; gap: 16px; padding: 14px 20px; background: var(--ink); color: #fff; border: 1px solid var(--ink); border-radius: 5px; font-size: 13px; font-weight: 500; box-shadow: 0 2px 2px #21221f08; transition: background 160ms, translate 160ms; }
 .primary:hover { background: #41453b; translate: 0 -1px; }
 .textLink { display: inline-flex; align-items: center; gap: 8px; font-size: 12px; color: #6e7565; }
 .textLink:hover { color: #21221f; }
+/* 手写风附注和星形装饰仅参与视觉排版。 */
 .heroNote { margin-top: 34px; font-family: "Kaiti SC", "STKaiti", Georgia, serif; color: #969a8b; font-size: 13px; display: flex; align-items: center; gap: 8px; }
 .scribbleStar { font-family: Georgia, serif; color: #929a74; font-size: 24px; }
+/* 预览外壳轻微旋转并设置阴影，min-width:0 防止网格项被内容撑宽。 */
 .preview { min-width: 0; border: 1px solid #e0e3d9; border-radius: 9px; background: #fafafa; box-shadow: 0 12px 50px #3c442508, 0 2px 8px #3c442505; rotate: -1deg; }
 .previewHeading { padding: 14px 18px; border-bottom: 1px solid var(--line); display: flex; align-items: center; justify-content: space-between; font-size: 10px; color: #777d70; }
 .previewHeading > span:first-child { display: flex; align-items: center; gap: 7px; color: #69745e; }
 .previewHeading > span:last-child { font: 8px ui-monospace, monospace; letter-spacing: 1px; }
 .tinyLogo { font-size: 20px; color: #4c5841; }
+/* 点阵预览固定宽高比，卡片和 SVG 连线在相同相对容器内绝对定位。 */
 .scene { position: relative; aspect-ratio: 600 / 440; background-image: radial-gradient(#dce1d2 0.65px, transparent 0.65px); background-size: 17px 17px; }
 .wires { position: absolute; inset: 0; width: 100%; height: 100%; stroke: #a3ad90; stroke-width: 1; }
 .wires circle { fill: #a3ad90; }
+/* 预览卡片作为按钮可点击，hover 上移，activeCard 通过边框/阴影反馈当前选择。 */
 .scene > button { position: absolute; display: flex; flex-direction: column; text-align: left; border: 1px solid #e1e4d8; border-radius: 5px; padding: 14px; background: #fff; color: #373a35; box-shadow: 0 2px 5px #32471504; transition: box-shadow 180ms, border-color 180ms, translate 180ms; }
 .scene > button:hover { translate: 0 -3px; }
 .scene .activeCard { border-color: #9aa77d; box-shadow: 0 0 0 2px #9aa77d15, 0 4px 12px #32471508; }
 .cardLabel { display: flex; align-items: center; gap: 5px; font-size: 9px; color: #9aab88; }
+/* 三类预览卡片各有位置、旋转和排版；纸角、艺术图与标签是局部装饰。 */
 .ideaCard { left: 5%; top: 17%; width: 42%; min-height: 41%; rotate: -3deg; }
 .ideaCard strong { margin-top: 14px; margin-bottom: 13px; font-size: clamp(13px, 1.6vw, 22px); font-family: "Songti SC", Georgia, serif; font-weight: 400; line-height: 1.55; }
 .cardText { font-size: 9px; line-height: 1.8; color: #9ba48f; }
 .paperCorner { position: absolute; bottom: 4px; right: 4px; width: 10px; height: 10px; border-right: 1px solid #d9dece; border-bottom: 1px solid #d9dece; }
+/* 艺术卡片给 SVG 可用高度，使用无填充线稿；便签另有底色与字号。 */
 .scene .artCard { top: 8%; right: 7%; width: 29%; min-height: 49%; background: #edeaf7; rotate: 4deg; }
 .artCard svg { width: 100%; max-height: 150px; flex: 1; stroke: #53584d; stroke-width: 1.2; fill: none; }
 .artCaption { font: italic 8px Georgia, serif; text-align: center; color: #909e79; }
 .scene .noteCard { left: 38%; bottom: 9%; width: 37%; min-height: 27%; background: #f0eedf; rotate: 2deg; }
 .noteCard strong { margin: 9px 0 12px; font-size: clamp(11px, 1.4vw, 18px); font-family: "Songti SC", Georgia, serif; font-weight: 400; line-height: 1.5; }
 .noteTag { align-self: flex-start; font-size: 8px; padding: 3px 5px; border: 1px solid #d6d6ba; border-radius: 3px; color: #8f9278; }
+/* 随手附注与假协作光标定位在预览中，光标不拦截鼠标事件。 */
 .looseNote { position: absolute; left: 8%; bottom: 12%; color: #aab39c; rotate: -10deg; font: italic 14px Georgia, serif; }
 .cursor { position: absolute; right: 17%; bottom: 20%; color: #879567; rotate: -12deg; pointer-events: none; }
 .cursor span { position: absolute; top: 20px; left: 12px; background: #879567; color: white; border-radius: 3px; padding: 3px 7px; font-size: 9px; }
+/* 预览页脚横排指示点与页码，aria-pressed 标示当前点，最后一项推到右侧。 */
 .previewFooter { display: flex; align-items: center; gap: 10px; padding: 13px 18px; border-top: 1px solid var(--line); font-size: 9px; color: #a1a992; }
 .previewFooter > div { display: flex; gap: 5px; }
 .previewFooter button { width: 5px; height: 5px; border-radius: 50%; background: #d8dfcc; }
 .previewFooter button[aria-pressed="true"] { background: #879567; }
 .previewFooter > span:last-child { margin-left: auto; font: 9px ui-monospace, monospace; }
+/* 宣言横条用上下边线与两侧注记分隔首屏和后续内容。 */
 .manifestoStrip { display: flex; align-items: center; justify-content: space-between; gap: 20px; max-width: 1224px; margin: 0 auto; padding: 25px 0; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); }
 .manifestoStrip > span { font: 8px ui-monospace, monospace; letter-spacing: 0.6px; color: #a0a494; }
 .manifestoStrip p { font-size: 13px; color: #646c58; letter-spacing: 0.3px; }
 .manifestoStrip p span { color: #9ba28e; }
+/* 功能区域限制最大宽度；标题与说明左右对齐，功能卡使用三列网格。 */
 .space { max-width: 1320px; margin: auto; padding: 105px 48px; }
 .sectionHeading { display: flex; align-items: flex-end; justify-content: space-between; gap: 30px; margin-bottom: 48px; }
 .sectionHeading h2, .faq h2 { font-size: 34px; line-height: 1.5; letter-spacing: -1px; font-weight: 500; margin-top: 18px; }
 .sectionHeading > p { padding-bottom: 5px; color: #6c7166; line-height: 1.9; font-size: 13px; }
 .featureGrid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 32px; }
 .featureGrid article { min-width: 0; }
+/* 每个功能插画使用固定高度裁剪容器，内部收集/连线/创作布局分别绘制。 */
 .featureArt { position: relative; height: 185px; border: 1px solid #eaede4; border-radius: 6px; background: #f9faf6; overflow: hidden; margin-bottom: 25px; }
+/* 收集示例用轻微旋转和水平位移错开三条素材，保持纵向居中。 */
 .collectArt { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 9px; }
 .collectArt span { display: flex; align-items: center; gap: 9px; padding: 8px 12px; min-width: 70%; border: 1px solid #e1e6d7; border-radius: 4px; background: #fff; font-size: 10px; color: #859471; rotate: -2deg; }
 .collectArt span:nth-child(2) { rotate: 2deg; translate: 8px 0; }
 .collectArt span:nth-child(3) { rotate: -1deg; translate: -5px 0; }
 .collectArt svg { width: 14px; }
+/* 连线示例 SVG 铺满插画，两个端点卡片和装饰字形单独定位。 */
 .connectArt svg { width: 100%; height: 100%; stroke: #b1b99e; }
 .connectArt span { position: absolute; top: 39px; left: 23px; padding: 10px 13px; border: 1px solid #e1e5d6; border-radius: 5px; background: #fff; color: #8a9877; font-size: 11px; }
 .connectArt span:nth-of-type(2) { top: 110px; left: auto; right: 35px; background: #edf0e1; }
 .connectArt i { position: absolute; top: 38px; right: 25px; color: #a0ad86; font: 32px Georgia, serif; }
+/* 创作示例居中纸张和标题，编辑徽标独立固定在插画右下附近。 */
 .createArt { display: grid; place-items: center; }
 .createArt > div { display: flex; flex-direction: column; align-items: center; gap: 12px; padding: 24px; background: #f1efe3; width: 72%; rotate: -2deg; border: 1px solid #e0dfcf; }
 .createArt > div > span { font: 7px ui-monospace, monospace; letter-spacing: 1px; color: #9da184; }
 .createArt strong { font: 25px "Songti SC", Georgia, serif; color: #6e7857; letter-spacing: 1px; }
 .editBadge { position: absolute; right: 14px; bottom: 24px; display: flex; align-items: center; gap: 5px; padding: 5px 8px; border: 1px solid #dce3cf; background: #fff; border-radius: 4px; font-size: 8px; color: #889874; }
+/* 编号、功能标题与正文使用逐级字号，正文行高便于多行阅读。 */
 .featureNumber { color: #a4ab98; font: 9px ui-monospace, monospace; letter-spacing: 0.7px; }
 .featureGrid h3 { font-size: 18px; font-weight: 500; margin: 12px 0; letter-spacing: -0.4px; }
 .featureGrid p { font-size: 12px; color: #6c7166; line-height: 1.9; }
+/* 工作流区域用浅底与上下边线分隔，两列分别承载引语和步骤。 */
 .workflow { background: #f7f7f4; border-top: 1px solid #e9ece1; border-bottom: 1px solid #e9ece1; display: grid; grid-template-columns: 1fr 1fr; gap: 90px; padding: 85px max(48px, calc((100vw - 1224px) / 2)); }
+/* 引号绝对定位在文案旁，标题自身保持相对定位，签名字体与正文区分。 */
 .quote { position: relative; }
 .quoteMark { font: 80px/1 Georgia, serif; position: absolute; top: -30px; left: -12px; color: #d9dfca; }
 .quote h2 { position: relative; font: 31px/1.7 "Songti SC", Georgia, serif; color: #586449; }
 .quote em { display: block; font-style: normal; }
 .quote p { font-size: 12px; color: #747a6d; line-height: 2; margin-top: 18px; }
 .signature { display: block; font: italic 13px Georgia, serif; color: #a3ad94; margin-top: 30px; }
+/* 步骤纵向居中，每项含编号、文字和右侧不收缩的图标。 */
 .workflowList { display: flex; flex-direction: column; justify-content: center; }
 .workflowList > div { display: flex; gap: 18px; padding: 24px 0; border-bottom: 1px solid #dfe5d4; }
 .workflowList > div:first-child { padding-top: 0; }
@@ -97,11 +123,13 @@
 .workflowList h3 { font-size: 15px; font-weight: 500; color: #5e6e4e; margin-bottom: 8px; }
 .workflowList p { font-size: 11px; line-height: 1.8; color: #747a6d; }
 .workflowList svg { flex-shrink: 0; color: #a5b38e; margin-left: auto; }
+/* FAQ 桌面为标题/问题两列，问题按钮整行可点击；展开内容是否存在由组件决定。 */
 .faq { max-width: 1320px; padding: 105px 48px; margin: auto; display: grid; grid-template-columns: 0.8fr 1.2fr; gap: 90px; }
 .faqItem { border-bottom: 1px solid var(--line); }
 .faqItem button { display: flex; align-items: center; justify-content: space-between; gap: 20px; width: 100%; padding: 23px 0; font-size: 14px; text-align: left; }
 .faqItem svg { flex-shrink: 0; color: #929b84; transition: rotate 160ms; }
 .faqItem p { padding: 0 28px 24px 0; font-size: 12px; line-height: 1.9; color: #8b947e; }
+/* 收尾 CTA 居中，星形装饰绝对定位；页脚内容横排并用 auto margin 推开链接。 */
 .closing { position: relative; border-top: 1px solid var(--line); text-align: center; padding: 85px 24px 90px; }
 .closing h2 { font-size: 38px; letter-spacing: -1.3px; font-weight: 500; margin: 18px 0; }
 .closing p { font-size: 13px; color: #74796d; margin-bottom: 28px; }
@@ -110,8 +138,11 @@
 .footer > p { font-size: 11px; color: #a1a992; }
 .footer > a:not(:first-child) { margin-left: auto; display: flex; gap: 7px; align-items: center; font-size: 11px; color: #7e8b6a; }
 .footer > span { color: #abb39d; font: 8px ui-monospace, monospace; }
+/* 断行标记默认隐藏，本文件没有另行显示它的媒体查询。 */
 .mobileBreak { display: none; }
+/* 大屏仅增大首屏上下留白。 */
 @media (min-width: 1400px) { .hero { padding-top: 105px; padding-bottom: 110px; } }
+/* 中屏压缩页面边距、标题、按钮及区块间距，仍保留主要双栏/三栏结构。 */
 @media (max-width: 1050px) {
   .nav, .hero, .space, .faq, .footer { padding-left: 30px; padding-right: 30px; }
   .hero { gap: 26px; }
@@ -124,6 +155,7 @@
   .featureGrid { gap: 20px; }
   .faq { gap: 45px; }
 }
+/* 窄屏隐藏导航链接，将首屏、功能、工作流和 FAQ 转为单列，并缩小装饰及页脚内容。 */
 @media (max-width: 760px) {
   .nav { height: 74px; gap: 15px; padding-left: 22px; padding-right: 22px; }
   .nav nav { display: none; }
@@ -159,6 +191,7 @@
   .footer > p { display: none; }
   .footer > span { flex-basis: 100%; }
 }
+/* 极窄屏进一步压缩边距和预览卡片文字，隐藏品牌副标，避免最小视口拥挤。 */
 @media (max-width: 380px) {
   .page :global(.brand small) { display: none; }
   .hero { padding-left: 20px; padding-right: 20px; }
@@ -170,4 +203,5 @@
   .ideaCard strong { margin-top: 8px; margin-bottom: 8px; }
   .noteTag { font-size: 7px; padding: 2px; }
 }
+/* 按减少动态效果偏好关闭链接、按钮和 FAQ 图标的过渡。 */
 @media (prefers-reduced-motion: reduce) { .page a, .page button, .faqItem svg { transition: none; } }

src/components/ui/icon-button.module.css

@@ -1,3 +1,5 @@
+/* IconButton 的共享尺寸、交互态和 tooltip 外观；尺寸从所在 Toolbar 的自定义属性继承，缺省为 32px 控件/20px 图标。 */
+/* 固定 flex 尺寸避免拥挤时压缩；inline-flex 居中图标，透明背景显露宿主表面，文字颜色继承宿主。 */
 .button {
   display: inline-flex;
   align-items: center;
@@ -13,10 +15,13 @@
   color: inherit;
   cursor: pointer;
 }
+/* SVG 同时约束宽高与 flex-basis，防止图标在文字/布局挤压下变形。 */
 .button svg { width: var(--toolbar-icon-size, 20px); height: var(--toolbar-icon-size, 20px); flex: 0 0 var(--toolbar-icon-size, 20px); }
+/* 悬停填底、键盘可见焦点描边、禁用态降低透明度并提示不可操作。 */
 .button:hover { background: #e9e7e3; }
 .button:focus-visible { outline: 2px solid #9d7d66; outline-offset: 2px; }
 .button:disabled { opacity: 0.45; cursor: not-allowed; }
 
+/* tooltip 使用高层级深色面板与有限宽度；arrow 颜色与面板一致。 */
 .tooltip { z-index: 1000; max-width: 240px; padding: 6px 9px; border-radius: 6px; background: #49372e; color: #fffdf9; font-size: 12px; line-height: 1.45; box-shadow: 0 3px 12px #372f2420; user-select: none; }
 .arrow { fill: #49372e; }

src/components/ui/toolbar.module.css

@@ -1,3 +1,5 @@
+/* Toolbar 共享表面：统一控件尺寸变量、排列间距、边框和背景；不负责自身在画布中的定位。 */
+/* 提供后代按钮消费的 CSS 变量；半透明背景与 backdrop blur 处理工具栏背后的内容。 */
 .surface {
   --toolbar-icon-size: 20px;
   --toolbar-control-width: 32px;
@@ -18,5 +20,7 @@
 }
 
 /* Text in the view controls already creates wider visual spacing. */
+/* 含缩放文字的视图工具栏增加横向留白，不改变控件本身的尺寸。 */
 .relaxed { column-gap: 6px; padding-inline: 6px; }
+/* 分隔线保持 1px flex 基准，避免被相邻控件挤宽或挤没。 */
 .divider { flex: 0 0 1px; width: 1px; height: 16px; margin: 0 2px; background: #ece6df; }

src/components/workspace/editable-title.module.css

@@ -1,9 +1,15 @@
+/* EditableTitle 的只读标题/输入框切换样式；壳体作为错误提示的定位参照，网络和提交状态由组件控制。 */
+/* 相对定位保留标题所在行，绝对定位错误框不会把工具栏向下撑开。 */
 .shell { position: relative; display: flex; align-items: center; }
+/* 两种状态共用高度、字体和透明边框，降低进入编辑时的尺寸跳变。 */
 .title, .input { box-sizing: border-box; min-width: 0; max-width: 100%; height: 32px; padding: 0 6px; border: 1px solid transparent; border-radius: 5px; background: transparent; color: inherit; font: inherit; line-height: 30px; }
+/* 非编辑标题单行省略；悬停仅作用于可用按钮，选中态由 data-selected 控制。 */
 .title { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; text-align: left; }
 .title:hover:not(:disabled) { background: #f0ece6; }
 .title[data-selected="true"] { background: #ede5dc; border-color: #d3c0b2; }
 .title:disabled { cursor: default; }
+/* 编辑态给定目标宽度但受上方 max-width 限制，readonly 时降低透明度。 */
 .input { width: 220px; border-color: #a47764; background: white; outline: none; }
 .input[readonly] { opacity: 0.65; }
+/* 错误框显示在标题下方，并以视口宽度限制最大宽度；长说明允许换行。 */
 .error { position: absolute; top: calc(100% + 10px); left: 0; width: 260px; max-width: calc(100vw - 40px); padding: 8px 10px; border: 1px solid #e5c7b8; border-radius: 7px; background: #fff9f3; color: #a25439; font-size: 12px; line-height: 1.6; white-space: normal; box-shadow: 0 4px 12px #32251a0a; }

src/components/workspace/workspace.module.css

@@ -1,3 +1,5 @@
+/* 工作区壳体、目录、账户菜单与画布浮动标题；CSS Module 负责显示，账号/画布生命周期和侧栏开关由组件管理。 */
+/* 侧栏宽度变量供侧栏本体和浮动标题共同消费，根容器至少占满动态视口高度。 */
 .shell {
   --sidebar-width: 270px;
   display: flex;
@@ -5,6 +7,7 @@
   background: #fffefb;
   color: #37352f;
 }
+/* 侧栏插槽 sticky 固定在滚动视口顶部；裁剪展开过渡期间的内容，层级高于画布。 */
 .sidebarSlot {
   position: sticky;
   top: 0;
@@ -14,6 +17,7 @@
   overflow: hidden;
   z-index: 30;
 }
+/* 侧栏采用纵向 flex，导航区可滚动、账户区留在底部；最大宽度给主区域保留至少 40px。 */
 .sidebar {
   display: flex;
   flex-direction: column;
@@ -29,30 +33,38 @@
   letter-spacing: -0.15px;
   color: #37352f;
 }
+/* 顶行按钮分居两端；搜索框 focus-within 让输入聚焦时整个框有反馈。 */
 .topRow { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; color: #85817b; }
 .search { display: flex; align-items: center; gap: 7px; min-height: 32px; border: 1px solid #e6e3df; border-radius: 7px; padding: 4px 8px; color: #97938d; }
 .search:focus-within { border-color: #b2a292; box-shadow: 0 0 0 2px #b2a29218; }
 .search input { min-width: 0; width: 100%; padding: 0; background: transparent; border: 0; outline: none; font: inherit; color: #37352f; }
 .search input::placeholder { color: #9a9690; }
+/* flex:1 配合 min-height:0 才允许长目录在侧栏内部滚动。 */
 .navigation { flex: 1; min-height: 0; overflow-y: auto; padding-top: 10px; }
+/* 首页与目录链接共用行高/图标间距，长标题省略；aria-current 对当前页提供选中背景。 */
 .home, .pageLink { display: flex; align-items: center; gap: 8px; padding: 4px 8px; min-height: 30px; border-radius: 6px; font-weight: 450; }
 .home { width: fit-content; font-weight: 600; background: #ecebe8; }
 .pageLink { margin: 1px 0; }
 .pageLink svg { flex-shrink: 0; color: #87837c; }
 .pageLink span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .pageLink:hover, .pageLink[aria-current="page"] { background: #eae7e2; }
+/* 分组名称、空态提示和错误分别排版；错误允许在任意位置折行。 */
 .sectionLabel { display: flex; justify-content: space-between; padding: 18px 7px 6px; color: #9b9690; font-size: 11px; font-weight: 400; letter-spacing: 0; }
 .hint { padding: 4px 8px; color: #9a948c; line-height: 1.6; font-size: 12px; }
 .error { margin: 6px 4px; font-size: 12px; color: #b14b3c; overflow-wrap: anywhere; }
+/* 账户区域向侧栏底部靠齐，按钮占满宽度以便整行点击。 */
 .accountArea { margin-top: auto; padding-top: 6px; }
 .accountButton { display: flex; align-items: center; gap: 8px; padding: 6px 7px; min-height: 36px; width: 100%; border-radius: 6px; text-align: left; color: #37352f; }
 .accountButton:hover { background: #edeae5; }
+/* 头像固定尺寸并裁成圆形，图片 object-fit:cover；缺图时容纳首字占位。 */
 .avatar { display: grid; place-items: center; flex: 0 0 24px; width: 24px; height: 24px; overflow: hidden; border-radius: 50%; background: #e8e0d6; color: #705844; font-size: 12px; font-weight: 600; }
 .avatar img { display: block; width: 100%; height: 100%; object-fit: cover; }
 .avatarLarge { flex-basis: 36px; width: 36px; height: 36px; font-size: 16px; }
+/* 账户文字允许收缩和省略，副文字在此布局隐藏。 */
 .accountText { display: flex; flex: 1; flex-direction: column; min-width: 0; }
 .accountText strong { font-size: 13px; font-weight: 550; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
 .accountText small { display: none; }
+/* 原生 popover 的面板位置/宽度约束；自身可滚动且从左下角进入，不用 CSS 切换 open 状态。 */
 .accountPopup {
   position: fixed;
   inset: auto auto 50px 8px;
@@ -73,31 +85,40 @@
   letter-spacing: -0.15px;
   transform-origin: bottom left;
 }
+/* 仅 popover 打开时播放进入动画；backdrop 保持透明，但是否可交互仍由 popover 行为决定。 */
 .accountPopup:popover-open { animation: account-enter 130ms ease-out; }
 .accountPopup::backdrop { background: transparent; }
+/* 菜单头、工作区字母头像及身份行共用纵向文字布局，长名称省略。 */
 .accountHeading { display: flex; align-items: center; gap: 10px; padding: 8px 7px 10px; }
 .workspaceAvatar { display: grid; place-items: center; flex: 0 0 36px; height: 36px; border-radius: 7px; color: #72533e; background: #eee8df; font-size: 19px; font-weight: 600; }
 .accountHeading > div, .popupIdentity > div { display: flex; flex-direction: column; min-width: 0; gap: 1px; }
 .accountHeading strong { font-size: 14px; font-weight: 600; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
 .accountHeading small { color: #8b8780; font-size: 12px; }
+/* 菜单分组和身份区域提供内间距，邮箱允许断行；工作区列表限制高度后独立滚动。 */
 .menuGroup { padding: 1px 0; }
 .popupIdentity { display: flex; align-items: center; gap: 8px; padding: 8px 7px 7px; }
 .popupIdentity strong { font-size: 12px; font-weight: 500; }
 .popupIdentity small { color: #8b8780; font-size: 11px; overflow-wrap: anywhere; letter-spacing: 0; }
 .workspaceList { max-height: min(220px, 30dvh); overflow-y: auto; }
+/* 菜单项整行可点，文字可收缩，图标保持宽度；disabled 态显式降低透明度。 */
 .menuItem { display: flex; align-items: center; gap: 9px; width: 100%; min-height: 31px; padding: 5px 8px; border-radius: 5px; text-align: left; font-size: 13px; line-height: 20px; font-weight: 450; }
 .menuItem > span:not(.workspaceMini) { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .menuItem > svg { flex-shrink: 0; }
 .menuItem:hover { background: #f1f0ed; }
 .menuItem:disabled { opacity: 0.45; cursor: not-allowed; }
+/* 工作区小头像与新建/登出颜色区分，separator 分隔组而不引入额外布局容器。 */
 .workspaceMini { display: grid; place-items: center; flex: 0 0 20px; height: 20px; border-radius: 4px; color: #82634c; background: #f1ebe3; font-size: 11px; font-weight: 600; }
 .newWorkspace { color: #2383e2; }
 .logout { color: #78746d; font-size: 12px; }
 .separator { height: 1px; margin: 6px 7px; background: #eeece8; }
+/* 左上浮动条以 --floating-left 定位；侧栏展开时偏移到侧栏右侧，位置和宽度作 240ms 过渡。 */
 .floating { --floating-left: 12px; position: fixed; left: var(--floating-left); top: 12px; max-width: calc(100vw - var(--floating-left) - 12px); z-index: 40; transition: left 240ms cubic-bezier(0.22, 1, 0.36, 1), max-width 240ms cubic-bezier(0.22, 1, 0.36, 1); }
+/* 展开侧栏时使用实际受视口约束的侧栏宽度计算偏移；账户 popover 也继承同一偏移变量。 */
 .floating[data-sidebar-collapsed="false"], .accountPopup[data-sidebar-collapsed="false"] { --floating-left: calc(min(var(--sidebar-width), calc(100vw - 40px)) + 12px); }
+/* 浮动条错误绝对定位于条下方，账户设置面板则沿用对话框容器。 */
 .floatingError { position: absolute; left: 0; top: 42px; width: 240px; padding: 10px; background: white; border: 1px solid #e7e2db; border-radius: 8px; color: #b14b3c; font-size: 12px; }
 .settingsPanel { color: #37352f; border-color: #e6e2dc; border-radius: 12px; }
+/* 设置表单纵向排布身份、字段及操作；提交按钮区分主动作，禁用时保留位置。 */
 .settingsForm { display: flex; flex-direction: column; gap: 16px; padding-top: 4px; }
 .settingsIdentity { display: flex; align-items: center; gap: 10px; font-size: 13px; color: #89837b; overflow-wrap: anywhere; }
 .settingsForm label { display: flex; flex-direction: column; gap: 6px; font-size: 13px; font-weight: 500; }
@@ -106,35 +127,48 @@
 .settingsActions button { padding: 6px 12px; border: 1px solid #e2ddd6; border-radius: 6px; font-size: 13px; }
 .settingsActions button[type="submit"] { background: #37352f; color: white; border-color: #37352f; }
 .settingsActions button:disabled { opacity: 0.5; cursor: not-allowed; }
+/* 固定全视口画布置于底层；点阵背景与加载/错误状态由后续类分别承担。 */
 .graph { position: fixed; inset: 0; z-index: 0; display: flex; width: 100%; height: 100dvh; background: #fffefb; }
 .graphSurface { width: 100%; height: 100%; background-image: radial-gradient(#b8aea245 1px, transparent 1px); background-size: 22px 22px; }
 .graphStatus { position: absolute; left: 50%; top: 72px; transform: translateX(-50%); max-width: calc(100vw - 48px); padding: 8px 12px; border-radius: 6px; background: #fffefbe6; color: #9a948c; text-align: center; font-size: 13px; }
+/* 账户菜单从轻微下移/缩小过渡到正常位置与不透明状态。 */
 @keyframes account-enter { from { opacity: 0; transform: translateY(4px) scale(0.985); } to { opacity: 1; transform: translateY(0) scale(1); } }
+/* 较窄视口将侧栏目标宽度收为 240px；仍受上方 max-width 约束。 */
 @media (max-width: 600px) { .shell { --sidebar-width: 240px; } }
+/* 减少动态效果偏好下关闭菜单进入动画；浮动条过渡在文件后部单独关闭。 */
 @media (prefers-reduced-motion: reduce) { .accountPopup:popover-open { animation: none; } }
 
+/* 浮动条 logo 链接沿用 Toolbar 控件尺寸与键盘焦点样式，保证和旁边按钮对齐。 */
 .logoLink { display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto; box-sizing: border-box; width: var(--toolbar-control-width, 32px); height: var(--toolbar-control-height, 32px); padding: 4px 6px; border-radius: 5px; }
 .logoLink img { display: block; width: var(--toolbar-icon-size, 20px); height: var(--toolbar-icon-size, 20px); }
 .logoLink:hover { background: #e9e7e3; }
 .logoLink:focus-visible { outline: 2px solid #9d7d66; outline-offset: 2px; }
 
+/* 浮动头像按钮同样使用共享尺寸；从浮动条打开的账户面板改为顶端定位。 */
 .floatingAvatarButton { display: grid; place-items: center; flex: 0 0 auto; box-sizing: border-box; width: var(--toolbar-control-width, 32px); height: var(--toolbar-control-height, 32px); border-radius: 5px; }
 .floatingAvatarButton:hover { background: #e9e7e3; }
+/* clamp 把账户面板左边界限制在视口内；transform-origin 随顶部锚点改为左上。 */
 .accountPopup[data-floating="true"] { inset: 62px auto auto clamp(8px, var(--floating-left, 12px), max(8px, calc(100vw - 308px))); max-height: calc(100dvh - 76px); transform-origin: top left; }
 
+/* 浮动头像采用图标尺寸，标题允许 flex 收缩但保留溢出区域给编辑错误提示。 */
 .floatingAvatarButton .avatar { flex-basis: var(--toolbar-icon-size, 20px); width: var(--toolbar-icon-size, 20px); height: var(--toolbar-icon-size, 20px); font-size: 14px; }
 .floatingTitle { flex: 1 1 auto; min-width: 0; max-width: 240px; margin: 0; color: #37352f; font-size: 14px; line-height: var(--toolbar-control-height, 32px); font-weight: 500; overflow: visible; }
+/* 中等窄屏降低标题最大宽度，不改变标题内容或编辑状态。 */
 @media (max-width: 700px) { .floatingTitle { max-width: 180px; } }
+/* 极窄且侧栏仍展开时隐藏 logo/标题/分隔，保留浮动条其余控件。 */
 @media (max-width: 420px) {
   .floating[data-sidebar-collapsed="false"] .logoLink,
   .floating[data-sidebar-collapsed="false"] .floatingTitle,
   .floating[data-sidebar-collapsed="false"] > span[aria-hidden="true"] { display: none; }
 }
+/* 按用户偏好关闭浮动条位移/宽度过渡。 */
 @media (prefers-reduced-motion: reduce) { .floating { transition: none; } }
 
+/* 递归目录清除列表默认缩进，层级缩进由组件布局提供；行本身允许标题收缩。 */
 .directoryList { list-style: none; padding: 0; margin: 0; }
 .directoryRow { display: flex; align-items: center; min-width: 0; }
 .directoryRow .pageLink { flex: 1; min-width: 0; padding-left: 3px; }
+/* 可折叠项按钮与叶项占位共享 20px 列宽，保持各行标题对齐；焦点内描边不扩尺寸。 */
 .directoryToggle, .directorySpacer { flex: 0 0 20px; width: 20px; height: 26px; }
 .directoryToggle { display: grid; place-items: center; border: 0; border-radius: 4px; background: transparent; color: #87837c; cursor: pointer; }
 .directoryToggle:hover { background: #eae7e2; }

src/lib/canvas-core/coordinates.ts

@@ -2,6 +2,7 @@
  * 嵌套 canvas 的坐标换算：Transform 把一个 canvas 的局部空间映射到项目世界空间。
  * 统一采用平移、等比缩放和旋转，不处理 skew/非等比父变换。owner 改变时通过世界空间中转，
  * 保持节点外观和连线曲线位置；表现单位的 data 修正由结构/编辑规划器另行生成。
+ * 数学辅助函数依赖已校验的有限几何/正比例；它们不逐项代替 schema、registry 或可见性校验。
  */
 import type { Document, Geometry, Id, Json, Point } from './types.ts';
 import { ancestors } from './document.ts';
@@ -22,9 +23,10 @@ export function toWorld(transform: Transform, point: Point): Point { const value
 export function toLocal(transform: Transform, point: Point): Point { return rotate({ x: (point.x - transform.x) / transform.scale, y: (point.y - transform.y) / transform.scale }, -transform.rotation); }
 /** 将可识别的 JSON 对象视为字段表，空值/原始值/数组按空表处理，不修改源数据。 */
 const object = (value: Json | undefined) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
-/** 对已识别的 bezier-chain 换空间；未知路径原样返回，严格写入边界由 convertPath 把关。
+/** type/knots 可识别时逐点换空间；其它路径原样返回，不在本函数完整验证曲线形状。
  * knot.position 是位置，in/out 与首尾 control 是偏移向量，向量不能叠加平移。 */
 export function transformPath(path: Json, transform: Transform, inverse = false): Json {
+  // 直接调用可对部分字段做转换；实际需要换空间时，convertPath 会先检查支持的路径格式。
   const raw = object(path);
   if (raw.type !== 'bezier-chain' || !Array.isArray(raw.knots)) return path;
   /** 保留点的扩展字段；vector 模式把变换平移归零，仅施加旋转/比例。 */
@@ -42,13 +44,15 @@ export function transformPath(path: Json, transform: Transform, inverse = false)
 /** 合成父变换与分区入口几何，得到子 canvas 内容区原点/比例/旋转。
  * 24/36 是格式 1 的内容内边距，要乘 presentation.unitScale，和 renderer 的投影保持一致。 */
 export function childCanvasTransform(parent:Transform,geometry:Geometry,presentation:Json|undefined):Transform {
+  // unitScale 由专用读取器检查；contentScale 在这里仅按 number 且 >0 选择，有限性等约束依赖上游 schema。
   const data=object(presentation),units=unitScale(presentation),scale=(typeof data.contentScale==='number'&&data.contentScale>0?data.contentScale:1)*units;
   // 入口绕中心旋转，因此先把内容内边距写成相对中心偏移，再旋转并加回中心。
   const offset=rotate({x:24*units-geometry.width/2,y:36*units-geometry.height/2},geometry.rotation);
   const start=toWorld(parent,{x:geometry.x+geometry.width/2+offset.x,y:geometry.y+geometry.height/2+offset.y});
   return{...start,scale:parent.scale*scale,rotation:((parent.rotation+geometry.rotation)%360+360)%360};
 }
-/** 从根向目标逐级合成入口变换；ancestors 同时检查缺失父项与循环。 */
+/** 从根向目标逐级合成入口变换；ancestors 检查缺失父项与循环。
+ * 这里只要求每层入口存在且为 node，不检查组件是否已知/展开；可编辑性与可见性由上层决定。 */
 export function canvasTransform(document:Document,canvasId:Id):Transform {
   let result:Transform={...origin};
   for(const id of ancestors(document,canvasId).reverse()){
@@ -65,7 +69,8 @@ export function convertGeometry(geometry:Geometry,from:Transform,to:Transform):G
   const center=toLocal(to,toWorld(from,{x:geometry.x+geometry.width/2,y:geometry.y+geometry.height/2})),ratio=from.scale/to.scale,width=geometry.width*ratio,height=geometry.height*ratio;
   return{x:center.x-width/2,y:center.y-height/2,width,height,rotation:((geometry.rotation+from.rotation-to.rotation)%360+360)%360};
 }
-/** 严格曲线换空间：null/同变换无需改；不支持的路径拒绝，不擅自解释未知 payload。 */
+/** null/同变换先原样返回；只有实际需要换空间时才检查支持的曲线格式，不支持就拒绝。
+ * 两次转换分别完成旧局部→世界、世界→新局部；无须改变 knot ID 或曲线段拓扑。 */
 export function convertPath(path:Json,from:Transform,to:Transform):Json {
   if(path===null||sameTransform(from,to))return path;
   if(!connectionPathValid(path))throw fault('unsupported_coordinate_path');

src/lib/canvas-core/copy-paths.ts

@@ -1,6 +1,7 @@
 /**
  * 组件声明式引用路径的遍历器，供复制/解散等纯规划复用。
- * 只访问自有字段，不用字符串相似度猜 ID；这里 yield 可写 slot，调用者必须先复制数据再改。
+ * 普通路径段只访问自有字段，不用字符串相似度猜 ID；这里 yield 可写 slot，调用者必须先复制数据再改。
+ * path 应先经组件定义校验：本遍历器不重新禁止空路径或原型敏感键，数组 * 按下标位置枚举。
  */
 import type { Json } from './types.ts';
 import { fault } from './values.ts';
@@ -14,7 +15,7 @@ export function* copySlots(data: Json, path: readonly string[]): Generator<{pare
     const {value, depth} = work.pop()!, key = path[depth];
     if (key === '*') {
       if (!Array.isArray(value)) throw fault('invalid_copy_reference');
-      // 终端 * 直接枚举数组项位置；非终端 * 继续匹配下一路径段。
+      // 终端 * 直接枚举 0..length-1，不另用 hasOwn 检查空洞；非终端 * 继续匹配下一路径段。
       if (depth === path.length - 1) { for (let i = 0; i < value.length; i++) yield {parent: value as unknown as Record<string, Json>, key: String(i)}; }
       else for (let i = value.length - 1; i >= 0; i--) work.push({value: value[i], depth: depth + 1});
     } else if (value && typeof value === 'object' && Object.hasOwn(value, key)) {
@@ -23,7 +24,8 @@ export function* copySlots(data: Json, path: readonly string[]): Generator<{pare
     }
   }
 }
-/** 在 slot 上读取引用 ID；null 代表无引用，many 要求数组，每个 ID 必须非空字符串。 */
+/** 在 slot 上读取引用 ID；整个 slot 为 null 表示无引用，many 要求数组，每个 ID 必须非空字符串。
+ * many 数组里的 null 不等于无引用，会拒绝；many 与路径中的 * 是独立的两层展开规则。 */
 export function* copyReferenceIds(data: Json, ref: {path: readonly string[]; many?: boolean}): Generator<string> {
   for (const {parent, key} of copySlots(data, ref.path)) {
     const value = parent[key]; if (value === null) continue;

src/lib/canvas-core/creation-draft.ts

@@ -1,6 +1,7 @@
 /**
  * 同步事务内的大批创建优化。追加表用固定成员的 base+added 视图避免每新增一项都复制整表，
- * 累计 64 项后折叠为新 base。只用于尚未发布的 draft，提交前统一物化为标准文档表。
+ * 已有追加层达到 64 项时，下一次追加先折叠为新 base。只用于未发布 draft，提交前统一物化文档表。
+ * 输入表须已具固定成员；视图借用 base 和未变记录，不是任意可变 Map 的隔离器。
  */
 import {detachElementData} from './element-data.ts';
 import type {CanvasRecord,Change,Document,ElementRecord,Id} from './types.ts';
@@ -14,12 +15,14 @@ const overlays=new WeakMap<object,{base:ReadonlyMap<Id,unknown>;added:ReadonlyMa
 function append<T>(input:ReadonlyMap<Id,T>,id:Id,value:T):ReadonlyMap<Id,T>{
  if(input.has(id))throw fault('duplicate_identity',[id]);
  let previous=overlays.get(input) as {base:ReadonlyMap<Id,T>;added:ReadonlyMap<Id,T>}|undefined;
- // 控制覆盖层大小；到阈值后重建 base，而不是让链条随着事务长度无限加深。
+ // 当前 input 若含 64 个 added，本次先通过 readMap(input) 折叠，再以新 added 放入第 65 个；不是整个事务最多 64 项。
  if(previous&&previous.added.size>=64)previous=undefined;
+ // overlays 记录的是框架创建的视图身份；普通输入直接借用，只有已知旧 overlay 才需要折叠。
  const base=previous?.base??(overlays.has(input)?readMap(input):input),added=new Map(previous?.added);
  added.set(id,value);
  /** 迭代先 base 后 added，保持插入顺序；视图的 get/has 优先查 appended 成员。 */
  const entries=function*():Generator<[Id,T],undefined,unknown>{yield* base;yield* added;return undefined;};
+ // get 用 has 区分“added 中显式存 undefined”与缺失；迭代顺序始终 base 在前、追加成员在后。
  // keys/values/iterator 复用 entries；forEach 第三个参数仍是安全视图，不泄漏 added Map。
  const view:ReadonlyMap<Id,T>=Object.freeze({size:base.size+added.size,get:(key:Id)=>added.has(key)?added.get(key):base.get(key),has:(key:Id)=>added.has(key)||base.has(key),entries,
   *keys():Generator<Id,undefined,unknown>{for(const [key]of entries())yield key;return undefined;},*values():Generator<T,undefined,unknown>{for(const [,item]of entries())yield item;return undefined;},[Symbol.iterator]:entries,
@@ -29,14 +32,17 @@ function append<T>(input:ReadonlyMap<Id,T>,id:Id,value:T):ReadonlyMap<Id,T>{
 }
 /** Internal editor path: input tables already have fixed membership. */
 /** 仅接收 before=null 且 after 存在的创建变化，校验 JSON/ID 后捕获记录并追加相应表。
- * 整图依赖可在后续命令补齐，因此此处不提前做完整树/端点校验。 */
+ * 整图依赖可在后续命令补齐，因此此处不提前做完整树/端点校验。
+ * 本层只检查创建形状、JSON、ID 一致及活表重复；registry 支持与墓碑禁复用由 editor/最终校验负责。 */
 export function stageCreation(document:Document,change:Extract<Change,{kind:'canvas'|'element'}>):Document{
  if(change.before!==null||!change.after)throw fault('invalid_creation_draft');
  if(!validJson(change.after))throw fault(change.kind==='canvas'?'invalid_canvas':'invalid_element',[change.id]);
  if(change.after.id!==change.id)throw fault('identity_mismatch',[change.id]);
  const value=change.kind==='element'?detachElementData(change.after as ElementRecord):freeze(clone(change.after));
+ // 只替换被追加的表，另一表/墓碑沿用；新 Document 标记为 draft，旧视图不随本次 added 改变。
  const next=Object.freeze({...document,...(change.kind==='canvas'?{canvases:append(document.canvases,change.id,value as CanvasRecord)}:{elements:append(document.elements,change.id,value as ElementRecord)})});drafts.add(next);return next;
 }
-/** Only published documents use the core's owned table envelopes. */
-/** 只有已标记的 draft 需要通过空 changes 重新捕获表；普通文档原样复用。 */
+/** Materialize transaction-local append tables before publication. */
+/** 只有已标记 draft 通过空 changes 物化成工厂 envelope/readMap；其它文档原样返回。
+ * 不在这里校验 schema/树，也不把任何外来 Document 自动视为已校验或深度不可变。 */
 export const materializeCreations=(document:Document)=>drafts.has(document)?applyChanges(document,[]):document;

src/lib/canvas-core/creation-size-plan.ts

@@ -22,12 +22,14 @@ export function validateCreationSizeEffect(value: unknown): asserts value is Cre
  * Already-issued operation bodies are deliberately outside this function.
  */
 /** 仅原创建仍在 undo、目标仍活且未被用户缩放时，准备默认尺寸与历史修正。
- * 返回候选 document/history/changes；原输入始终不变，失败不留下半份历史。 */
+ * 返回候选 document/history/changes，不发布状态；输入须来自已捕获的不可变文档与历史。
+ * 这里按 geometry.resize 能力判定，不限定 componentId 必须是 image；图片授权条件由外层 grant 决定。 */
 export function planCreationSize(document: Document, history: HistoryState, registry: Registry,
   entryId: Id, target: Target, size: { readonly width: number; readonly height: number }) {
   /** 统一将失败绑定到目标 ID，便于调用方解释为何不能再自动调整。 */
   const fail = (code: string): never => { throw fault(code, [target.id]); };
   if (![size.width, size.height].every(value => Number.isFinite(value) && value > 0)) fail('invalid_creation_size');
+  // 创建项必须仍在已应用 undo 时间线上；已撤销到 redo、被淘汰或目标换代的尺寸结果不能采用。
   const index = history.undo.indexOf(entryId), entry = history.entries.get(entryId);
   const current = document.elements.get(target.id);
   if (index < 0 || !entry || current?.incarnation !== target.incarnation || current.structure !== 'node') fail('creation_size_target_changed');
@@ -40,7 +42,7 @@ export function planCreationSize(document: Document, history: HistoryState, regi
   const units = unitScale(created.data.presentation);
   const baseline = { width: created.geometry.width / units, height: created.geometry.height / units };
   const ratio = { width: size.width / baseline.width, height: size.height / baseline.height };
-  /** 同一生命周期的节点才属于本次自动尺寸修正对象。 */
+  /** 调用处已按 target.id 取记录，这里再限制 incarnation 与 node 结构；不单独比较元素 ID。 */
   const matches = (element: ElementRecord | undefined) => element?.incarnation === target.incarnation && element.structure === 'node';
   /** 比较宽高除 unitScale 后的视觉值，移动/换 owner 不等同于用户主动缩放。 */
   const unchanged = (element: ElementRecord | undefined) => matches(element) && element!.structure === 'node'
@@ -52,9 +54,11 @@ export function planCreationSize(document: Document, history: HistoryState, regi
   // Rewind on private roots. applyChanges intentionally preserves historical
   // incarnations here; this is inspection, not a user-visible delete/restore.
   let original = document;
-  // 从创建项起回退已应用历史，得到创建前私有基线；不产生用户可见的删除/恢复代次。
+  // 从创建项起回退全部已应用项，得到创建前私有基线；此处用 applyChanges 而非 planHistoryChanges，
+  // 因而允许检查途中存在历史代次/墓碑组合，不把它们作为最终文档发布。
   const applied = history.undo.slice(index);
   for (const id of [...applied].reverse()) original = applyChanges(original, invert(history.entries.get(id)!.changes));
+  // original 追踪旧时间线，amended 追踪修正后的时间线；inheriting 只在匹配创建之后开启。
   let amended = original, inheriting = false;
   const entries = new Map(history.entries);
   // 先按 undo 的正向顺序重建已应用项，再倒序遍历 redo 栈还原未来重做时间线。
@@ -63,11 +67,12 @@ export function planCreationSize(document: Document, history: HistoryState, regi
     const id = timeline[cursor], source = entries.get(id)!;
     const end = applyChanges(original, source.changes), isApplied = cursor < applied.length;
     if (isApplied && !unchanged(end.elements.get(target.id))) fail('creation_size_user_resized');
-    // A future explicit resize remains a resize to the user's chosen dimensions.
-    // Only its before value inherits the asynchronous default correction.
+    // A future resize preserves each dimension explicitly changed by the user.
+    // Its before value and unchanged dimensions may inherit the default correction.
     const futureResize = !isApplied && inheriting && matches(end.elements.get(target.id)) && !unchanged(end.elements.get(target.id));
     let resizeConsumed = false;
-    /** redo 中用户显式改过的维度停止继承默认比例；仅修正其 before，不改用户指定的 after。 */
+    /** redo 中按宽/高分别判断：被用户改过的维度将 ratio 置 1，保留其 after；
+     * before 重取修正时间线，未被用户改变的另一维仍可继承默认比例。每项最多消费一次。 */
     const preserveFutureResize = () => {
       if (!futureResize || resizeConsumed) return;
       const value = end.elements.get(target.id) as ElementRecord & { structure: 'node' };
@@ -76,9 +81,10 @@ export function planCreationSize(document: Document, history: HistoryState, regi
       resizeConsumed = true;
     };
     const changes: Change[] = [];
-    // 每条 next 都基于 amended 的实际 before 重建，保证修正后的连续历史仍条件匹配。
+    // 目标整记录/geometry 变化从 amended 重取 before；其它变化保留原条件，继续用 applyChanges 校验。
     for (const change of source.changes) {
       let next = change;
+      // 整记录变化也要重取真实 before；其它对象/字段沿用原变化，保证整条时间线仍按原次序检查。
       if (change.kind === 'element' && change.id === target.id) {
         const before = amended.elements.get(target.id) ?? null;
         const birth = id === entryId && change === creations[0];
@@ -98,6 +104,7 @@ export function planCreationSize(document: Document, history: HistoryState, regi
       amended = applyChanges(amended, [next]);
       changes.push(next);
     }
+    // 整项完成后再推进旧时间线；只有变化内容确实不同才替换 entries 中这一项，operationIds/标签保持。
     original = end;
     if (!equal(changes, source.changes)) entries.set(id, freeze({ ...source, changes }));
   }
@@ -112,10 +119,12 @@ export function planCreationSize(document: Document, history: HistoryState, regi
   ]);
   const nextDocument = applyChanges(document, changes);
   validateDocument(nextDocument, registry);
-  // 最后用组件自己的 resize handler 对照约束，自动尺寸不能绕过组件 min/max/aspect 政策。
+  // 调用已安装 resize handler，把其生成变化应用后的目标记录与直接候选比较；不一致就拒绝。
+  // 这能执行组件实际实现的限制，不凭 capability 名称宣称所有组件都有 min/max/aspect 政策。
   const handler = registry.handlers.get(current!.componentId)?.get('geometry.resize');
   const proposed = handler!({ element: current!, input: freeze({ patch: { width: after.width, height: after.height } }) });
   for (const change of proposed) if (change.target.id !== target.id || change.target.incarnation !== target.incarnation || change.field !== 'geometry') fail('invalid_handler_change');
   if (!equal(applyChanges(document, proposed).elements.get(target.id), nextDocument.elements.get(target.id))) fail('creation_size_constraint');
+  // 仅返回当前几何 changes，历史 entries 是整条修正时间线；两栈顺序沿用，不把上方 redo 检查变成实际重做。
   return Object.freeze({ document: nextDocument, changes, history: Object.freeze({ undo: history.undo, redo: history.redo, entries: readMap(entries) }) });
 }

src/lib/canvas-core/curve-hit.ts

@@ -1,6 +1,7 @@
 /**
  * 有限预算的三次曲线命中精判。先用控制点包围盒排除，再用弦线距离与平坦度误差判断；
- * 不能确定时用 de Casteljau 二分。预算/数值精度不足明确返回 possible，不能伪称已证明 miss。
+ * 不能确定时用 de Casteljau 二分。预算/数值精度不足明确保留可能命中，不能伪称已证明 miss。
+ * 上层须提供合法曲线/点、非负半径和有效预算，本函数没有独立参数校验或 registry 检查。
  */
 import type {Point} from './types.ts';
 import type {Cubic} from './geometry.ts';
@@ -16,12 +17,18 @@ function split([a,b,c,d]:Cubic):[Cubic,Cubic]{const ab=mid(a,b),bc=mid(b,c),cd=m
  * maxSteps 限总工作，maxDepth 限细分深度，error 控制可接受平坦度；stack 用显式 DFS。
  * 每轮：包围盒排除→near±flat 判定→足够平/深度已满则记 possible→否则入栈左右子曲线。
  * near 是到端点弦线段距离，flat 包括两控制点到该弦的偏差及 roundoff。
- * 剩余 stack 非空表示总预算耗尽，仍可能有未检查的命中区域。 */
+ * 剩余 stack 非空表示总预算耗尽，仍可能有未检查的命中区域。
+ * certainty 只在 hit=true 时区分 confirmed/possible；hit=false 的正常返回也固定带 possible，不是“可能没命中”的三态枚举。 */
 export function hitCubic(curve:Cubic,point:Point,radius:number,options:{error:number;maxDepth:number;maxSteps:number}){
+ // 栈中保存尚未证明可排除的子曲线，steps 按实际取出的子曲线计数；possible 记住已停止细分的模糊区域。
  const stack:{curve:Cubic;depth:number}[]=[{curve,depth:0}];let steps=0,possible=false,estimate=Infinity,error=0;
  while(stack.length&&steps<options.maxSteps){const item=stack.pop()!;steps++;const xs=item.curve.map(p=>p.x),ys=item.curve.map(p=>p.y),dx=Math.max(0,Math.min(...xs)-point.x,point.x-Math.max(...xs)),dy=Math.max(0,Math.min(...ys)-point.y,point.y-Math.max(...ys));if(Math.hypot(dx,dy)>radius)continue;
+  // 弦距离 near 与 flat 给出保守区间：near-flat 超半径可排除，near+flat 在半径内可确认。
+  // 数值非有限时直接返回 possible 且 budget=true；该标志此时不只是“栈还有工作”的含义。
   const[a,b,c,d]=item.curve,roundoff=Number.EPSILON*64*Math.max(1,Math.abs(point.x),Math.abs(point.y),...xs.map(Math.abs),...ys.map(Math.abs)),flat=Math.max(distance(b,a,d),distance(c,a,d))+roundoff,near=distance(point,a,d);if(!Number.isFinite(flat)||!Number.isFinite(near))return{hit:true,certainty:'possible' as const,steps,distance:Infinity,error:Infinity,budget:true};if(near-flat>radius)continue;if(near+flat<=radius)return{hit:true,certainty:'confirmed' as const,steps,distance:near,error:flat,budget:false};
+  // 达到平坦误差或深度阈值只保留 possible，budget 可仍为 false；继续二分时先压右再压左，按左优先 DFS。
   if(flat<=options.error||item.depth>=options.maxDepth){possible=true;if(near<estimate){estimate=near;error=flat;}continue;}const[left,right]=split(item.curve);stack.push({curve:right,depth:item.depth+1},{curve:left,depth:item.depth+1});
  }
+ // estimate/error 来自已记住的最小 near 模糊区，不是所有曲线的精确最近距离；全被排除时 estimate 仍是 Infinity。
  return{hit:possible||stack.length>0,certainty:'possible' as const,steps,distance:estimate,error,budget:stack.length>0};
 }

src/lib/canvas-core/data-containers.ts

@@ -4,12 +4,14 @@
  */
 // Private shape provenance: values may still be mutable and require capture.
 // Always copy; external Object.freeze is never accepted as ownership evidence.
+// WeakSet 以新容器身份为键，不按内容相等判断；容器不再被外部引用时，标记不会单独阻止回收。
 const owned = new WeakSet<object>();
 /** 消费 iterable 得到新数组并浅冻结；不会冻结数组中的业务值。 */
 export function dataArray<T>(values: Iterable<T>): readonly T[] {
   const result = Object.freeze(Array.from(values)); owned.add(result); return result;
 }
-/** 浅复制对象的可枚举自有属性再冻结外壳；不是任意对象的深复制器。 */
+/** 浅复制对象的可枚举自有属性再冻结外壳；不是任意对象的深复制器。
+ * 对象展开会读取 getter 并保留嵌套值引用，也不保留原对象原型或属性描述符。 */
 export function dataRecord<T extends object>(value: T): Readonly<T> {
   const result = Object.freeze({...value}); owned.add(result); return result;
 }

src/lib/canvas-core/dissolve.ts

@@ -12,7 +12,8 @@ import {repairConnectionOwners} from './structure.ts';
 import {clone,equal,fault,freeze} from './values.ts';
 
 /** Remove an owning canvas, retaining its entry and promoting only direct members. */
-/** 验证 canvas/入口生命周期，规划成员和引用转换；根不能解散，任何不支持路径整体拒绝。 */
+/** 验证 canvas/入口生命周期并规划成员/引用转换；根不能解散，必需转换遇到不支持能力或格式时抛错。
+ * 源应是有效不可变文档；本函数不执行最终 validateDocument，也不调用宿主 policy 或直接发布。 */
 export function planDissolveCanvas(document:Document,registry:Registry,canvasId:Id,entryTarget:Target):{readonly changes:readonly Change[];readonly commands:readonly Command[]}{
   const canvas=document.canvases.get(canvasId);if(!canvas)throw fault('canvas_not_loaded',[canvasId]);
   if(!canvas.parent)throw fault('cannot_dissolve_root',[canvasId]);
@@ -23,7 +24,7 @@ export function planDissolveCanvas(document:Document,registry:Registry,canvasId:
   for(const element of document.elements.values())if(element.ownerCanvasId===canvasId&&element.structure==='node'){
     if(!registry.supports(element,'geometry.move'))throw fault('unsupported_capability',[element.id,'geometry.move']);
     const target={id:element.id,incarnation:element.incarnation},geometry=convertGeometry(element.geometry,from,to),presentation=withUnitScale(element.data.presentation,unitScale(element.data.presentation)*from.scale/to.scale);
-    // 即使最终用 changes 原子提交，也要向 editor 暴露逐成员 policy 检查，防止入口权限越权。
+    // commands 仅给 editor 逐成员做 policy 检查，不在此执行 element.move handler；几何转换直接由上面的坐标数学生成。
     commands.push({type:'element.move',target,canvasId:parent});
     changes.push({kind:'field',target,field:'ownerCanvasId',before:canvasId,after:parent});
     if(!equal(geometry,element.geometry))changes.push({kind:'field',target,field:'geometry',before:element.geometry,after:geometry});
@@ -35,7 +36,8 @@ export function planDissolveCanvas(document:Document,registry:Registry,canvasId:
   // 在私有候选文档上计算边的新公共上级，并把曲线从旧 owner 空间一并转换。
   const promoted=applyChanges(document,changes);changes.push(...repairConnectionOwners(document,promoted));
   // Only declared canvas references have meaning here. Opaque payloads are retained.
-  // 只解释已知组件明确声明的 canvas 引用；opaque payload 和普通字面 ID 文本保留。
+  // 扫描整个 promoted 文档中已知组件声明的 canvas 引用，因此子树外的引用也可能需要修正。
+  // opaque payload 与未声明的普通字面 ID 保留；引用路径复用 copy schema，但这里不执行复制的 external 策略。
   for(const element of promoted.elements.values()){
     if(registry.resolve(element)!=='known')continue;
     const references=registry.components.get(element.componentId)?.copy?.references.filter(reference=>reference.target==='canvas')??[];
@@ -48,12 +50,14 @@ export function planDissolveCanvas(document:Document,registry:Registry,canvasId:
       const map=(value:Json):Json=>{if(typeof value!=='string'||!value)throw fault('invalid_copy_reference',[element.id]);return value===canvasId?parent:value;};
       slot.parent[slot.key]=reference.many?(value as Json[]).map(map):map(value);
     }
-    // 仅产生实际改变的顶层 data 字段，并要求 content.edit 能力/宿主 policy 通过。
+    // 仅产生实际改变的顶层 data 字段；此处检查 content.edit 已安装，宿主 policy 由返回 commands 交给 editor 重查。
+    // 不调用 content.edit handler 生成变化，最终 schema/关系检查仍由事务发布路径执行。
     for(const key of Object.keys(data))if(!equal(data[key],element.data[key])){
       if(!registry.supports(element,'content.edit'))throw fault('unsupported_capability',[element.id,'content.edit']);
       changes.push({kind:'field',target:{id:element.id,incarnation:element.incarnation},field:`data.${key}`,before:element.data[key],after:data[key]});
       commands.push({type:'element.data',target:{id:element.id,incarnation:element.incarnation},patch:{[key]:data[key]}});
     }
   }
+  // 保留原入口元素与边 ID；只移除 canvas 记录，不用 removalChanges 的子树删除语义。
   return freeze({changes,commands});
 }

src/lib/canvas-core/document.ts

@@ -16,7 +16,8 @@ function documentEnvelope(document:Document):Document{const value=Object.freeze(
 export const isFactoryDocument=(document:Document)=>factoryDocuments.has(document);
 
 /** 捕获输入记录、拒绝同一表内重复 ID，并脱离调用者的可变数据。
- * 不在此处验证整棵树或所有跨记录引用；完整发布前仍需 validateDocument。 */
+ * 不在此处验证整棵树、组件 schema 或所有跨记录引用；完整发布前仍需 validateDocument。
+ * canvas 总是复制冻结，element 可复用元素捕获模块已持有的记录；墓碑复制表成员，元素固有证明只省去重复形状遍历。 */
 export function createDocument(projectId: Id, canvases: readonly CanvasRecord[], elements: readonly ElementRecord[] = [], tombstones: ReadonlyMap<Id, number> = new Map()): Document {
   for (const element of elements) { const id = element.id; if (!staticElementProofs.has(element)&&!validJson(element)) throw fault('invalid_element', [id]); }
   for (const canvas of canvases) if (!validJson(canvas)) throw fault('invalid_canvas');
@@ -61,14 +62,19 @@ const staticElementProofs=new WeakSet<object>();
 /** 校验单条记录的基础形状、墓碑代次和已知组件数据。
  * staticElementProofs 仅缓存已捕获记录的固有形状；墓碑和 registry 相关检查每次仍执行。 */
 export function validateElementRecord(element: ElementRecord, registry: Registry, tombstones: ReadonlyMap<Id,number> = new Map(), componentData = true): void {
+  // 静态证明仅随不可变记录身份复用，不能因浅冻结或一个文档 envelope 标记就跳过校验。
   const proven=!!element&&staticElementProofs.has(element);
   if (!proven&&(!element || !validJson(element) || typeof element.id !== 'string' || !element.id || typeof element.ownerCanvasId !== 'string' || !element.ownerCanvasId || typeof element.componentId !== 'string' || !element.componentId || !['node','connection'].includes(element.structure) || !Number.isSafeInteger(element.incarnation) || element.incarnation < 1 || !Number.isSafeInteger(element.dataVersion) || element.dataVersion < 1 || !element.data || typeof element.data !== 'object' || Array.isArray(element.data) || !validJson(element.data))) throw fault('invalid_element', [element?.id]);
+  // 墓碑属于当前文档上下文，即使同一记录以前通过过形状校验，也要重新核对已死亡代次。
   const dead=tombstones.get(element.id);if(dead!==undefined&&element.incarnation<=dead)throw fault('stale_incarnation',[element.id]);
+  // 只有精确支持的组件版本进入 schema 检查；未知组件/不支持版本仍须通过通用形状约束，不在这里解释其 payload。
   const definition=registry.components.get(element.componentId);
   if(componentData&&registry.resolve(element)==='known'&&(!definition||definition.structure!==element.structure||!componentDataValid(element,definition)))throw fault('invalid_component_data',[element.id]);
+  // 命中固有证明只能略过下方几何/端点形状遍历，不能略过上方墓碑与本次启用的 schema 检查。
   if(proven)return;
   if(element.structure==='node'){if(!geometryValid(element.geometry))throw fault('invalid_geometry',[element.id]);}
   else if(!element.source||!element.target||typeof element.source.elementId!=='string'||!element.source.elementId||typeof element.target.elementId!=='string'||!element.target.elementId||[element.source,element.target].some(endpoint=>endpoint.portId!==undefined&&(typeof endpoint.portId!=='string'||!endpoint.portId))||!validJson(element.path))throw fault('invalid_endpoint',[element.id]);
+  // 拓扑规划可 componentData=false；此时仍可记固有证明，但以后启用 schema 的调用依然会重查 data。
   if(hasOwnedElementData(element))staticElementProofs.add(element);
 }
 
@@ -101,6 +107,7 @@ function validateElementInDocument(document:Document,element:ElementRecord,regis
 function* validateDocumentChecks(document:Document,registry:Registry,componentData:boolean):Generator<void,void>{
   if(!document.canvases.size)throw fault('missing_root');
   for(const[id,incarnation]of document.tombstones){yield;validateTombstone(id,incarnation);}
+  // 一次遍历累计入口占用和根数；必须继续到最后，才能得到根数及所有元素的完整结论。
   const entries=new Set<Id>();let roots=0;
   for(const canvas of document.canvases.values()){yield;roots+=validateCanvasInDocument(document,canvas,entries);}
   if(roots!==1)throw fault('invalid_roots');
@@ -111,7 +118,8 @@ function* validateDocumentChecks(document:Document,registry:Registry,componentDa
 export function* validateDocumentTopologySteps(document:Document,registry:Registry):Generator<void,void>{yield* validateDocumentChecks(document,registry,false);}
 /** 含组件 payload 的完整分片校验；必须迭代到结束才证明整份文档通过。 */
 export function* validateDocumentSteps(document:Document,registry:Registry):Generator<void,void>{yield* validateDocumentChecks(document,registry,true);}
-/** 同步完整校验，要求恰好一个根，所有拥有关系、端点和组件数据均合法。 */
+/** 同步走完整文档检查：要求一个根，检查拥有关系、入口、节点端点及连线共同 owner。
+ * 已支持的精确组件版本检查 data schema；未知/不支持版本按通用记录规则保留，不冒称已理解其 payload。 */
 export function validateDocument(document:Document,registry:Registry):void{
   if(!document.canvases.size)throw fault('missing_root');
   for(const[id,incarnation]of document.tombstones)validateTombstone(id,incarnation);
@@ -120,21 +128,24 @@ export function validateDocument(document:Document,registry:Registry):void{
   if(roots!==1)throw fault('invalid_roots');
   for(const element of document.elements.values())validateElementInDocument(document,element,registry,true);
 }
-/** 一批有序修改及其允许的 canvas 上下文；回放不能跨越已冻结的操作范围。 */
+/** 一批有序修改及可选 canvas 上下文；当前执行器用它检查 field 目标的 owner。
+ * 这不是覆盖所有 change 种类的授权器；整元素/树修改还需调用方规划、权限及发布前校验。 */
 export type ReplayChangeBatch = {readonly changes:readonly Change[];readonly canvasIds?:readonly Id[]};
-/** 在私有表副本中应用一批变化；默认校验 before 条件，失败不会修改输入文档。 */
+/** 在已捕获的不可变文档上，以私有表副本应用变化；默认校验 before 条件。
+ * 未改记录沿用原引用，不是任意外部 Document 的深隔离入口；修改记录的 freeze 也可能触及共享嵌套值。 */
 export function applyChanges(document: Document, changes: readonly Change[], conditional = true): Document {
   return applyChangeBatches(document,[{changes}],conditional,false);
 }
 /** Ordered conditional replay against one private draft; no intermediate document escapes. */
-/** 顺序回放多批变化，已经满足的 after 可跳过，但仍检查目标的 scope。 */
+/** 顺序回放多批变化，已经满足的 after 可跳过；field 变化在跳过前仍检查当前 owner 范围。
+ * 批次未提供 canvasIds 或提供空数组时，这一局部 owner 范围检查不启用。 */
 export function replayChanges(document:Document,batches:Iterable<ReplayChangeBatch>):Document {
   return applyChangeBatches(document,batches,true,true);
 }
 /** 三类变化共用的执行器：field 改字段、element 增删元素、canvas 改树记录。
  * 仅在全部循环成功后返回冻结 envelope，不泄漏半成品；此处不做整图合法性校验。 */
 function applyChangeBatches(document:Document,batches:Iterable<ReplayChangeBatch>,conditional:boolean,replay:boolean):Document {
-  // 复制表成员而复用未改记录；出错时丢弃这些私有 Map，输入快照保持不变。
+  // 复制表成员而复用未改记录；失败不返回私有 Map。对有效不可变输入，不会发布或改写原快照。
   const elements = new Map(document.elements), canvases = new Map(document.canvases), tombstones = new Map(document.tombstones);
   for (const batch of batches) for (const change of batch.changes) {
     if(replay){
@@ -158,7 +169,8 @@ function applyChangeBatches(document:Document,batches:Iterable<ReplayChangeBatch
         if (change.afterPresent === false) delete data[dataKey]; else data[dataKey] = clone(change.after);
         elements.set(element.id, freeze({ ...element, data }));
       } else elements.set(element.id, freeze({ ...element, [change.field]: clone(change.after) }) as ElementRecord);
-    // 整元素修改必须匹配 before；删除同时保留墓碑，使旧 incarnation 永远不能复活。
+    // 整元素修改在 conditional=true 时匹配 before；删除只记录已死亡的最大代次。
+    // 此执行器不直接以墓碑拒绝后续插入，发布前 validateElementRecord/validateDocument 才拦截旧代次。
     } else if (change.kind === 'element') {
       if (conditional && !equal(elements.get(change.id) || null, change.before)) throw fault('element_conflict', [change.id]);
       if (change.after) {
@@ -184,6 +196,7 @@ function applyChangeBatches(document:Document,batches:Iterable<ReplayChangeBatch
 }
 /** 检测回放目标效果是否已经存在；字段目标必须仍是同一个 incarnation 才可视为满足。 */
 function changeSatisfied(elements:ReadonlyMap<Id,ElementRecord>,canvases:ReadonlyMap<Id,CanvasRecord>,change:Change):boolean {
+  // canvas/element 使用整记录 after 比较；删除后的缺失等同于 after:null，重复删除可跳过。
   if(change.kind==='canvas')return equal(canvases.get(change.id)??null,change.after);
   if(change.kind==='element')return equal(elements.get(change.id)??null,change.after);
   const element=elements.get(change.target.id);

src/lib/canvas-core/duplicate-checkpoint.ts

@@ -2,6 +2,7 @@
  * 可暂停/恢复的深复制准备状态机。检查点保存 ID、阶段、游标、DFS stack 和稳定映射，
  * 不保存元素 payload 的第二份副本；输出记录是由源与映射确定性重建的缓存。
  * 每次 step 只推进有限语义工作，但持久源校验、分片调度、checkpoint 保存和渐进加入由 runtime 负责。
+ * 构造器仍同步展开源表并校验保存状态，step 也没有按字节/毫秒强制切断单记录转换。
  */
 import {detachJsonData} from './json-data.ts';
 import type { CanvasRecord, Change, Document, ElementRecord, Id, Point, Registry, Target } from './types.ts';
@@ -22,7 +23,8 @@ type Immutable<T>=T extends object?{readonly [K in keyof T]:Immutable<T[K]>}:T;
 export type DuplicateCheckpoint=Immutable<MutableCheckpoint>;
 /** 形状辅助检查：数组成员必须是非空字符串；是否存在/重复由后续检查负责。 */
 const ids=(value:unknown):value is Id[]=>Array.isArray(value)&&value.every(id=>typeof id==='string'&&!!id);
-/** 校验外部检查点格式、阶段/计数/去重与前缀边界；与实际源的一致性在工厂中进一步核验。 */
+/** 检查 DTO 中明确列出的格式、阶段/计数、去重与前缀边界；不是按源重新推导整个已保存执行轨迹。
+ * 与实际源的部分成员/映射一致性在工厂核验；可信持久记录与 token 来源由 runtime 边界保证。 */
 export function validateDuplicateCheckpoint(value:DuplicateCheckpoint):void{
   if(!value||!validJson(value)||value.version!==1)throw fault('copy_checkpoint_interpreter_unavailable');
   if(![value.projectId,value.sourceToken,value.schemaToken].every(id=>typeof id==='string'&&!!id)||!phases.includes(value.phase)||!Number.isSafeInteger(value.cursor)||value.cursor<(value.phase==='seed'?-1:0)||![value.steps,value.emitted,value.emittedEdges].every(n=>Number.isSafeInteger(n)&&n>=0)||!Array.isArray(value.selection)||!value.selection.length||value.selection.some(t=>!t||typeof t.id!=='string'||!t.id||!Number.isSafeInteger(t.incarnation)||t.incarnation<1)||!value.offset||![value.offset.x,value.offset.y].every(Number.isFinite))throw fault('invalid_copy_checkpoint');
@@ -33,7 +35,8 @@ export function validateDuplicateCheckpoint(value:DuplicateCheckpoint):void{
   if(!Array.isArray(value.members)||value.members.some(pair=>!Array.isArray(pair)||pair.length!==2||typeof pair[0]!=='string'||!pair[0]||!ids(pair[1]))||new Set(value.members.map(pair=>pair[0])).size!==value.members.length||value.emitted>value.order.length||value.emittedEdges>value.edges.length||value.emittedEdges>0&&value.emitted!==value.order.length||value.expanding&&(typeof value.expanding.canvas!=='string'||!value.expanding.canvas||!Number.isSafeInteger(value.expanding.index)||value.expanding.index< -1))throw fault('invalid_copy_checkpoint');
 }
 /** 创建或恢复解释器；绑定 project/sourceToken/schemaToken/选区/偏移/预留映射，任一不符拒绝续跑。
- * token 的真实源摘要/定义签名由调用方提供并验证，这里不读取 Blob 或计算 SHA。 */
+ * token 的真实源摘要/定义签名由调用方提供并验证，这里只比较字符串，不读取 Blob 或计算 SHA。
+ * 绑定匹配不等于任意外来检查点已获防篡改证明；范围/阶段状态应来自可信恢复记录。 */
 export function createDuplicatePlanner(document:Document,registry:Registry,selection:readonly Target[],options:DuplicateOptions,binding:{sourceToken:string;schemaToken:string;checkpoint?:DuplicateCheckpoint;topologyOnly?:boolean}){
   const offset=options.worldOffset??{x:32,y:32},idFactory=options.createId,suppliedMapping=options.mapping?freeze(clone(options.mapping)):undefined;
   // 从检查点复制出私有可变 state，旧 checkpoint 保持不变；新任务从 selection 开始。
@@ -56,7 +59,8 @@ export function createDuplicatePlanner(document:Document,registry:Registry,selec
   const supplied=suppliedMapping?[...Object.keys(suppliedMapping.elements).map(id=>({id,kind:'element' as const})),...Object.keys(suppliedMapping.canvases).map(id=>({id,kind:'canvas' as const}))]:[];
   // 这些 Map 是派生输出缓存，overlay 内部可读其增长，不作为第二份发布文档。
   const outputElements=new Map<Id,ElementRecord>(),outputCanvases=new Map<Id,CanvasRecord>(),output=duplicateOverlay(document,outputElements,outputCanvases),changes:Change[]=[];
-  // 源校验每次重开重新执行；topologyOnly 仅用于明确的结构源，最终输出仍执行完整数据校验。
+  // 源校验每次重开重新执行；topologyOnly 跳过源的组件 payload schema。
+  // 本解释器继续到 result 时校验源+副本完整输出；若 runtime 在 ready 接管逐记录生成，则由那条消费路径完成后续校验。
   let treeCache=0,edgeCache=0,sourceChecks:Generator<void>|undefined=(binding.topologyOnly?validateDocumentTopologySteps:validateDocumentSteps)(document,registry),outputChecks:Generator<void>|undefined,validated=false;
   /** 切换解释阶段并重置/指定该阶段 cursor，不改稳定 ID 或输出前缀。 */
   const phase=(next:DuplicateCheckpoint['phase'],cursor=0)=>{state.phase=next;state.cursor=cursor;};
@@ -69,7 +73,8 @@ export function createDuplicatePlanner(document:Document,registry:Registry,selec
   /** 只为尚未分配的源项取新 ID；优先宿主预留值，used 同时覆盖源、墓碑与全部新值。 */
   function allocate(id:Id,kind:'elements'|'canvases'){const map=suppliedMapping?.[kind],value=map&&Object.hasOwn(map,id)?map[id]:idFactory();if(typeof value!=='string'||!value||used.has(value))throw fault('duplicate_identity',[value]);used.add(value);return value;}
   return Object.freeze({
-    /** 源已校验且刚到 emit，范围/映射固定，可以交给运行时逐记录转换，不要求完整计划已生成。 */
+    /** 源检查迭代已结束、阶段刚到 emit 且 emitted=0 时可接管范围/映射；不是完整计划已生成或已加入画布。
+     * topologyOnly 下“源检查结束”仍只证明拓扑路径通过，不证明所有组件 payload schema。 */
     ready():boolean{return !sourceChecks&&state.phase==='emit'&&state.emitted===0;},
     /** 返回阶段、语义 steps 和已分配数；不冒称解析/加入/网络已完成。 */
     progress(){return Object.freeze({phase:state.phase,steps:state.steps,allocated:state.elementIds.length+state.canvasIds.length});},
@@ -98,7 +103,8 @@ export function createDuplicatePlanner(document:Document,registry:Registry,selec
           if(task.kind==='canvas'){if(canvases.has(task.id))break;canvases.add(task.id);state.canvases.push(task.id);state.order.push(task);state.expanding={canvas:task.id,index:(members.get(task.id)?.length??0)-1};}
           else{if(copied.has(task.id))break;copied.add(task.id);state.copied.push(task.id);state.order.push(task);const child=children.get(task.id);if(child)state.work.push({kind:'canvas',id:child});}break;
         }
-        // 扫描上级入边与范围内边；随后 element/canvas 分配都把新 ID 写回 state，恢复可重用。
+        // 与同步规划器相同：显式选边、复制 canvas 的边及指向复制节点的入边；只有源端被复制不足以自动带上出边。
+        // 随后 element/canvas 分配都把新 ID 写回 state，恢复重用已有分配，不为同一前缀再造身份。
         case 'edges':if(state.cursor<sourceElements.length){const record=sourceElements[state.cursor++];if(record.structure==='connection'&&(selected.has(record.id)||canvases.has(record.ownerCanvasId)||copied.has(record.target.elementId))){state.edges.push(record.id);copied.add(record.id);state.copied.push(record.id);}}else phase('allocate-elements');break;
         case 'allocate-elements':if(state.cursor<state.copied.length){const id=state.copied[state.cursor++],value=allocate(id,'elements');elementIds.set(id,value);state.elementIds.push([id,value]);}else phase('allocate-canvases');break;
         case 'allocate-canvases':if(state.cursor<state.canvases.length){const id=state.canvases[state.cursor++],value=allocate(id,'canvases');canvasIds.set(id,value);state.canvasIds.push([id,value]);}else phase('mapping');break;
@@ -110,7 +116,8 @@ export function createDuplicatePlanner(document:Document,registry:Registry,selec
       // 每次状态机工作/阶段切换单调计数；step 的 wall time 和 yield 时机由宿主软预算决定。
       state.steps++;return false;
     },
-    /** 仅 done 且本轮最终校验成功后返回完整冻结计划；不能把未完成缓存当成可提交计划。 */
+    /** 仅 done 且本轮最终校验成功后返回完整冻结计划；不能把未完成缓存当成可提交计划。
+     * 返回的是准备 changes，不是 editor 提交/持久化/服务端确认结果；调用 result 也不会发网络请求。 */
     result():DuplicatePlan{if(!validated||state.phase!=='done')throw fault('copy_plan_not_ready');return freeze({version:1,roots:state.roots.map(id=>elementIds.get(id)!),elementIds:Object.fromEntries(elementIds),canvasIds:Object.fromEntries(canvasIds),changes:[...changes]});},
   });
 }

src/lib/canvas-core/duplicate.ts

@@ -2,6 +2,7 @@
  * 完整快照上的深复制纯规划：先确定范围和稳定 ID 映射，再生成节点/canvas，最后生成边。
  * 同时选分区入口和其内部节点时只复制一次；原上级 C→F 保留，新增边可连接原 C 与新 F′。
  * 这里只返回计划，不改 editor、不上传图片、不启动生成；runtime 负责调度、持久源和逐批加入。
+ * 源须在规划期间保持不可变；资源 ID 沿 data/copy 声明处理，不在这里复制文件字节或创建资源绑定。
  */
 import type { CanvasRecord, Change, Data, Document, ElementRecord, Id, Json, Point, Registry, Target } from './types.ts';
 import { copySlots } from './copy-paths.ts';
@@ -20,6 +21,7 @@ export type DuplicateOptions = { readonly createId: () => Id; readonly worldOffs
 export function remapCopyData(element: ElementRecord, registry: Registry, elements: ReadonlyMap<Id, Id>, canvases: ReadonlyMap<Id, Id>, document: Document): Data {
   const definition = registry.components.get(element.componentId), schema = definition?.copy;
   if (registry.resolve(element) !== 'known' || !schema) throw fault('copy_schema_unavailable', [element.id]);
+  // data 完整 JSON 复制后再改声明路径；未声明为引用的字符串（即使看起来像 ID）原样保留。
   const data = clone(element.data) as Record<string, Json>;
   for (const ref of schema.references) {
     for (const slot of copySlots(data, ref.path)) {
@@ -37,13 +39,15 @@ export function remapCopyData(element: ElementRecord, registry: Registry, elemen
       slot.parent[slot.key] = ref.many ? (value as Json[]).map(mapped) : mapped(value);
     }
   }
-  // omit 删除对象字段，拒绝删除数组下标造成稀疏数据；生成任务状态通过声明省略，不复制成新任务。
+  // omit 只删除声明的对象字段，数组下标不能直接删成空洞；是否清除任务状态取决于该组件 copy.omit，
+  // 规划器本身不识别所有插件的任务字段，也不把复制出的配置当成启动生成命令。
   for (const path of schema.omit) for (const slot of copySlots(data, path)) { if (Array.isArray(slot.parent)) throw fault('invalid_copy_omit', [element.id]); delete slot.parent[slot.key]; }
   return data;
 }
 
 /** Pure, complete-snapshot planning. Runtime owns time slicing, durable source/mapping and partial progress. */
-/** 分步迭代器：yield 给调用者调度机会，本身不 await、不落盘；耗尽后才返回完整已校验计划。 */
+/** 分步迭代器：yield 给调用者调度机会，本身不 await、不落盘；耗尽后才返回完整已校验计划。
+ * yield 点不是字节/耗时硬上限，单条记录的 clone、引用转换或祖先遍历仍可能较重。 */
 export function* planDuplicateSteps(document: Document, registry: Registry, selection: readonly Target[], options: DuplicateOptions): Generator<void, DuplicatePlan> {
   yield* validateDocumentSteps(document, registry);
   const offset = options.worldOffset ?? { x: 32, y: 32 };
@@ -78,6 +82,7 @@ export function* planDuplicateSteps(document: Document, registry: Registry, sele
     }
   }
   // 边另外扫描：显式选中、属于复制 canvas、或指向复制节点的入边均纳入，源端可仍指向原上级节点。
+  // 仅 source 被复制、target 在外部的出边，不因 source 在范围内就自动纳入；显式选中等其它条件仍可纳入。
   const edges: ElementRecord[] = [];
   for (const element of document.elements.values()) { yield; if (element.structure === 'connection' && (selected.has(element.id) || copiedCanvases.has(element.ownerCanvasId) || copied.has(element.target.elementId))) { edges.push(element); copied.add(element.id); } }
   // ID 分配前先保留源元素/canvas/墓碑全部 ID；同一 used 集合还防止两种新 ID 互撞。
@@ -124,6 +129,7 @@ export function* planDuplicateSteps(document: Document, registry: Registry, sele
 /** 共享确定性转换器：canvas 改 parent/entry 映射，节点改身份/owner/data 与根级偏移。
  * 同步及 checkpoint planner 都使用这里，避免两套复制产品规则。 */
 export function duplicateTreeChange(document:Document,registry:Registry,kind:'element'|'canvas',record:ElementRecord|CanvasRecord,elementIds:ReadonlyMap<Id,Id>,canvasIds:ReadonlyMap<Id,Id>,copiedCanvases:ReadonlySet<Id>,offset:Point):Exclude<Change,{kind:'field'}>{
+    // 调用方须提供已固定且覆盖范围的映射；此转换器不自行分配缺失 ID，canvas 分支依赖非空 parent、只供子 canvas 使用。
     if (kind === 'canvas') {
       const canvas=record as CanvasRecord,parent=canvas.parent!;
       const after = { ...clone(canvas), id: canvasIds.get(canvas.id)!, parent: { ...parent, canvasId: canvasIds.get(parent.canvasId) ?? parent.canvasId, entryElementId: elementIds.get(parent.entryElementId)! } };
@@ -140,9 +146,11 @@ export function duplicateTreeChange(document:Document,registry:Registry,kind:'el
       return { kind: 'element', id: after.id, before: null, after };
     }
 }
-/** 映射边端点（外部端点沿用原 ID），按新端点算共同 owner，转换曲线后创建新 ID/incarnation=1。 */
+/** 映射边端点（外部端点沿用原 ID），按新端点算共同 owner，转换曲线后创建新 ID/incarnation=1。
+ * 端点结构与组件定义的 copy.references 是两套路径：前者在此映射，后者交给 remapCopyData。 */
 export function duplicateEdgeChange(document:Document,registry:Registry,edge:ElementRecord,elementIds:ReadonlyMap<Id,Id>,canvasIds:ReadonlyMap<Id,Id>,nodes:Document):Extract<Change,{kind:'element'}>{
     if (edge.structure !== 'connection') throw fault('invalid_copy_endpoint');
+    // 与 convertPath 的同变换早返回不同，这里即使 owner 空间不变，也先要求复制支持该曲线格式。
     if (!connectionPathValid(edge.path)) throw fault('unsupported_copy_path', [edge.id]);
     const source = { ...edge.source, elementId: elementIds.get(edge.source.elementId) ?? edge.source.elementId }, target = { ...edge.target, elementId: elementIds.get(edge.target.elementId) ?? edge.target.elementId };
     const owner = commonCanvas(nodes, nodes.elements.get(source.elementId)!.ownerCanvasId, nodes.elements.get(target.elementId)!.ownerCanvasId), transform = canvasTransform(nodes, owner);
@@ -155,7 +163,8 @@ export function duplicateEdgeChange(document:Document,registry:Registry,edge:Ele
         const from = toWorld(canvasTransform(document, a.ownerCanvasId), { x: a.geometry.x + a.geometry.width / 2, y: a.geometry.y + a.geometry.height / 2 }), to = toWorld(canvasTransform(nodes, b.ownerCanvasId), { x: b.geometry.x + b.geometry.width / 2, y: b.geometry.y + b.geometry.height / 2 });
         return { x: to.x - from.x, y: to.y - from.y };
       };
-      // knot 按链中序号在两端位移间插值；一端仍为原节点时，不把整条线简单平移。
+      // knot 按序号 t=(index+1)/(count+1) 在线两端世界位移间插值，不按弧长或几何距离加权。
+      // 这里只移动 knot.position，in/out 等偏移向量已在前面的空间转换中处理，不再次加位移。
       const from = displacement(edge.source.elementId, source.elementId), to = displacement(edge.target.elementId, target.elementId), knots = path.knots;
       path = { ...path, knots: knots.map((raw, index) => { const knot = raw as Record<string, Json>, point = knot.position as { x: number; y: number }, world = toWorld(transform, point), t = (index + 1) / (knots.length + 1); return { ...knot, position: toLocal(transform, { x: world.x + from.x * (1 - t) + to.x * t, y: world.y + from.y * (1 - t) + to.y * t }) }; }) };
     }
@@ -167,7 +176,8 @@ export function duplicateOverlay(document:Document,elements:ReadonlyMap<Id,Eleme
 
 /** Internal overlay avoids an O(document size) clone between planning phases. Additions own unique IDs. */
 /** 只读接口覆盖层：新增 ID 保证唯一，先查 additions，迭代则 base 后 additions。
- * additions 在规划过程中仍会增长，故这个 view 只供内部计算，不是固定成员的发布快照。 */
+ * additions 在规划过程中仍会增长，故这个 view 只供内部计算，不是固定成员的发布快照。
+ * 本函数不验证 base/additions 的 ID 不相交；规划器分配时保证此约定，否则 size/迭代会出现重复。 */
 function overlay<K,V>(base: ReadonlyMap<K,V>, additions: ReadonlyMap<K,V>): ReadonlyMap<K,V> {
   const view: ReadonlyMap<K,V> = {
     // get/has 与所有迭代器读取同一组当前表；forEach 的第三参数仍是这个只读接口。

src/lib/canvas-core/editor.ts

@@ -1,7 +1,8 @@
 /**
  * 纯编辑器与单 Root 发布协调器：命令先在私有 draft 上规划，再统一发布 document/history/operations/runtime。
  * 不在这里执行网络或 IndexedDB；engine 通过同步准备钩子装配 ledger 等事实，调度器在发布后异步处理。
- * 修改入口共用 entered 防重入和 disposed 生命周期检查；协调提案另用 rootRevision 拒绝过期计划。
+ * 命令/协调发布入口共用 entered 防重入和 disposed 检查；协调提案另用 rootRevision 拒绝过期计划。
+ * dispose/subscribe 和只读查询有各自生命周期规则，entered 是同步重入闸门，不是跨线程或网络锁。
  */
 import {dataArray,dataRecord} from './data-containers.ts';
 import {stageCreation,materializeCreations} from './creation-draft.ts';
@@ -29,9 +30,13 @@ export type EditorOptions<Runtime = undefined> = {
   policy?: (command: Command, document: Document) => Availability;
   /** 撤销/重做独立准入钩子，runtime 可据依赖、未知请求或权限阻止栈移动。 */
   traversalPolicy?: (entry: HistoryEntry, direction: 'undo' | 'redo') => Availability;
+  /** listener 抛错后的诊断回调；诊断本身失败也不能回滚已经发布的状态。 */
   onListenerError?: (error: unknown) => void;
+  /** 明确开放 changes.apply 给可信宿主；仍执行 policy 和发布前文档检查。 */
   allowRawChanges?: boolean;
+  /** 恢复层预先校验的核心快照；初始化直接沿用其中 history/operations，不在此完整解码恢复 DTO。 */
   recovery?: CoreSnapshot & { readonly rootRevision: number };
+  /** 与初始核心快照配套的宿主 runtime；其内部不可变性由宿主负责。 */
   runtime?: Runtime;
   /** engine 安装的同步 reducer，将核心提交变成下一份 runtime；抛错拒绝整次发布。 */
   reduceRuntime?: (previous: Runtime, next: CoreSnapshot, commit: Commit) => Runtime;
@@ -58,17 +63,20 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
   // 文档索引与 runtime 覆盖范围同次绑定；同一个 doc 对象的加载事实也可能更新。
   const bindCoverage=(snapshot:Snapshot<Runtime>,queries:ReturnType<typeof createDocumentQueries>)=>options.queryCoverage?withQueryCoverage(queries,options.queryCoverage(snapshot)):queries;
   let queries=bindCoverage(state,createDocumentQueries(document,options.registry,state.revision,options.queryBudget));
-  // WeakMap 按确切快照身份保存查询，既拒绝错误快照，也不永久保留已废弃文档。
+  // WeakMap 按 Document 对象身份保存查询，不按整个 Root 身份；同文档的 runtime-only 发布会更新这条关联。
+  // 旧 Document 尚有外部引用时可查旧索引；未登记的外来 Document 明确拒绝，WeakMap 不独自保活旧文档。
   const queriesByDocument=new WeakMap([[document,queries]]);
   // entered 覆盖准备、发布和通知，防止 handler/reducer/observer 同步重入造成半份状态。
   let entered = false, disposed = false, sequence = 0;
   for (const intent of state.operations.values()) sequence = Math.max(sequence, intent.sequence);
   const listeners = new Set<(commit: Commit, snapshot: Snapshot<Runtime>) => void>();
+  // createId 可能在最终发布前被调用；失败的候选不会回收已经向宿主申请过的 ID。
   const createId = options.createId || (() => globalThis.crypto.randomUUID());
   const limit = options.historyLimit ?? 100;
   if (!Number.isSafeInteger(limit) || limit < 1) throw fault('invalid_history_limit');
 
-  /** 命令→候选文档/changes 的纯规划；不创建历史、不发送请求，也不改当前 state。 */
+  /** 命令→候选文档/changes 的同步规划，不创建历史、不发送请求，也不替换当前 state。
+   * policy/handler 由宿主提供，须遵守无外部写入约定；本函数不能回滚插件自己的副作用。 */
   function plan(document: Document, command: Command): { document: Document; changes: readonly Change[] } {
     const permission = options.policy?.(command, document);
     if (permission && !permission.enabled) throw fault(permission.code, permission.targets);
@@ -107,11 +115,13 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
         if (!validJson(command.path)) throw fault('invalid_connection_path', [element.id]);
         changes = options.registry.handlers.get(element.componentId)!.get('connection.edit')!({ element, input: freeze({ patch: { path: clone(command.path) } }) });
         for (const change of changes) if (change.kind !== 'field' || change.field !== 'path' || change.target.id !== element.id || change.target.incarnation !== element.incarnation) throw fault('invalid_handler_change', [element.id]);
+      // 端点命令只要求 connection.edit 已安装，直接生成 source/target 变化，不调用该 handler。
       } else if(command.type==='connection.endpoints'){
         if(element.structure!=='connection'||!options.registry.supports(element,'connection.edit'))throw fault('unsupported_capability',[element.id]);
         changes=[];
         for(const [field,endpoint]of [['source',command.source],['target',command.destination]] as const)if(endpoint&&!equal(element[field],endpoint))changes=[...changes,{kind:'field',target:command.target,field,before:element[field],after:clone(endpoint)}];
         if(changes.length)changes=[...changes,...repairConnectionOwners(document,applyChanges(document,changes))];
+      // 删除使用结构规划器收集子树/附边，不通过单一内容或几何 handler。
       } else if (command.type === 'element.remove') {
         changes = removalChanges(document,command.target,queriesByDocument.get(document));
       // 跨 owner 移动需要同时处理归属、几何、视觉单位、入口子 canvas 与相关边。
@@ -142,7 +152,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
         if (command.type === 'element.data') run('content.edit', command.patch);
         else {
           if (element.structure !== 'node' || Object.keys(command.patch).some(key => !['x', 'y', 'width', 'height', 'rotation'].includes(key))) throw fault('invalid_geometry_patch', [element.id]);
-          // 混合几何 patch 按 move→resize→rotate 分发，各 handler 只能处理自己的字段。
+          // 按输入字段拆成 move→resize→rotate；上方检查输出目标与 geometry 字段，具体几何语义仍由 handler 实现。
           const parts: [Capability, Partial<Geometry>][] = [
             ['geometry.move', Object.fromEntries(Object.entries(command.patch).filter(([key]) => key === 'x' || key === 'y'))],
             ['geometry.resize', Object.fromEntries(Object.entries(command.patch).filter(([key]) => key === 'width' || key === 'height'))],
@@ -153,7 +163,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
         changes = output;
       }
     }
-    // 创建可先放入临时 draft 容器，整批结束统一物化，减少大量创建时的重复表复制。
+    // 创建先放入临时 draft 容器，整批结束统一物化；其它修改沿有序 changes 应用，返回的变化另做 JSON 捕获。
     const next = command.type==='element.create'||command.type==='canvas.create'?stageCreation(document,changes[0] as Extract<Change,{kind:'canvas'|'element'}>):applyChanges(document, changes);
     return { document: next, changes: freeze(clone(changes)) };
   }
@@ -170,7 +180,8 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
     if(isThenable(runtime))throw fault('async_transaction');
     return runtime===next.runtime?next:Object.freeze({...next,runtime});
   }
-  /** 发布后通知 listener 快照；逐个隔离异常，观察者失败不能回滚已提交的 Root。 */
+  /** 发布后通知 listener 快照；逐个隔离异常，观察者失败不能回滚已提交的 Root。
+   * 本轮遍历 listener 集合的数组副本，通知期间退订不撤回副本中尚未调用的 listener。 */
   function emit(commit: Commit) {
     for (const listener of [...listeners]) try { listener(commit, state); } catch (error) { try { options.onListenerError?.(error); } catch { /* Observers cannot roll back a committed state. */ } }
   }
@@ -199,7 +210,8 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
       history = Object.freeze({ ...history, entries: readMap(entries) });
     }
     if (outbound) {
-      // 收集旧/新 owner、父 canvas 和端点 owner，形成跨图版本/claim 的完整参与者范围。
+      // 按变化种类收集参与者：canvas 自身及父项、元素旧/新 owner、新建边或端点变化涉及的端点 owner。
+      // 这是出站意图的 canvasIds 来源，不是一次对所有可能插件引用的全图扫描。
       const canvasIds = new Set<Id>();
       for (const change of changes) {
         if (change.kind === 'canvas') {
@@ -239,6 +251,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
     }
     const next: CoreSnapshot = Object.freeze({ revision: state.revision + 1, document, history, operations: readMap(operations) });
     const commit = freeze({ revision: next.revision, origin, changes, operationIds });
+    // reducer/prepareRuntime/查询构建都在 state 赋值前完成；拒绝只丢弃候选，不能撤回宿主钩子的外部副作用。
     const runtime = options.reduceRuntime ? options.reduceRuntime(state.runtime, next, commit) : state.runtime;
     if (isThenable(runtime)) throw fault('async_transaction');
     // 查询更新也在赋值之前准备；订阅者不会看到新文档搭配旧索引的短暂组合。
@@ -249,14 +262,15 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
     return Object.freeze({ status: 'applied', revision: state.revision, operationIds, ...(historyEntryId ? { historyEntryId } : {}) });
   }
 
-  /** 同步事务：多条 dispatch 共享 draft，任一命令失败使整批拒绝；回调结束后 tx 关闭。 */
+  /** 同步事务：多条 dispatch 共享 draft，正常 Error 失败会阻止发布；回调结束后 tx 关闭。
+   * failed 是 unknown 但当前分支用真值判断；宿主 policy/handler 应抛 Error，不应依赖抛 null/false/0 的拒绝语义。 */
   function transaction(callback: (transaction: Transaction) => unknown, settings: { label?: string; groupId?: Id; history?: boolean; origin?: Origin } = {}): Result {
     try { assertOpen(); } catch (error) { return reject(error); }
     entered = true;
     let active = true, document = state.document, failed: unknown;
     const changes: Change[] = [];
     const tx: Transaction = Object.freeze({
-      /** 私有 dispatch 记住第一次失败，后续命令不再继续推进 draft。 */
+      /** 私有 dispatch 记录规划抛错；常规 Error 被 failed 真值分支记住，后续命令停止推进。 */
       dispatch(command: Command): Availability {
         if (!active) throw fault('transaction_closed');
         if (failed) return { enabled: false, ...reject(failed) };
@@ -277,6 +291,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
       // 全部命令规划结束才物化创建记录并做整图校验，允许同批先创建节点再接边。
       document=materializeCreations(document);
       validateDocument(document, options.registry);
+      // 无变化或表内容/迭代顺序与原文档相同，直接报告 applied；不分配历史/操作 ID，也不通知订阅者。
       if (!changes.length || documentsEqual(document, state.document)) return Object.freeze({ status: 'applied', revision: state.revision, operationIds: Object.freeze([]) });
       let history = state.history, historyEntryId: Id | undefined;
       if (settings.history !== false && (!settings.origin || settings.origin === 'user')) {
@@ -292,10 +307,11 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
           entries.set(historyEntryId, dataRecord(freeze({ id: historyEntryId, label: settings.label || 'Edit', changes: dataArray(freeze([...changes])), operationIds: dataArray<Id>([]), ...(settings.groupId ? { groupId: settings.groupId } : {}) })));
           undo.push(historyEntryId);
         }
-        // 容量淘汰移除最旧 entry；资源 pin 的后续扫描以更新后的 history 为准。
+        // 仅从当前 history 淘汰最旧 entry；未解决操作的 historyTransition 等证据仍可能 pin 住旧资源。
         while (undo.length > limit) entries.delete(undo.shift()!);
         history = Object.freeze({ undo: Object.freeze(undo), redo: Object.freeze([]), entries: readMap(entries) });
       }
+      // history:false 或非 user origin 可不建历史项，但 outbound 由 publish 的 origin 规则独立决定。
       return publish(document, freeze([...changes]), settings.origin || 'user', history, historyEntryId);
     } catch (error) { active = false; return reject(error); }
     finally { entered = false; }
@@ -304,7 +320,8 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
   function dispatch(command: Command, settings?: Parameters<typeof transaction>[1]): Result {
     return transaction(tx => { tx.dispatch(command); }, settings);
   }
-  /** 只规划和校验可用性，不分配操作 ID、不发布；提交时还要重新校验当前状态。 */
+  /** 只规划和校验可用性，不分配操作 ID、不发布；提交时还要重新校验当前状态。
+   * can 只检查 disposed，不占 entered；宿主提供的 policy/handler 可能仍被调用，不应有外部写入。 */
   function can(command: Command): Availability {
     try { if (disposed) throw fault('editor_disposed'); const result = plan(state.document, command); validateDocument(result.document, options.registry); return { enabled: true }; }
     catch (error) { const result = reject(error); return { enabled: false, code: result.code, targets: result.targets }; }
@@ -319,6 +336,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
       const entry = state.history.entries.get(id)!;
       const allowed = options.traversalPolicy?.(entry, direction);
       if (allowed && !allowed.enabled) throw fault(allowed.code, allowed.targets);
+      // undo 反转变化顺序和值，redo 使用正向变化；私有执行先通过最终文档校验，才构造新的两栈。
       const planned=direction==='undo'?invert(entry.changes):entry.changes;
       const {document,changes,remap,restored}=planHistoryChanges(state.document,planned,options.registry);
       const entries=new Map(state.history.entries);
@@ -326,6 +344,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
       // Frozen operations retain their original identities and incarnations.
       // 显式恢复的生命周期影响可继续遍历的历史目标；已冻结操作身份不在这里改写。
       if(restored)for(const [otherId,other]of entries)if(otherId!==id)entries.set(otherId,dataRecord(freeze({...other,changes:dataArray(freeze(other.changes.map(remap)))})));
+      // 当前 entry 仍存“可重做的正向 changes”；undo 后把实际逆向变化再 invert，保留新恢复代次。
       entries.set(id,dataRecord(freeze({...entry,changes:dataArray(freeze(direction==='undo'?invert(changes):changes))})));
       const history: HistoryState = Object.freeze({ undo: Object.freeze(direction === 'undo' ? state.history.undo.slice(0, -1) : [...state.history.undo, id]), redo: Object.freeze(direction === 'redo' ? state.history.redo.slice(0, -1) : [...state.history.redo, id]), entries: readMap(entries) });
       return publish(document, changes, direction, history, id);
@@ -335,7 +354,8 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
   // 公开只读快照与绑定查询；指定未知 document 查查询会拒绝，不隐式混用当前索引。
   return Object.freeze({ getSnapshot: () => state,getQueries:(document=state.document)=>{const value=queriesByDocument.get(document);if(!value)throw fault('query_snapshot_unavailable');return value;}, registry: options.registry, dispatch, transaction, can,
     /** Coordinator entry: document, amended history and outbound fact share one Root. */
-    /** 异步图片尺寸解析只提交仍匹配 Root/目标的计划，并修正原创建历史，不额外造用户项。 */
+    /** 接收异步解码后的尺寸，入口本身同步；匹配 Root/目标后修正原创建历史，不额外造用户项。
+     * asset-resolution 仍可产生出站 operation，并与原创建 entry 关联，不是完全跳过 history/runtime。 */
     resolveCreationSize(effect: CreationSizeEffect, expectedRootRevision: number): Result {
       try { assertOpen(); } catch (error) { return reject(error); }
       entered = true;
@@ -363,6 +383,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
         if (expectedRootRevision !== state.rootRevision) throw fault('stale_plan');
         const runtime = reduce(state.runtime);
         if (isThenable(runtime)) throw fault('async_transaction');
+        // 相同 runtime 引用视为 no-op，prepareRuntime 不执行；调用方须返回新对象而非原地改旧状态。
         if (runtime !== state.runtime) {
           const nextState=prepareState(Object.freeze({ ...state, rootRevision: state.rootRevision + 1, runtime })),nextQueries=bindCoverage(nextState,queries);
           state=nextState;queries=nextQueries;queriesByDocument.set(state.document,queries);
@@ -373,7 +394,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
       finally { entered = false; }
     },
     /** Engine-only canonical proposal: validation and runtime state publish as one root. */
-    /** 将已校验的 ACK/恢复提案与 runtime 一起发布；旧 rootRevision 提案明确拒绝。
+    /** 接收 ACK/恢复提案并重新捕获校验文档，与 runtime 一起发布；旧 rootRevision 提案明确拒绝。
      * 可替换 history/operations，但不允许改写原有操作身份；文档实际变化才推进 revision。 */
     reconcile(document: Document, runtime: Runtime, expectedRootRevision: number, replacement?: { readonly history: HistoryState; readonly operations: ReadonlyMap<Id,OperationIntent> }): Result {
       try { assertOpen(); } catch (error) { return reject(error); }
@@ -384,7 +405,8 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
         const next = createDocument(document.projectId, [...document.canvases.values()], [...document.elements.values()], document.tombstones);
         validateDocument(next, options.registry);
         let nextSequence=sequence;
-        // 恢复替换必须让两栈精确覆盖 entry，entry 的 operation ID 必须存在，序列保持单调。
+        // 替换时要求两栈精确覆盖 entries、历史关联的 operation ID 存在，已有操作内容完全相等。
+        // 新操作的 sequence 在此仅检查正安全整数，再取最大值供后续分配；完整恢复校验由宿主边界完成。
         if(replacement){
           const {history,operations}=replacement,ids=[...history.undo,...history.redo];
           if(new Set(ids).size!==ids.length||ids.length!==history.entries.size||ids.some(id=>!history.entries.has(id)))throw fault('invalid_history');
@@ -392,6 +414,7 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
           for(const [id,intent]of operations){if(id!==intent.id||!Number.isSafeInteger(intent.sequence)||intent.sequence<1)throw fault('invalid_operation_sequence');nextSequence=Math.max(nextSequence,intent.sequence);}
           for(const [id,entry]of history.entries)if(entry.id!==id||entry.operationIds.some(operationId=>!operations.has(operationId)))throw fault('invalid_history');
         }
+        // 即使文档相等，reconcile 仍发布一个新 rootRevision 与 ACK 通知；仅文档变化推进 revision。
         const changed = !documentsEqual(next, state.document);
         const nextState=prepareState(Object.freeze({ ...state, ...(replacement?{history:replacement.history,operations:replacement.operations}:{}), document: changed ? next : state.document, runtime, revision: state.revision + Number(changed), rootRevision: state.rootRevision + 1 })),nextQueries=bindCoverage(nextState,changed?advanceDocumentQueries(queries,next,options.registry,state.revision+1):queries);
         state=nextState;queries=nextQueries;queriesByDocument.set(state.document,queries);
@@ -407,7 +430,8 @@ export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime
     dispose() { disposed = true; listeners.clear(); },
   });
 }
-/** 比较规范化表，先做身份/大小快判；无净变化的事务不增加 revision 或历史。 */
+/** 比较表的迭代顺序与内容，先做身份/大小快判；不是忽略插入顺序的 Map 集合等价。
+ * transaction 用它省去重复发布，reconcile 用它决定是否推进文档 revision。 */
 function documentsEqual(a: Document, b: Document): boolean {
   if(a===b)return true;
   if(a.canvases.size!==b.canvases.size||a.elements.size!==b.elements.size||a.tombstones.size!==b.tombstones.size)return false;

src/lib/canvas-core/element-data.ts

@@ -8,7 +8,8 @@ import {detachJsonData} from './json-data.ts';
 // Provenance comes from detaching JSON data, never from an external freeze or
 // document envelope. This does not assert record validity or registry support.
 const owned=new WeakSet<object>();
-/** 已由本模块捕获的记录直接复用；外部记录重新复制冻结，再标记新记录身份。 */
+/** 已由本模块捕获的记录直接复用；外部记录重新按 JSON 语义复制冻结，再标记新记录身份。
+ * 此处不调用组件 schema；捕获成功与记录合法是两项独立事实。 */
 export function detachElementData(record:ElementRecord):ElementRecord{
  if(record&&typeof record==='object'&&owned.has(record))return record;
  const value=detachJsonData(record);
@@ -21,7 +22,8 @@ export const hasOwnedElementData=(record:ElementRecord)=>!!record&&typeof record
 // Framework-owned validators depend only on detached immutable data. Custom
 // validators remain live, including their method receiver and external context.
 const builtinValidators=new WeakSet<Function>(),dataProofs=new WeakMap<object,ComponentDefinition['validate']>();
-/** 标记框架内置、仅依赖输入的纯校验器；不要用它包装依赖外部可变状态的校验器。 */
+/** 标记框架内置、仅依赖输入的纯校验器；不要用它包装依赖外部可变状态的校验器。
+ * WeakSet 只记录这项声明，不能自动证明函数无副作用或不读取闭包状态。 */
 export function builtinDataValidator<T extends ComponentDefinition['validate']>(validate:T):T{builtinValidators.add(validate);return validate;}
 /** 检查组件 data，只有“owned 记录 + 内置 validator”组合才允许复用成功结果。
  * 失败不缓存；更换 validator 后缓存也不命中；Reflect.apply 保留定义对象作为 this。 */
@@ -29,6 +31,7 @@ export function componentDataValid(record:ElementRecord,definition:ComponentDefi
  // record 身份和具体 validator 函数同时匹配，才能跳过一次已成功的 schema 检查。
  const validate=definition.validate,reusable=hasOwnedElementData(record)&&builtinValidators.has(validate);
  if(reusable&&dataProofs.get(record)===validate)return true;
+ // 校验器抛错会直接传播给上层；这里只缓存正常返回且通过的结果，不吞错或缓存失败。
  const valid=Reflect.apply(validate,definition,[record.data]);
  if(valid&&reusable)dataProofs.set(record,validate);
  return valid;

src/lib/canvas-core/features.ts

@@ -1,6 +1,7 @@
 /**
  * 内置 feature 与 component 装配。Handler 是纯规划器：读取目标与 patch，只返回字段变化。
  * 权限、事务与发布仍由 editor 负责；UI 不能绕过 editor 直接调用 handler 来写文档。
+ * capability 表示安装了哪类行为，schema 与各 handler 的实际检查仍须分别阅读。
  */
 import {builtinDataValidator} from './element-data.ts';
 import {rectangleGeometry,bezierChainSegments,type BezierChain} from './geometry.ts';
@@ -15,12 +16,14 @@ const geometryHandler = (allowed: readonly (keyof Geometry)[], constrain?: (geom
   if (element.structure !== 'node') throw fault('unsupported_capability', [element.id]);
   const patch = input.patch as Partial<Geometry>;
   if (!patch || Object.values(patch).some(value => typeof value !== 'number' || !Number.isFinite(value)) || Object.keys(patch).some(key => !allowed.includes(key as keyof Geometry))) throw fault('invalid_geometry_patch', [element.id]);
+  // constrain 在字段形状检查后执行；此处不归一 rotation 或单独证明最终宽高为正，交给文档几何校验。
   const after = constrain ? constrain({ ...element.geometry, ...patch }) : { ...element.geometry, ...patch };
   return equal(element.geometry, after) ? [] : [{ kind: 'field', target: { id: element.id, incarnation: element.incarnation }, field: 'geometry', before: element.geometry, after }];
 };
 /** 移动仅允许 x/y，不能顺带修改大小、旋转或 owner。 */
 export const movable = () => defineFeature('geometry.move', { 'geometry.move': geometryHandler(['x', 'y']) });
-/** 捕获 min/max/aspect 配置，构造只修改 width/height 的缩放行为。 */
+/** 浅捕获 min/max/aspect 选项，检查显式 min/max，再构造只修改 width/height 的缩放行为。
+ * 缺省 min=1、max=100000；aspect 默认不启用，内置图片也复用这份默认缩放 feature。 */
 export const resizable = (inputOptions: { min?: number; max?: number; aspect?: boolean } = {}) => {
   const options = Object.freeze({ ...inputOptions });
   if (options.min !== undefined && (!Number.isFinite(options.min) || options.min <= 0) || options.max !== undefined && (!Number.isFinite(options.max) || options.max < (options.min ?? 1))) throw fault('invalid_resize_constraint');
@@ -32,6 +35,7 @@ export const resizable = (inputOptions: { min?: number; max?: number; aspect?: b
     return geometryHandler(['width', 'height'], geometry => {
       // owner 变换后 unitScale 也会改变，因此 min/max 要乘它才能维持同一视觉尺寸约束。
       const units=unitScale(element.data.presentation),min=(options.min??1)*units,max=(options.max??100000)*units;
+      // 先逐维 clamp，再按原 width/height 比例重算另一维；同时给宽高且 aspect=true 时以宽度为主。
       let width = Math.min(max, Math.max(min, geometry.width)), height = Math.min(max, Math.max(min, geometry.height));
       // 宽度优先；只给高度时反算宽度。保持原比例后越界则拒绝，不分别截断而破坏比例。
       if (options.aspect) {
@@ -44,13 +48,16 @@ export const resizable = (inputOptions: { min?: number; max?: number; aspect?: b
   },
   });
 };
-/** 旋转只产生 rotation 修改；[0,360) 等最终范围约束由几何校验处理。 */
+/** 旋转 handler 只接受 rotation patch，但输出的是整份 geometry 字段变化。
+ * 不把 360/-1 自动归一到 [0,360)，最终几何校验负责拒绝越界结果。 */
 export const rotatable = () => defineFeature('geometry.rotate', { 'geometry.rotate': geometryHandler(['rotation']) });
 /** 内容编辑按顶层 data 键生成独立条件变化，保存存在性，区分缺失字段与 null。 */
 export const editable = () => defineFeature('content.edit', {
   'content.edit': ({ element, input }) => {
     const patch = input.patch as Data;
     if (!patch || !validJson(patch) || Array.isArray(patch)) throw fault('invalid_data_patch', [element.id]);
+    // 签名要求 Data 对象；上面的运行时 guard 检查 JSON 值域并排除数组，不是任意未知输入的完整对象 schema。
+    // patch 中出现的键都表示写入，null 是显式值；此 handler 没有以 undefined 表示删除的约定。
     // 每个字段携带 before，ACK/重放时才能检查冲突，而不是用整份节点覆盖后来的编辑。
     return Object.entries(patch).flatMap(([key, after]): FieldChange[] => {
       const before = element.data[key] ?? null;
@@ -58,7 +65,8 @@ export const editable = () => defineFeature('content.edit', {
     });
   },
 });
-/** 内置节点的基础 data 合同：title/text 为字符串，允许其它合法 JSON 扩展字段。 */
+/** 内置节点共用的基础 data 合同：title/text 为字符串，检查已识别 unitScale，允许其它合法 JSON 扩展。
+ * 图片 URL/资源身份、图标名或任务字段并不由此函数逐项验证；它也不代表所有表现字段都有专门 schema。 */
 const textData = builtinDataValidator((data: Data) => presentationUnitsValid(data.presentation) && validJson(data) && typeof data.title === 'string' && typeof data.text === 'string');
 /** 安装文本、图片、脚本、图标、frame 和 connection 的默认定义。
  * 节点共用基础行为；frame 不安装旋转行为。复制声明与资源字段也是定义的一部分。 */
@@ -67,18 +75,23 @@ export function builtinComponents(): readonly ComponentDefinition[] {
     id, dataVersion: 1, structure: 'node', validate: textData,
     features: [movable(), resizable(), ...(id === 'frame' ? [] : [rotatable()]), editable()],
     resourceFields: ['image', 'plain-image'].includes(id) ? ['assetId','asset'] : [],
-    // frame 的 ports 引用必须随复制映射；任务/run/progress 不复制成新的执行任务。
+    // frame ports[].nodeId 是显式 element 引用，复制范围外引用按 reject；局部 port id/handle 不是这里的映射目标。
+    // 只 omit 下列四个顶层任务状态字段，不递归猜测任意插件任务结构；资源字段按声明另供 runtime 扫描。
     geometry:rectangleGeometry,copy: { references: id === 'frame' ? [{path:['ports','*','nodeId'],target:'element',external:'reject'}] : [], omit: [['taskId'], ['runId'], ['progress'], ['runStatus']] },
+  // 后续 connection 使用单独定义：strokeWidth 取 appearance.width 的真值或 1.5，并不在这里验证其类型/正数范围。
+  // segments 要求 displayPath 已提供且可解释，再调用共享 Bezier 生成器；输出有效性由几何查询边界继续检查。
   })).concat([defineComponent({ id: 'connection', dataVersion: 1, structure: 'connection', validate: builtinDataValidator((data:Data) => validJson(data)), features: [editable(), connectionEditable()], resourceFields: [],geometry:{kind:'connection',version:1,strokeWidth:({element})=>{const appearance=element.data.appearance;return (appearance&&typeof appearance==='object'&&!Array.isArray(appearance)?appearance.width:undefined) as number||1.5;},segments:context=>{if(context.displayPath===undefined||!connectionPathValid(context.displayPath))throw fault('unsupported_connection_geometry');return bezierChainSegments(context.source,context.target,context.displayPath as unknown as BezierChain|null);}}, copy: { references: [], omit: [] } })]);
 }
 
-/** null 表示默认连线；否则仅支持最多 64 个 knot 的 bezier-chain，并校验控制点/唯一 ID。 */
+/** null 表示默认连线；否则仅支持最多 64 个 knot 的 bezier-chain，并校验控制点/唯一 ID。
+ * 这里只检查所需路径字段，不拒绝所有扩展键；corner/smooth/symmetric 是模式标签，不在此验证控制柄相切或镜像关系。 */
 export function connectionPathValid(path: Json): boolean {
   if (path === null) return true;
   if (typeof path !== 'object' || Array.isArray(path) || path.type !== 'bezier-chain' || !Array.isArray(path.knots) || path.knots.length > 64) return false;
   // 控制点只能是有限 x/y；缺少坐标、数组或非对象值均不接受。
   const point = (value: Json | undefined) => value && typeof value === 'object' && !Array.isArray(value) && typeof value.x === 'number' && typeof value.y === 'number' && Number.isFinite(value.x) && Number.isFinite(value.y);
   if (path.startControl !== undefined && !point(path.startControl) || path.endControl !== undefined && !point(path.endControl)) return false;
+  // 每个 knot 的 ID 非空且本路径内唯一；位置和 in/out 都必须是有限点，空 knots 数组也合法。
   const ids = new Set<string>();
   for (const knot of path.knots) {
     if (!knot || typeof knot !== 'object' || Array.isArray(knot) || typeof knot.id !== 'string' || !knot.id || ids.has(knot.id) || !['corner', 'smooth', 'symmetric'].includes(knot.mode as string) || !point(knot.position) || !point(knot.in) || !point(knot.out)) return false;
@@ -86,7 +99,8 @@ export function connectionPathValid(path: Json): boolean {
   }
   return true;
 }
-/** 连线编辑 handler：旧 path 也必须可解释，拒绝用当前协议重写未知曲线路径。 */
+/** 连线编辑 handler：旧 path 也必须可解释，拒绝用当前协议重写未知曲线路径。
+ * feature ID 为 connection.path，但注册 capability 键是 connection.edit；editor 按后者查 handler。 */
 export const connectionEditable = () => defineFeature('connection.path', { 'connection.edit': ({ element, input }) => {
   const path = (input.patch as { path?: Json }).path;
   if (element.structure !== 'connection' || !connectionPathValid(element.path)) throw fault('unsupported_connection_path', [element.id]);

src/lib/canvas-core/geometry.ts

@@ -1,6 +1,7 @@
 /**
  * 与渲染框架无关的基本几何协议。所有计算输入必须在同一坐标空间；
  * bounds 负责粗筛，hit 负责矩形精判，曲线 segments 由模型命中和 SVG 绘制共享。
+ * 函数不主动校验输入几何/容差/控制点，也不换算 viewport 或 presentation.unitScale，调用方先统一空间。
  */
 import type {Geometry,Point} from './types.ts';
 /** 轴对齐包围盒，用于空间索引粗筛；旋转节点的盒会大于其实际轮廓。 */
@@ -14,12 +15,15 @@ export type BezierChain={readonly knots:readonly{readonly position:Point;readonl
 /** 绕节点中心旋转后的 AABB：宽=|cos|·w+|sin|·h，高=|sin|·w+|cos|·h。 */
 export function rectangleBounds(g:Geometry):Rect{const angle=g.rotation*Math.PI/180,c=Math.abs(Math.cos(angle)),s=Math.abs(Math.sin(angle)),width=g.width*c+g.height*s,height=g.width*s+g.height*c;return{x:g.x+g.width/2-width/2,y:g.y+g.height/2-height/2,width,height};}
 /** 将点反向旋转到矩形自身坐标，计算到矩形的距离，再与容差比较。
- * 角外区域使用欧氏距离而非扩展 AABB；浮点误差余量随坐标尺度调整。 */
+ * 角外区域使用欧氏距离而非扩展 AABB；浮点误差余量随坐标尺度调整。
+ * 点在矩形内部时距离为 0；tolerance 由调用方保证非负，正常边界含在命中内。 */
 export function hitRectangle(g:Geometry,point:Point,tolerance=0):boolean{const angle=-g.rotation*Math.PI/180,c=Math.cos(angle),s=Math.sin(angle),dx=point.x-g.x-g.width/2,dy=point.y-g.y-g.height/2,x=dx*c-dy*s,y=dx*s+dy*c,ox=Math.max(0,Math.abs(x)-g.width/2),oy=Math.max(0,Math.abs(y)-g.height/2);return Math.hypot(ox,oy)<=tolerance+Number.EPSILON*64*Math.max(1,Math.abs(point.x),Math.abs(point.y),g.width,g.height);}
 /** 默认矩形节点协议；空 dataDependencies 表示形状仅依赖 geometry，不因 title 等数据变化重建。 */
 export const rectangleGeometry=Object.freeze({kind:'node' as const,version:1 as const,dataDependencies:Object.freeze([] as string[]),bounds:({geometry}:{geometry:Geometry})=>rectangleBounds(geometry),hit:({geometry,point,tolerance}:{geometry:Geometry;point:Point;tolerance:number})=>hitRectangle(geometry,point,tolerance)});
 /** Shared by the built-in model protocol and the SVG renderer; all arguments are in one display space. */
 /** 由锚点链生成每段三次曲线：上一 knot.out 和下一 knot.in 分别作为控制偏移。
- * 无显式首尾控制柄时，按端点距离的 0.4 倍选择长度并限制在 40–240。
- * add 把相对偏移变成绝对控制点；map 对每对相邻 anchors 输出一段。 */
+ * 无显式首尾控制柄时，reach 按两端直线距离的 0.4 倍限制在 40–240，再乘相应法向量。
+ * 本函数不归一 normal；只有单位法向量才使 reach 等于控制柄的实际长度。
+ * add 把相对偏移变成绝对控制点；map 对每对相邻 anchors 输出一段，共 knots.length+1 段。
+ * 无 knot 时直接生成端点间一段；这里不根据 smooth/symmetric 标签自动修正控制柄。 */
 export function bezierChainSegments(from:Connector,to:Connector,path?:BezierChain|null):Cubic[]{const reach=Math.min(240,Math.max(40,Math.hypot(to.point.x-from.point.x,to.point.y-from.point.y)*.4)),knots=path?.knots??[],anchors=[from.point,...knots.map(knot=>knot.position),to.point],add=(a:Point,b:Point)=>({x:a.x+b.x,y:a.y+b.y});return anchors.slice(0,-1).map((point,index)=>[point,add(point,index?knots[index-1].out:path?.startControl??{x:from.normal.x*reach,y:from.normal.y*reach}),add(anchors[index+1],index<knots.length?knots[index].in:path?.endControl??{x:to.normal.x*reach,y:to.normal.y*reach}),anchors[index+1]]);}

src/lib/canvas-core/gesture-placement.ts

@@ -12,8 +12,10 @@ type PlacementStep={canvasId:Id;parentCanvasId:Id;entryId:Id;incarnation:number;
 /** A short-lived reader of the visible owner chain relative to one view, not the project root.
  * Cache by owner only during this admission/publication, so multi-selection shares ancestry work. */
 /** 给定不可变文档/view/registry，返回短生命周期 owner→入口链读取器。
- * Map 只在一次准入或发布比较中复用，多选共享祖先扫描，不能跨文档更新继续使用。 */
+ * Map 只在一次准入或发布比较中复用，多选共享祖先扫描，不能跨文档更新继续使用。
+ * 返回数组/步骤没有运行时 freeze，geometry 也沿用记录引用；readonly 是调用约定，不应修改缓存结果。 */
 export function createGesturePlacementReader(document:Document,viewCanvasId:Id,registry:Registry){
+ // 链按 owner→view 方向排列，不包含 view 自身在更上级的入口；读同一 owner 会返回同一个数组。
  const values=new Map<Id,readonly PlacementStep[]>();
  /** 向 view 回溯目标拥有链，缺失/循环/隐藏入口明确拒绝；成功后才缓存完整链。 */
  return(ownerCanvasId:Id):readonly PlacementStep[]=>{
@@ -24,6 +26,7 @@ export function createGesturePlacementReader(document:Document,viewCanvasId:Id,r
   while(id!==viewCanvasId){
    if(seen.has(id))throw fault('canvas_cycle',[id]);seen.add(id);
    const parent=document.canvases.get(id)?.parent;
+   // owner 缺失或已回溯到无父根，统一视为不在此 view；仅 view 本身缺失在上方报 canvas_missing。
    if(!parent)throw fault('target_outside_view',[ownerCanvasId]);
    const entry=document.elements.get(parent.entryElementId);
    // A future/unknown entry is a collapsed placeholder; never interpret its payload.
@@ -31,6 +34,7 @@ export function createGesturePlacementReader(document:Document,viewCanvasId:Id,r
    // 未知/未来入口已在上方拒绝；已知入口仍可能折叠，折叠子内容不允许开始手势。
    const raw=entry.data.presentation,presentation=raw&&typeof raw==='object'&&!Array.isArray(raw)?raw:{};
    if(presentation.collapsed===true)throw fault('target_hidden',[ownerCanvasId]);
+   // 签名只读这些坐标字段，不校验整个 presentation；contentScale 这里仅检查 number 且 >0。
    const contentScale=typeof presentation.contentScale==='number'&&presentation.contentScale>0?presentation.contentScale:1;
    chain.push({canvasId:id,parentCanvasId:parent.canvasId,entryId:entry.id,incarnation:entry.incarnation,componentId:entry.componentId,dataVersion:entry.dataVersion,geometry:entry.geometry,contentScale,unitScale:unitScale(raw)});
    id=parent.canvasId;

src/lib/canvas-core/gestures.ts

@@ -1,7 +1,9 @@
 /**
- * 每个 editor 的临时交互会话：多个 view 各自保存选择/视口/工具/mode，共用一份已提交文档。
- * 同时至多存在一个节点或连线手势；baseline/preview 均是短生命周期状态，不写 history/ledger。
- * pointerup 时才通过 editor 提交净修改；取消仅清预览，不回写旧整节点，因此不会撤掉晚到资源 ACK。
+ * 一个 manager 的临时交互会话：多个 view 各自保存选择/视口/工具/mode，共用 editor 已提交文档。
+ * 单个 manager 内至多一个节点或连线手势；同一 editor 若另建 manager，并不共享这项互斥。
+ * baseline/preview 均是短生命周期状态，不写 history/ledger。
+ * 输入绑定通常在 pointerup 调用 commit；本模块不接 DOM 事件，只有显式 commit 才发 editor 命令。
+ * 取消仅清预览，不回写旧整节点，因此不会撤掉晚到资源 ACK；session listener 仍由本模块同步通知。
  */
 import type { Editor } from './editor.ts';
 import type { Availability, Capability, ElementRecord, Geometry, Id, Json, Result, Target } from './types.ts';
@@ -24,10 +26,11 @@ export function createSessions(editor: Editor) {
   let snapshot: SessionSnapshot = Object.freeze({ views: readMap(new Map<Id, ViewState>()), gesture: null, connectionGesture: null, lastCancelReason: null });
   // 开始手势时捕获原记录，用它计算净几何差；提交时仍以 editor 当前数据为准，不恢复整条记录。
   let baseline = new Map<Id, ElementRecord>(), connectionBaseline: ElementRecord | undefined, disposed = false, nextGestureToken = 0;
-  // Compare adjacent published identities without duplicating the per-view mode table.
+  // 相邻 editor 发布的文档身份用于 mode/坐标签名比较；runtime-only 发布仍会重新检查 editor.can 的当前准入。
   let publishedDocument=editor.getSnapshot().document;
   const listeners = new Set<() => void>();
-  /** 对监听列表做副本迭代并隔离异常，renderer 出错不能影响已提交模型。 */
+  /** 对监听列表做副本迭代并隔离异常，renderer 出错不能影响已提交模型。
+   * 会话本身没有 entered 重入闸门；监听器不应同步递归制造新会话操作。 */
   const notify = () => { for (const listener of [...listeners]) try { listener(); } catch { /* A renderer cannot invalidate model commits. */ } };
   /** 一次发布 views；若被中断的是手势拥有者，同时清 baseline 和预览，只通知一次。 */
   function publishViews(views:Map<Id,ViewState>,cancelOwnedView?:Id,reason='view_interrupted'){
@@ -37,7 +40,8 @@ export function createSessions(editor: Editor) {
   }
   /** 复制视图表并替换一项，可在同一发布中带上切工具/切 canvas 等取消原因。 */
   function setView(view: ViewState,cancelOwnedReason?:string) { const views = new Map(snapshot.views); views.set(view.id, view); publishViews(views,cancelOwnedReason?view.id:undefined,cancelOwnedReason); }
-  /** 幂等取消当前手势，保留 committed 文档及资源状态；重复 cancel 不重复通知。 */
+  /** 幂等取消本 manager 当前手势，保留 committed 文档及资源状态；重复 cancel 不重复通知。
+   * cancel 不接 viewId，属于 manager 级清理入口，不执行单 view 所有权校验。 */
   function cancel(reason = 'canceled') {
     if (!snapshot.gesture && !snapshot.connectionGesture) return;
     baseline.clear(); connectionBaseline = undefined; snapshot = Object.freeze({ ...snapshot, gesture: null, connectionGesture: null, lastCancelReason: reason }); notify();
@@ -49,6 +53,7 @@ export function createSessions(editor: Editor) {
     for (const [id, view] of views) {
       // 当前 canvas 被删除时回到根；失效 selection 清理，模式还需检查相邻发布的元素身份。
       const canvasMissing = !document.canvases.has(view.canvasId);
+      // selection 只保留仍存在的 ID，不按 incarnation/owner/可见性重新筛；mode 才比较相邻发布的完整身份字段。
       const selection = [...view.selection].filter(target => document.elements.has(target)), modes = new Map([...view.modes].filter(([target]) => {
         const before=beforeDocument.elements.get(target),after=document.elements.get(target);
         return !!before&&!!after&&before.incarnation===after.incarnation&&before.ownerCanvasId===after.ownerCanvasId&&before.structure===after.structure&&before.componentId===after.componentId&&before.dataVersion===after.dataVersion;
@@ -64,7 +69,8 @@ export function createSessions(editor: Editor) {
     const oldPlacement=activeView?createGesturePlacementReader(beforeDocument,activeView.canvasId,editor.registry):undefined,newPlacement=activeView?createGesturePlacementReader(document,activeView.canvasId,editor.registry):undefined;
     /** 同文档无需重算；旧/新链不再可读或值变化都按坐标上下文失效处理。 */
     const placementChanged=(owner:Id)=>{if(beforeDocument===document)return false;try{return !oldPlacement||!newPlacement||!equal(oldPlacement(owner),newPlacement(owner));}catch{return true;}};
-    // 连线预览只依赖 path、身份、owner 和准入；普通内容或资源 ACK 不应自动取消它。
+    // 连线预览检查 path、身份、owner、坐标祖先链和当前准入；普通内容/资源 ACK 本身不直接取消，
+    // 但若该发布使 policy 不再允许 connection.path，后面的 editor.can 仍会取消。
     if (!cancelReason&&snapshot.connectionGesture?.phase === 'active') {
       const current = document.elements.get(snapshot.connectionGesture.target.id), before = connectionBaseline;
       if (!current || current.structure !== 'connection' || before?.structure !== 'connection' || current.incarnation !== before.incarnation || current.ownerCanvasId !== before.ownerCanvasId || current.componentId!==before.componentId || current.dataVersion!==before.dataVersion || !equal(current.path, before.path)) cancelReason='target_changed';
@@ -100,7 +106,8 @@ export function createSessions(editor: Editor) {
         ['geometry.resize', Object.fromEntries(Object.entries(patch).filter(([key]) => key === 'width' || key === 'height'))],
         ['geometry.rotate', Object.fromEntries(Object.entries(patch).filter(([key]) => key === 'rotation'))],
       ];
-      // move/resize/rotate 依次读取上一步预览结果；handler 只能给同目标生成合法 geometry。
+      // update 不以空 patch 做整命令 policy 预检，而是逐项检查实际使用的 capability、handler 输出目标与几何。
+      // move/resize/rotate 依次读取上一步预览结果；真正 commit 仍会通过 editor 再查 policy。
       for (const [capability, value] of parts) if (Object.keys(value).length) {
         if (!editor.registry.supports(element, capability)) throw fault('unsupported_capability', [target.id]);
         const changes = editor.registry.handlers.get(element.componentId)!.get(capability)!({ element, input: freeze({ patch: value }) });
@@ -112,6 +119,7 @@ export function createSessions(editor: Editor) {
         }
       }
       // 更新 preview 不触发 editor 命令，所以 pointermove 不制造 history 或出站请求。
+      // 即使 patch 结果相同，本路径仍替换会话快照并 notify，不像 tool/mode 有相同值早返回。
       const preview = new Map(snapshot.gesture.preview); preview.set(target.id, (element as ElementRecord & { structure: 'node' }).geometry);
       snapshot = Object.freeze({ ...snapshot, gesture: freeze({ ...snapshot.gesture, preview: readMap(preview) }) }); notify();
       return { enabled: true };
@@ -120,36 +128,42 @@ export function createSessions(editor: Editor) {
   return Object.freeze({
     /** 外部订阅读取当前只读会话，不能直接修改内部 Map/Set。 */
     getSnapshot: () => snapshot,
-    /** 创建独立 view，返回带 attached 标记的幂等卸载函数；只释放这个 view 与其手势。 */
+    /** 创建独立 view，返回内部带 attached 布尔标记的幂等卸载闭包；只释放这个 view 与其手势。
+     * 已 dispose 或重复 view ID 都报 duplicate_view；卸载不关闭 editor，也不停止 runtime 持久任务。 */
     attach(id: Id, canvasId = [...editor.getSnapshot().document.canvases.values()].find(canvas => !canvas.parent)!.id) {
       if (disposed || snapshot.views.has(id)) throw fault('duplicate_view', [id]);
       if (!editor.getSnapshot().document.canvases.has(canvasId)) throw fault('canvas_missing', [canvasId]);
       setView(freeze({ id, canvasId, selection: readSet<Id>([]), viewport: { x: 0, y: 0, zoom: 1 }, tool: 'select', modes: readMap(new Map<Id, string>()) }));
       let attached=true;return () => { if(!attached)return;attached=false;if(!snapshot.views.has(id))return;const views=new Map(snapshot.views);views.delete(id);publishViews(views,id,'view_detached'); };
     },
-    /** 切换查看的 canvas，清 selection/modes，并取消属于该 view 的旧坐标手势。 */
+    /** 设置查看的 canvas，清 selection/modes，并取消属于该 view 的旧坐标手势。
+     * 即使传相同 canvasId 也走清理/通知；它不是相同值 no-op 的入口。 */
     canvas(id: Id, canvasId: Id) {
       const current = view(id);
       if (!editor.getSnapshot().document.canvases.has(canvasId)) throw fault('canvas_missing', [canvasId]);
       setView(freeze({ ...current, canvasId, selection: readSet<Id>([]), modes: readMap(new Map<Id, string>()) }),'canvas_changed');
     },
-    /** 捕获有效元素 ID 为只读选择集合；这是会话选择，不是文档命令。 */
+    /** 捕获存在的元素 ID 为去重选择集合；不要求属于此 view、可见或已安装组件。
+     * selection 不携带 incarnation，也不是授权证据；begin/提交另行核对目标与准入。 */
     select(id: Id, ids: readonly Id[]) {
       const current = view(id), document = editor.getSnapshot().document;
       for (const target of ids) if (!document.elements.has(target)) throw fault('element_missing', [target]);
       setView(freeze({ ...current, selection: readSet(ids) }));
     },
-    /** 保存有限 pan 和正 zoom；改变观察视口不修改元素几何或 history。 */
+    /** 保存有限 pan 和正 zoom；不修改元素几何/history，也不自动取消当前手势。
+     * 屏幕输入如何随 pan/zoom 换算由输入绑定负责，此处不保存 DOM 指针坐标。 */
     viewport(id: Id, viewport: ViewState['viewport']) {
       if (![viewport.x, viewport.y, viewport.zoom].every(Number.isFinite) || viewport.zoom <= 0) throw fault('invalid_viewport');
       setView(freeze({ ...view(id), viewport: { ...viewport } }));
     },
     /** select/pan 切换会取消本 view 的手势；重复设置相同工具不发通知。 */
     tool(id: Id, tool: ViewState['tool']) { const current=view(id);if(tool!=='select'&&tool!=='pan')throw fault('invalid_tool');if(current.tool===tool)return;setView(freeze({ ...current, tool }),'tool_changed'); },
-    /** 保存某元素的临时编辑模式；空值移除，不创建持久的业务字段。 */
+    /** 保存某元素的临时模式字符串；null/空串移除，非空值要求元素存在。
+     * 不在此枚举模式名或检查 capability；mode 不是可编辑权限，也不是持久业务字段。 */
     mode(id: Id, target: Id, mode: string | null) { const current = view(id);if(mode!==null&&typeof mode!=='string')throw fault('invalid_mode');if(mode&&!editor.getSnapshot().document.elements.has(target))throw fault('element_missing',[target]);if((current.modes.get(target)??null)===(mode||null))return;const modes = new Map(current.modes); if (mode) modes.set(target, mode); else modes.delete(target); setView(freeze({ ...current, modes: readMap(modes) })); },
     /** 节点手势准入：select 工具、无其它手势、目标去重/版本支持、可见拥有链及 policy 全部通过。
-     * 先把整组选区检查完再替换 baseline，拒绝不会留下半组手势。 */
+     * 先把整组目标检查完再替换 baseline，拒绝不会留下半组手势；targets 不必等于 view.selection。
+     * 空 geometry patch 的 editor.can 不调用 move/resize/rotate handler，实际能力仍在 update/commit 检查。 */
     begin(viewId: Id, targets: readonly Target[]): Availability {
       try {
         if(view(viewId).tool!=='select')throw fault('tool_not_select');
@@ -188,7 +202,8 @@ export function createSessions(editor: Editor) {
         return { enabled: true };
       } catch (error) { const result = reject(error); return { enabled: false, code: result.code, targets: result.targets }; }
     },
-    /** 连线结束只 dispatch 一次；先标 committing，结束后无论成功/拒绝都清预览。 */
+    /** 连线结束只 dispatch 一次；先标 committing，使 editor 发布监听暂不按 active 取消自己的提交。
+     * 正常提交和 catch 都调用 manager 级 cancel；错误 view 的提交调用也可能取消当前另一 view 的手势。 */
     commitConnection(viewId: Id): Result {
       try {
         view(viewId);
@@ -200,7 +215,9 @@ export function createSessions(editor: Editor) {
       } catch (error) { cancel('commit_failed'); return reject(error); }
     },
     update,
-    /** 节点手势提交一个同步事务，把各目标相对 baseline 的净字段变化合成一个 Transform 历史项。 */
+    /** 节点手势提交一个同步事务，仅遍历 preview 中的目标，合并相对 baseline 的净字段变化。
+     * 有实际文档变化时通常形成一个 Transform 历史项；空预览/无净变化遵守 editor 的 no-op 语义。
+     * 与连线提交相同，异常路径会取消本 manager 当前手势，而不只清理传入的 view。 */
     commit(viewId: Id): Result {
       try {
         view(viewId);
@@ -221,7 +238,8 @@ export function createSessions(editor: Editor) {
       } catch (error) { cancel('commit_failed'); return reject(error); }
     },
     cancel,
-    /** 渲染时优先读取预览，否则读取最新 committed 几何；取消后自然显露最新模型。 */
+    /** 按元素 ID 优先读取本 manager 预览，否则读取最新 committed 几何；取消后自然显露最新模型。
+     * 无 viewId 参数，不过滤调用者视图；投影/renderer 负责决定这个元素是否应在该 view 显示。 */
     effectiveGeometry(id: Id): Geometry | undefined {
       const element = editor.getSnapshot().document.elements.get(id);
       return snapshot.gesture?.preview.get(id) || (element?.structure === 'node' ? element.geometry : undefined);

src/lib/canvas-core/history-transition.ts

@@ -18,11 +18,12 @@ export type HistoryTransition={readonly version:1;readonly rootRevision:number;r
 // only its flattened changes, never registry-dependent references or callbacks.
 const transitionChanges=new WeakMap<HistoryTransition,readonly Change[]>();
 const immutableData=new WeakSet<object>();
-/** 检查可安全跨持久切点复用的深不可变普通数据，最多 64 层。
+/** 检查缓存候选的冻结数据描述符与普通原型，最多递归 64 层；不是单独的 JSON/schema 校验器。
  * 冻结的 getter 仍可能返回不同值，稀疏数组也不是完整区间，因此都不允许缓存。 */
 function immutablePlainData(value:unknown,depth=0):boolean{
   if(depth>64)return false;
   if(value===null||typeof value!=='object')return typeof value!=='function';
+  // 只记住已遍历成功的对象身份；祖先链若太深仍会先被 depth 条件拒绝。
   if(immutableData.has(value))return true;
   if(!Object.isFrozen(value)||Object.getPrototypeOf(value)!==(Array.isArray(value)?Array.prototype:Object.prototype))return false;
   if(Array.isArray(value))for(let i=0;i<value.length;i++)if(!Object.hasOwn(value,i))return false;
@@ -44,7 +45,8 @@ function splice<T>(before:readonly T[],after:readonly T[]):Splice<T>{
 }
 /** Store changed ranges only. Clearing redo/eviction still retains the removed entry records needed to reverse that transition. */
 /** 对比两份 history，记录新增、删除和修改的 entry 及两栈顺序。
- * 默认无变化不造记录；recordNoop 用于调用方显式需要记录发布边界的情形。 */
+ * 默认无变化不造记录；recordNoop 用于调用方显式需要记录发布边界的情形。
+ * 来源应是不可变 history：两栈和区间内的 Change 沿用引用，最终 freeze 不等于任意外部输入的深复制。 */
 export function describeHistoryTransition(before:HistoryState,after:HistoryState,rootRevision:number,entryId?:Id,recordNoop=false):HistoryTransition|undefined{
   const entries:EntryPatch[]=[];
   for(const id of new Set([...before.entries.keys(),...after.entries.keys()])){const a=before.entries.get(id),b=after.entries.get(id);if(equal(a,b))continue;entries.push({id,before:meta(a),after:meta(b),changes:splice(a?.changes??[],b?.changes??[]),operationIds:splice(a?.operationIds??[],b?.operationIds??[])});}
@@ -52,9 +54,10 @@ export function describeHistoryTransition(before:HistoryState,after:HistoryState
   return freeze({version:1,rootRevision,...(entryId?{entryId}:{}),before:{undo:before.undo,redo:before.redo},after:{undo:after.undo,redo:after.redo},entries});
 }
 /** 验证外部/恢复的增量 DTO，未知 version 明确要求其它解释器。
- * checkChanges 可由调用方注入更严格的 Change 校验，本函数本身不依赖 registry。 */
+ * checkChanges 可由调用方注入更严格的 Change 校验；未传时只检查 DTO/区间形状，不解释每条 Change 的领域语义。
+ * rootRevision 只在此检查非负整数，不在此证明 transition 属于哪次实际发布。 */
 export function validateHistoryTransition(value:unknown,checkChanges?:(value:unknown)=>unknown):asserts value is HistoryTransition{
-  // 四个局部校验器统一抛领域错误，分别约束普通记录、非负整数、单 ID 和 ID 数组。
+  // 四个局部校验器统一抛领域错误，分别约束非数组记录形状、非负整数、非空 ID 和 ID 数组。
   const object=(v:unknown):Record<string,unknown>=>{if(!v||typeof v!=='object'||Array.isArray(v))throw fault('invalid_history_transition');return v as Record<string,unknown>;};
   const integer=(v:unknown)=>{if(typeof v!=='number'||!Number.isSafeInteger(v)||v<0)throw fault('invalid_history_transition');};
   const id=(v:unknown)=>{if(typeof v!=='string'||!v)throw fault('invalid_history_transition');};
@@ -72,8 +75,9 @@ export function validateHistoryTransition(value:unknown,checkChanges?:(value:unk
   }
 }
 /** Conditional metadata-only replay. A mismatch leaves the supplied history untouched. */
-/** 先检查栈和每个区间仍匹配预期，再在私有副本上正向/反向回放元数据。
- * 任一冲突抛出而不修改输入 history；不能拿旧 journal 覆盖新的历史顺序。 */
+/** 先检查两栈，再逐 entry 检查元数据/数组区间并在私有副本上正向或反向回放。
+ * 不改写输入两栈/entries 表；不能拿旧 journal 覆盖新的历史顺序。
+ * history/transition 应已捕获：补丁内 Change 会沿用并冻结，不应把此接口当任意外部值的深隔离入口。 */
 export function applyHistoryTransition(history:HistoryState,transition:HistoryTransition,direction:'forward'|'reverse'):HistoryState{
   validateHistoryTransition(transition);const reverse=direction==='reverse',source=reverse?transition.after:transition.before,destination=reverse?transition.before:transition.after;
   if(!equal({undo:history.undo,redo:history.redo},source))throw fault('history_transition_conflict');
@@ -91,6 +95,7 @@ export function applyHistoryTransition(history:HistoryState,transition:HistoryTr
 export function historyTransitionChanges(transition:HistoryTransition):readonly Change[]{
   const cached=transitionChanges.get(transition);if(cached)return cached;
   validateHistoryTransition(transition);
+  // 仅收集被记录的变化区间两侧，未重复保存的共同前后缀不在本结果中；它不是完整 history 的展开。
   const changes=transition.entries.flatMap(patch=>[...patch.changes.before,...patch.changes.after]);
   // 属性来自原型或 getter 时不可把一次结果当永久事实，避免错误释放资源 pin。
   const ownRanges=Object.hasOwn(transition,'entries')&&transition.entries.every(patch=>Object.hasOwn(patch,'changes')&&Object.hasOwn(patch.changes,'before')&&Object.hasOwn(patch.changes,'after'));

src/lib/canvas-core/history.ts

@@ -9,15 +9,17 @@ import { freeze } from './values.ts';
 
 /** Pure history execution, also used to validate recovery proposals before publication. */
 /** 顺序回放一组历史修改，完成整份文档校验后返回候选文档和实际 changes。
- * remap 供调用者把其它历史目标同步映射到恢复后的 incarnation；失败时原文档不变。 */
+ * remap 供调用者把其它历史目标同步映射到恢复后的 incarnation；函数不发布任何候选。
+ * initial/planned 应来自已捕获的不可变状态，底层 applyChanges/freeze 不是任意外部对象的深隔离入口。 */
 export function planHistoryChanges(initial:Document,planned:readonly Change[],registry:Registry){
   // ID →（旧 incarnation → 新 incarnation）；同一批恢复可能形成多级映射链。
   const generations=new Map<Id,Map<number,number>>();
-  // 追踪到最终代次，避免后面的字段修改仍指向本批较早的已替换代次。
+  // 追踪到本批最终代次；每次恢复分配更大代次，因此按这些内部生成的映射链前进。
   const incarnation=(id:Id,value:number)=>{const mapping=generations.get(id);while(mapping?.has(value))value=mapping.get(value)!;return value;};
   // 只改生命周期身份：字段目标与整元素 before/after 都要一致，canvas 变更原样通过。
   const remap=(change:Change):Change=>{
     if(change.kind==='field'){const next=incarnation(change.target.id,change.target.incarnation);return next===change.target.incarnation?change:freeze({...change,target:{...change.target,incarnation:next}});}
+    // 整元素 before/after 只替换顶层 incarnation，记录内其它字段与引用不在此重新解释。
     if(change.kind==='element'){const record=(value:ElementRecord|null)=>value?{...value,incarnation:incarnation(value.id,value.incarnation)}:null;return freeze({...change,before:record(change.before),after:record(change.after)});}
     return change;
   };
@@ -31,5 +33,6 @@ export function planHistoryChanges(initial:Document,planned:readonly Change[],re
   }
   // 暂态允许先恢复端点再恢复边；只有整批完成后才检查最终树、引用和 owner 一致性。
   validateDocument(document,registry);
+  // restored 只表示是否建立过恢复代次映射；即使 false，文档也可能因普通字段/删除变化而改变。
   return{document,changes:freeze(changes),remap,restored:generations.size>0};
 }

src/lib/canvas-core/index.ts

@@ -21,8 +21,10 @@ export type {DuplicatePlan,DuplicateOptions} from './duplicate.ts';
 export {createDuplicatePlanner,validateDuplicateCheckpoint} from './duplicate-checkpoint.ts';
 export type {DuplicateCheckpoint} from './duplicate-checkpoint.ts';
 
-// 查询按不可变文档快照绑定；更新 API 用于沿发布变化推进关系与空间索引。
+// 查询按不可变文档快照绑定；此处公开建表/增量推进与查询类型。
+// withQueryCoverage 是宿主加载链直接使用的模块 API，没有在这个根入口重导出。
 export {createDocumentQueries,advanceDocumentQueries} from './queries.ts';
 export type {DocumentQueries,Bounds,QueryBudget,QueryCoverage,ElementLookup,IdQueryResult} from './queries.ts';
 
+// 公开共享几何函数；预算曲线细分 hitCubic 和 history 执行规划器等仍从内部模块使用，不在此整包重导出。
 export {rectangleGeometry,rectangleBounds,hitRectangle,bezierChainSegments} from './geometry.ts';

src/lib/canvas-core/json-data.ts

@@ -7,8 +7,9 @@ import {clone,freeze} from './values.ts';
 // Private provenance for a fresh, recursively frozen JSON clone. A caller can
 // request a detached copy, but cannot grant this fact to an existing object.
 const detached=new WeakSet<object>();
-/** JSON 复制后递归冻结；对象结果记录到 WeakSet，原始值直接返回。
- * clone 会按 JSON 规则处理数据，所以不可用它代替迁移输入的严格捕获校验。 */
+/** JSON 复制后递归冻结；仅对象结果记录到 WeakSet。
+ * 输入先经过 JSON 序列化语义：toJSON/getter 可能执行，稀疏槽/数组中的非法 JSON 值可能转为 null。
+ * 循环或 BigInt 等仍会抛错；它不保留任意输入原貌，不能替代迁移输入的严格捕获校验。 */
 export function detachJsonData<T>(input:T):T {
   const value=freeze(clone(input));
   if(value&&typeof value==='object')detached.add(value);

src/lib/canvas-core/queries.ts

@@ -3,6 +3,7 @@
  * 关系表描述 owner、子 canvas、关联边与声明引用；空间表按 owner canvas 分网格存节点包围盒。
  * 更新采用 touched bucket 的 copy-on-write，未变索引保持身份，供局部订阅复用。
  * 查询完整性与命中成功分开：没查到不一定不存在，加载不完整/协议失败必须显式报告。
+ * 工厂不执行 validateDocument；输入文档须已校验且不可变，局部加载的完整性由宿主绑定 coverage。
  */
 import {rectangleBounds,hitRectangle} from './geometry.ts';
 import type {Change,Document,ElementRecord,Geometry,Id,Point,ReadonlyValueSet,Registry} from './types.ts';
@@ -18,7 +19,8 @@ type Relation=Map<Id,ReadonlyValueSet<Id>>;
 type Spatial={cells:Relation;entries:Map<Id,Box>;oversized:ReadonlyValueSet<Id>};
 /** 单元素声明引用的正向集合；complete=false 时不能据此证明它没有其它引用。 */
 type References={elements:ReadonlySet<Id>;canvases:ReadonlySet<Id>;complete:boolean};
-/** cellSize 控制格子边长，两项上限限制单对象/单查询覆盖的格子数，避免坐标范围拖垮枚举。 */
+/** cellSize 控制格子边长，两项上限限制单对象/单查询覆盖的格子数，避免坐标范围拖垮枚举。
+ * 这是格子枚举预算，不限制结果 ID 数或扫描耗时；超限查询可能转而扫描此 owner 全部节点。 */
 export type QueryBudget={readonly cellSize?:number;readonly maxElementCells?:number;readonly maxQueryCells?:number};
 /** 已补默认值并验证后的预算，后续同一索引链不能静默换配置。 */
 type ResolvedBudget=Required<QueryBudget>;
@@ -49,7 +51,8 @@ function cells(box:Box,limit:number,cellSize:number):string[]|undefined{
  if(![x0,x1,y0,y1,count].every(Number.isSafeInteger)||count<1||count>limit)return;
  const keys:string[]=[];for(let x=x0;x<=x1;x++)for(let y=y0;y<=y1;y++)keys.push(`${x},${y}`);return keys;
 }
-/** 只解析组件明确声明的复制引用；未知 schema/解析失败标记不完整，不能猜 payload 中的 ID。 */
+/** 只解析组件 copy.references 的声明路径；未知 schema/解析失败标记不完整，不猜 payload 中的 ID。
+ * complete 仅说明这些声明可解析，不验证被引用对象存在、external 策略或隐藏在未声明字段中的引用。 */
 function refs(record:ElementRecord,registry:Registry):References{
  const elements=new Set<Id>(),canvases=new Set<Id>(),schema=registry.components.get(record.componentId)?.copy;
  if(registry.resolve(record)!=='known'||!schema)return{elements,canvases,complete:false};
@@ -72,7 +75,8 @@ export type ElementLookup={readonly status:'present';readonly element:ElementRec
 export type IdQueryResult={readonly ids:readonly Id[];readonly complete:boolean};
 /** 与一个确切 document/registry/revision 绑定的公共查询。
  * members/child/incident 提供稳定排序；Result 版本另外携带加载完整性。
- * candidateNodes 是空间粗筛，hitNodeBounds 用矩形精判，hitNodes 使用组件 hit 协议。 */
+ * candidateNodes 是空间粗筛，hitNodeBounds 用矩形精判，hitNodes 使用组件 hit 协议。
+ * 查询的是指定 owner 的直接节点，不自动投影整棵子树、折叠重定向或检查编辑权限。 */
 export type DocumentQueries={
  readonly coverage:QueryCoverage;
  lookupElement(id:Id):ElementLookup;
@@ -101,7 +105,8 @@ function expose(document:Document,revision:number,tables:Tables,previous?:Docume
  // 关系子表按身份复用；referenceComplete 只有全部记录引用声明均可解释时才为真。
  const relation=Object.freeze({ownerMembers:previous&&tables.members===privateTables.get(previous)!.members?previous.relations.ownerMembers:readMap(tables.members),canvasChildren:previous&&tables.children===privateTables.get(previous)!.children?previous.relations.canvasChildren:readMap(tables.children),childCanvasByEntry:previous&&tables.childByEntry===privateTables.get(previous)!.childByEntry?previous.relations.childCanvasByEntry:readMap(tables.childByEntry),incidentEdges:previous&&tables.incident===privateTables.get(previous)!.incident?previous.relations.incidentEdges:readMap(tables.incident),elementReferrers:previous&&tables.elementRefs===privateTables.get(previous)!.elementRefs?previous.relations.elementReferrers:readMap(tables.elementRefs),canvasReferrers:previous&&tables.canvasRefs===privateTables.get(previous)!.canvasRefs?previous.relations.canvasReferrers:readMap(tables.canvasRefs),opaqueReferences:tables.opaque,referenceComplete:tables.opaque.size===0});
  const spatial=spatialViews(tables,previous);
- /** 从网格收集候选并做 AABB 过滤；超大查询扫描全部 entries，普通查询同时加入 oversized。 */
+ /** 从网格收集候选并做 AABB 过滤；超大查询扫描全部 entries，普通查询同时加入 oversized。
+  * 空间表只含 node；曲线命中由其它适配路径完成，返回顺序按模型插入 rank，不是渲染命中优先级。 */
  function candidates(canvas:Id,rect:Bounds){
    if(!document.canvases.has(canvas))throw fault('canvas_not_loaded',[canvas]);if(![rect.x,rect.y,rect.width,rect.height].every(Number.isFinite)||rect.width<0||rect.height<0)throw fault('invalid_query_bounds');
    // Set 合并多个格子的重复 ID；无效 Box 保留为候选，后续精判负责报告不完整。
@@ -118,9 +123,11 @@ function expose(document:Document,revision:number,tables:Tables,previous?:Docume
    document,registry:tables.registry,revision,budget:tables.budget,relations:relation,spatial,
    // 关系查询首先检查目标表项存在，再按元素/画布各自 rank 排序；不是遍历请求 queue。
    members:(canvas:Id)=>{if(!document.canvases.has(canvas))throw fault('canvas_not_loaded',[canvas]);return sortedBucket(tables.members.get(canvas)??empty,tables.order);},childCanvases:(canvas:Id)=>{if(!document.canvases.has(canvas))throw fault('canvas_not_loaded',[canvas]);return sortedBucket(tables.children.get(canvas)??empty,tables.canvasOrder);},incident:(element:Id)=>{if(!document.elements.has(element))throw fault('element_missing',[element]);return sortedBucket(tables.incident.get(element)??empty,tables.order);},orderedElements:(ids:Iterable<Id>)=>sorted(ids),orderedCanvases:(ids:Iterable<Id>)=>sorted(ids,tables.canvasOrder),candidateNodes:candidates,
-   /** 点周围容差框粗筛，再调用自定义 hit（无协议则矩形回退）；抛错项进入 unavailable。 */
+   /** 点周围容差框粗筛，再调用自定义 hit；无 node 协议或未知组件时回退到矩形，不自动列入 unavailable。
+    * 自定义 hit 抛错/返回非 boolean，或缓存 Box 非有限时才列 unavailable；命中不等于 registry 支持编辑。 */
    hitNodes(canvas:Id,point:Point,tolerance=0){if(![point.x,point.y,tolerance].every(Number.isFinite)||tolerance<0)throw fault('invalid_query_point');const hits:Id[]=[],unavailable:Id[]=[];for(const id of candidates(canvas,{x:point.x-tolerance,y:point.y-tolerance,width:2*tolerance,height:2*tolerance})){const record=document.elements.get(id)! as Extract<ElementRecord,{structure:'node'}>;try{if(!finite(tables.spatial.get(canvas)!.entries.get(id)!))throw fault('geometry_unavailable');const protocol=tables.registry.resolve(record)==='known'?tables.registry.components.get(record.componentId)?.geometry:undefined,result=protocol?.kind==='node'?protocol.hit({element:record,geometry:record.geometry,point,tolerance}):hitRectangle(record.geometry,point,tolerance);if(typeof result!=='boolean')throw fault('invalid_geometry_response');if(result)hits.push(id);}catch{unavailable.push(id);}}return Object.freeze({ids:Object.freeze(hits),complete:!unavailable.length,unavailable:Object.freeze(unavailable)});},
-   /** 对候选按旋转矩形距离精判；无效几何使 complete=false，不当作可靠 miss。 */
+   /** 对候选按旋转矩形距离精判；缓存 Box 无效使 complete=false，不当作可靠 miss。
+    * 即使本次只需矩形，前面自定义 bounds 失败产生的 NaN Box 也会让该项跳过，不绕过共享粗筛失败。 */
    hitNodeBounds(canvas:Id,point:Point,tolerance=0){if(![point.x,point.y,tolerance].every(Number.isFinite)||tolerance<0)throw fault('invalid_query_point');const ids=candidates(canvas,{x:point.x-tolerance,y:point.y-tolerance,width:2*tolerance,height:2*tolerance}),hits:Id[]=[];let complete=true;for(const id of ids){const g=(document.elements.get(id)! as Extract<ElementRecord,{structure:'node'}>).geometry,box=tables.spatial.get(canvas)!.entries.get(id)!;if(!finite(box)){complete=false;continue;}const angle=-g.rotation*Math.PI/180,c=Math.cos(angle),s=Math.sin(angle),dx=point.x-g.x-g.width/2,dy=point.y-g.y-g.height/2,x=dx*c-dy*s,y=dx*s+dy*c,ox=Math.max(0,Math.abs(x)-g.width/2),oy=Math.max(0,Math.abs(y)-g.height/2);if(Math.hypot(ox,oy)<=tolerance+Number.EPSILON*64*Math.max(1,Math.abs(point.x),Math.abs(point.y),g.width,g.height))hits.push(id);}return Object.freeze({ids:Object.freeze(hits),complete});},
  });privateTables.set(view,tables);return view;
 }
@@ -128,10 +135,12 @@ function expose(document:Document,revision:number,tables:Tables,previous?:Docume
 const queryBases=new WeakMap<DocumentQueries,DocumentQueries>();
 // 相同 namespace 来源只捕获一次只读副本，防止宿主后来修改集合污染已发布证据。
 const namespaceCopies=new WeakMap<object,ReadonlyValueSet<Id>>();
-/** 捕获外部 ID 集合的成员，缓存仅按原对象身份复用；输入合同应视为不可变值。 */
+/** 捕获外部 ID 集合的成员，缓存仅按原对象身份复用；输入合同应视为不可变值。
+ * 同一来源对象后续被原地改动，再绑定也仍取第一次副本；新的证据必须传新的集合对象。 */
 function ownedNamespace(ids:ReadonlyValueSet<Id>){let value=namespaceCopies.get(ids);if(!value){value=readSet(ids);namespaceCopies.set(ids,value);}return value;}
 /** Bind completeness to the same publication as the model, without rebuilding indexes. */
-/** 不重建索引，仅替换同次发布中的加载证据与完整性方法；未知 canvas/矛盾完整声明拒绝。 */
+/** 不重建索引，只绑定调用方提供的加载证据；检查重复/未知完整 canvas 以及 projectComplete 的显式矛盾。
+ * 不读取服务端 manifest，也不推导声明是否真实；基础 candidateNodes/关系读取仍只返回现有记录。 */
 export function withQueryCoverage(queries:DocumentQueries,input:QueryCoverage):DocumentQueries {
  const base=queryBases.get(queries)??queries,ids=Object.freeze([...input.completeCanvasIds]);
  if(new Set(ids).size!==ids.length||ids.some(id=>!base.document.canvases.has(id))||input.projectComplete&&(!input.topologyComplete||ids.length!==base.document.canvases.size))throw fault('invalid_query_coverage');
@@ -139,7 +148,8 @@ export function withQueryCoverage(queries:DocumentQueries,input:QueryCoverage):D
  const coverage=Object.freeze({...(input.elementIds?{elementIds:ownedNamespace(input.elementIds)}:{}),...(input.loadedElementIds?{loadedElementIds:ownedNamespace(input.loadedElementIds)}:{}),projectComplete:input.projectComplete,topologyComplete:input.topologyComplete,completeCanvasIds:ids}),complete=new Set(ids);
  const view:DocumentQueries=Object.freeze({...base,coverage,
    relations:Object.freeze({...base.relations,referenceComplete:base.relations.referenceComplete&&coverage.projectComplete}),
-   /** 已有记录优先 present；完整项目、命名空间排除、或已加载且有墓碑时才能判 absent。 */
+   /** 已有记录优先 present；projectComplete 可直接判缺失为 absent。
+    * 部分项目须有 elementIds：命名空间排除该 ID，或该 ID 已加载且有墓碑时才判 absent，其余 unloaded。 */
    lookupElement:(id:Id):ElementLookup=>{const element=base.document.elements.get(id);return element?Object.freeze({status:'present',element}):Object.freeze({status:coverage.projectComplete||coverage.elementIds&&(!coverage.elementIds.has(id)||coverage.loadedElementIds?.has(id)&&base.document.tombstones.has(id))?'absent':'unloaded'});},
    // 成员完整性按 owner，子树按 topology，关联边按整个项目，三者不能互相替代。
    membersResult:(canvas:Id)=>Object.freeze({ids:base.members(canvas),complete:complete.has(canvas)}),
@@ -152,13 +162,16 @@ export function withQueryCoverage(queries:DocumentQueries,input:QueryCoverage):D
  });queryBases.set(view,base);const tables=privateTables.get(base);if(tables)privateTables.set(view,tables);return view;
 }
 /** Pure derived query snapshot. Never serialize these tables or publish them as a second document. */
-/** 从零构造纯派生索引，复用同一 advance 算法，避免维护两套建表规则。 */
+/** 从零构造纯派生索引，复用 advance 建表；默认把输入当完整文档，不自动检测部分加载。
+ * 部分模型调用方必须随后 withQueryCoverage 绑定真实证据，否则默认 complete=true 不代表读取已完成。 */
 export function createDocumentQueries(document:Document,registry:Registry,revision=0,options:QueryBudget={}):DocumentQueries{return advanceDocumentQueries(undefined,document,registry,revision,undefined,options);}
 /** 在当前发布前准备下一份索引；changes 精确列出受影响 ID，否则按新旧表并集检查。
- * 必须与同一项目/registry/预算配合，revision 不可倒退，同 revision 不接受另一份 document。 */
+ * 必须与同一项目/registry/预算配合，revision 不可倒退，同 revision 不接受另一份 document。
+ * changes 是可信提示，不核对是否漏列真实差异；提供不完整/错误提示可能留下旧索引，无清单时才全表比较。 */
 export function advanceDocumentQueries(previous:DocumentQueries|undefined,document:Document,registry:Registry,revision:number,changes?:readonly Change[],options:QueryBudget={}):DocumentQueries{
  if(!Number.isSafeInteger(revision)||revision<0||previous&&(previous.document.projectId!==document.projectId||revision<previous.revision||revision===previous.revision&&document!==previous.document))throw fault('invalid_query_revision');
  const old=previous?privateTables.get(previous):undefined;if(previous&&!old)throw fault('invalid_query_snapshot');if(old&&old.registry!==registry)throw fault('query_registry_changed');if(old&&Object.keys(options).length&&!equal(old.budget,budget(options)))throw fault('query_budget_changed');if(previous?.document===document&&previous.revision===revision)return previous;
+ // 非空 options 是按默认值补齐后的完整预算声明，不是叠加旧预算的 patch；须与旧配置相等。
  // 精确 changes 限定扫描范围；ACK 等没有差异列表的路径保守比较新旧记录。
  const configuration=old?.budget??budget(options),oldDoc=previous?.document,ids=changes?new Set(changes.filter(change=>change.kind!=='canvas').map(change=>change.kind==='field'?change.target.id:change.id)):new Set([...(oldDoc?.elements.keys()??[]),...document.elements.keys()]),canvasIds=changes?new Set(changes.filter(change=>change.kind==='canvas').map(change=>change.id)):new Set([...(oldDoc?.canvases.keys()??[]),...document.canvases.keys()]);
  const members=editRelation(old?.members??new Map()),children=editRelation(old?.children??new Map()),incident=editRelation(old?.incident??new Map()),elementRefs=editRelation(old?.elementRefs??new Map()),canvasRefs=editRelation(old?.canvasRefs??new Map());let childByEntry=old?.childByEntry??new Map<Id,Id>(),forward=old?.forward??new Map<Id,References>(),opaque=old?.opaque??empty,spatial=old?.spatial??new Map<Id,Spatial>();
@@ -177,7 +190,7 @@ export function advanceDocumentQueries(previous:DocumentQueries|undefined,docume
    const oldRefs=forward.get(id),schema=after?registry.components.get(after.componentId)?.copy:undefined,referenceFieldsUnchanged=!!changes&&!replaced.has(id)&&!!schema&&schema.references.every(ref=>!dataFields.get(id)?.has(ref.path[0])),nextRefs=after?(before&&oldRefs&&before.componentId===after.componentId&&before.dataVersion===after.dataVersion&&(referenceFieldsUnchanged||equal(before.data,after.data))?oldRefs:refs(after,registry)):undefined;
    if(oldRefs!==nextRefs)for(const kind of ['elements','canvases'] as const){const table=kind==='elements'?elementRefs:canvasRefs;for(const target of oldRefs?.[kind]??[])if(!nextRefs?.[kind].has(target))table.change(target,id,false);for(const target of nextRefs?.[kind]??[])if(!oldRefs?.[kind].has(target))table.change(target,id,true);}
    if(oldRefs!==nextRefs&&(!!oldRefs?.complete!==!!nextRefs?.complete||!equal([...(oldRefs?.elements??[])],[...(nextRefs?.elements??[])])||!equal([...(oldRefs?.canvases??[])],[...(nextRefs?.canvases??[])])||!oldRefs&&nextRefs||oldRefs&&!nextRefs)){if(forward===old?.forward)forward=new Map(forward);if(nextRefs)forward.set(id,nextRefs);else forward.delete(id);}
-   // 无法解释引用的活元素进入 opaque 集合，提示调用方不能把空引用结果当作完整证明。
+   // 无法解释引用的活元素进入 opaque 集合；opaqueReferences 描述引用可解释性，不表示整元素已失去几何/显示能力。
    const shouldOpaque=!!after&&!nextRefs?.complete;if(opaque.has(id)!==shouldOpaque){const next=new Set(opaque);if(shouldOpaque)next.add(id);else next.delete(id);opaque=readSet(next);}
    // 自定义几何未声明 dataDependencies 时保守重建；明确空数组则普通 data 编辑不重算 Box。
    const was=before?.structure==='node'?before:undefined,now=after?.structure==='node'?after:undefined,protocol=now&&registry.resolve(now)==='known'?registry.components.get(now.componentId)?.geometry:undefined,shapeDataChanged=protocol?.kind==='node'&&!equal(before?.data,after?.data)&&(protocol.dataDependencies===undefined||protocol.dataDependencies.some(key=>!equal(before?.data[key],after?.data[key])));if(was?.ownerCanvasId!==now?.ownerCanvasId||!equal(was?.geometry,now?.geometry)||before?.componentId!==after?.componentId||before?.dataVersion!==after?.dataVersion||shapeDataChanged){if(was)spatialChange(was.ownerCanvasId,id,null);if(now)spatialChange(now.ownerCanvasId,id,nodeBox(now,registry));}
@@ -187,6 +200,7 @@ export function advanceDocumentQueries(previous:DocumentQueries|undefined,docume
  for(const id of canvasIds){const before=oldDoc?.canvases.get(id)?.parent,after=document.canvases.get(id)?.parent;if(equal(before,after)||!after)continue;children.change(after.canvasId,id,true);if(childByEntry===old?.childByEntry)childByEntry=new Map(childByEntry);childByEntry.set(after.entryElementId,id);}
  // 删除旧格子占用、再插新 Box；超限/无效 Box 放 oversized，不能因预算或错误漏出候选。
  if(spatialChanges.size){spatial=new Map(spatial);for(const[canvas,updates]of spatialChanges){const base=spatial.get(canvas),entries=new Map(base?.entries),grid=editRelation(base?.cells??new Map()),large=new Set(base?.oversized??[]);for(const[id,box]of updates){const before=entries.get(id);if(before)for(const key of cells(before,configuration.maxElementCells,configuration.cellSize)??[])grid.change(key,id,false);large.delete(id);if(box){entries.set(id,box);const keys=cells(box,configuration.maxElementCells,configuration.cellSize);if(keys)for(const key of keys)grid.change(key,id,true);else large.add(id);}else entries.delete(id);}if(entries.size)spatial.set(canvas,{entries,cells:grid.finish(),oversized:readSet(large)});else spatial.delete(canvas);}}
- // 关系桶 finish 后装配；只在增删记录时重算全局插入顺序，最后返回与文档同 revision 的视图。
+ // 关系桶 finish 后装配；精确 changes 未报告增删时复用旧 rank，否则按文档迭代顺序重算/比较。
+ // expose 返回基础完整 coverage，不继承旧查询的加载声明；宿主应在同次发布重新绑定当前 coverage。
  const tables:Tables={registry,budget:configuration,members:members.finish(),children:children.finish(),childByEntry,incident:incident.finish(),elementRefs:elementRefs.finish(),canvasRefs:canvasRefs.finish(),forward,opaque,spatial,order:old&&changes&&!changes.some(change=>change.kind==='element'&&(!change.before||!change.after))?old.order:order(old?.order,document.elements.keys()),canvasOrder:old&&changes&&!changes.some(change=>change.kind==='canvas'&&(!change.before||!change.after))?old.canvasOrder:order(old?.canvasOrder,document.canvases.keys())};return expose(document,revision,tables,previous);
 }

src/lib/canvas-core/registry.ts

@@ -2,6 +2,7 @@
  * 组件定义的装配与显式数据迁移。Registry 保存可复用的定义/handler，不保存元素实例或 view 状态。
  * 装配时把 feature 合成为 componentId→capability→handler 查找表，冲突即拒绝，避免依赖安装顺序。
  * 迁移只生成候选记录，不写 editor；调用方负责把结果作为一次合法事务发布。
+ * 冻结的是定义配置容器，handler 函数及其闭包仍沿用；容器只读不证明外部上下文不会变化。
  */
 import type { Capability, CapabilityHandler, ComponentDefinition, Data, ElementRecord, Feature, Json, Registry, ReadonlyValueSet } from './types.ts';
 import { clone, fault, freeze, readMap, readSet } from './values.ts';
@@ -11,7 +12,8 @@ export function defineFeature(id: string, handlers: Partial<Record<Capability, C
   if (!id || !Object.values(handlers).length || Object.values(handlers).some(value => typeof value !== 'function')) throw fault('invalid_feature');
   return freeze({ id, handlers: { ...handlers } });
 }
-/** 校验组件定义与复制/几何协议，捕获其配置容器，防止装配后被外部改写。 */
+/** 校验组件定义与复制/几何协议，并复制声明过的配置容器后冻结。
+ * validate、几何方法、feature handler 和 migration 函数本身保持原引用，不复制函数闭包。 */
 export function defineComponent(definition: ComponentDefinition): ComponentDefinition {
   if (!definition.id || !Number.isSafeInteger(definition.dataVersion) || definition.dataVersion < 1 || typeof definition.validate !== 'function') throw fault('invalid_component');
   // 复制路径访问自有字段，禁止原型污染键；数组遍历由 * 路径段表达。
@@ -47,7 +49,8 @@ export function createRegistry(definitions: readonly ComponentDefinition[]): Reg
     }
     components.set(definition.id, definition); capabilities.set(definition.id, readSet(found.keys())); handlers.set(definition.id, readMap(found));
   }
-  // 只识别已安装的精确数据版本；可保留未知记录，但不能假设它可被当前 handler 编辑。
+  // 这里只按 componentId+dataVersion 分派，不执行 data schema 或结构校验；known 不是整条记录合法的证明。
+  // 可保留未知记录，但不能假设它可被当前 handler 编辑。
   const resolve: Registry['resolve'] = element => {
     const definition = components.get(element.componentId);
     if (!definition) return 'unknown-component';
@@ -59,10 +62,10 @@ export function createRegistry(definitions: readonly ComponentDefinition[]): Reg
     supports: (element: ElementRecord, capability: Capability) => resolve(element) === 'known' && !!capabilities.get(element.componentId)?.has(capability) });
 }
 /** Capture each field once; JSON.stringify would silently erase invalid values. */
-/** 迁移边界的严格 JSON 捕获：每个字段只读取一次，捕获后递归冻结。
+/** 迁移边界的 JSON 捕获：遍历的自有可枚举字符串字段取值一次，捕获后递归冻结。
  * 不先 JSON.stringify，因为 undefined、函数、非有限数会被丢弃/改值，掩盖非法迁移输出。 */
 function captureMigrationData(input:unknown,id:string):Data {
-  // 统一带原元素 ID 抛出 invalid_migration，便于调用方保留原记录并报告失败对象。
+  // 本函数发现形状非法时带原元素 ID 抛 invalid_migration；getter/转换器自身抛出的异常不在这里包装。
   const invalid=():never=>{throw fault('invalid_migration',[id]);};
   // 递归接收 JSON 原子、稠密数组和普通对象；深度上限防止循环/异常深输入无限递归。
   const capture=(value:unknown,depth=0):Json=>{
@@ -78,6 +81,7 @@ function captureMigrationData(input:unknown,id:string):Data {
       const result:Json[]=[];for(let index=0;index<value.length;index++){if(!Object.hasOwn(value,index))return invalid();result.push(capture(value[index],depth+1));}return freeze(result);
     }
     if(Object.getPrototypeOf(value)!==Object.prototype)return invalid();
+    // Object.keys 不遍历不可枚举字段；getter 在这里读取，结果复制为普通数据属性，不保留原描述符。
     const source=value as Record<string,unknown>;
     return freeze(Object.fromEntries(Object.keys(source).map(key=>[key,capture(source[key],depth+1)])));
   };
@@ -88,9 +92,11 @@ function captureMigrationData(input:unknown,id:string):Data {
 
 /** 按 migrations[旧版本] 逐级转换到当前版本，每步重新捕获，最后通过目标 schema。
  * 未知组件/未来版本原样保留；缺 converter 或任一步失败抛错，不返回半迁移记录。
- * ID、incarnation、owner 与其它信封字段不变，转换器只负责 data。 */
+ * ID、incarnation、owner 与其它信封字段值不变，转换器只负责 data。
+ * 其余信封对象按引用沿用，返回时 freeze 可能冻结这些共享嵌套值；调用方应传入已捕获的记录。 */
 export function migrateElement(element: ElementRecord, registry: Registry): ElementRecord {
   const definition = registry.components.get(element.componentId);
+  // 未安装/未来版本保持原引用且不捕获；即使版本已是当前版本，下方仍捕获 data 并校验 schema。
   if (!definition || element.dataVersion > definition.dataVersion) return element;
   let data = captureMigrationData(element.data,element.id), version = element.dataVersion;
   // 一个 converter 仅前进一个版本，不把“有版本号”当成自动跨版本兼容承诺。

src/lib/canvas-core/structure.ts

@@ -1,6 +1,7 @@
 /**
  * 文档结构修改的纯规划函数：删除拥有子树，以及重挂后的连线 owner 修复。
  * 只返回条件 Change，不直接发布 editor 状态；调用方把它们合入一次事务再校验。
+ * 文档应是有效、已捕获的不可变快照；返回 before 保留记录引用，freeze 不提供任意外部输入隔离。
  */
 import type {DocumentQueries} from './queries.ts';
 import type { Change, Document, Id, Target } from './types.ts';
@@ -18,11 +19,13 @@ export function removalChanges(document:Document,target:Target,queries?:Document
     while(stack.length){const id=stack.pop()!;if(canvases.has(id))continue;canvases.add(id);stack.push(...queries.childCanvases(id));for(const member of queries.members(id))elements.add(member);}
     // 关联边可能属于更上级 canvas，即使不在子树成员表中也必须随端点删除。
     for(const id of [...elements])for(const edge of queries.incident(id))elements.add(edge);
+    // 按原表顺序输出元素删除，再输出 canvas 删除；最终关系合法性在事务整批完成后检查。
     return freeze([...queries.orderedElements(elements).map(id=>({kind:'element' as const,id,before:document.elements.get(id)!,after:null})),...queries.orderedCanvases(canvases).map(id=>({kind:'canvas' as const,id,before:document.canvases.get(id)!,after:null}))]);
   }
   // 扫描路径构造 parent→children 临时表；Set 去重，stack 避免 JS 递归调用栈增长。
   const element=targetElement(document,target),elements=new Set<Id>([element.id]),canvases=new Set<Id>(),children=new Map<Id,Id[]>();
   for(const canvas of document.canvases.values())if(canvas.parent){const list=children.get(canvas.parent.canvasId)??[];list.push(canvas.id);children.set(canvas.parent.canvasId,list);}
+  // 只从“目标是入口”的子 canvas 开始，不因节点视觉上处在某个矩形内就扩大删除范围。
   const stack=[...document.canvases.values()].filter(canvas=>canvas.parent?.entryElementId===element.id).map(canvas=>canvas.id);
   while(stack.length){const id=stack.pop()!;if(canvases.has(id))continue;canvases.add(id);for(const child of children.get(id)??[])stack.push(child);}
   // 先收集全部被删成员，再找相关边，防止边扫描先后顺序影响删除结果。
@@ -35,11 +38,13 @@ export function removalChanges(document:Document,target:Target,queries?:Document
 }
 
 /** Ownership changes and their curve coordinates are one operation, with the same stable edge identity. */
-/** 端点重挂后，把边移到两端所属 canvas 的最近共同上级，保持边 ID/incarnation。
- * 曲线坐标属于旧 owner 空间，因此 owner 与 path 必须作为同一操作一起转换。 */
+/** 端点或端点 owner 改变后，把边移到两端所属 canvas 的最近共同上级，保持边 ID/incarnation。
+ * 曲线坐标属于旧 owner 空间，因此需要转换时 owner 与 path 必须作为同一操作一起提交。
+ * 只修复 owner 发生变化的边；不会仅因祖先几何变了就重写同 owner 的局部路径。 */
 export function repairConnectionOwners(before:Document,document:Document):readonly Change[] {
   const changes:Change[]=[];
   for(const edge of document.elements.values())if(edge.structure==='connection'){
+    // 缺端点暂时跳过，交给整图校验拒绝；此规划器不会自行补端点或删除悬空边。
     const source=document.elements.get(edge.source.elementId),target=document.elements.get(edge.target.elementId);if(!source||!target)continue;
     const owner=commonCanvas(document,source.ownerCanvasId,target.ownerCanvasId);if(owner===edge.ownerCanvasId)continue;
     // 旧 owner 可能已从新文档移除：优先用 before 的变换解释旧曲线，再转到新 owner。
@@ -47,5 +52,6 @@ export function repairConnectionOwners(before:Document,document:Document):readon
     changes.push({kind:'field',target:{id:edge.id,incarnation:edge.incarnation},field:'ownerCanvasId',before:edge.ownerCanvasId,after:owner});
     if(!equal(edge.path,path))changes.push({kind:'field',target:{id:edge.id,incarnation:edge.incarnation},field:'path',before:edge.path,after:path});
   }
+  // 这里只返回补偿变化；document 参数不在本函数内被替换或发布。
   return freeze(changes);
 }

src/lib/canvas-core/types.ts

@@ -17,7 +17,8 @@ export type Point = { readonly x: number; readonly y: number };
 export type Geometry = Point & { readonly width: number; readonly height: number; readonly rotation: number };
 /** 拥有树的一条记录；根的 parent 为 null，子 canvas 指向父 canvas 及父内的入口元素。 */
 export type CanvasRecord = { readonly id: Id; readonly parent: null | { readonly canvasId: Id; readonly entryElementId: Id } };
-/** 元素 ID 加生命周期 incarnation；删除后恢复同 ID 时换代，旧回调不能命中新对象。 */
+/** 元素 ID 加生命周期 incarnation；删除后恢复同 ID 时换代，由 targetElement 等运行时检查拦截旧目标。
+ * 类型本身不验证代次数值，也不是权限凭证。 */
 export type Target = { readonly id: Id; readonly incarnation: number };
 /** 连线指向的节点及可选端口；端点的 owner 不必等于连线 owner。 */
 export type Endpoint = { readonly elementId: Id; readonly portId?: string };
@@ -28,11 +29,13 @@ export type ElementRecord = ElementBase & (
   | { readonly structure: 'node'; readonly geometry: Geometry }
   | { readonly structure: 'connection'; readonly source: Endpoint; readonly target: Endpoint; readonly path: Json }
 );
-/** 项目规范化事实表；父子/引用关系通过 ID 连接，tombstones 保留已死代次下限。 */
+/** 项目规范化事实表；父子/引用关系通过 ID 连接，tombstones 保存每个 ID 已死亡的最大代次。
+ * Map 在运行时使用，持久化要经 codec；readonly 类型不等于 JSON 可直接序列化或输入已校验。 */
 export type Document = { readonly projectId: Id; readonly canvases: ReadonlyMap<Id, CanvasRecord>; readonly elements: ReadonlyMap<Id, ElementRecord>; readonly tombstones: ReadonlyMap<Id, number> };
 /** 可修改字段白名单；data. 后缀表示一个顶层键，整份 geometry 是一个条件字段。 */
 export type Field = `data.${string}` | 'geometry' | 'ownerCanvasId' | 'source' | 'target' | 'path';
-/** 字段条件变化：before/after 与存在性一起比较，使缺失和显式 null 不混淆。 */
+/** 字段条件变化；data 顶层键结合 beforePresent/afterPresent 区分缺失与显式 null，缺省存在性为 true。
+ * 非 data 字段按整体 before/after 比较，不用这两个标记表达信封字段缺失。 */
 export type FieldChange = { readonly kind: 'field'; readonly target: Target; readonly field: Field; readonly before: Json; readonly after: Json; readonly beforePresent?: boolean; readonly afterPresent?: boolean };
 /** 统一变化格式；元素/canvas 的 null 表示不存在，可表达创建、删除、替换及反向修改。 */
 export type Change = FieldChange
@@ -59,13 +62,15 @@ export type Rejected = { readonly status: 'rejected'; readonly code: string; rea
 export type Applied = { readonly status: 'applied'; readonly revision: number; readonly operationIds: readonly Id[]; readonly historyEntryId?: Id };
 /** 公共命令结果的判别联合，调用方必须按 status 处理失败。 */
 export type Result = Applied | Rejected;
-/** 一个逻辑撤销单元，包含正向变化和关联操作 ID；不把每个 pointermove 当一项。 */
+/** 一个逻辑撤销单元，保存正向 changes 和关联操作 ID；一次 entry 可按 groupId 合并多次提交。
+ * undo 时计算逆变化，恢复代次后可修订这些正向 changes；它不是永远不变的原请求 body。 */
 export type HistoryEntry = { readonly id: Id; readonly label: string; readonly changes: readonly Change[]; readonly operationIds: readonly Id[]; readonly groupId?: Id };
 /** undo/redo 两个 ID 栈（尾部为栈顶），entries 保存记录，栈项与 ledger 事实分开。 */
 export type HistoryState = { readonly undo: readonly Id[]; readonly redo: readonly Id[]; readonly entries: ReadonlyMap<Id, HistoryEntry> };
 /** 图片默认尺寸解析对原创建历史的修正计划；绑定目标代次与创建 entry，避免多造用户步骤。 */
 export type CreationSizeEffect = { readonly version: 1; readonly kind: 'creation-size'; readonly entryId: Id; readonly target: Target; readonly size: { readonly width: number; readonly height: number } };
-/** 所有意图共用的身份、单调序列、参与 canvas、changes、依赖及可选历史修正证据。 */
+/** 所有意图共用的身份、单调序列、参与 canvas、changes、依赖及可选历史修正证据。
+ * operationSchemaVersion 是意图解释版本，historyTransition/historyEffect 是本地历史证据，不是服务端请求版本。 */
 type IntentBase = { readonly historyEffect?:CreationSizeEffect; readonly historyTransition?:HistoryTransition; readonly id: Id; readonly operationSchemaVersion: 1; readonly sequence: number; readonly origin: Origin; readonly canvasIds: readonly Id[]; readonly changes: readonly Change[]; readonly dependencies: readonly Id[] };
 /** 生成任务的稳定输入；目标代次、模型/提示词/参数随逻辑操作保存，凭证不入文档。 */
 export type RunInput = { readonly target: Target; readonly boardId: Id; readonly modelId: string; readonly prompt: string; readonly parameters: Data; readonly propagate: boolean };
@@ -84,24 +89,31 @@ export type CoreSnapshot = { readonly revision: number; readonly document: Docum
 export type Snapshot<Runtime = unknown> = CoreSnapshot & { readonly rootRevision: number; readonly runtime: Runtime };
 /** 命令或能力预检查结果；enabled=false 给出原因，不以按钮是否灰掉代替真正提交校验。 */
 export type Availability = { readonly enabled: true } | { readonly enabled: false; readonly code: string; readonly targets: readonly Id[] };
-/** 只暴露读能力的集合合同，forEach 也只接触只读视图。 */
+/** 类型合同仅列读方法；真正隐藏 add/delete 和保护 forEach 第三个参数要由 readSet 等工厂实现。
+ * TypeScript 结构兼容并不阻止外部把原生 Set 当作这个接口传入。 */
 export type ReadonlyValueSet<T> = Pick<ReadonlySet<T>, 'size' | 'has' | 'entries' | 'keys' | 'values' | typeof Symbol.iterator> & { forEach(callback: (value: T, value2: T, set: ReadonlyValueSet<T>) => void): void };
 /** 编辑行为的稳定标识，组件通过安装 feature 获得对应 handler。 */
 export type Capability = 'geometry.move' | 'geometry.resize' | 'geometry.rotate' | 'content.edit' | 'connection.edit';
-/** 读取当前元素和输入，返回字段变化；不能越权写其它元素，也不在这里发布或访问网络。 */
+/** 读取当前元素和输入，返回字段变化；约定只规划而不发布/访问网络。
+ * editor 再检查输出目标/字段；函数类型不自动证明实现纯净，也不能回滚 handler 自己的外部副作用。 */
 export type CapabilityHandler = (context: { readonly element: ElementRecord; readonly input: Readonly<Record<string, unknown>> }) => readonly FieldChange[];
 /** 可复用行为集合；同一组件安装重复 capability 时 registry 明确拒绝。 */
 export type Feature = { readonly id: string; readonly handlers: Readonly<Partial<Record<Capability, CapabilityHandler>>> };
 /** Path segments address own fields; * iterates array entries. many marks a terminal ID array. */
-/** 声明 data 内的 ID 路径；* 遍历数组，many 表示终端 ID 数组，external 决定外部引用保留/拒绝。 */
+/** 声明 data 内的 ID 路径；* 遍历数组，many 表示终端 ID 数组。
+ * external 是深复制的外部引用策略；其它规划器可复用路径，但不必沿用复制的 preserve/reject 语义。 */
 export type CopyReference = { readonly path: readonly string[]; readonly target: 'element' | 'canvas'; readonly many?: boolean; readonly external: 'preserve' | 'reject' };
 /** 深复制时只重写声明引用并删 omit 字段；不能扫描任意相似字符串猜测引用。 */
 export type CopySchema = { readonly references: readonly CopyReference[]; readonly omit: readonly (readonly string[])[] };
 /** 节点几何协议的计算输入；geometry 可是预览值，不要求等于记录的 committed 几何。 */
 export type NodeGeometryContext={readonly element:Extract<ElementRecord,{structure:'node'}>;readonly geometry:Geometry};
-/** 版本化的纯几何扩展：节点 bounds/hit，边 strokeWidth/segments；不依赖 renderer 实例。 */
+/** 版本化的纯几何扩展约定：节点 bounds/hit，边 strokeWidth/segments；不依赖 renderer 实例。
+ * node dataDependencies 缺省时数据变化保守重算，空数组表示不依赖 data；role 提示 bounds 的用途。
+ * connection 输入已含展示锚点/变换，displayPath 可为 undefined；返回值仍由查询边界验证，类型不代替校验。 */
 export type GeometryProtocol=({readonly kind:'node';readonly version:1;readonly dataDependencies?:readonly string[];bounds(context:NodeGeometryContext&{readonly role:'logical'|'hit'|'paint'}):import('./geometry.ts').Rect;hit(context:NodeGeometryContext&{readonly point:Point;readonly tolerance:number}):boolean}|{readonly kind:'connection';readonly version:1;strokeWidth(context:{readonly element:Extract<ElementRecord,{structure:'connection'}>;readonly transform:{readonly x:number;readonly y:number;readonly scale:number;readonly rotation:number}}):number;segments(context:{readonly element:Extract<ElementRecord,{structure:'connection'}>;readonly source:import('./geometry.ts').Connector;readonly target:import('./geometry.ts').Connector;readonly displayPath:Json|undefined;readonly transform:{readonly x:number;readonly y:number;readonly scale:number;readonly rotation:number}}):readonly import('./geometry.ts').Cubic[]});
-/** 一种组件的定义：精确版本/schema、feature、迁移、资源字段、几何及复制声明，可服务多个实例。 */
+/** 一种组件的定义，可服务多个实例：dataVersion/validate、features、逐级 migrations、顶层 resourceFields、geometry 和 copy。
+ * 未提供 copy 不表示可以猜引用复制；resourceFields 只声明资源扫描入口，不在定义里保存文件字节或用户凭证。 */
 export type ComponentDefinition = { readonly id: string; readonly dataVersion: number; readonly structure: ElementRecord['structure']; readonly features: readonly Feature[]; readonly validate: (data: Data) => boolean; readonly migrations?: Readonly<Record<number, (data: Data) => Data>>; readonly resourceFields?: readonly string[]; readonly geometry?:GeometryProtocol; readonly copy?: CopySchema };
-/** 只读定义与编译后能力表；resolve 区分未知组件和不支持版本，supports 只允许精确已知版本。 */
+/** 只读定义与编译后能力表；resolve 只按组件 ID/精确数据版本分类，不执行 data schema。
+ * supports 还要求 capability 已安装，仍不代替 policy、命令规划或最终文档校验。 */
 export type Registry = { readonly components: ReadonlyMap<string, ComponentDefinition>; readonly capabilities: ReadonlyMap<string, ReadonlyValueSet<Capability>>; readonly handlers: ReadonlyMap<string, ReadonlyMap<Capability, CapabilityHandler>>; readonly resolve: (element: ElementRecord) => 'known' | 'unknown-component' | 'unsupported-version'; readonly supports: (element: ElementRecord, capability: Capability) => boolean };

src/lib/canvas-core/units.ts

@@ -30,13 +30,15 @@ export function presentationRecord(value:Json|undefined):Readonly<Record<string,
   unitScale(value);return value;
 }
 /** Normalize only the framework-owned unit field; all other presentation properties survive. */
-/** 返回替换比例后的元数据：等效值复用原对象，比例为 1 时省略保留字段。
+/** 返回替换比例后的元数据：等效值原样复用；需要重写且新比例为 1 时才删除保留字段。
  * 仅更新 unitScale，不清掉宿主扩展字段；字段全部清空时返回 undefined。 */
 export function withUnitScale(value:Json|undefined,scale:number):Json|undefined {
   if(!Number.isFinite(scale)||scale<=0)throw fault('invalid_presentation_units');
   // 坐标换算可能产生接近 1 的浮点误差，统一表示能减少无意义的模型修改。
   const normalized=closeNumber(scale,1)?1:scale;
+  // no-op 先返回，因此显式 unitScale:1 不一定被删；原始值/数组按默认比例 1 等效时也可原样通过。
   if(closeScale(unitScale(value),normalized))return value;
+  // 只有确实改比例才要求元数据可合并，拒绝原始值/数组，避免把宿主扩展值覆盖成对象。
   const fields=new Map(Object.entries(presentationRecord(value)));
   if(normalized===1)fields.delete('unitScale');else fields.set('unitScale',normalized);
   return fields.size?Object.fromEntries(fields):undefined;

src/lib/canvas-core/values.ts

@@ -5,11 +5,13 @@
  */
 import type { Id, Json, ReadonlyValueSet } from './types.ts';
 
-/** 构造携带稳定错误码和相关对象 ID 的错误，供命令层返回可解释的拒绝结果。 */
+/** 构造携带稳定错误码和相关对象 ID 的错误，供命令层返回可解释的拒绝结果。
+ * targets 沿用传入数组引用；这个辅助函数本身不捕获或冻结错误明细。 */
 export function fault(code: string, targets: readonly Id[] = []): Error & { code: string; targets: readonly Id[] } {
   return Object.assign(new Error(code), { code, targets });
 }
-/** 将捕获的异常归一化为只读 rejected 结果；无领域错误码时使用 invalid_command。 */
+/** 将捕获的异常归一化为浅冻结的 rejected 外壳；无领域错误码时使用 invalid_command。
+ * 已有 targets 数组仍沿用原引用，不应把外壳冻结解释为整个错误结果深度不可变。 */
 export function reject(error: unknown) {
   const value = error as { code?: string; targets?: readonly string[] };
   return Object.freeze({ status: 'rejected' as const, code: value?.code || 'invalid_command', targets: value?.targets || [] });
@@ -24,13 +26,15 @@ export function freeze<T>(value: T): T {
   return value;
 }
 /** JSON 往返复制已验证的数据，切断共享引用；undefined 原样返回。
- * 此处不是校验器：JSON 会丢弃某些非法字段，因此外部输入必须在复制前验证。 */
+ * 此处不是校验器：JSON 会执行 toJSON、读取可枚举字段并丢弃/改写不支持的值。
+ * 不保留原型、描述符或共享子对象身份；需要严格输入语义时须在调用边界捕获。 */
 export function clone<T>(value: T): T {
   if (value === undefined) return value;
   return JSON.parse(JSON.stringify(value)) as T;
 }
-/** 按可枚举自有键递归比较 JSON 风格的值；数组与对象不能互相视为相等。
- * 不处理任意循环对象，也不把 Map/Set 等实例当成业务值来比较。 */
+/** 先以 Object.is 判断，再按可枚举自有字符串键递归比较 JSON 风格的值；数组与对象不能互相视为相等。
+ * 不检查 Symbol/不可枚举字段，数组长度本身也不在 Object.keys 中；稀疏数组不适合作为此比较器的输入。
+ * 不处理任意循环对象，也不提供 Map/Set 成员比较语义。 */
 export function equal(a: unknown, b: unknown): boolean {
   if (Object.is(a, b)) return true;
   if (!a || !b || typeof a !== 'object' || typeof b !== 'object' || Array.isArray(a) !== Array.isArray(b)) return false;
@@ -46,6 +50,7 @@ export function isOwnedMapView(value:object){return ownedMapViews.has(value);}
 /** 复制表成员并仅暴露读取能力，外部既拿不到原 Map，也拿不到 set/delete。
  * value 保留原引用，深度不可变性由生产这些 value 的模块负责。 */
 export function readMap<K, V>(input: ReadonlyMap<K, V>): ReadonlyMap<K, V> {
+  // 从此以后 input 的增删与本视图无关；但 K/V 对象仍共享引用，键/值本身不是在此深复制的。
   const map = new Map(input);
   const view: ReadonlyMap<K, V> = {
     get size() { return map.size; }, get: key => map.get(key), has: key => map.has(key),
@@ -58,6 +63,7 @@ export function readMap<K, V>(input: ReadonlyMap<K, V>): ReadonlyMap<K, V> {
 }
 /** 捕获一份成员集合并隐藏 add/delete；回调同样只接触只读视图。 */
 export function readSet<T>(input: Iterable<T>): ReadonlyValueSet<T> {
+  // 成员表独立于原 iterable，成员若为对象则仍保留原身份；隐藏可变方法并不冻结对象成员。
   const set = new Set(input);
   const view: ReadonlyValueSet<T> = {
     get size() { return set.size; }, has: key => set.has(key), entries: () => set.entries(), keys: () => set.keys(), values: () => set.values(),
@@ -66,7 +72,9 @@ export function readSet<T>(input: Iterable<T>): ReadonlyValueSet<T> {
   return Object.freeze(view);
 }
 /** 递归检查 JSON 值域：排除 undefined/函数/非有限数，最多允许 64 层。
- * 这里只检查值形状，不验证组件 schema，也不是所有原型/属性描述符的严格捕获器。 */
+ * 对象要求 Object.prototype 原型，但只遍历 Object.values；Symbol/不可枚举属性不参与。
+ * 数组用 every 跳过空洞，也不检查额外属性；它不是稠密数组或所有属性描述符的严格捕获器。
+ * 校验读取可能触发 getter；这里不证明组件 schema、输入稳定性或数据所有权。 */
 export function validJson(value: unknown, depth = 0): value is Json {
   if (depth > 64) return false;
   if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;

src/lib/canvas-runtime/ledger.ts

@@ -26,14 +26,17 @@ export type FrozenRequest = {
 };
 /** 意图及其本地解析状态；blocked 不等于丢弃，elided/retired 不等于收到服务器 applied 回执。 */
 export type OperationRecord = { readonly intent: OperationIntent; readonly phase: 'pending' | 'frozen' | 'resolved' | 'blocked'; readonly requestId?: Id; readonly blockers: readonly string[]; readonly resolution?: 'applied' | 'not-applied' | 'superseded' | 'discarded' | 'satisfied' | 'elided'; readonly elisionId?: Id; readonly elision?: ElisionProof; readonly recoveryId?: Id; readonly replacementId?: Id; readonly basePresence: Readonly<Record<Id, Presence>> };
-/** generation 随账本事实改变递增，durableGeneration 仅确认已实际存储的前缀。 */
+/** generation 随账本事实改变递增；durableGeneration 是宿主报告的已存前缀。
+ * markDurable 只检查水位范围，本模块不访问存储或证明 fsync/事务真的完成。 */
 export type LedgerSnapshot = { readonly generation: number; readonly durableGeneration: number; readonly operations: ReadonlyMap<Id, OperationRecord>; readonly requests: ReadonlyMap<Id, FrozenRequest> };
 
 /** A field-safe compressor for a wholly unsent segment. Frozen records never enter here. */
-/** 仅压缩完全未冻结的变化段：create 后字段修改并入新对象，同字段连续变化合并。
- * preserveLifecycle 保留创建/删除，preserveChecks 保留条件 no-op；不能用最后整节点覆盖替代字段链。 */
+/** 用于调用方已确认完全未冻结的变化段：合并 create 后字段修改及同字段链。
+ * 本函数不读 ledger、basePresence 或 possiblyApplied，不能单独证明可抵消已发送/未知结果的生命周期。
+ * preserveLifecycle 只阻止 create→delete 抵消，preserveChecks 只保留合并后字段 no-op；不是停用所有压缩。 */
 export function compressChanges(changes: readonly Change[], options: { preserveLifecycle?: boolean; preserveChecks?: boolean } = {}): readonly Change[] {
-  // positions 按元素/canvas ID 保存结果索引栈，只尝试合并同对象最近变化，保留原条件顺序。
+  // positions 按元素/canvas ID 保存索引栈，只尝试同对象最近一项；其它对象的变化可以夹在两项之间。
+  // 若同对象中间出现不同字段，则不跨过它继续向前找同字段，因此不是任意字段的全段最后值覆盖。
   const result: (Change | undefined)[] = [], positions = new Map<string, number[]>();
   for (const change of changes) {
     const id = change.kind === 'field' ? change.target.id : change.id;
@@ -57,7 +60,8 @@ export function compressChanges(changes: readonly Change[], options: { preserveL
   return freeze(result.filter((change): change is Change => change !== undefined));
 }
 
-/** 从已有快照复制可变表，所有有效修改后重新捕获只读快照；旧 Snapshot 的成员不会改变。 */
+/** 从已有快照复制 Map 成员，修改后发布新的只读表视图；不在此验证完整恢复 DTO。
+ * 初始记录沿用引用，宿主须先解码捕获为不可变记录；构造器不是任意外部对象的深隔离入口。 */
 export function createLedger(initial?: LedgerSnapshot) {
   let generation = initial?.generation ?? 0, durableGeneration = initial?.durableGeneration ?? 0;
   const operations = new Map(initial?.operations), requests = new Map(initial?.requests);
@@ -84,7 +88,8 @@ export function createLedger(initial?: LedgerSnapshot) {
   return Object.freeze({
     /** 读取最新捕获的只读事实，不暴露内部可变表。 */
     getSnapshot: () => cached,
-    /** 校验身份/序列/基线与依赖，再添加 pending；同 ID 同意图幂等，改意图则拒绝。 */
+    /** 检查单条身份、正安全整数序列、基线枚举和依赖，再添加 pending。
+     * 不在此证明全账本 sequence 唯一/递增；同 ID 同意图直接返回，也不会更新第一次的 basePresence。 */
     add(intent: OperationIntent, basePresence: Readonly<Record<Id, Presence>>) {
       if (!intent.id || !Number.isSafeInteger(intent.sequence) || intent.sequence < 1 || new Set(intent.dependencies).size !== intent.dependencies.length || Object.values(basePresence).some(value => !['absent', 'exists', 'unknown'].includes(value))) throw fault('invalid_operation');
       const existing = operations.get(intent.id);
@@ -99,8 +104,9 @@ export function createLedger(initial?: LedgerSnapshot) {
     },
     /** 给可变意图设置/清除 blocker；有原因变 blocked，无原因回 pending，不改冻结请求。 */
     block(id: Id, reasons: readonly string[]) { const operation = operations.get(id); if (!operation || !['pending', 'blocked'].includes(operation.phase)) return; operations.set(id, freeze({ ...operation, phase: reasons.length ? 'blocked' : 'pending', blockers: [...reasons] })); changed(); },
-    /** 原子绑定多个 ready 意图到同一请求；参与者版本精确覆盖、类型一致、依赖已解决或在同批。
-     * 只在这里序列化 payload 一次，后续 submit/query 都使用保存的 body 和请求 ID。 */
+    /** 完成输入/ready 检查后，同次更新请求和所有操作的绑定：参与版本覆盖、类型一致，依赖已解决或在同批。
+     * payload 在这里 JSON 序列化一次，后续沿用 body/ID；wire 语义、意图到参与者的推导由编译/调度层核对。
+     * 这次内存更新本身不等于一次持久事务，也不自动取得 scheduler claims。 */
     freeze(input: { id: Id; kind?: FrozenRequest['kind']; ownerCanvasId?: Id; runId?: Id; protocolVersion?: number; operationIds: readonly Id[]; canvasIds: readonly Id[]; expectedVersions: Readonly<Record<Id, number>>; payload: Json }) {
       if (!input.id || requests.has(input.id) || !Number.isSafeInteger(input.protocolVersion ?? 1) || (input.protocolVersion ?? 1) < 1 || !input.operationIds.length || (!input.canvasIds.length && input.kind!=='asset.upload' && input.kind!=='run.cancel') || !validJson(input.payload) || new Set(input.operationIds).size !== input.operationIds.length || new Set(input.canvasIds).size !== input.canvasIds.length || Object.keys(input.expectedVersions).length !== input.canvasIds.length || input.canvasIds.some(id => !id || !Number.isSafeInteger(input.expectedVersions[id]) || input.expectedVersions[id] < 0)) throw fault('invalid_frozen_request');
       if (input.kind === 'run.start' && (!input.ownerCanvasId || !input.canvasIds.includes(input.ownerCanvasId))) throw fault('invalid_run_request');
@@ -122,11 +128,13 @@ export function createLedger(initial?: LedgerSnapshot) {
       if (request.phase === 'resolved') throw fault('request_resolved', [id]);
       const next: FrozenRequest = freeze({ ...request, phase: 'dispatch-marked', attempt: request.attempt + 1, retryAt: undefined, retryAction: undefined }); requests.set(id, next); changed(); return next;
     },
-    /** 记录执行结果；applied 且 reconciled 才解除逻辑操作，受理/未协调成功仍 waiting。
+    /** 接受上层已解释的 Outcome；本函数不验证协议身份、canonical 模型或 not-applied 的零写入证据。
+     * applied 且 reconciled 才解除逻辑操作，受理/未协调成功仍 waiting；reconciled 默认 true，调用方需按协调状态传入。
      * not-applied 结束旧请求但阻塞原意图，不能自动换 key 当作用户已重新授权执行。 */
     result(id: Id, outcome: Outcome, error?: string, reconciled = true) {
       const request = requireRequest(id);
       if ((request.phase === 'resolved' || request.outcome === 'applied') && request.outcome !== outcome) throw fault('receipt_conflict', [id]);
+      // 这里只拒绝与既有 applied/resolved outcome 不同的回执；相同 outcome 的阶段准入仍由调用链维持。
       const phase = (outcome === 'applied' && reconciled) || outcome === 'not-applied' ? 'resolved' : 'waiting';
       requests.set(id, freeze({ ...request, phase, outcome, error, retryAt: undefined, retryAction: undefined }));
       if (outcome === 'applied' && reconciled) for (const operationId of request.operationIds) operations.set(operationId, freeze({ ...operations.get(operationId)!, phase: 'resolved', resolution: 'applied' }));
@@ -161,7 +169,8 @@ export function createLedger(initial?: LedgerSnapshot) {
     },
     /** Local retirement is not an applied receipt. Validate the complete closure before mutating. */
     /** 用户恢复决策的本地退休：先验证整组与依赖闭包，再标记 superseded/discarded/satisfied。
-     * 上传和执行结果未知的请求不能在这里被静默丢弃；replacement ID 必须是全新的。 */
+     * 上传和执行结果未知的请求不能在这里被静默丢弃；replacement ID 不能撞已有/本批操作。
+     * 只标记原操作退休，不创建 replacement，不改工作文档/history，须由 engine 在同一 Root 组织其它修改。 */
     retire(recoveryId:Id,decisions:readonly {operationId:Id;resolution:'superseded'|'discarded'|'satisfied';replacementId?:Id}[]) {
       const ids=new Set(decisions.map(decision=>decision.operationId));
       if(!recoveryId||ids.size!==decisions.length||new Set(decisions.flatMap(decision=>decision.replacementId?[decision.replacementId]:[])).size!==decisions.filter(decision=>decision.replacementId).length)throw fault('invalid_recovery_decisions');
@@ -175,17 +184,20 @@ export function createLedger(initial?: LedgerSnapshot) {
       for(const decision of decisions)operations.set(decision.operationId,freeze({...operations.get(decision.operationId)!,phase:'resolved',resolution:decision.resolution,recoveryId,...(decision.replacementId?{replacementId:decision.replacementId}:{})}));
       if(decisions.length)changed();
     },
-    /** 保存原请求的 dueAt/action，重试计划也是可恢复事实；实际 heap 是 scheduler 的派生索引。 */
+    /** 保存原请求的 dueAt/action；这里只要求 dueAt 有限，不要求大于当前时间。
+     * 重试计划是可恢复事实，实际 heap/timer 是 scheduler 的派生索引；这里不启动 timer。 */
     scheduleRetry(id: Id, dueAt: number, action: 'submit' | 'query') {
       const request = requireRequest(id);
       if (request.phase === 'resolved' || !Number.isFinite(dueAt)) throw fault('invalid_retry', [id]);
       requests.set(id, freeze({ ...request, retryAt: dueAt, retryAction: action })); changed();
     },
-    /** 为未解决请求记录解释器/权限等阻碍，并清重试计划；保留 body/key 和 claims 的恢复依据。 */
+    /** 为未解决请求记录解释器/权限等阻碍，发生写入时清 retry 元数据，保留 body/key。
+     * 已 resolved 或 error 相同直接 no-op；相同 error 的早返回不会再清已有 retry 元数据。 */
     blockRequest(id: Id, error: string) { const request = requireRequest(id); if (request.phase === 'resolved' || request.error === error) return; requests.set(id, freeze({ ...request, error, retryAt: undefined, retryAction: undefined })); changed(); },
     /** 仅允许 durable 水位单调前进到当前 generation 内；不新增业务 generation。 */
     markDurable(through: number) { if (!Number.isSafeInteger(through) || through < durableGeneration || through > generation) throw fault('invalid_durable_generation'); durableGeneration = through; refresh(); },
-    /** 发送标记后且未确定 not-applied 均按可能已执行处理；这是保守风险依据，不是成功证明。 */
+    /** 精确条件为 phase!=frozen 且 outcome!=not-applied，按可能已执行处理；applied/resolved 也可为 true。
+     * 这是基于账本标记的保守风险读取，不查询网络，不证明成功，也不取代实际发送前持久化屏障。 */
     possiblyApplied(id: Id) { const request = requireRequest(id); return request.phase !== 'frozen' && request.outcome !== 'not-applied'; },
   });
 }

src/lib/canvas-runtime/scheduler.ts

@@ -1,7 +1,8 @@
 /**
  * 从 ledger 派生执行顺序的调度器：ready FIFO+queued 去重、依赖索引、canvas claims 与重试 min-heap。
  * 所有权威变化通过 options.mutate 写回 Root；队列本身既不是历史，也不保存另一套任务状态。
- * 发送前先持久化精确 body/key 和 dispatch 标记，结果协调及持久化成功后才释放占用。
+ * 发送前等待宿主持久化精确 body/key 和 dispatch 标记，结果协调及持久化成功后才释放占用。
+ * claims/holds 只约束本 scheduler；跨标签、进程或服务端的 writer/身份隔离由 engine 与 storage 端口负责。
  */
 import type { Id, Json, OperationIntent } from '../canvas-core/types.ts';
 import { fault, readMap } from '../canvas-core/values.ts';
@@ -21,27 +22,40 @@ type Ledger = ReturnType<typeof createLedger>;
 /** engine 提供准入、纯编译、原子账本更新、持久屏障、外部端口和完成协调。
  * complete 必须连回执/基线/working/ledger 一起处理，不允许仅把请求先标成功。 */
 export type SchedulerOptions = {
+  /** false 进入准入等待集合，由 refreshAdmission 唤醒；不在此把逻辑操作改为 blocked。 */
   admit?: (intent:OperationIntent)=>boolean;
   /** 每次准入/唤醒读取当前权威快照，不信任入队时捕获的旧状态。 */
   getLedger(): LedgerSnapshot;
   /** 在 engine 的受控发布路径内修改账本，失败不能留下半份持久事实。 */
   mutate(reduce: (ledger: Ledger) => void): void;
-  /** 等待当前 Root 可靠存储；失败保持请求身份与占用，不退回生成新请求。 */
+  /** 等待当前 Root 可靠存储；失败保持请求身份与占用，不退回生成新请求。
+   * scheduler 信任此 Promise 的持久承诺，本身不核对 durableGeneration/底层事务。 */
   persist(): Promise<void>;
+  /** 为新冻结请求分配 ID；恢复/重试沿用原 ID，不再次调用此工厂。 */
   createId(): Id;
+  /** 从当前意图推导需要 claim 的 canvas；编译结果必须覆盖同一集合。 */
   participants(intent: OperationIntent): readonly Id[];
+  /** 同步编译一个意图；不在这里发送，payload/版本随后由 ledger.freeze 捕获。 */
   compile(intent: OperationIntent, requestId: Id): CompiledRequest;
+  /** 将选中的连续候选缩为非空前缀，返回值必须是 1..intents.length 的整数。 */
   batchLimit?: (intents: readonly OperationIntent[]) => number;
+  /** 可选抵消协调钩子：先实际标记 ledger，再返回已抵消的候选前缀 ID；调度器不自行构造证明。 */
   elide?: (intents: readonly OperationIntent[]) => readonly Id[];
+  /** 多意图编译器仅在最终候选数 >1 时使用，单项仍走 compile。 */
   compileBatch?: (intents: readonly OperationIntent[], requestId: Id) => CompiledRequest;
+  /** 使用保存的冻结请求发写端口；端口负责协议/权限与回执解释，不得重编 payload。 */
   submit(request: FrozenRequest, signal: AbortSignal): Promise<OperationStatus>;
+  /** 按原请求身份查结果，端口解释回执；端口抛错时 scheduler 统一记为 unresolved/transport_unknown。 */
   query(request: FrozenRequest, signal: AbortSignal): Promise<OperationStatus>;
+  /** 恢复时确认冻结格式是否有解释器；省略钩子只默认支持 protocolVersion=1。 */
   supportsRequest?: (request: FrozenRequest) => boolean;
-  /** Atomically reconcile the receipt/base/working document and the ledger outcome. */
+  /** 同步协调回执/base/working 与 ledger 的宿主边界；不得返回异步准备结果。 */
   complete(request: FrozenRequest, status: OperationStatus): { readonly blocked: true } | void;
+  /** 报告存储/协调/编译错误，scheduler 隔离此回调抛错，不能用它改写请求结果。 */
   onError(error: unknown): void;
   clock?: Clock;
   concurrency?: number;
+  /** 按 submit attempt 提供有限退避毫秒；正常值取至少 1ms，端口 retryAfterMs 可覆盖此次值。 */
   retryDelay?: (attempt: number) => number;
 };
 
@@ -58,7 +72,8 @@ export function createScheduler(options: SchedulerOptions) {
   const waiters = new Map<Id, Set<Id>>(), dependents = new Map<Id, Set<Id>>(), indexed = new Set<Id>();
   // 最早 dueAt 优先；同到期按入堆 sequence 稳定排序，token 让旧 timer/旧重试条目惰性失效。
   const retry = createMinHeap<{ id: Id; dueAt: number; sequence: number; token: number }>((a, b) => a.dueAt - b.dueAt || a.sequence - b.sequence);
-  // active 只跟踪当前异步句柄/AbortController；任务完成事实仍必须回到 ledger。
+  // active 跟踪整条异步流水线（包含发送前/后的持久化等待），不是仅统计正在进行的 HTTP 请求。
+  // 句柄/AbortController 属于调度器，任务完成事实仍必须回到 ledger。
   const tokens = new Map<Id, number>(), active = new Map<Id, { controller: AbortController; promise: Promise<void>; kind: FrozenRequest['kind'] }>();
   // 多个恢复/关闭流程可独立 hold；只有最后一个 token 释放才继续准入，已启动工作仍正常收尾。
   const holds = new Set<symbol>();
@@ -73,7 +88,7 @@ export function createScheduler(options: SchedulerOptions) {
   const report = (error: unknown) => { try { options.onError(error); } catch { /* Reporting cannot change a receipt. */ } };
   /** 旧冻结协议必须有解释器才重试；缺钩子时仅默认支持协议 1。 */
   const supported = (request: FrozenRequest) => options.supportsRequest?.(request) ?? request.protocolVersion === 1;
-  /** 总并发上限之外，上传独占一个 lane；其它类别仍可使用剩余网络执行位。 */
+  /** 总 active 上限之外，asset.upload 至多占一个 lane；其它类别可用剩余流水线执行位。 */
   const canRun = (kind: FrozenRequest['kind']) => active.size < concurrency && (kind !== 'asset.upload' || ![...active.values()].some(task => task.kind === 'asset.upload'));
 
   /** 先读 ledger 检查 pending/依赖/门禁，再用 queued 去重入 FIFO；不是通知一次就盲发一次。 */
@@ -100,7 +115,8 @@ export function createScheduler(options: SchedulerOptions) {
     enqueue(id);
   }
   /** Only a contiguous mutable document prefix may share a request. Task barriers stay visible. */
-  /** 只选连续未冻结 document.change 前缀，最多 64 意图/10000 changes，遇任务屏障或占用即停。
+  /** 只选连续未冻结 document.change 前缀，最多 64 意图；追加候选时不让累计 changes 超过 10000。
+   * 首意图本身超过 10000 时仍可单独返回，不把它拆成字段请求；遇任务屏障/占用即停。
    * 仅合并有相交参与者的 lane；独立 canvas 保留各自失败/重试边界。 */
   function batch(first: OperationIntent, canvases: Set<Id>): readonly OperationIntent[] {
     const selected = [first], ids = new Set([first.id]);
@@ -143,7 +159,8 @@ export function createScheduler(options: SchedulerOptions) {
     }
     for (const id of request.operationIds) for (const dependent of dependents.get(id) ?? []) enqueue(dependent);
   }
-  /** 可选写回可恢复 retry 元数据，再用新 token 入 heap；重建索引时 persist=false 避免重复写事实。 */
+  /** 可选 mutate 写回 retry 元数据，再用新 token 入 heap；persist=false 仅表示不重复写账本。
+   * 此处没有 await 存储屏障，真正可靠落盘仍由 launch/resume 的 options.persist 完成。 */
   function schedule(id: Id, dueAt: number, action: 'submit' | 'query', persist = true) {
     if (persist) options.mutate(ledger => ledger.scheduleRetry(id, dueAt, action));
     const token = (tokens.get(id) ?? 0) + 1; tokens.set(id, token);
@@ -160,7 +177,8 @@ export function createScheduler(options: SchedulerOptions) {
     if (stopped || holds.size || active.size >= concurrency || !retry.peek()) return;
     timer = clock.setTimer(() => { timer = undefined; pump(); }, Math.max(0, retry.peek()!.dueAt - clock.now()));
   }
-  /** 安装 active 句柄后在微任务中执行：dispatch 标记→持久化→submit/query→原子协调→持久化。 */
+  /** 安装 active 句柄后在微任务中执行：submit 先标 dispatch；query 保留现有发送风险，再共同等待持久化。
+   * 调端口→同步 complete→再次持久化；hold 不撤回已启动流水线，stop 则让晚到结果不再采纳。 */
   function launch(id: Id, action: 'submit' | 'query') {
     if (active.has(id) || stopped || holds.size) return;
     const controller = new AbortController();
@@ -186,6 +204,7 @@ export function createScheduler(options: SchedulerOptions) {
         else {
           // A missing receipt is unknown, so the only write retry reuses this frozen request.
           // 首次 submit 未知先 query；query 仍未知才原样重试 submit；accepted 一直查，不换请求身份。
+          // accepted 的查询/submit 都继续 query；其它 submit 结果先 query，非 accepted 的 query 结果才允许同身份 submit。
           const nextAction = status.outcome === 'accepted' || action === 'submit' ? 'query' : 'submit';
           schedule(id, clock.now() + Math.max(1, status.retryAfterMs ?? delay(current.attempt)), nextAction);
           await options.persist();
@@ -203,7 +222,8 @@ export function createScheduler(options: SchedulerOptions) {
     });
     active.set(id, { controller, promise, kind: options.getLedger().requests.get(id)?.kind });
   }
-  /** 可重入保护下消费到期请求和最多 64 个 ready 项；等待者移到索引，不在 FIFO 无界反复轮询。 */
+  /** 防同步重入地处理到期请求，再从本轮 ready 前缀最多取 64 项；retry 循环没有同样的 64 项上限。
+   * 等待者移到索引，ready 尚有余量且有容量时安排下一轮 timer，不代表总队列大小有上限。 */
   function pump() {
     if (stopped || holds.size || pumping) return;
     pumping = true;
@@ -250,7 +270,8 @@ export function createScheduler(options: SchedulerOptions) {
           }
           const intents = options.compileBatch ? candidates : [record.intent];
           const participants = [...new Set(intents.flatMap(intent => options.participants(intent)))].sort();
-          // 编译参与者必须与规划一致，随后 freeze/own/launch；失败阻塞原意图而非偷偷重新编另一请求。
+          // 编译参与者必须与实际 intents 推导的集合一致，随后 freeze/own/launch；没有 compileBatch 时只编译首意图。
+          // 异常走原逻辑 ID 的 block；若已 frozen，ledger.block 不会把它退回 pending，冻结身份仍保留。
           const requestId = options.createId(), compiled = intents.length > 1 ? options.compileBatch!(intents, requestId) : options.compile(record.intent, requestId);
           if (participants.length !== compiled.canvasIds.length || participants.some(canvas => !compiled.canvasIds.includes(canvas))) throw fault('participant_mismatch');
           options.mutate(ledger => ledger.freeze({ ...compiled, id: requestId, operationIds: intents.map(intent => intent.id) }));
@@ -267,7 +288,8 @@ export function createScheduler(options: SchedulerOptions) {
     }
   }
   return Object.freeze({
-    /** 首次启动（已运行时幂等）：先恢复全部未解决 claims，按原 retry/body/key 继续；解释器缺失仍保留占用。 */
+    /** 首次启动（已运行时幂等）：先恢复全部未解决 claims，之后才开始端口工作；claim 冲突会在仍 stopped 时抛错。
+     * 解释器缺失保留占用并写 blocker；此步骤不做完整恢复 DTO 校验，也不从单个错误推断请求未执行。 */
     start() {
       if (closed) throw fault('scheduler_closed');
       if (!stopped) return;
@@ -284,7 +306,8 @@ export function createScheduler(options: SchedulerOptions) {
     },
     /** 门禁事实变化后显式重试准入，未满足者继续等待，不制造定时器忙轮询。 */
     refreshAdmission(){for(const id of [...admissionWaiters])enqueue(id);if(ready.size)requestPump();},
-    /** 新逻辑操作通知只推进派生索引，重复 notify 不重复注册依赖或入队。 */
+    /** 新逻辑操作通知推进派生索引；正在 queued 时不重复入队，indexed 让依赖只注册一次。
+     * 已出队的 pending 操作后续 notify 可再次尝试准入；通知本身不新增 ledger 意图。 */
     notify(operationIds: readonly Id[]) { for (const id of operationIds) index(id); requestPump(); },
     /** Acquire synchronously, then settle(): already admitted work completes with its original identity. */
     /** 同步阻止新准入并清唤醒 timer；返回幂等释放函数，已准入异步工作不被撤销或换身份。 */
@@ -316,7 +339,8 @@ export function createScheduler(options: SchedulerOptions) {
     },
     /** 返回当前占用表的只读副本，调用者不能手改 claim 绕过未知请求。 */
     getClaims: () => readMap(claims),
-    /** 等待当前微任务/pump/active 收尾，不主动等待未来 retry timer，因此不是“全部已同步”保证。 */
+    /** 等待当前微任务/pump/active 收尾，不主动等待未来 retry timer，因此不是“全部已同步”保证。
+     * 端口若长期不完成（包括忽略 abort），active Promise 仍可让 settle 一直等待。 */
     async settle() {
       do {
         if (scheduledPump) await scheduledPump;
@@ -324,7 +348,8 @@ export function createScheduler(options: SchedulerOptions) {
         if (!stopped && !holds.size && pumpTimer !== undefined) { clock.clearTimer(pumpTimer); pumpTimer = undefined; pump(); }
       } while (scheduledPump || active.size || (!stopped && !holds.size && pumpTimer !== undefined));
     },
-    /** 永久关闭本 scheduler、取消 timer 并 abort active；晚到响应因 stopped 不再采纳，不能再 start。 */
+    /** 永久关闭本 scheduler、取消 timer 并请求 abort active；晚到响应因 stopped 不再采纳，不能再 start。
+     * abort 不证明外部未执行，也不清 ledger/claims/派生容器或替 engine 关闭存储；活动句柄在 finally 收尾。 */
     stop() { closed = true; stopped = true; if (timer !== undefined) clock.clearTimer(timer); if (pumpTimer !== undefined) clock.clearTimer(pumpTimer); timer = pumpTimer = undefined; for (const item of active.values()) item.controller.abort(); },
   });
 }

src/lib/canvas-runtime/structures.ts

@@ -1,6 +1,7 @@
 /**
  * runtime 使用的基础调度容器，不包含任务状态事实：FIFO 存可执行顺序，min-heap 存优先项。
  * 两者都是内存结构，ledger/checkpoint 才负责可恢复事实；容器本身不去重、不校验依赖或执行网络。
+ * T 值按引用保存/返回，不复制冻结任务对象，也不以 size/clear 修改外部任务事实。
  */
 /** FIFO with amortized O(1) removal, without Array.shift on each item. */
 /** 当前接口是先进先出队列：push 入尾、pop 出头，并非 history 的后进先出 stack。
@@ -24,12 +25,13 @@ export function createDeque<T>() {
     },
     /** 同时丢弃底层数组和游标，释放旧任务引用。 */
     clear() { items = []; head = 0; },
-    /** 返回有效区间的数组副本，外部改副本不会更改队列成员。 */
+    /** 返回有效区间的浅数组副本，改副本成员位置不改队列；对象成员仍共享引用。 */
     values() { return items.slice(head); },
   };
 }
 /** 数组实现二叉最小堆，compare<0 表示左项优先；peek O(1)，push/pop O(log n)。
- * 相等优先级不保证插入稳定性，上层若需要 FIFO tie-break 必须把序列写进 comparator。 */
+ * 相等优先级不保证插入稳定性，上层若需要 FIFO tie-break 必须把序列写进 comparator。
+ * compare 应稳定、同步且不抛错；容器不校验 comparator，比较中途异常也不提供事务回滚。 */
 export function createMinHeap<T>(compare: (left: T, right: T) => number) {
   // 父下标 (i-1)>>1，左右孩子 2i+1/2i+2；堆序只要求父不大于孩子，不是全数组排序。
   const items: T[] = [];

tests/api-smoke.mjs

@@ -1,10 +1,17 @@
+/**
+ * 已构建 Next 应用的本地 HTTP smoke：启动临时 Foundry 替身和 next start，遍历页面、代理、资源及认证响应。
+ * 需要已有可用构建，运行会占用 127.0.0.1:3005；脚本不执行 next build，也不连接真实 Foundry/模型服务。
+ * 断言以 HTTP、文件字节及内存状态为准，不验证浏览器交互、真实登录提供商或数据库事务。
+ */
 import assert from "node:assert/strict";
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
 import { once } from "node:events";
 import { fileURLToPath } from "node:url";
 import { readdir, readFile } from "node:fs/promises";
+// 应用使用固定端口；upstream 另选随机端口，由子进程环境变量指定为代理源站。
 const host = "http://127.0.0.1:3005";
+// 图谱、画布版本、会话剩余秒数与 profile 都是本次进程的内存夹具。
 const graphs = new Map();
 let releaseStream = () => {};
 let canvasSnapshot = { version: 1, document: { schema_version: 1, nodes: [], edges: [], viewport: { x: 0, y: 0, zoom: 1 } } };
@@ -13,23 +20,28 @@ let mockProfile = {
   id: "user", username: "test", display_name: "Test User", email: "test@example.com",
   avatar_url: "https://lh3.googleusercontent.com/test-avatar=s96-c",
 };
+// 最小 Foundry HTTP 替身：有效测试会话才发续期提示，并按路由返回页面代理需要的响应。
 const upstream = createServer(async (req, res) => {
   res.setHeader("Content-Type", "application/json");
   if (req.headers.authorization === "Bearer test-only-session" && !req.url.endsWith("/auth/logout")) res.setHeader("X-Foundry-Session-Expires-In", mockSessionSeconds);
+  // 把 workspace/board slug 归一到同一记录，供四种 ID/slug 组合读取校验；不是通用路由解析器。
   const canonical = req.url.replace("/workspaces/creative-space/", "/workspaces/space/").replace("/materials/my-board", "/materials/foundry-generated-id");
   if (req.url.includes("/canvas")) assert.equal(req.headers.accept, "application/vnd.foundry.canvas+json;version=2");
+  // 资源 GET 返回短 PNG 头字节或不支持 MIME；POST 汇总 multipart 原始字节并回显幂等键。
   if (req.url.startsWith("/projects/endoleap/workspaces/space/assets")) {
     if (req.headers.authorization !== "Bearer test-only-session") { res.statusCode = 401; res.end(JSON.stringify({error:"invalid_session"})); return; }
     if (req.method === "GET") { res.setHeader("X-Asset-Variant", new URL(req.url,"http://mock").searchParams.get("variant") === "preview" ? "preview" : "original"); res.setHeader("Content-Type", req.url.endsWith("/bad") ? "image/svg+xml" : "image/png"); res.end(Buffer.from([137,80,78,71,13,10,26,10])); return; }
     let bytes = Buffer.alloc(0); for await (const chunk of req) bytes = Buffer.concat([bytes, chunk]);
     res.end(JSON.stringify({type:req.headers["content-type"],bytes:bytes.length,key:req.headers["idempotency-key"],multipart:bytes.includes(Buffer.from('name="image"'))})); return;
   }
+  // 先写 JSON 前缀，再延迟 15.2 秒完成 body，用于检查旧总超时不截断合法传输。
   if (canonical.endsWith("/materials/slow-body-board/canvas")) {
     res.setHeader("ETag", '\"210\"');
     res.write('{"version":210,"document":');
     await new Promise((resolve) => setTimeout(resolve, 15200));
     res.end('{"schema_version":2,"nodes":[],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}}'); return;
   }
+  // 由 releaseStream 控制尾部放行：代理必须在完整 JSON 可用之前转交头和首块。
   if (canonical.endsWith("/materials/stream-board/canvas")) {
     assert.equal(req.headers.authorization, "Bearer test-only-session");
     res.setHeader("ETag", '\"1\"'); res.setHeader("X-Canvas-Schema-Version", "2");
@@ -37,9 +49,11 @@ const upstream = createServer(async (req, res) => {
     await new Promise((resolve) => { releaseStream = resolve; });
     res.end('{"schema_version":2,"nodes":[],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}}'); return;
   }
+  // V2 子命令只回显 URL、方法与关键头；这个分支不执行真正的连接、AI 或结构事务。
   if (canonical.includes("/canvas/")) {
     res.end(JSON.stringify({url:req.url,method:req.method,accept:req.headers.accept,key:req.headers["idempotency-key"],version:req.headers["if-match"]})); return;
   }
+  // 旧完整快照 GET/PATCH 独立维护版本，If-Match 过期时返回 412；不与图谱元信息共用版本。
   if (canonical === "/projects/endoleap/workspaces/space/materials/foundry-generated-id/canvas") {
     if (req.headers.authorization !== "Bearer test-only-session") { res.statusCode = 401; res.end(JSON.stringify({ error: "invalid_session" })); return; }
     if (req.method === "GET") { res.setHeader("X-Canvas-Schema-Version", String(canvasSnapshot.document.schema_version)); res.setHeader("ETag", '"' + canvasSnapshot.version + '"'); res.end(JSON.stringify(canvasSnapshot)); return; }
@@ -50,6 +64,7 @@ const upstream = createServer(async (req, res) => {
     canvasSnapshot = { version: canvasSnapshot.version + 1, document };
     res.setHeader("ETag", '"' + canvasSnapshot.version + '"'); res.end(JSON.stringify({ version: canvasSnapshot.version })); return;
   }
+  // 其余分支提供登出、图谱创建/重命名、登录 token 和 profile；未知路由返回 404。
   if (req.url.endsWith("/auth/logout")) {
     res.statusCode = 204;
     res.end();
@@ -59,6 +74,7 @@ const upstream = createServer(async (req, res) => {
     for await (const chunk of req) raw += chunk;
     const input = JSON.parse(raw);
     assert.deepEqual(input, { kind: "board", title: "未命名图谱", content: { schema_version: 1 } });
+    // 图谱 ID 由替身分配，同时保留 slug；创建响应只回身份字段，详细内容需后续 GET。
     const graph = { ...input, slug: "my-board", id: "foundry-generated-id", workspace_id: "space", version: 1 };
     graphs.set(graph.id, graph);
     res.statusCode = 201;
@@ -100,8 +116,10 @@ const upstream = createServer(async (req, res) => {
     res.end("{}");
   }
 });
+// 先监听随机端口再启动 Next 子进程，保证应用首次代理请求就能连到替身。
 await new Promise((r) => upstream.listen(0, "127.0.0.1", r));
 const port = upstream.address().port;
+// 启动 next start 消费已有构建，捕获 stdout/stderr 供启动失败诊断，不运行开发服务器。
 const app = spawn(
   process.execPath,
   [
@@ -118,10 +136,12 @@ const app = spawn(
     stdio: ["ignore", "pipe", "pipe"],
   },
 );
+// 收集子进程启动输出；轮询中若提前退出，错误包含这些诊断文本。
 let startup = "";
 app.stdout.on("data", (x) => (startup += x));
 app.stderr.on("data", (x) => (startup += x));
 try {
+  // 最多轮询 100 次，失败后等待 100ms，再检查首页是否可用；不能只凭 spawn 返回就宣称服务已启动。
   let ready = false;
   for (let n = 0; n < 100; n++) {
     if (app.exitCode !== null)
@@ -135,6 +155,7 @@ try {
     await new Promise((r) => setTimeout(r, 100));
   }
   assert(ready, "Frontend did not start");
+  // 逐页检查状态和公共元信息；这些是服务端 HTML 断言，不代表页面客户端交互已验证。
   for (const path of ["/", "/login", "/auth/callback", "/dashboard", "/dashboard?demo=1", "/dashboard/space/foundry-generated-id"]) {
     const page = await fetch(host + path);
     assert.equal(page.status, 200, path);
@@ -146,6 +167,7 @@ try {
     assert(html.includes('/brand/icons/favicon.ico'));
     assert(html.includes('/brand/icons/apple-touch-icon.png'));
   }
+  // 逐个下载本地品牌资产并与仓库原字节比较，检查静态服务没有替换或遗漏文件。
   const brandRoot = new URL("../public/brand/", import.meta.url);
   const assets = (await readdir(brandRoot, { recursive: true })).filter((file) => /\.(png|ico|svg)$/.test(file));
   assert.equal(assets.length, 88);
@@ -154,6 +176,7 @@ try {
     assert.equal(response.status, 200, asset);
     assert.deepEqual(Buffer.from(await response.arrayBuffer()), await readFile(new URL(asset, brandRoot)), asset);
   }
+  // 按 manifest 枚举图标分片，核对 immutable 缓存头和 JSON 内容，与目录数量的日志文案区分。
   const iconManifest = JSON.parse(await readFile(new URL("../src/lib/canvas-icon-assets.json", import.meta.url), "utf8"));
   for (const file of Object.values(iconManifest.assets)) {
     const path = iconManifest.root + "/" + file;
@@ -163,6 +186,7 @@ try {
     assert.deepEqual(await response.json(), JSON.parse(await readFile(new URL("../public" + path, import.meta.url), "utf8")));
   }
   assert.equal((await fetch(host + "/missing-page")).status, 404);
+  // 登录代理必须去掉响应体 token，改设 HttpOnly/SameSite cookie，并报告上游计时。
   const res = await fetch(host + "/api/foundry/auth/login", {
     method: "POST",
     headers: { "Content-Type": "application/json", Origin: host },
@@ -190,6 +214,7 @@ try {
     while (true) { const next = await reader.read(); if (next.done) break; raw += new TextDecoder().decode(next.value); }
     assert.equal(JSON.parse(raw).document.schema_version, 2);
   } finally { clearTimeout(streamTimer); releaseStream(); }
+  // 子命令循环只检查头透传；随后检查资源 variant、目录分页与 AI 查询参数白名单。
   const v2Base = host + "/api/foundry/workspaces/space/materials/foundry-generated-id/canvas";
   const idem = "11111111-1111-4111-8111-111111111111";
   for (const path of ["connections", "subgraphs", "subgraphs/migrate", "subgraphs/frame-1/members", "subgraphs/frame-1/dissolve", "transactions/tx-1/undo", "ai/runs", "ai/runs/run-1/cancel", "ai/runs/run-1/apply"]) {
@@ -202,6 +227,7 @@ try {
   assert.equal(directoryQuery.get("include_subgraphs"), "true"); assert.equal(directoryQuery.get("offset"), "100");
   const events = await (await fetch(v2Base + "/ai/runs/run-1?after_seq=12&limit=100&status=active&include_descendants=true&cursor=cursor&secret=drop", { headers: { Cookie: session } })).json();
   const query = new URL(events.url, "http://mock").searchParams; assert.equal(query.get("after_seq"), "12"); assert.equal(query.get("include_descendants"), "true"); assert.equal(query.get("cursor"), "cursor"); assert.equal(query.get("secret"), null);
+  // 验证慢 body 完整读取和 trace 标识，再检查资源认证、MIME 拒绝、nosniff 与 multipart 转发。
   const slowSnapshot = await fetch(host + "/api/foundry/workspaces/space/materials/slow-body-board/canvas", { headers: { Cookie: session } });
   assert.ok(slowSnapshot.headers.get("x-canvas-trace-id")); assert.equal((await slowSnapshot.json()).version, 210, "A valid body can finish after the old 15-second total deadline");
   const asset = await fetch(host + "/api/foundry/workspaces/space/assets/image-1", { headers: { Cookie: session } });
@@ -211,6 +237,7 @@ try {
   const form = new FormData(); form.set("image", new Blob([new Uint8Array([137,80,78,71])], { type: "image/png" }), "test.png");
   const upload = await (await fetch(host + "/api/foundry/workspaces/space/assets", { method: "POST", headers: { Cookie: session, Origin: host, "Idempotency-Key": idem }, body: form })).json();
   assert.match(upload.type, /^multipart\/form-data; boundary=/); assert.equal(upload.key, idem); assert.ok(upload.multipart);
+  // 有效会话首页重定向且不缓存私有结果；dashboard 初始 HTML 不应包含画布或 landing。
   const signedInHome = await fetch(host + "/", { headers: { Cookie: session }, redirect: "manual" });
   assert.equal(signedInHome.status, 307);
   assert.equal(signedInHome.headers.get("location"), "/dashboard");
@@ -222,6 +249,7 @@ try {
   assert.match(dashboardHtml, /aria-label="(?:工作空间侧边栏|正在加载侧边栏)"/);
   assert(!dashboardHtml.includes('data-testid="rf__wrapper"'));
   assert(!dashboardHtml.includes('class="landing"'));
+  // 无会话或过期会话首页保持 landing，避免错误重定向到个人工作区。
   for (const guestHeaders of [{}, { Cookie: "foundry_session=expired-session" }]) {
     const guestHome = await fetch(host + "/", { headers: guestHeaders, redirect: "manual" });
     assert.equal(guestHome.status, 200);
@@ -240,6 +268,7 @@ try {
     200,
   );
   assert.equal((await fetch(host + "/api/foundry/profile")).status, 401);
+  // 续期只接受有效剩余秒数；非法上游值和无效会话不应产生新的 Set-Cookie。
   mockSessionSeconds = "3600";
   const renewed = await fetch(host + "/api/foundry/profile", { headers: { Cookie: session } });
   assert.equal(renewed.status, 200); assert.match(renewed.headers.get("set-cookie") || "", /Max-Age=3600/);
@@ -251,6 +280,7 @@ try {
   const expiredSession = await fetch(host + "/api/foundry/profile", { headers: { Cookie: "foundry_session=expired" } });
   assert.equal(expiredSession.status, 401); assert.equal(expiredSession.headers.get("set-cookie"), null);
 
+  // 读取头像再修改公开资料，确认未涉及的头像字段保持。
   const profile = await (await fetch(host + "/api/foundry/profile", { headers: { Cookie: session } })).json();
   assert.equal(profile.avatar_url, "https://lh3.googleusercontent.com/test-avatar=s96-c");
   const updated = await fetch(host + "/api/foundry/profile", {
@@ -263,6 +293,7 @@ try {
   assert.equal(updatedProfile.display_name, "Updated name");
   assert.equal(updatedProfile.avatar_url, profile.avatar_url);
 
+  // 经真实代理创建、读取和重命名内存图谱，检查服务分配身份、内容保留和元信息版本递增。
   const create = await fetch(host + "/api/foundry/workspaces/space/materials", {
     method: "POST",
     headers: { "Content-Type": "application/json", Cookie: session, Origin: host },
@@ -287,6 +318,7 @@ try {
   assert.equal(renamed.version, 2);
   assert.deepEqual(renamed.content, stored.content);
 
+  // workspace/board 各自使用 ID 或 slug 的四种组合都应定位同一图谱和独立画布版本。
   for (const workspace of ["space", "creative-space"]) for (const board of ["foundry-generated-id", "my-board"]) {
     const path = `/api/foundry/workspaces/${workspace}/materials/${board}`;
     const material = await (await fetch(host + path, { headers: { Cookie: session } })).json();
@@ -296,6 +328,7 @@ try {
     assert.equal((await snapshot.json()).version, 1);
   }
   const canvasPath = "/api/foundry/workspaces/creative-space/materials/my-board/canvas";
+  // 生成超过 1 MiB 的完整快照经代理保存/恢复，再用旧版本重发检查 412；不是增量或大文件性能测试。
   const largeDocument = { schema_version: 1, nodes: Array.from({ length: 15 }, (_, index) => ({ id: "text-" + index, type: "material", position: { x: index * 300, y: 100 }, width: 260, height: 200, data: { kind: "text", title: "保存测试", text: "x".repeat(90000), fontSize: 24, rotation: 30, textStyle: { bold: true, color: "#123456" } } })), edges: [], viewport: { x: 20, y: 40, zoom: 0.75 } };
   const savedCanvas = await fetch(host + canvasPath, { method: "PATCH", headers: { Cookie: session, Origin: host, "Content-Type": "application/json", "If-Match": '"1"' }, body: JSON.stringify({ document: largeDocument }) });
   assert.equal(savedCanvas.status, 200); assert.equal(savedCanvas.headers.get("etag"), '"2"');
@@ -304,6 +337,7 @@ try {
   assert.deepEqual(restoredCanvas.document, largeDocument);
   const conflict = await fetch(host + canvasPath, { method: "PATCH", headers: { Cookie: session, Origin: host, "Content-Type": "application/json", "If-Match": '"1"' }, body: JSON.stringify({ document: largeDocument }) });
   assert.equal(conflict.status, 412); assert.equal((await conflict.json()).error, "version_conflict");
+  // 旧 frameId 成员关系及三种名称显示模式往返，逐次使用当前画布版本。
   const frameDocument = structuredClone(largeDocument);
   frameDocument.nodes.unshift({ id: "frame-1", type: "frame", position: { x: 0, y: 0 }, width: 640, height: 400, data: { kind: "frame", title: "参考分区", text: "", rotation: 0, labelMode: "fixed" } });
   frameDocument.nodes[1].data.frameId = "frame-1";
@@ -317,10 +351,12 @@ try {
   }
   assert.equal((await fetch(host + canvasPath)).status, 401);
   assert.equal((await fetch(host + "/api/foundry/workspaces/space/search/my-board/canvas")).status, 404);
+  // 超过画布 body 上限的请求必须返回 413，不能转成成功保存。
   const oversizedCanvas = await fetch(host + canvasPath, { method: "PATCH", headers: { Cookie: session, "Content-Type": "application/json" }, body: JSON.stringify({ document: "x".repeat(5 * 1024 * 1024) }) });
   assert.equal(oversizedCanvas.status, 413);
 
 
+  // 检查跨源拒绝、路径白名单、OAuth challenge、Secure cookie、非法 JSON、大小上限及方法过滤。
   for (const origin of ["https://example.com", "null"])
     assert.equal(
       (
@@ -351,17 +387,20 @@ try {
     assert.equal(invalid.status, status);
   }
   assert.equal((await fetch(host + "/api/foundry/profile", { method: "PUT" })).status, 405);
+  // 查询保留 kind/limit 而删除未许可 secret；此处使用替身回显观察最终上游路径。
   const materials = await fetch(host + "/api/foundry/workspaces/space/materials?kind=board&limit=100&secret=drop", {
     method: "PATCH", headers: { "Content-Type": "application/json" }, body: "{}",
   });
   assert.deepEqual(await materials.json(), {
     url: "/projects/endoleap/workspaces/space/materials?kind=board&limit=100", method: "PATCH",
   });
+  // OAuth 只检查重定向地址与 challenge，不实际打开提供商或完成授权。
   for (const provider of ["google", "slack"]) {
     const redirect = await fetch(host + "/api/oauth/" + provider + "?challenge=" + "a".repeat(43), { redirect: "manual" });
     assert.equal(redirect.status, 302);
     assert.equal(redirect.headers.get("location"), `http://127.0.0.1:${port}/projects/endoleap/auth/${provider}?challenge=${"a".repeat(43)}`);
   }
+  // 登出保持 204 空体并清除 cookie；下方 PASS 长文是摘要，实际覆盖以逐项断言为准。
   const logout = await fetch(host + "/api/foundry/auth/logout", {
     method: "POST", headers: { "Content-Type": "application/json", Cookie: session }, body: "{}",
   });
@@ -371,6 +410,7 @@ try {
   console.log(
     "PASS: V2 commands, idempotency and query forwarding, authenticated binary assets and multipart uploads, Canvas GET/PATCH and independent versions, ETag/If-Match, 1+ MiB snapshot restore, conflict and 5 MiB limit, four ID/slug combinations, authenticated home redirect, anonymous and expired-session landing, canvas-free dashboard, 88 original brand assets, 97 hashed icon shards with immutable caching, favicon metadata, avatar and profile updates, App Router pages and metadata, body validation, method and query filtering, OAuth redirects, logout, session cookie, token removal, authenticated proxy, invalid session, cross-origin rejection, path allowlist, OAuth validation",
   );
+// 结束或断言失败均终止 Next 子进程并关闭替身监听；此处没有额外的强制退出超时。
 } finally {
   const exited = once(app, "exit");
   app.kill("SIGTERM");

tests/board-directory.test.mjs

@@ -1,7 +1,13 @@
+/**
+ * board 目录分页、树构建、祖先定位与筛选测试。请求由内存函数提供，不访问实际 workspace 服务。
+ * 列表顺序不保证父项先到；孤儿和循环节点仍须可访问，不能递归死循环。
+ */
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { loadBoardDirectory, boardDirectory, activeBoardAncestors, filterBoardDirectory } from '../src/lib/board-directory.ts';
+// 生成带 ID、slug 和 parent_board_id 的最小目录项，默认 title 使用 ID。
 const board=(id,parent,title=id)=>({id,parent_board_id:parent,title,workspace_id:'w',kind:'board',version:1,slug:id+'-slug'});
+// 第一页故意子先父后，下一页才给孙项；检查 include_subgraphs、offset 与 URL 编码，再检查层级、slug 祖先链和筛选路径。
 test('directory includes subgraphs, traverses all pages and preserves nested ownership',async()=>{
  const calls=[];const request=async(path)=>{calls.push(path);const offset=new URLSearchParams(path.split('?')[1]).get('offset');return offset==='0'?{items:[board('child','parent'),board('parent')],next_offset:100}:{items:[board('grandchild','child')],next_offset:null};};
  const boards=await loadBoardDirectory(request,'space slug');assert.equal(calls.length,2);assert.ok(calls.every(path=>path.includes('include_subgraphs=true')));assert.ok(calls[1].endsWith('offset=100'));assert.ok(calls[0].includes('space%20slug'));
@@ -10,9 +16,11 @@ test('directory includes subgraphs, traverses all pages and preserves nested own
  assert.deepEqual(filterBoardDirectory(roots,'grandchild')[0].children[0].children.map(item=>item.board.id),['grandchild']);
  assert.equal(filterBoardDirectory(roots,'parent')[0].children.length,1);
 });
+// 父项缺失及双节点循环都提升为可见根项，子列表为空，避免丢失入口或无限嵌套。
 test('missing parents and corrupt cycles remain accessible without recursive loops',()=>{
  const roots=boardDirectory([board('orphan','missing'),board('a','b'),board('b','a')]);assert.deepEqual(roots.map(item=>item.board.id),['orphan','a','b']);assert.ok(roots.every(item=>item.children.length===0));
 });
+// 非递增 next_offset 明确拒绝；已经 abort 的信号由请求替身抛回，加载器不得吞掉取消。
 test('directory rejects non-advancing pagination and propagates aborts',async()=>{
  await assert.rejects(loadBoardDirectory(async()=>({items:[],next_offset:0}),'w'),/invalid_pagination/);
  const controller=new AbortController();controller.abort();await assert.rejects(loadBoardDirectory(async(_path,options)=>{options.signal.throwIfAborted();},'w',controller.signal),{name:'AbortError'});

tests/canvas-assets.test.mjs

@@ -1,10 +1,17 @@
+/**
+ * 旧画布附件上传助手和显示 URL 转换测试。请求为替身，检查 FormData、错误和资源地址，不是真实上传或图像解码。
+ * 这里的上传重试属于 canvas-assets helper，不可等同于 headless ledger 的持久冻结请求恢复。
+ */
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { uploadCanvasImage } from '../src/lib/canvas-assets.ts';
 import { managedImageSource } from '../src/lib/canvas-v2.ts';
+// 固定 data URL 仅用来构造与对比二进制前缀，并非完整 PNG 解码样本。
 const source='data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB';
+// 固定资产身份；返回值必须是项目管理的地址，任意外域响应不被当作受管上传结果。
 const id='77777777-7777-4777-8777-777777777777';
 const asset={id,url:`https://api.foundry.entroia.com/projects/endoleap/workspaces/w/assets/${id}`,width:1,height:1,bytes:24,mime_type:'image/png'};
+// 首例直接比对 FormData.image 原字节、上传路径、POST 和幂等键形状，返回值保留服务资产元数据。
 test('attachment upload sends the original file bytes',async()=>{
  const bytes=Buffer.from(source.split(',')[1],'base64');let calls=0;
  const result=await uploadCanvasImage(async(path,options)=>{
@@ -13,15 +20,18 @@ test('attachment upload sends the original file bytes',async()=>{
  },'w',new Blob([bytes],{type:'image/png'}),'image.png');
  assert.equal(calls,1);assert.deepEqual(result,asset);
 });
+// 权限拒绝直接传播；格式类似但地址不受管理的成功响应也要拒绝，不能把任意 URL 写成上传结果。
 test('attachment upload propagates permission failures and rejects unmanaged response URLs',async()=>{
  const file=new Blob(['test'],{type:'image/png'});
  await assert.rejects(uploadCanvasImage(async()=>{throw new Error('forbidden');},'w',file,'test.png'),/forbidden/);
  await assert.rejects(uploadCanvasImage(async()=>({...asset,url:'https://invalid.example/a.png'}),'w',file,'test.png'),/invalid_asset_response/);
 });
+// 模拟第一次连接丢失、第二次成功；此例直接断言两次调用与相同幂等键，文件字节传递由首例单独检查。
 test('uncertain upload retries the exact bytes with the same idempotency key',async()=>{
  let calls=0,key;
  await uploadCanvasImage(async(_path,options)=>{calls++;if(!key)key=options.headers['Idempotency-Key'];assert.equal(options.headers['Idempotency-Key'],key);if(calls===1)throw new TypeError('connection lost');return asset;},'w',new Blob(['test'],{type:'image/png'}),'test.png');assert.equal(calls,2);
 });
+// 受管原始 URL 转同源认证代理，preview 仅加显示变体参数；普通外部图片地址保持原样。
 test('preview URLs are renderer-only and do not replace original managed references',()=>{
  assert.equal(managedImageSource(asset.url),`/api/foundry/workspaces/w/assets/${id}`);assert.equal(managedImageSource(asset.url,true),`/api/foundry/workspaces/w/assets/${id}?variant=preview`);
  assert.equal(managedImageSource('https://example.com/photo.png',true),'https://example.com/photo.png');

tests/canvas-frames.test.mjs

@@ -1,16 +1,23 @@
+/**
+ * 旧 frameId 分区成员模型的拖入、随动与恢复测试；不是 headless ownerCanvasId 树或 linked-board 深子 canvas 的全部规则。
+ * 成员关系由明确 drop 决定，几何重叠本身不代表已经加入分区。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { canvasReducer, decodeCanvas, emptyCanvas, makeCanvasNode } from "../src/lib/canvas.ts";
 import { assignFrameMembership, frameDropFeedback } from "../src/lib/canvas-frames.ts";
 
+// frame、位于内部但尚未登记的 member，以及外部 icon；可分别检查 drop 准入和已有成员随动。
 function seeded() {
   const frame = makeCanvasNode("frame", { x: 100, y: 100 });
   const member = makeCanvasNode("text", { x: 160, y: 160 });
   const outsider = makeCanvasNode("icon", { x: 900, y: 120 });
   return { frame, member, outsider, document: { ...emptyCanvas(), nodes: [frame, member, outsider] } };
 }
+// 把给定快照包成空历史结构，保持所有测试通过相同 reducer 入口。
 function state(document) { return { past: [], present: document, future: [] }; }
 
+// 多种内容 drop 到重叠 frame 时预览应与最终成员选择一致；较小 frame 优先，移到外部则同时显示和执行 detach。
 test("drop previews match actual assignment for every content type, exits and overlapping frames", () => {
   const { frame } = seeded();
   const smaller = makeCanvasNode("frame", { x: 120, y: 120 }); smaller.width = 300; smaller.height = 240;
@@ -26,6 +33,7 @@ test("drop previews match actual assignment for every content type, exits and ov
   }
 });
 
+// 只给 dropped IDs 分配成员，拖 frame 或其他节点不能顺手收集原本重叠的内容。
 test("only dropped content joins a frame; pre-existing overlapping content stays outside", () => {
   const { frame, member, outsider, document } = seeded();
   assert.equal(document.nodes[1].data.frameId, undefined);
@@ -38,6 +46,7 @@ test("only dropped content joins a frame; pre-existing overlapping content stays
   assert.equal(assignFrameMembership([frame, member, outsider], [member.id])[2].data.frameId, undefined);
 });
 
+// 已有成员随 frame 同量移动，旁边 outsider 不改位置和归属；undo 恢复成员坐标与 frameId。
 test("frames carry existing members without collecting newly overlapped content and undo restores positions", () => {
   const { frame, member, outsider, document } = seeded();
   member.data.frameId = frame.id;
@@ -51,6 +60,7 @@ test("frames carry existing members without collecting newly overlapped content
   assert.equal(history.present.nodes[1].data.frameId, frame.id);
 });
 
+// 已有成员拖出清除 frameId，落进另一 frame 则换归属；以同一位置比较两种节点集合。
 test("dragging out detaches content and dragging between frames reassigns membership", () => {
   const { frame, member } = seeded();
   member.data.frameId = frame.id;
@@ -60,6 +70,7 @@ test("dragging out detaches content and dragging between frames reassigns member
   assert.equal(assignFrameMembership([frame, second, member], [member.id])[2].data.frameId, second.id);
 });
 
+// 同时上报父 frame 和成员的最终位置时，不能再把父位移叠加到成员，避免双重移动。
 test("multi-selection does not move frame members twice", () => {
   const { frame, member, document } = seeded();
   member.data.frameId = frame.id;
@@ -70,6 +81,7 @@ test("multi-selection does not move frame members twice", () => {
   assert.deepEqual(result.present.nodes[1].position, { x: 260, y: 260 });
 });
 
+// 旧模型删除 frame 保留内容并清成员关联，undo 可恢复原 frameId；这不是 headless 删除 owning 子树的产品规则。
 test("deleting a frame keeps its content and undo restores membership", () => {
   const { frame, member, document } = seeded();
   member.data.frameId = frame.id;
@@ -80,6 +92,7 @@ test("deleting a frame keeps its content and undo restores membership", () => {
   assert.equal(canvasReducer(removed, { type: "undo" }).present.nodes[1].data.frameId, frame.id);
 });
 
+// hidden/fixed/scaled 标签、名称与 frameId 往返保存，frame 渲染层序为 -1，设置历史可撤销。
 test("all label modes, frame names and memberships survive save/restore and settings undo", () => {
   const { frame, member, document } = seeded();
   member.data.frameId = frame.id;
@@ -95,6 +108,7 @@ test("all label modes, frame names and memberships survive save/restore and sett
   }
 });
 
+// 缺失 frame、frame 作为别的内容成员、非法标签和 frame 旋转均拒绝；限制属于本旧格式。
 test("invalid frame references, label modes, frame nesting and rotation are rejected", () => {
   for (const mutate of [
     ({ member }) => { member.data.frameId = "missing"; },

tests/canvas-geometry.test.mjs

@@ -1,12 +1,19 @@
+/**
+ * 旧 CanvasElement 几何与能力测试，直接验证类、纯函数和旧 reducer；不分派真实 pointer 事件。
+ * 多方向/旋转样本用对边锚点及连接端点作为几何不变量，避免只比较宽高变化。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { CanvasElement, CardElement, TextCardElement, ImageCardElement, ScriptCardElement, PlainTextElement, elementCapabilities } from "../src/lib/canvas-elements.ts";
 import { nodeConnector, connectorBezier, nodeCenter, nodeSize, resizeFromPointer, rotateVector, rotationFromPointer } from "../src/lib/canvas-geometry.ts";
 import { branchCanvasNode, canvasReducer, decodeCanvas, emptyCanvas } from "../src/lib/canvas.ts";
 
+// 浮点误差容差为 1e-5，失败消息保留 actual/expected，供旋转与坐标换算诊断。
 function close(actual, expected) { assert(Math.abs(actual - expected) < 0.00001, `${actual} != ${expected}`); }
+// 将几何 patch 与旧 node.data 中的 rotation/fontSize 合并，重算中心和端点时使用同一模型形状。
 function transformed(node, patch) { return { ...node, ...patch, data: { ...node.data, rotation: patch.rotation ?? node.data.rotation, fontSize: patch.fontSize ?? node.data.fontSize } }; }
 
+// 三种卡片共享变换和 branching；PlainText 只继承公共变换，不能通过错误 ID 或自身 ID 绕过不连线/不分支能力。
 test("card types inherit common element transforms and add branching; plain text inherits only common transforms", () => {
   for (const Type of [TextCardElement, ImageCardElement, ScriptCardElement]) {
     const element = new Type({ x: 0, y: 0 });
@@ -27,12 +34,14 @@ test("card types inherit common element transforms and add branching; plain text
   assert.throws(() => branchCanvasNode({ ...emptyCanvas(), nodes: [node] }, node.id, "right"), /纯文本/);
 });
 
+// 五种旋转角度乘八方向 handle，检查受影响尺寸和相反局部锚点世界坐标保持不变。
 test("all eight handles resize cards while retaining the opposite local anchor, including rotated cards", () => {
   const directions = ["top", "right", "bottom", "left", "top-left", "top-right", "bottom-left", "bottom-right"];
   for (const rotation of [0, 37, 90, 180, 270]) {
     for (const direction of directions) {
       const node = new TextCardElement({ x: 100, y: 200 }).toNode();
       node.data.rotation = rotation;
+      // hx/hy 表示当前 handle 的局部符号；位移先旋转到世界，再比较缩放前后相反侧锚点的世界位置。
       const hx = direction.includes("left") ? -1 : direction.includes("right") ? 1 : 0;
       const hy = direction.includes("top") ? -1 : direction.includes("bottom") ? 1 : 0;
       const delta = rotateVector({ x: hx * 60, y: hy * 40 }, rotation);
@@ -49,6 +58,7 @@ test("all eight handles resize cards while retaining the opposite local anchor,
   }
 });
 
+// 纯文本宽高独立改变，最小值受限但不改变字号；仅拉宽或拉高不应连带另一维度。
 test("plain text width and height resize independently without changing the font", () => {
   const node = new PlainTextElement({ x: 0, y: 0 }).toNode();
   const patch = resizeFromPointer(node, "bottom-right", { x: 240, y: 72 });
@@ -61,6 +71,7 @@ test("plain text width and height resize independently without changing the font
   assert(min.width >= 60); assert(min.height >= 24); assert.equal(min.fontSize, undefined);
 });
 
+// 旋转跟随指针绕中心方向，Shift 风格吸附到 15 度，负方向归一为 0..360 范围。
 test("rotation follows the pointer, supports 15-degree snapping and normalizes the angle", () => {
   const node = new TextCardElement({ x: 0, y: 0 }).toNode();
   const center = nodeCenter(node);
@@ -71,6 +82,7 @@ test("rotation follows the pointer, supports 15-degree snapping and normalizes t
   close(rotationFromPointer(node, start, { x: center.x, y: center.y - 100 }), 270);
 });
 
+// checkpoint 内变换可保存恢复并一次 undo；纯文本 type、宽高、旋转和原字号各自保持正确。
 test("geometry and plain-text type survive save/restore and transforms undo as one gesture", () => {
   const node = new PlainTextElement({ x: 20, y: 30 }).toNode();
   let state = { past: [], present: { ...emptyCanvas(), nodes: [node] }, future: [] };
@@ -84,6 +96,7 @@ test("geometry and plain-text type survive save/restore and transforms undo as o
   close(undo.present.nodes[0].data.rotation, 0);
 });
 
+// 旧 material/text 草稿仍解码成卡片且补默认 rotation；负尺寸、超界角度及超大字号逐项拒绝。
 test("old text-card drafts remain cards and invalid transform values are rejected", () => {
   const old = { id: "old", type: "material", position: { x: 0, y: 0 }, data: { kind: "text", title: "Old", text: "Keep" } };
   const document = { ...emptyCanvas(), nodes: [old] };
@@ -94,6 +107,7 @@ test("old text-card drafts remain cards and invalid transform values are rejecte
   }
 });
 
+// 对 0/90/180 度检查四个边中心和单位法线，再验证缩放后的实际 right/bottom 锚点。
 test("connection endpoints stay on the exact border centers after resize and rotation", () => {
   const node = new TextCardElement({ x: 20, y: 30 }).toNode();
   const expected = {
@@ -115,6 +129,7 @@ test("connection endpoints stay on the exact border centers after resize and rot
   assert.deepEqual(nodeConnector(resized, "bottom").point, { x: 200, y: 280 });
 });
 
+// Bezier 字符串必须从精确 source anchor 开始到 target anchor 结束；selected 仅改变 UI，不改变几何路径。
 test("Bezier paths include both exact card anchors, independent of selected handle sizes", () => {
   const source = new TextCardElement({ x: 20, y: 30 }).toNode();
   const target = new TextCardElement({ x: 500, y: 180 }).toNode();

tests/canvas-icons.test.mjs

@@ -1,3 +1,7 @@
+/**
+ * 本地图标目录/分片和共享 ResourceLoader 测试。直接读仓库生成资产，校验本地哈希和引用，不访问图标 CDN。
+ * loader 的活跃并发与缓存容量受限，不能据此推断待处理队列本身有长度上限。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
@@ -8,10 +12,12 @@ import { iconAsset, validateIconShard } from "../src/lib/canvas-icon-loader.ts";
 import { decodeCanvas, emptyCanvas, makeCanvasNode } from "../src/lib/canvas.ts";
 import { createResourceLoader } from "../src/lib/resource-loader.ts";
 
+// 核对目录数量、ID 唯一性、分片文件哈希/体积/合法 SVG 数据、每个图标和分类存在；选取三个 ID 再验证旧快照往返。
 test("all Lucide and experimental Tabler IDs map to valid local shards and survive snapshots", async () => {
   assert.equal(catalog.filter((icon) => icon.source === "lucide").length, 2313);
   assert.equal(catalog.filter((icon) => icon.source === "tabler").length, 24);
   assert.equal(new Set(catalog.map((icon) => icon.name)).size, catalog.length);
+  // 按 manifest 逐分片读取本地 JSON；文件名哈希取 trimEnd 后文本的 SHA-256 前 12 位，单片小于 20000 字节。
   const loaded = new Map();
   for (const asset of Object.values(manifest.assets)) {
     const content = await readFile(`public${manifest.root}/${asset}`, "utf8");
@@ -30,13 +36,16 @@ test("all Lucide and experimental Tabler IDs map to valid local shards and survi
   }
 });
 
+// 对 script、onload、外部 paint URL 和 use/href 的样例逐个拒绝；这是数据校验例，不是完整浏览器 SVG 安全审计。
 test("icon data rejects executable shapes, events and external paint references", () => {
   for (const node of [["script", {}], ["path", { onload: "alert(1)" }], ["path", { fill: "url(https://example.com)" }], ["use", { href: "bad" }]]) {
     assert.throws(() => validateIconShard({ Star: [node] }));
   }
 });
 
+// 让 setImmediate 推进到调度任务阶段；用于观察尚未开始、排队及已释放容量的加载。
 const tick = () => new Promise((resolve) => setImmediate(resolve));
+// request 后立即 abort，尚未进入调度时不能启动网络加载，也不能把未完成值留入缓存。
 test("an immediately unmounted icon does not start a network request", async () => {
   let calls = 0;
   const loader = createResourceLoader(async () => { calls++; return "unused"; });
@@ -47,8 +56,10 @@ test("an immediately unmounted icon does not start a network request", async ()
   assert.equal(calls, 0); assert.equal(loader.peek("unused"), undefined);
 });
 
+// 同 key a 两个订阅只加载一次，容量二时 c 等待；完成后缓存命中不新增调用，峰值为二。
 test("loader bounds concurrency, deduplicates shared shards and reuses cache", async () => {
   let active = 0, peak = 0, calls = 0;
+  // 手动完成 active 加载，用于在容量为二时观察第三项等待及共享 key 去重。
   const finish = [];
   const loader = createResourceLoader(async (key) => {
     active++; peak = Math.max(peak, active); calls++;
@@ -62,6 +73,7 @@ test("loader bounds concurrency, deduplicates shared shards and reuses cache", a
   assert.equal(await loader.request("a"), "a"); assert.equal(calls, 3); assert.equal(peak, 2);
 });
 
+// 取消排队 b 后它永不启动；取消 a 的一个订阅不能中止另一个订阅共享的 active a。
 test("unused queued loads never start; a remaining subscriber keeps a shared load alive", async () => {
   const seen = []; let release;
   const loader = createResourceLoader(async (key) => { seen.push(key); if (key === "a") await new Promise((resolve) => release = resolve); return key; }, 1);
@@ -73,6 +85,7 @@ test("unused queued loads never start; a remaining subscriber keeps a shared loa
   await rejected; assert.equal(await shared, "a"); await tick(); assert.deepEqual(seen, ["a"]);
 });
 
+// active abort 后释放容量，失败 key 可重新加载；容量二的 LRU 在加入 a/b 后淘汰更早 fail，保留仍在缓存的 a。
 test("active aborts and failed requests can retry; least recently used cache is bounded", async () => {
   let fail = true;
   const loader = createResourceLoader(async (key, signal) => {

tests/canvas-media.test.mjs

@@ -1,3 +1,7 @@
+/**
+ * 旧画布 CanvasElement 类体系的纯图片能力及图标搜索测试，与 headless component registry 的模型定义分开。
+ * 只操作节点数据、几何和序列化，不挂载 renderer 或读取图片字节。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { canvasReducer, decodeCanvas, emptyCanvas, makeCanvasNode } from "../src/lib/canvas.ts";
@@ -5,6 +9,7 @@ import { CanvasElement, CardElement, PlainImageElement } from "../src/lib/canvas
 import { resizeFromPointer } from "../src/lib/canvas-geometry.ts";
 import { iconCatalog, iconsById, searchIcons } from "../src/components/canvas/icon-catalog.ts";
 
+// PlainImageElement 继承通用变换但不继承 CardElement，比例缩放、名称和 src 可恢复，重命名可撤销。
 test("plain images inherit transforms without card connections and preserve source/name on restore", () => {
   const image = new PlainImageElement({ x: 0, y: 0 }, "", "data:image/png;base64,YQ==");
   assert(image instanceof CanvasElement); assert.equal(image instanceof CardElement, false);
@@ -18,6 +23,7 @@ test("plain images inherit transforms without card connections and preserve sour
   assert.equal(canvasReducer(renamed, { type: "undo" }).present.nodes[0].data.title, "图片");
 });
 
+// 纯图片不能作为卡片连线目标；删除连线后 javascript: src 仍必须被解码器拒绝。
 test("plain image sources are required and pure images cannot acquire card connections", () => {
   const image = makeCanvasNode("plain-image", { x: 0, y: 0 }, "data:image/png;base64,YQ==");
   const card = makeCanvasNode("text", { x: 300, y: 0 });
@@ -27,6 +33,7 @@ test("plain image sources are required and pure images cannot acquire card conne
   assert.throws(() => decodeCanvas(JSON.stringify(document)));
 });
 
+// 图标 ID 唯一并符合后端字符形状，中文类别与英文词可搜索；仅验证当前本地目录，不请求后端搜索。
 test("the complete Lucide catalog has unique backend-compatible identifiers and searchable names", () => {
   assert(iconCatalog.length > 2000);
   assert.equal(iconsById.size, iconCatalog.length);

tests/canvas-member-scenario.mjs

@@ -1,21 +1,32 @@
+/**
+ * 旧 linked-board 成员迁移的 hook 与 DOM 场景，由 canvas-ui-check 提供运行环境。
+ * 内存 records/receipt 模拟版本、丢响应和能力探测；它验证客户端协调，不能替代后端数据库原子性或持久恢复测试。
+ */
 import assert from 'node:assert/strict';
 
+// 先直接驱动 useCanvasTree 精确控制竞态，再以 GraphCanvas 的拖放事件检查局部状态和其他节点可编辑。
 export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasNode,emptyCanvas,tick,mock,GraphCanvas,event,window}) {
+ // 父画布拥有分区入口和其他文本，子画布拥有待迁移图标；投影 ID 与服务端本地 ID 区分。
  const parent='aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',child='bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
  const frame=makeCanvasNode('frame',{x:100,y:100});frame.id='frame';frame.data.subgraph={boardId:child};
  const icon=makeCanvasNode('icon',{x:10,y:20});icon.id='moving';
  const other=makeCanvasNode('text',{x:950,y:100});other.id='other';
  let records,tree,posts,saves,release,mode,receipt,key,body,capability=true,capMode="",capCalls=0;
+ // 统一生成 JSON 响应，HTTP 错误也由客户端常规解析路径处理。
  const json=(v,status=200)=>new Response(JSON.stringify(v),{status,headers:{'content-type':'application/json'}});
+ // 只挂载 hook 并暴露最新 tree，测试直接调用命令而不依赖 DOM 手势。
  function Fixture(){const seed=structuredClone(records.get(parent));tree=useCanvasTree(parent,'w',seed.document,seed);return null;}
+ // 卸载后重建父子快照与请求记录；模式选择控制能力慢响应、失败、版本冲突、丢 ACK 或挂起提交。
  const reset=async(nextMode='success')=>{
   await act(async()=>{root.render(null);await tick();});localStorage.clear();
   records=new Map([[parent,{version:1,document:{...emptyCanvas(),schema_version:2,nodes:[structuredClone(frame),structuredClone(other)]}}],[child,{version:1,document:{...emptyCanvas(),schema_version:2,nodes:[structuredClone(icon)]}}]]);
   posts=[];saves=[];release=null;mode=nextMode;receipt=null;key=null;body=null;capMode=nextMode;capCalls=0;
   if(mode==='queued'){const second=structuredClone(icon);second.id='moving-two';second.position={x:100,y:20};records.get(child).document.nodes.push(second);mode='delayed';}
+  // 内存 API 按路径分流：完整快照保存、版本命令、分区创建与成员迁移，各自记录参与者版本。
   mock(async(url,options={})=>{
    const parts=new URL(url,'http://localhost').pathname.split('/'),id=parts[6],suffix=parts.slice(8).join('/'),method=options.method||'GET';
    if(suffix==='ai/runs')return json({runs:[]});
+   // 慢响应延迟超过两秒；一次网络失败只影响首个请求，允许检查重新探测而非永久判为不支持。
    if(suffix==='capabilities'){
     capCalls++;if(capMode==='slowcap'){await new Promise(r=>setTimeout(r,2100));if(options.signal?.aborted)throw new DOMException('Aborted','AbortError');}
     if(capMode==='cap-failure'&&capCalls===1)throw new TypeError('network unavailable');
@@ -27,6 +38,7 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
     const document=JSON.parse(options.body).document;saves.push({id,document});records.set(id,{version:records.get(id).version+1,document});return json({version:records.get(id).version});
    }
    if(suffix==='ai/runs'&&method==='POST'){const next=structuredClone(records.get(id));next.version++;records.set(id,next);return json({canvas_version:next.version,board_id:id});}
+   // 模拟创建父入口和新子图，可在状态已写入后暂缓返回，制造上传完成先于命令响应的窗口。
    if(suffix==='subgraphs'&&method==='POST'){
     const input=JSON.parse(options.body).frame,next=structuredClone(records.get(parent)),childID='66666666-6666-4666-8666-666666666666';
     const added=makeCanvasNode('frame',input.position);added.id=input.id;added.data.subgraph={boardId:childID};next.document.nodes.push(added);next.version++;records.set(parent,next);
@@ -34,29 +46,36 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
     if(mode==='create-delayed')await new Promise(resolve=>{release=resolve;});
     return json({transaction_id:crypto.randomUUID(),parent:{board_id:parent,...structuredClone(next)},snapshots:[{board_id:parent,...structuredClone(next)}],child:{board_id:childID,...empty}});
    }
+   // 保存原 body/key；命中上一次回执必须逐字节相同，返回既有结果而不再移动成员。
    assert.equal(suffix,'subgraphs/frame/members');posts.push({body:options.body,key:options.headers['Idempotency-Key']});
    if(receipt && options.headers['Idempotency-Key']===key){assert.equal(options.body,body);return json(receipt);}
    receipt=null;
    body=options.body;key=options.headers['Idempotency-Key'];const input=JSON.parse(body);
+   // 先核对双方期望版本，412/409 模式在迁移前返回；成功路径转换 owner 局部坐标并同时更新两个记录。
    for(const id of [parent,child])assert.equal(input.expected_versions[id],records.get(id).version);
    if(mode==='conflict'){records.get(parent).version++;mode='success';return json({error:'version_conflict'},412);}
    if(mode==='rejected'){mode='success';return json({error:'ownership_conflict'},409);}
    const source=structuredClone(records.get(input.source_board_id)),target=structuredClone(records.get(input.target_board_id));
    const moving=source.document.nodes.find(n=>n.id===input.node_ids[0]);const pos=input.positions?.[moving.id]||moving.position;
+   // 本夹具中分区内容原点相对父画布为 (124,136)，进出分区据此增减坐标。
    const converted=input.source_board_id===child?{x:pos.x+124,y:pos.y+136}:{x:pos.x-124,y:pos.y-136};
    source.document.nodes=source.document.nodes.filter(n=>n.id!==moving.id);target.document.nodes.push({...moving,position:converted});source.version++;target.version++;records.set(input.source_board_id,source);records.set(input.target_board_id,target);
    receipt={transaction_id:crypto.randomUUID(),snapshots:[...records].map(([board_id,value])=>({board_id,...structuredClone(value)}))};
+   // lost 在记录已更新后回 502；delayed 则挂起成功 ACK，分别覆盖不确定重试与并行本地编辑。
    if(mode==='lost')return json({error:'upstream_unavailable'},502);
    if(mode==='delayed')await new Promise(resolve=>{release=resolve;});
    return json(receipt);
   });
   await act(async()=>{root.render(h(Fixture));await tick();await tick();});
  };
+ // 有限轮询并推进 React effect，超时描述具体等待条件，不把请求已发出当作已确认。
  const wait=async(check,label)=>{for(let i=0;i<120;i++){if(check())return;await act(async()=>{await new Promise(r=>setTimeout(r,30));});}throw new Error('Timeout '+label);};
+ // 选中投影图标并模拟拖到父坐标，再提交跨 owner 迁移，等待请求实际进入替身。
  const start=async()=>{
   await act(async()=>{tree.select(child+'::moving');tree.setDragging(true);tree.nodesChanged([{type:'position',id:child+'::moving',position:{x:950,y:200},dragging:false}]);tree.setDragging(false);void tree.moveMembers(parent,'frame',child,parent,['moving'],[parent,child]);await tick();});
   await wait(()=>posts.length,'move admission');
  };
+ // 迁移携带落点，不先 PATCH；挂起期间只保护待移动成员，其他文本/拖动仍可继续。
  await reset('delayed');await start();
  assert.equal(saves.length,0,'Drop-only atomic moves must not PATCH first');assert.equal(tree.busy,false,'Member moves must not lock all editing');assert.equal(tree.memberJobs.length,1);
  assert.deepEqual(JSON.parse(posts[0].body).positions.moving,{x:826,y:64});
@@ -64,6 +83,7 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
  assert.equal(tree.rootDocument.nodes.find(n=>n.id==='other').data.text,'同步期间编辑');
  await act(async()=>{tree.nodesChanged([{type:'position',id:child+'::moving',position:{x:1200,y:900},dragging:false}]);await tick();});
  assert.deepEqual(tree.current.current.get(child).nodes[0].position,{x:826,y:64},'Pending member cannot move again');
+ // 放行 ACK 后检查坐标、选中和唯一归属，同时保留并最终保存无关编辑；其 undo 不能复活旧 owner。
  await act(async()=>{release();await tick();await tick();});await wait(()=>!tree.memberJobs.length,'move acknowledged');
  assert.equal(tree.rootDocument.nodes.find(n=>n.id==='other').data.text,'同步期间编辑','Remote snapshots preserve local text');
  assert.deepEqual(tree.rootDocument.nodes.find(n=>n.id==='other').position,{x:1100,y:130},'Remote snapshots preserve unrelated dragging');
@@ -76,13 +96,16 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
  await act(async()=>{await tree.redo();await tick();});
  assert.deepEqual(tree.rootDocument.nodes.find(n=>n.id==='other').position,{x:1100,y:130});
  console.log('PASS member sync: one POST, no preceding PATCH, local editing during delayed commit, geometry and draft merge');
+ // 丢 ACK 的重试沿用完全相同的 body/key，并保留响应丢失之后的新编辑。
  await reset('lost');await start();await wait(()=>tree.memberJobs[0]?.error,'uncertain result');
  assert.equal(tree.busy,false);await act(async()=>{tree.nodeAction('other',id=>({type:'edit',id,text:'响应丢失后的编辑'}));tree.retryMembers();await tick();});
  await wait(()=>!tree.memberJobs.length,'idempotent retry');assert.equal(posts.length,2);assert.equal(posts[0].body,posts[1].body);assert.equal(posts[0].key,posts[1].key);assert.equal(tree.rootDocument.nodes.find(n=>n.id==='other').data.text,'响应丢失后的编辑');
  console.log('PASS member retry: lost acknowledgement reuses body/key, keeps edits and does not duplicate ownership');
+ // 明确拒绝后读取新版本再构造新命令，因此新幂等键与旧键不同。
  await reset('conflict');await start();await wait(()=>tree.memberJobs[0]?.error,'version rejection');
  await act(async()=>{tree.retryMembers();await tick();});await wait(()=>!tree.memberJobs.length,'fresh version retry');assert.equal(posts.length,2);assert.notEqual(posts[0].key,posts[1].key);assert.equal(JSON.parse(posts[1].body).expected_versions[parent],2);
  console.log('PASS member conflict: definite zero-write rejection reloads versions before a fresh command');
+ // 两个迁移共享参与者，第二个等待首个 ACK 后的新版本；不额外发送坐标 PATCH。
  await reset('queued');await start();
  await act(async()=>{tree.nodesChanged([{type:'position',id:child+'::moving-two',position:{x:1000,y:300},dragging:false}]);void tree.moveMembers(parent,'frame',child,parent,['moving-two'],[parent,child]);await tick();});
  assert.equal(posts.length,1,'Second ownership change waits for participant versions');
@@ -91,6 +114,7 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
  assert.equal(saves.length,0);assert.equal(tree.rootDocument.nodes.filter(n=>n.id.startsWith('moving')).length,2);assert.equal(tree.current.current.get(child).nodes.length,0);
  console.log('PASS member queue: unrelated cross-frame drops serialize versions without extra coordinate PATCH');
  await reset();
+ // 未上传图片尚无服务端节点：本地切换归属可撤销；上传到当前 owner 后，后续 undo/redo 才使用服务端迁移。
  const pendingImage=makeCanvasNode('image',{x:200,y:200},'blob:editable-upload');pendingImage.id='pending-image';pendingImage.pendingUpload=pendingImage.id;
  await act(async()=>{tree.dispatch({type:'nodes',changes:[{type:'add',item:pendingImage}]});tree.movePendingImage(parent,child,pendingImage.id);await tick();});
  assert.equal(posts.length,0);assert.equal(saves.length,0);assert.deepEqual(tree.current.current.get(child).nodes.find(n=>n.id===pendingImage.id).position,{x:76,y:64});
@@ -102,6 +126,7 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
  await act(async()=>{await tree.undo();await tick();});assert.ok(tree.rootDocument.nodes.some(n=>n.id===pendingImage.id));assert.ok(!tree.current.current.get(child).nodes.some(n=>n.id===pendingImage.id));
  await act(async()=>{await tree.redo();await tick();});assert.ok(tree.current.current.get(child).nodes.some(n=>n.id===pendingImage.id));assert.equal(posts.length,2,'Undo/redo after persistence use real ownership transactions');
  console.log('PASS pending image ownership: editable local moves, atomic local undo, current-owner upload resolution and transactional undo after persistence');
+ // 版本刷新和分区创建响应都不能覆盖本地 pending/已完成图片；重复父快照也只能采用一次。
  await reset('create-delayed');
  const asyncImage=makeCanvasNode('image',{x:800,y:500},'blob:async-upload');asyncImage.id='async-image';asyncImage.pendingUpload=asyncImage.id;
  await act(async()=>{tree.dispatch({type:'nodes',changes:[{type:'add',item:asyncImage}]});await tick();});
@@ -112,13 +137,17 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
  await act(async()=>{tree.resolveImageUpload(asyncImage.id,{id:'77777777-7777-4777-8777-777777777777',url:'https://api.foundry.entroia.com/projects/endoleap/workspaces/w/assets/77777777-7777-4777-8777-777777777777'});release();await creation;await tick();});
  assert.ok(tree.rootDocument.nodes.some(n=>n.id===asyncImage.id&&!n.pendingUpload),'Concurrent command response cannot overwrite the resolved image');assert.equal(tree.rootDocument.nodes.filter(n=>n.id==='new-frame').length,1,'Repeated parent snapshots are adopted only once');
  console.log('PASS upload command races: version-only refresh and duplicate transaction snapshots retain pending/ready local images');
+ // 慢能力探测和首次探测失败都不能误触发旧协议回退，失败后需重新探测。
  await reset('slowcap');await start();await wait(()=>!tree.memberJobs.length,'slow capability move');assert.equal(saves.length,0,'A slow capability response must not trigger legacy PATCH fallback');
  await reset('cap-failure');await start();await wait(()=>!tree.memberJobs.length,'capability retry');assert.equal(capCalls,2);assert.equal(saves.length,0,'A failed prefetch is retried rather than cached as unsupported');
  console.log('PASS member capabilities: responses slower than two seconds and transient prefetch errors retain atomic moves');
+ // 明确不支持 positions 时才走旧的坐标保存加迁移两请求路径。
  capability=false;await reset();await start();await wait(()=>!tree.memberJobs.length,'legacy move');assert.equal(saves.length,1,'Old backend retains the coordinate save');assert.equal(JSON.parse(posts[0].body).positions,undefined);
  console.log('PASS member compatibility: capability-gated positions and legacy two-request fallback');
+ // 切到真实 GraphCanvas DOM 事件：拖出子图显示局部同步徽标，另一个节点仍可拖动且 ACK 不复位它。
  capability=true;await reset('delayed');
  await act(async()=>{root.render(null);await tick();root.render(h(GraphCanvas,{board:{id:parent,workspace_id:'w',kind:'board',title:'Member gestures',version:1},snapshot:structuredClone(records.get(parent))}));await tick();await tick();});
+ // 每次按投影 ID 重新查子图图标；成功迁移后应以父画布本地 ID 出现。
  const member=()=>document.querySelector(`.react-flow__node[data-id="${child}::moving"]`);
  await wait(()=>member(),'expanded icon');
  await event(member(),'mousedown',{clientX:150,clientY:160,button:0,buttons:1});
@@ -127,6 +156,7 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
  assert.ok(document.querySelector('[aria-label="元素同步状态"]'),'Moving node has a local sync badge');
  assert.equal([...document.querySelectorAll('[role="status"]')].some(n=>n.textContent==='正在同步画布…'),false,'No full-canvas synchronization overlay');
  assert.equal(member().classList.contains('draggable'),false,'Only pending nodes and frame geometry are protected');
+ // 记录无关节点变换，确认同步中实际拖动生效，随后与 ACK 后 DOM 比较。
  const otherNode=()=>document.querySelector('.react-flow__node[data-id="other"]');assert.equal(otherNode().classList.contains('draggable'),true);
  const originalTransform=otherNode().style.transform;
  await event(otherNode(),'mousedown',{clientX:1000,clientY:150,button:0,buttons:1});await event(window,'mousemove',{clientX:1010,clientY:150,buttons:1});await event(window,'mousemove',{clientX:1100,clientY:180,buttons:1});await event(window,'mouseup',{clientX:1100,clientY:180,button:0});
@@ -136,5 +166,6 @@ export async function canvasMemberScenario({root,act,h,useCanvasTree,makeCanvasN
  assert.equal(otherNode().style.transform,changedTransform,'Acknowledgement does not reset concurrent dragging');
  assert.ok(document.querySelector('.react-flow__node[data-id="moving"]'),'Moved node has exactly one new owner');
  console.log('PASS member UI: real cross-frame icon gesture, local status, no overlay and concurrent unrelated drag');
+ // 正常结束卸载 hook/画布；整个 JSDOM 与全局资源由外层 canvas-ui-check 清理。
  await act(async()=>{root.render(null);await tick();});
 }

tests/canvas-response.test.mjs

@@ -1,9 +1,15 @@
+/**
+ * 响应头、body 总传输与空闲三类截止时间的组合测试。用 Response/ReadableStream 和 fetch 替身验证读取、取消与诊断。
+ * HTTP 状态 200 不代表 body 可用：传输中断、非法 JSON、后端错误和 204 在 api 层需要分别表达。
+ */
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { fetchCanvasResponse } from '../src/lib/canvas-response.ts';
 import { api, ApiError } from '../src/lib/api.ts';
+// 延迟第二个真实流块，使传输超过 header 截止但仍在 body/idle 截止内；不是网络服务计时。
 const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
 
+// header 返回后取消其截止约束，两个 UTF-8 块继续读完；ETag、完整字节数、chunk 数和 transfer_ms 报告均要保留。
 test('snapshot body outlives the header deadline and reports transfer timing and bytes',async()=>{
  const reports=[]; const bytes=new TextEncoder().encode('{"version":210,"document":{"title":"测试"}}');
  const upstream=new Response(new ReadableStream({async start(c){ c.enqueue(bytes.slice(0,10));await wait(50);c.enqueue(bytes.slice(10));c.close();}}),{headers:{ETag:'"210"'}});
@@ -11,15 +17,18 @@ test('snapshot body outlives the header deadline and reports transfer timing and
  assert.equal(response.headers.get('etag'),'"210"');assert.equal((await response.json()).version,210);
  assert.equal(reports.length,1);assert.equal(reports[0].outcome,'complete');assert.equal(reports[0].bytes,bytes.length);assert.ok(reports[0].transfer_ms>=30);assert.equal(reports[0].chunks,2);
 });
+// 首块后不再产生数据，触发 idle 超时；consumer 必须收到 TimeoutError，上游 cancel 被调用，不能返回空快照。
 test('snapshot idle timeout aborts unfinished bodies instead of returning a valid empty snapshot',async()=>{
  const reports=[];let cancelled=false;
  const upstream=new Response(new ReadableStream({start(c){c.enqueue(new TextEncoder().encode('{"version":'));},cancel(){cancelled=true;}}));
  const response=await fetchCanvasResponse('https://example.test',{}, {headersMs:100,bodyMs:500,idleMs:15},async()=>upstream,r=>reports.push(r));
  await assert.rejects(response.json(),{name:'TimeoutError'});assert.ok(cancelled);assert.equal(reports[0].outcome,'error');assert.equal(reports[0].error,'TimeoutError');
 });
+// fetch 尚未返回头时监听 AbortSignal，header 超时应以 TimeoutError 拒绝，而不是等待 body 读取。
 test('header deadline rejects a server that has not responded',async()=>{
  await assert.rejects(fetchCanvasResponse('https://example.test',{}, {headersMs:10,bodyMs:500,idleMs:100},(_url,options)=>new Promise((_resolve,reject)=>options.signal.addEventListener('abort',()=>reject(options.signal.reason)))),{name:'TimeoutError'});
 });
+// 调用方 abort 和 consumer 直接 cancel 两条路径都释放上游读取，分别核对 AbortError 和 cancel 总次数。
 test('disconnect and consumer cancellation release the upstream read',async()=>{
  const abort=new AbortController();let cancelled=0;
  const make=()=>new Response(new ReadableStream({cancel(){cancelled++;}}));
@@ -27,6 +36,7 @@ test('disconnect and consumer cancellation release the upstream read',async()=>{
  abort.abort();await assert.rejects(response.text(),{name:'AbortError'});
  const second=await fetchCanvasResponse('https://example.test',{}, {headersMs:100,bodyMs:500,idleMs:100},async()=>make());await second.body.cancel();assert.equal(cancelled,2);
 });
+// 临时替换全局 fetch，检查 interrupted/invalid JSON/server error/null 四种结果；finally 恢复原 fetch，避免污染其他用例。
 test('client distinguishes a failed 200 body transfer, malformed JSON, server errors and 204',async()=>{
  const original=globalThis.fetch;
  try {

tests/canvas-style.test.mjs

@@ -1,11 +1,16 @@
+/**
+ * 旧快照画布的分支创建、文字样式、图标变换与恢复校验。这里只验证 legacy reducer/schema，不代表 headless 增量事务实现。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { branchCanvasNode, canvasReducer, decodeCanvas, emptyCanvas, makeCanvasNode } from "../src/lib/canvas.ts";
 import { CanvasElement, CardElement, IconElement } from "../src/lib/canvas-elements.ts";
 import { resizeFromPointer } from "../src/lib/canvas-geometry.ts";
 
+// 每次返回一个新文本节点，避免样式/分支变更在不同测试之间共享可变实例。
 function seeded() { return { ...emptyCanvas(), nodes: [makeCanvasNode("text", { x: 100, y: 200 })] }; }
 
+// 从同一父节点分别创建 text/script/image，检查连线端口、图片源、快照往返，再用一次 replace 历史整体撤销。
 test("branch type selection creates the chosen text, script or uploaded image and keeps the link in one undo step", () => {
   for (const kind of ["text", "script", "image"]) {
     const original = seeded();
@@ -22,6 +27,7 @@ test("branch type selection creates the chosen text, script or uploaded image an
   }
 });
 
+// 连线释放在任意画布坐标时，新 script 直接落在该 release 点，并只增加一条边。
 test("a connection released on the canvas creates the chosen node at the release point", () => {
   const original = seeded();
   const at = { x: -300, y: 700 };
@@ -30,6 +36,7 @@ test("a connection released on the canvas creates the chosen node at the release
   assert.equal(result.edges.length, 1);
 });
 
+// 颜色/背景/字体/行高等样式与字号可保存和遍历历史；部分样式清除只改目标键，保留未涉及颜色。
 test("all text styles and font size survive serialization, undo and redo", () => {
   const original = seeded();
   const style = { color: "#123456", background: "#fedcba", bold: true, italic: true, underline: true, align: "right", fontFamily: "serif", lineHeight: 1.8 };
@@ -45,6 +52,7 @@ test("all text styles and font size survive serialization, undo and redo", () =>
   assert.equal(decodeCanvas(JSON.stringify(cleared.present)).nodes[0].data.textStyle.bold, false);
 });
 
+// 逐个非法样式/类型和可执行样式片段均拒绝；非法 icon ID 也不能通过旧快照恢复。
 test("unsafe CSS, unknown styles and invalid icon identifiers cannot enter a restored canvas", () => {
   for (const style of [{ color: "url(https://example.com)" }, { background: "red" }, { fontFamily: "custom" }, { lineHeight: Infinity }, { bold: "true" }, { align: "justify" }, { align: ["left"] }, { fontFamily: ["sans"] }, { position: "fixed" }, []]) {
     const doc = seeded(); doc.nodes[0].data.textStyle = style;
@@ -55,6 +63,7 @@ test("unsafe CSS, unknown styles and invalid icon identifiers cannot enter a res
   assert.throws(() => decodeCanvas(JSON.stringify({ ...emptyCanvas(), nodes: [icon] })), /图标/);
 });
 
+// IconElement 继承通用变换而非 CardElement，ID、颜色、旋转可恢复；等比缩放有最小尺寸且不能分支。
 test("icon elements inherit transforms without card branching, preserve their identity and resize proportionally", () => {
   const element = new IconElement({ x: 10, y: 20 });
   assert(element instanceof CanvasElement);

tests/canvas-sync.test.mjs

@@ -1,12 +1,20 @@
+/**
+ * 旧 CanvasSync 完整快照自动保存及旧加载/草稿恢复测试。正在发送的请求串行，排队文档只保留最新份。
+ * 显式 retry 可以发送最新文档，与 headless 冻结请求的未知结果查询/原字节重试是不同契约，不可相互替代。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { CanvasSync, canvasPath, canvasPayload, readLocalRecovery } from "../src/lib/canvas-sync.ts";
 import { emptyCanvas, makeCanvasNode, canvasReducer } from "../src/lib/canvas.ts";
 import { loadBoardCanvas } from "../src/lib/canvas-loader.ts";
+// 返回固定 text ID 的新快照，便于只改变内容而不被随机 ID 差异触发多余保存。
 function document(text = "") { const doc = emptyCanvas(); const node = makeCanvasNode("text", { x: 0, y: 0 }); node.id = "text"; node.data.text = text; doc.nodes.push(node); return doc; }
+// 手动完成首个请求以检查在途期间版本和队列合并，reject 也供故障场景使用。
 function deferred() { let resolve, reject; const promise = new Promise((yes, no) => { resolve = yes; reject = no; }); return { promise, resolve, reject }; }
+// setImmediate 让保存泵进入 request，再添加后续文档，避免只测同一同步调用窗口。
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 
+// A 请求挂起时排队 B/C 不并发发送；A ACK=2 后只发送 C，并使用连续 If-Match 1→2。
 test("serialized autosaves use successive versions and coalesce queued documents", async () => {
   const calls = [], first = deferred();
   const writer = new CanvasSync(async (path, options) => {
@@ -23,6 +31,7 @@ test("serialized autosaves use successive versions and coalesce queued documents
   assert.equal(JSON.parse(calls[1].body).document.nodes[0].data.text, "C"); assert.equal(writer.version, 3);
 });
 
+// 首次 version_conflict 停止自动写，后续 B 不再发送，旧服务版本和错误保留。
 test("version conflicts stop automatic writes and preserve the latest pending content", async () => {
   const calls = [];
   const writer = new CanvasSync(async (_path, options) => { calls.push(options); throw new Error("version_conflict"); }, "canvas", { version: 7, document: emptyCanvas() }, () => {});
@@ -30,6 +39,7 @@ test("version conflicts stop automatic writes and preserve the latest pending co
   assert.equal(calls.length, 1); assert.equal(writer.error, "version_conflict"); assert.equal(writer.version, 7);
 });
 
+// 故障后手动 retry 发送当前最新 B，成功清错误；没有承诺保留最初 A 的冻结字节。
 test("explicit retry sends the newest document after a failed write", async () => {
   const calls = [];
   const writer = new CanvasSync(async (_path, options) => { calls.push(options); if (calls.length === 1) throw new Error("upstream_unavailable"); return { version: 2 }; }, "canvas", { version: 1, document: emptyCanvas() }, () => {});
@@ -37,6 +47,7 @@ test("explicit retry sends the newest document after a failed write", async () =
   assert.equal(calls.length, 2); assert.equal(JSON.parse(calls[1].body).document.nodes[0].data.text, "B"); assert.equal(writer.error, "");
 });
 
+// selected/measured 的变更不产生保存，payload 去 UI 字段；真正内容变化才调用一次接口。
 test("selection and measured dimensions do not trigger redundant writes or leak UI fields", async () => {
   const initial = document("keep"); let calls = 0;
   const writer = new CanvasSync(async () => { calls++; return { version: 2 }; }, "canvas", { version: 1, document: initial }, () => {});
@@ -48,6 +59,7 @@ test("selection and measured dimensions do not trigger redundant writes or leak
   assert.equal(calls, 1);
 });
 
+// workspace/board 的 ID 与 slug 四组合都得到 canonical board 身份及保存快照，路径仍按传入引用构造。
 test("all ID/slug combinations load the same canonical board and snapshot", async () => {
   for (const workspace of ["space-id", "creative-space"]) for (const board of ["board-id", "my-board"]) {
     const calls = [];
@@ -57,11 +69,13 @@ test("all ID/slug combinations load the same canonical board and snapshot", asyn
   }
 });
 
+// 快照读取失败或 board 身份不符直接拒绝，不以空文档允许用户覆盖远端。
 test("failed snapshot loads and mismatched boards prevent editing rather than creating an empty replacement", async () => {
   await assert.rejects(loadBoardCanvas(async (path) => { if (path.endsWith("/canvas")) throw new Error("upstream_unavailable"); return { id: "board", workspace_id: "space", kind: "board" }; }, "space", "board"), /upstream/);
   await assert.rejects(loadBoardCanvas(async (path) => path.endsWith("/canvas") ? { version: 1, document: emptyCanvas() } : { id: "other", workspace_id: "space", kind: "board" }, "space", "board"), /invalid_reference/);
 });
 
+// dirty 及旧草稿可提供显式恢复候选；clean 备份或与远端相同内容返回 null，不能静默覆盖服务。
 test("dirty local recovery and legacy drafts are offered for explicit migration; clean backups never replace server data", () => {
   const remote = { version: 3, document: document("server") };
   const local = document("local");
@@ -72,6 +86,7 @@ test("dirty local recovery and legacy drafts are offered for explicit migration;
   assert.equal(readLocalRecovery(storage({ "key:recovery": JSON.stringify({ document: remote.document, dirty: true }) }), "key", remote), null);
 });
 
+// 指纹按内容规范化键序，textStyle 属性顺序不同不触发保存，也不被当作未保存草稿差异。
 test("canonical fingerprints ignore server JSON key ordering", async () => {
   const remote = document("same"), local = document("same");
   remote.nodes[0].data.textStyle = { bold: true, color: "#123456" };
@@ -85,6 +100,7 @@ test("canonical fingerprints ignore server JSON key ordering", async () => {
 });
 
 
+// 先挂起两种读取再检查 started=2，metadata/snapshot 必须并发启动。
 test("board metadata and snapshot begin concurrently without a request waterfall", async () => {
   const started = []; const releases = [];
   const loading = loadBoardCanvas((path) => { started.push(path); return new Promise((resolve) => releases.push(() => resolve(path.endsWith("/canvas") ? { version: 1, document: emptyCanvas() } : { id: "board", workspace_id: "space", kind: "board" }))); }, "space", "board");
@@ -92,6 +108,7 @@ test("board metadata and snapshot begin concurrently without a request waterfall
 });
 
 
+// 微小 viewport 浮点误差保持同一 state，正常 viewport 也不单独保存；随后内容变化才写一次。
 test("viewport restoration roundoff does not create an autosave", async () => {
  const doc=document("keep");doc.viewport={x:132.834729193,y:-73.098456241,zoom:0.637185392};
  const state={past:[],present:doc,future:[]};
@@ -104,6 +121,7 @@ test("viewport restoration roundoff does not create an autosave", async () => {
 });
 
 
+// pendingUpload/Blob 节点和触边只在本地可编辑；传输排除它们，确认后的新 src、最新坐标和连线才一起进入快照。
 test("editable local uploads and touching edges never enter transport snapshots",async()=>{
  const pending={...makeCanvasNode("image",{x:30,y:40},"blob:local-file"),pendingUpload:"upload-one"};pending.id="image-local";
  const initial=emptyCanvas(),calls=[];

tests/canvas-ui-check.mjs

@@ -1,3 +1,8 @@
+/**
+ * 旧画布 JSDOM 回归入口：临时 esbuild 打包实际 React 组件，再注入 DOM/布局/网络替身执行场景。
+ * 运行会编译临时 fixture；不启动浏览器或开发服务器。模拟尺寸、命中和指针捕获不能替代浏览器布局/手势验证。
+ * CANVAS_UI_FEEDBACK_ONLY 仅跑反馈；ROTATION_BASELINE 对打包输入移除旧点击阻止逻辑，用于复现旋转取消。
+ */
 // Isolated DOM regression check; no browser or dev server is used.
 // npm install --prefix /tmp/canvas-ui-tools --ignore-scripts esbuild jsdom
 // CANVAS_UI_TOOLS=/tmp/canvas-ui-tools node tests/canvas-ui-check.mjs
@@ -7,37 +12,46 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 
+// 测试工具从 CANVAS_UI_TOOLS 指定目录解析，业务 React/组件仍来自当前仓库依赖。
 const tools = createRequire(resolve(process.env.CANVAS_UI_TOOLS || "/tmp/canvas-ui-tools", "package.json"));
 const { JSDOM } = tools("jsdom");
 const { build, stop } = tools("esbuild");
+// 独立 DOM 和 localhost origin 提供 localStorage 等环境，不请求 localhost 服务。
 const dom = new JSDOM('<!doctype html><html><body><div id="app"></div></body></html>', { url: "http://localhost", pretendToBeVisual: true });
 const { window } = dom;
 // React's async act creates MessageChannels; track and close test-owned ports.
 const NativeMessageChannel = globalThis.MessageChannel;
 const channels = [];
 globalThis.MessageChannel = class extends NativeMessageChannel { constructor() { super(); channels.push(this); } };
+// 把组件依赖的 DOM API 暴露到 Node 全局；这是独立测试进程，finally 不逐项恢复这些全局。
 for (const key of ["window", "document", "HTMLElement", "Element", "Node", "SVGElement", "Event", "CustomEvent", "MouseEvent", "KeyboardEvent", "MutationObserver", "localStorage", "getComputedStyle"]) Object.defineProperty(globalThis, key, { value: key === "window" ? window : typeof window[key] === "function" && key === "getComputedStyle" ? window[key].bind(window) : window[key], configurable: true });
 Object.defineProperty(globalThis, "navigator", { value: window.navigator, configurable: true });
 globalThis.requestAnimationFrame = window.requestAnimationFrame.bind(window);
 globalThis.cancelAnimationFrame = window.cancelAnimationFrame.bind(window);
+// 媒体查询、矩阵和 React act 环境使用最小替身，仅满足组件读取的字段。
 window.matchMedia = () => ({ matches: false, addListener() {}, removeListener() {}, addEventListener() {}, removeEventListener() {} });
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 globalThis.DOMMatrixReadOnly = window.DOMMatrixReadOnly = class { m22 = 1; };
+// 把 MouseEvent 扩为最小 pointer 事件并固定鼠标类型；不是原生多指输入实现。
 class PointerEvent extends window.MouseEvent { constructor(type, init = {}) { super(type, init); this.pointerId = init.pointerId || 1; this.isPrimary = true; this.pointerType = "mouse"; } }
 globalThis.PointerEvent = window.PointerEvent = PointerEvent;
+// WeakMap 记录元素持有的 pointerId，仅模拟捕获 API 状态，不会自动重定向后续事件。
 const captures = new WeakMap();
 window.HTMLElement.prototype.setPointerCapture = function (id) { captures.set(this, id); };
 window.HTMLElement.prototype.hasPointerCapture = function (id) { return captures.get(this) === id; };
 window.HTMLElement.prototype.releasePointerCapture = function () { captures.delete(this); };
+// 优先用内联宽高，其余给确定默认值；所有矩形起点为零，不进行 CSS 排版计算。
 const width = (element) => parseFloat(element.style.width) || (element.className?.includes?.("react-flow__node") ? 260 : 1200);
 const height = (element) => parseFloat(element.style.height) || (element.getAttribute("aria-label") === "图标列表" ? 192 : element.className?.includes?.("react-flow__node") ? 200 : 800);
 for (const [key, get] of [["offsetWidth", width], ["offsetHeight", height], ["clientWidth", width], ["clientHeight", height]]) Object.defineProperty(window.HTMLElement.prototype, key, { get() { return get(this); } });
 window.HTMLElement.prototype.getBoundingClientRect = function () { return { x: 0, y: 0, left: 0, top: 0, width: width(this), height: height(this), right: width(this), bottom: height(this) }; };
+// observe 立即同步回调尺寸，unobserve/disconnect 无行为；不验证真实观察器调度顺序。
 globalThis.ResizeObserver = window.ResizeObserver = class {
   constructor(callback) { this.callback = callback; }
   observe(element) { this.callback([{ target: element, contentRect: element.getBoundingClientRect() }]); }
   unobserve() {} disconnect() {}
 };
+// 场景可替换 Foundry 请求处理器；图标请求记录后从本地 public 读 JSON，拒绝其他网络目标。
 let apiMock = null;
 const requests = [];
 globalThis.fetch = async (url, options) => {
@@ -47,26 +61,33 @@ globalThis.fetch = async (url, options) => {
   if (options?.signal?.aborted) throw new DOMException("Aborted", "AbortError");
   return new Response(await readFile(resolve("public", String(url).slice(1))), { headers: { "Content-Type": "application/json" } });
 };
+// 临时目录只存打包 fixture，finally 删除；不把生成文件写入项目源码。
 const folder = await mkdtemp(resolve(tmpdir(), "endoleap-canvas-ui-"));
 try {
   const outfile = resolve(folder, "fixture.cjs");
+  // 打包实际组件和 React 为 CJS，CSS 置空；因此本测试不能证明最终样式或 Next 路由行为。
   await build({
     stdin: { contents: 'export { default as GraphCanvas } from "./src/components/canvas/graph-canvas"; export { AppFeedback } from "./src/components/ui/app-feedback"; export { IconButton } from "./src/components/ui/icon-button"; export { notify, dismissNotification } from "./src/lib/notifications"; export { BoardDirectory } from "./src/components/workspace/board-directory"; export { useCanvasTree } from "./src/components/canvas/use-canvas-tree"; export { useCanvasAI } from "./src/components/canvas/use-canvas-ai"; export { IconPicker } from "./src/components/canvas/icon-picker"; export { makeCanvasNode, emptyCanvas } from "./src/lib/canvas"; export { createRoot } from "react-dom/client"; export { act, createElement } from "react";', resolveDir: process.cwd(), loader: "tsx" },
     outfile, bundle: true, platform: "node", format: "cjs", jsx: "automatic", logLevel: "silent", nodePaths: [resolve("node_modules")],
     loader: { ".css": "empty" },
     plugins: [{ name: "dynamic-component", setup(build) {
+      // Next Link 替换为 a，dynamic 替换为 lazy/Suspense；这些模块不经过实际 Next 运行时。
       build.onResolve({ filter: /^next\/link$/ }, () => ({ path: "link", namespace: "fixture" }));
       build.onResolve({ filter: /^next\/dynamic$/ }, () => ({ path: "dynamic", namespace: "fixture" }));
       build.onLoad({ filter: /.*/, namespace: "fixture" }, ({ path }) => ({ contents: path === "link" ? 'import React from "react"; export default function Link(props) { return React.createElement("a",props); }' : 'import React from "react"; export default function dynamic(loader) { const Component = React.lazy(loader); return function Dynamic(props) { return React.createElement(React.Suspense, {fallback:null}, React.createElement(Component,props)); }; }', resolveDir: process.cwd() }));
+      // 只修改本次编译读入的 toolbar 文本来复现旧 portal 冒泡问题，不改磁盘源码。
       if (process.env.ROTATION_BASELINE === "1") build.onLoad({ filter: /node-style-toolbar\.tsx$/ }, async ({ path }) => ({ contents: (await readFile(path, "utf8")).replace('onClick={(event) => event.stopPropagation()}', ''), loader: "tsx" }));
     } }],
   });
   const { GraphCanvas, AppFeedback, IconButton, notify, dismissNotification, BoardDirectory, useCanvasAI, useCanvasTree, IconPicker, makeCanvasNode, emptyCanvas, act, createElement: h, createRoot } = createRequire(import.meta.url)(outfile);
+  // 共享 React root 供各场景替换组件；tick 让 effect 推进，event 在 act 内选择事件类型并派发。
   const root = createRoot(document.querySelector("#app"));
   const tick = () => new Promise((resolve) => setTimeout(resolve, 30));
   const event = async (target, type, init = {}) => { assert.ok(target, `Missing target for ${type}`); await act(async () => { const Type = type.startsWith("pointer") ? PointerEvent : type.startsWith("key") ? window.KeyboardEvent : window.MouseEvent; target.dispatchEvent(new Type(type, { bubbles: true, cancelable: true, view: window, ...init })); await tick(); }); };
+  // 非 feedback-only 才执行目录、轮询、旧画布工具和三个子场景；反馈场景总是执行。
   if (process.env.CANVAS_UI_FEEDBACK_ONLY !== "1") {
   {
+    // 目录 fixture 验证折叠、当前项祖先展开以及搜索保留完整父路径。
     const boards = [{ id: "root", title: "主画布", workspace_id: "w", slug: "root-slug" }, { id: "child", title: "未命名分区", parent_board_id: "root", workspace_id: "w", slug: "child-slug" }, { id: "nested", title: "孙画布", parent_board_id: "child", workspace_id: "w" }];
     const renderDirectory = (active, query = "") => h(BoardDirectory, { boards, workspace: "space", active, query, demo: false });
     await act(async () => { root.render(renderDirectory("root-slug")); await tick(); });
@@ -81,12 +102,14 @@ try {
     console.log("PASS directory: nested children, collapse, active ancestor expansion and search paths");
   }
   {
+    // 记录长定时任务并手动触发，检查空闲轮询退避和可见性暂停；finally 清理所有捕获计时器。
     const originalSetTimeout = globalThis.setTimeout, originalClearTimeout = globalThis.clearTimeout;
     const scheduled = [];
     globalThis.setTimeout = (callback, delay, ...args) => { const handle = originalSetTimeout(callback, delay, ...args); if (delay >= 1000) scheduled.push({ callback, delay, handle }); return handle; };
     let calls = 0, controls, renders = 0;
     apiMock = async () => { calls++; return Response.json({ runs: [] }); };
     const tree = { busy: false, writers: { current: new Map() } };
+    // 挂载 AI hook 并计数渲染，检查空结果轮询既不重复请求也不造成额外渲染。
     function Probe() { renders++; controls = useCanvasAI("w", "root", true, tree); return null; }
     try {
       await act(async () => { root.render(h(Probe)); await tick(); });
@@ -105,13 +128,16 @@ try {
       console.log("PASS polling: single discovery, idle backoff, no empty rerenders, hidden pause and visible resume");
     } finally { globalThis.setTimeout = originalSetTimeout; for (const item of scheduled) originalClearTimeout(item.handle); apiMock = null; }
   }
+  // 播种 demo 旧快照、分区和边，随后以 DOM 事件检查工具栏和历史操作。
   const node = makeCanvasNode("text", { x: 100, y: 100 }); node.id = "text-one";
   const frameNode = makeCanvasNode("frame", { x: 500, y: 100 }); frameNode.id = "frame-one"; frameNode.data.title = "分区 A";
   localStorage.setItem("endoleap_canvas_v1:w:b", JSON.stringify({ ...emptyCanvas(), nodes: [node, frameNode, { ...makeCanvasNode("text", { x: 900, y: 100 }), id: "text-two" }], edges: [{ id: "edge-test", source: "text-one", target: "text-two", sourceHandle: "right", targetHandle: "left" }] }));
   await act(async () => { root.render(h(GraphCanvas, { board: { id: "b", workspace_id: "w", kind: "board", title: "test", version: 1 } })); await tick(); });
   await event(document.querySelector('[data-id="text-one"]'), "click");
+  // 每次重查旋转按钮，避免 portal 重渲染后持有旧引用。
   const toggle = () => document.querySelector('[aria-label="旋转模式"]');
   await event(toggle(), "click");
+  // baseline 预期复现即时取消；正常路径要求旋转保持并可 Escape、undo/redo。
   if (process.env.ROTATION_BASELINE === "1") {
     assert.equal(toggle().getAttribute("aria-pressed"), "false", "Baseline should reproduce immediate cancellation");
     console.log("PASS baseline: portal click cancels rotation before the fix");
@@ -131,6 +157,7 @@ try {
     assert.equal(requests.length, 0, "Closed picker and text-only board must not load icon shapes");
     console.log("PASS rotation: portal click, pointer rotation, Escape, undo and redo");
 
+    // 分区进出通过 mouse 拖动触发，分别检查松开前预览、归属徽标和状态提示。
     const textNode = document.querySelector('.react-flow__node[data-id="text-one"]');
     await event(textNode, "mousedown", { clientX: 200, clientY: 200, button: 0, buttons: 1 });
     await event(window, "mousemove", { clientX: 210, clientY: 200, buttons: 1 });
@@ -149,6 +176,7 @@ try {
     assert.ok(document.querySelector('[role="status"]').textContent.includes("已移出「分区 A」"));
     console.log("PASS frames: actual drag previews, membership badge, count and join/leave announcements");
 
+    // 分区名称模式支持鼠标与键盘选择及历史，八向缩放控制可由 Escape 退出。
     const frameElement = document.querySelector('.react-flow__node[data-id="frame-one"]');
     await event(frameElement, "click");
     const group = document.querySelector('[role="radiogroup"][aria-label="分区名称显示模式"]');
@@ -170,6 +198,7 @@ try {
     assert.equal(document.querySelectorAll('[data-resize-handle]').length, 0);
     console.log("PASS frames: icon segments, no member count, keyboard choice, undo/redo and eight resize handles");
 
+    // 连线编辑覆盖曲线点增删、箭头 marker、常驻动画和无执行事件时停止动画。
     await event(document.querySelector('.react-flow__edge[data-id="edge-test"]'), "click");
     assert.ok(document.querySelector('[aria-label="连线编辑"]'));
     await event(document.querySelector('[aria-label="添加曲线点"]'), "click");
@@ -186,6 +215,7 @@ try {
     assert.equal(document.querySelector('[aria-label="曲线点 1"]'), null);
     console.log("PASS edges: select, add/remove curve knot, markers and always/execution-only animation");
 
+    // IconPicker 以确定容器高度测试窗口化 DOM、按需分片、共享 Tabler 缓存和分类后滚动复位。
     let choice;
     await act(async () => { root.render(h(IconPicker, { close() {}, choose(name) { choice = name; } })); await tick(); });
     await act(async () => { await tick(); });
@@ -209,20 +239,25 @@ try {
     assert.equal(grid.querySelector("button").dataset.index, "0", "Category change resets virtual window");
     console.log("PASS picker: bounded DOM, on-demand data, shared Tabler load and selection");
   }
+  // 正常模式追加 V2 linked-board 场景；baseline 跳过它，但成员和上传场景仍会执行。
   if (process.env.ROTATION_BASELINE !== "1") {
     let scenario;
     await act(async () => { scenario = await import("./canvas-v2-scenario.mjs"); await tick(); });
     const { canvasV2Scenario } = scenario;
     await canvasV2Scenario({ root, act, h, GraphCanvas, window, makeCanvasNode, emptyCanvas, event, tick, mock: (handler) => { apiMock = handler; } });
   }
+  // 注入 hook 与 mock setter，成员场景可精确控制版本、能力和 ACK 竞态。
   const { canvasMemberScenario } = await import("./canvas-member-scenario.mjs");
   await canvasMemberScenario({ root, act, h, useCanvasTree, GraphCanvas, event, window, makeCanvasNode, emptyCanvas, tick, mock: (handler) => { apiMock = handler; } });
+  // 上传场景复用 DOM/root，以文件、Image 和 API 替身检查预览、编辑与清理。
   const { canvasUploadScenario } = await import("./canvas-upload-scenario.mjs");
   await canvasUploadScenario({ root, act, h, GraphCanvas, window, emptyCanvas, event, tick, mock: (handler) => { apiMock = handler; } });
   }
+  // 最后验证通用通知/tooltip 与 demo 画布提示，再卸载 root。
   const { feedbackScenario } = await import("./feedback-scenario.mjs");
   await feedbackScenario({ root, act, h, AppFeedback, IconButton, notify, dismissNotification, GraphCanvas, window, makeCanvasNode, emptyCanvas, event, tick });
   await act(async () => { root.unmount(); await tick(); });
+// 清理临时打包文件、JSDOM、esbuild 及 act 创建的 MessageChannel 端口，恢复原通道构造器。
 } finally {
   await rm(folder, { recursive: true, force: true }); window.close(); stop();
   for (const channel of channels) { channel.port1.close(); channel.port2.close(); }

tests/canvas-upload-scenario.mjs

@@ -1,19 +1,31 @@
+/**
+ * 旧快照画布的 DOM 上传回归场景，由 canvas-ui-check 注入 React root、事件和 API 替身。
+ * 不访问真实上传服务；文件内容是字符串 test，图片尺寸/加载事件由测试提供，不能证明真实图片解码或浏览器布局。
+ */
 import assert from 'node:assert/strict';
+// 依次验证本地预览、上传期间编辑、失败重试、取消/删除、迟到响应、尺寸和卸载清理。
 export async function canvasUploadScenario({root,act,h,GraphCanvas,window,emptyCanvas,event,tick,mock}) {
+ // 固定画布与资源身份；asset 是模拟服务返回的受管原图地址和元数据。
  const parent='cccccccc-cccc-4ccc-8ccc-cccccccccccc',assetID='dddddddd-dddd-4ddd-8ddd-dddddddddddd';
  const asset={id:assetID,url:`https://api.foundry.entroia.com/projects/endoleap/workspaces/w/assets/${assetID}`,width:640,height:1280,bytes:4,mime_type:'image/png'};
  let snapshot,uploads,saves,release,mode;
+ // 把替身结果编码为 Response，走应用实际的响应处理路径。
  const json=(v,status=200)=>new Response(JSON.stringify(v),{status,headers:{'content-type':'application/json'}});
+ // 包装 revokeObjectURL 记录释放行为，同时调用原实现；finally 恢复包装和 Image 构造器。
  const revoked=[],originalRevoke=URL.revokeObjectURL;URL.revokeObjectURL=(url)=>{revoked.push(url);originalRevoke(url);};
  const NativeImage=window.Image;
+ // 最多轮询 100 次，每轮等待 30ms 并通过 act 推进 effect；超时用 label 标记未完成阶段。
  const wait=async(check,label)=>{for(let i=0;i<100;i++){if(check())return;await act(async()=>{await new Promise(r=>setTimeout(r,30));});}throw new Error('Timeout '+label);};
+ // 先卸载旧画布再清空草稿，为每种响应模式重建空快照、上传记录和 PATCH 记录。
  async function reset(nextMode='delayed'){
   await act(async()=>{root.render(null);await tick();});localStorage.clear();snapshot={version:1,document:{...emptyCanvas(),schema_version:2}};uploads=[];saves=[];release=null;mode=nextMode;
+  // 内存服务：上传可立即成功、403 失败或挂起；快照 PATCH 检查版本，并禁止持久化 blob URL。
   mock(async(url,options={})=>{
    const parts=new URL(url,'http://localhost').pathname.split('/'),suffix=parts.slice(8).join('/'),method=options.method||'GET';
    if(parts.at(-1)==='assets'&&method==='POST'){
     const file=options.body.get('image');uploads.push({key:options.headers['Idempotency-Key'],bytes:Buffer.from(await file.arrayBuffer()),signal:options.signal});
     if(mode==='failed')return json({error:'forbidden'},403);
+    // 仅延迟模式保留 release，场景手动释放后才返回成功，制造本地编辑与 ACK 的竞态。
     if(mode==='delayed')await new Promise(resolve=>{release=resolve;});
     return json(asset,201);
    }
@@ -28,6 +40,7 @@ export async function canvasUploadScenario({root,act,h,GraphCanvas,window,emptyC
   });
   await act(async()=>{root.render(h(GraphCanvas,{board:{id:parent,workspace_id:'w',kind:'board',title:'Upload test',version:1},snapshot:structuredClone(snapshot)}));await tick();});
  }
+ // 点击工具栏并注入 FileList 替身，再派发 change；只模拟选文件流程，不调用系统文件选择器。
  async function choose(label='添加图片'){
   await event(document.querySelector(`[aria-label="${label}"]`),'click');
   const input=document.querySelector('input[type="file"][accept^="image/"]');
@@ -36,12 +49,15 @@ export async function canvasUploadScenario({root,act,h,GraphCanvas,window,emptyC
   await wait(()=>uploads.length,'upload started');
  }
  try {
+  // 首次上传先检查 blob 预览已出现、字节到达替身，但服务端文档和保存记录仍为空。
   await reset();await choose();
   const local=document.querySelector('.react-flow__node img[src^="blob:"]');assert.ok(local,'Selected file immediately appears on the canvas before upload acknowledgement');const localURL=local.getAttribute('src');
   assert.ok(document.querySelector('[aria-label="图片上传状态"]'));assert.equal(snapshot.document.nodes.length,0);assert.equal(saves.length,0);assert.deepEqual(uploads[0].bytes,Buffer.from('test'));
   const imageNodeID=local.closest('.react-flow__node').dataset.id;
+  // 按最初节点 ID 每次重查 DOM，避免异步重渲染后继续持有已替换元素。
   const editable=()=>document.querySelector(`.react-flow__node[data-id="${imageNodeID}"]`);
   assert.ok(editable().classList.contains('draggable'),'Uploading images are real draggable nodes');
+  // 上传挂起时实际派发拖动、标题输入和缩放事件，记录结果用于 ACK 后比较。
   await event(editable(),'mousedown',{clientX:200,clientY:200,button:0,buttons:1});await event(window,'mousemove',{clientX:210,clientY:200,buttons:1});await event(window,'mousemove',{clientX:280,clientY:250,buttons:1});await event(window,'mouseup',{clientX:280,clientY:250,button:0});
   const editedPosition=editable().style.transform;
   await event(editable().querySelector('[title="双击编辑名称"]'),'dblclick');
@@ -53,19 +69,23 @@ export async function canvasUploadScenario({root,act,h,GraphCanvas,window,emptyC
   const resize=document.querySelector('[data-resize-handle="bottom-right"]'),surface=editable().querySelector('[style*="rotate("]');
   await event(resize,'pointerdown',{clientX:400,clientY:400,button:0});await event(surface,'pointermove',{clientX:460,clientY:440,buttons:1});await event(surface,'pointerup',{clientX:460,clientY:440});await event(window,'keydown',{key:'Escape'});
   const editedWidth=editable().style.width,editedHeight=editable().style.height;
+  // 上传不锁住其他内容创建；确认后先保留本地预览，等远端 load 事件才释放 blob URL。
   await event(document.querySelector('[aria-label="添加文本卡片"]'),'click');assert.equal(document.querySelectorAll('.react-flow__node').length,2,'Other content can be added during upload');
   await act(async()=>{release();await tick();});await wait(()=>document.querySelector('.react-flow__node img[src$="?variant=preview"]'),'managed image rendered');
   assert.ok(document.querySelector(`img[src="${localURL}"]`),'Local image remains visible while remote preview loads');
   const remote=document.querySelector('.react-flow__node img[src$="?variant=preview"]');await act(async()=>{remote.dispatchEvent(new window.Event('load'));await tick();});
   assert.ok(!document.querySelector(`img[src="${localURL}"]`));assert.ok(revoked.includes(localURL));await wait(()=>snapshot.document.nodes.some(n=>n.data.src===asset.url),'original reference saved');
+  // 确认资源引用只保存一次，并保留上传期间的标题、位置和尺寸修改。
   const persisted=snapshot.document.nodes.find(n=>n.id===imageNodeID);assert.equal(persisted.data.title,'上传前改名');assert.equal(editable().style.transform,editedPosition);assert.equal(editable().style.width,editedWidth);assert.equal(editable().style.height,editedHeight);
   assert.equal(snapshot.document.nodes.filter(n=>n.data.src===asset.url).length,1);assert.equal(snapshot.document.nodes.find(n=>n.data.src===asset.url).data.assetId,assetID);
   console.log('PASS uploads: immediate local preview, unrelated editing, original-byte attachment and no blob URL persistence');
+  // 403 后预览和文件仍保留；手动重试沿用第一次幂等键，最终只落一个节点。
   await reset('failed');await choose();await wait(()=>document.querySelector('[aria-label="图片上传状态"]')?.textContent.includes('上传未完成'),'visible upload failure');
   assert.ok(document.querySelector('img[src^="blob:"]'));assert.equal(saves.length,0);const key=uploads[0].key;mode='delayed';
   await event([...document.querySelectorAll('[aria-label="图片上传状态"] button')].find(n=>n.textContent==='重试'),'click');assert.equal(uploads.length,2);assert.equal(uploads[1].key,key,'Manual retry retains the original idempotency key');
   await act(async()=>{release();await tick();});await wait(()=>snapshot.document.nodes.length===1,'retry saves exactly one image');assert.equal(snapshot.document.nodes[0].data.src,asset.url);
   console.log('PASS upload retry: retained file/preview, stable idempotency key and exactly one persisted node');
+  // 取消相当于可撤销的本地删除；随后单独检查上传中删除、ACK 迟到以及撤销后的受管资源恢复。
   await reset('failed');await choose();await wait(()=>document.querySelector('[aria-label="图片上传状态"]')?.textContent.includes('上传未完成'),'failed cancellation');
   const cancelledURL=document.querySelector('img[src^="blob:"]').getAttribute('src');await event([...document.querySelectorAll('[aria-label="图片上传状态"] button')].find(n=>n.textContent==='取消'),'click');assert.equal(document.querySelector('img[src^="blob:"]'),null);assert.equal(saves.length,0);await event(document.querySelector('[aria-label="撤销"]'),'click');assert.ok(document.querySelector(`img[src="${cancelledURL}"]`),'Undo restores a locally deleted upload');
   await reset();await choose();const deletedID=document.querySelector('.react-flow__node').dataset.id;
@@ -73,10 +93,13 @@ export async function canvasUploadScenario({root,act,h,GraphCanvas,window,emptyC
   await act(async()=>{release();await tick();});await act(async()=>{await new Promise(r=>setTimeout(r,900));});assert.equal(snapshot.document.nodes.length,0,'Late upload completion must not resurrect a deleted node');
   await event(document.querySelector('[aria-label="撤销"]'),'click');await wait(()=>snapshot.document.nodes.length===1,'undo after upload completed');assert.equal(snapshot.document.nodes[0].id,deletedID);assert.equal(snapshot.document.nodes[0].data.src,asset.url);
   console.log('PASS editable uploads: move/resize/rename persist through acknowledgement, late completion respects deletion and undo');
+  // 尺寸替身异步回调 640×960；立即/延迟上传两条路径都应形成 320×480，元数据确认不额外占撤销步骤。
   window.Image=class {naturalWidth=640;naturalHeight=960;set src(_){setTimeout(()=>this.onload?.(),0);}};
   await reset('immediate');await choose('添加纯图片');await wait(()=>snapshot.document.nodes.length===1,'fast upload dimensions');assert.equal(snapshot.document.nodes[0].width,320);assert.equal(snapshot.document.nodes[0].height,480);await event(document.querySelector('[aria-label="撤销"]'),'click');assert.equal(document.querySelector('.react-flow__node'),null,'Intrinsic size and attachment acknowledgement do not add undo steps');
   await reset();await choose('添加纯图片');assert.equal(document.querySelector('.react-flow__node').style.width,'320px');assert.equal(document.querySelector('.react-flow__node').style.height,'480px');
+  // 卸载后检查 signal 已取消与 URL 已释放；再放行旧响应，不能触发文档保存。
   const unmountedURL=document.querySelector('img[src^="blob:"]').getAttribute('src');await act(async()=>{root.render(null);await tick();});assert.ok(uploads[0].signal.aborted);assert.ok(revoked.includes(unmountedURL));release();await tick();assert.equal(saves.length,0);
   console.log('PASS upload cleanup: undoable deletion, unmount revocation/abort and plain-image aspect ratio');
+ // 无论断言是否失败，都恢复全局替身并卸载此场景的组件。
  } finally {window.Image=NativeImage;URL.revokeObjectURL=originalRevoke;await act(async()=>{root.render(null);await tick();});}
 }

tests/canvas-v2-scenario.mjs

@@ -1,18 +1,27 @@
+/**
+ * 旧 schema_version=2 linked-board 画布的 JSDOM 集成场景，不是 headless 增量协议版本号。
+ * 真实组件消费内存 API 替身：快照、事务回执、AI 模型/事件和图片均由此文件生成；不调用模型供应商或实际 Foundry 服务。
+ */
 import assert from 'node:assert/strict';
+// 依次检查只读加载、子图编辑/AI、折叠展开、分区 undo/redo、跨 owner 连线与图片处理。
 export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvasNode,emptyCanvas,event,tick,mock}) {
+ // 构造父入口、子节点、外部 AI 文本与图片；父边引用入口 port，子内容只存在子快照中。
  const parent='22222222-2222-4222-8222-222222222222', child='11111111-1111-4111-8111-111111111111';
  const frame=makeCanvasNode('frame',{x:100,y:100});frame.id='linked-frame';frame.data={...frame.data,title:'真实子图',subgraph:{boardId:child},ports:[{id:'out',nodeId:'child-text',handle:'right',direction:'output'}],presentation:{collapsed:false,contentScale:1,expandedSize:{width:640,height:400},collapsedSize:{width:240,height:140}}};
  const inside=makeCanvasNode('text',{x:10,y:20});inside.id='child-text';inside.data.title='子节点';inside.data.text='原始输入';
  const target=makeCanvasNode('text',{x:950,y:100});target.id='outside';target.data.ai={enabled:true,modelId:'test-text',prompt:'继续整理',parameters:{}};
  const image=makeCanvasNode('image',{x:1100,y:450},'https://example.com/reference.png');image.id='image-target';image.data.title='图片目标';
  const legacy=makeCanvasNode('plain-image',{x:1600,y:100},'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB');legacy.id='legacy-image';
+ // Map 是模拟服务端快照事实；版本随每个写分支递增，不能与投影画面中的 :: ID 混用。
  const records=new Map([[parent,{version:10,document:{...emptyCanvas(),schema_version:2,nodes:[frame,target,image,legacy],edges:[{id:'boundary',source:frame.id,sourceHandle:'port:out',target:target.id,targetHandle:'left',data:{animation:{mode:'executing',effect:'flow'}}}]}}],[child,{version:3,document:{...emptyCanvas(),schema_version:2,nodes:[inside]}}]]);
  let connectionReceipt=null,connectionKey=null,connectionBody=null,connectionRequests=0;
  const receipts=new Map();let createCount=0;
  let assetUploads=0;
  const saves=[];let job=null,poll=0,seq=0,imageRuns=0;const events=[];
+ // Response 包装走应用解码；emit 用递增 seq 支持 after_seq 事件过滤。
  const json=(data,status=200)=>new Response(JSON.stringify(data),{status,headers:{'content-type':'application/json'}});
  const emit=(type,data)=>events.push({seq:++seq,type,...data});
+ // 按 assets、快照、能力、模型、AI、连线和事务路径分流；未列出的请求立即失败。
  mock(async(url,options={})=>{
   if(new URL(url,'http://localhost').pathname.endsWith('/assets') && options.method==='POST') {
    assetUploads++;assert.ok(options.headers['Idempotency-Key']);assert.ok(options.body.get('image').size>0);
@@ -22,6 +31,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
   const parsed=new URL(url,'http://localhost'), parts=parsed.pathname.split('/');const board=parts[6], suffix=parts.slice(8).join('/'), method=options.method||'GET';
   const snapshot=records.get(board);assert.ok(snapshot,`Unknown canvas ${board} ${url}`);
   if(!suffix&&method==='GET')return json(structuredClone(snapshot));
+  // 快照保存检查 If-Match，禁止投影 ID 持久化和把子节点重复写入父画布。
   if(!suffix&&method==='PATCH'){
    if(options.headers['If-Match']!==`"${snapshot.version}"`)return json({error:'version_conflict'},412);
    const payload=JSON.parse(options.body).document;
@@ -32,6 +42,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
   if(suffix==='capabilities')return json({supported_schema_versions:[1,2],subgraphs:{connections:true}});
   if(suffix==='ai/models')return json({models:[{id:'test-text',label:'测试文本模型',available:true,output_modalities:['text'],input_modalities:['text'],parameters_schema:{type:'object',properties:{},additionalProperties:false}},{id:'test-image',label:'测试图片模型',available:true,output_modalities:['image'],input_modalities:['text','image'],parameters_schema:{type:'object',properties:{},additionalProperties:false}}]});
   if(suffix==='ai/runs'&&method==='GET')return json({runs:job&&['queued','running'].includes(job.status)?[{run_id:'test-run',board_id:child,status:job.status}]:[],next_cursor:null});
+  // 根据目标区分文本/图片模型及参与画布，校验幂等键与版本，再重置这次模拟 run 的事件序列。
   if(suffix==='ai/runs'&&method==='POST'){
    const input=JSON.parse(options.body);const isImage=input.node_id==='image-target';assert.equal(board,isImage?parent:child);assert.equal(input.node_id,isImage?'image-target':'child-text');assert.equal(input.model_id,isImage?'test-image':'test-text');assert.equal(input.propagate,!isImage);assert.equal(options.headers['If-Match'],`"${snapshot.version}"`);assert.ok(options.headers['Idempotency-Key']);
    snapshot.document.nodes.find(node=>node.id===input.node_id).data.ai={enabled:true,modelId:input.model_id,prompt:input.prompt,parameters:{},propagate:true};snapshot.version++;
@@ -40,6 +51,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
   if(suffix.startsWith('ai/runs/image-run-')&&suffix.endsWith('/cancel')&&method==='POST'){
    job.status='cancelled';emit('step.cancelled',{board_id:parent,node_id:'image-target'});return json({run_id:job.id,status:'cancelled'});
   }
+  // 图片轮询第二次生成 src/assetId 并发出 output/applied；取消状态不走成功写回分支。
   if(suffix.startsWith('ai/runs/image-run-')&&method==='GET'){
    poll++;if(job.status!=='cancelled')job.status=poll<2?'running':'succeeded';
    if(poll===2&&job.status==='succeeded'){
@@ -48,6 +60,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
    }
    const after=+(parsed.searchParams.get('after_seq')||0);return json({run_id:job.id,status:job.status,next_seq:seq,has_more:false,events:events.filter(e=>e.seq>after),steps:[{step_id:'image-step',board_id:parent,node_id:'image-target',status:job.status}],outputs:[],applied_versions:{}});
   }
+  // 三轮推进子文本生成、跨边活跃及父文本传播；应用靠 seq 游标读取新增事件。
   if(suffix==='ai/runs/test-run'&&method==='GET'){
    poll++;
    if(poll===1){job.status='running';emit('step.running',{board_id:child,node_id:'child-text'});}
@@ -55,6 +68,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
    if(poll>=3&&job.status!=='succeeded'){job.status='succeeded';records.get(parent).document.nodes.find(node=>node.id==='outside').data.text='向下传播结果';records.get(parent).version++;emit('step.applied',{board_id:parent,node_id:'outside',canvas_version:records.get(parent).version,patch:{text:'向下传播结果'}});emit('edge.completed',{logical_edge_id:parent+'/boundary'});}
    const after=+(parsed.searchParams.get('after_seq')||0);return json({run_id:'test-run',status:job.status,next_seq:seq,has_more:false,events:events.filter(e=>e.seq>after),steps:[{step_id:'one',board_id:child,node_id:'child-text',status:poll>=2?'succeeded':'running'},{step_id:'two',board_id:parent,node_id:'outside',status:poll>=3?'succeeded':poll>=2?'running':'queued'}],outputs:[],applied_versions:{}});
   }
+  // 首次连线在父入口增 port 与父边并更新双方版本，故意回 502；重试核对原 body/key 后返回同一回执。
   if(suffix==='connections'&&method==='POST'){
    connectionRequests++;
    if(connectionReceipt){assert.equal(options.headers['Idempotency-Key'],connectionKey);assert.equal(options.body,connectionBody);return json(connectionReceipt,201);}
@@ -67,11 +81,13 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
    connectionReceipt={transaction_id:'tx-connect',parent:{board_id:parent,...structuredClone(records.get(parent))},snapshots:[{board_id:parent,...structuredClone(records.get(parent))},{board_id:child,...structuredClone(records.get(child))}],undo_receipt:{expires_at:new Date(Date.now()+86400000).toISOString()}};
    return json({error:'upstream_unavailable'},502); // Simulate a lost response after the atomic commit.
   }
+  // 创建的撤销检查当前父/子版本，以新父版本恢复原内容并返回归档子 ID；回执由内存生成。
   if(suffix.startsWith('transactions/tx-create-')&&suffix.endsWith('/undo')&&method==='POST'){
    const id=suffix.split('/')[1],receipt=receipts.get(id),input=JSON.parse(options.body);assert.ok(receipt);assert.deepEqual(Object.keys(input.expected_versions).sort(),[parent,receipt.child].sort());assert.equal(input.expected_versions[parent],records.get(parent).version);assert.equal(input.expected_versions[receipt.child],records.get(receipt.child).version);
    const next={...receipt.before,version:records.get(parent).version+1};records.set(parent,next);records.get(receipt.child).version++;
    return json({transaction_id:'undo-'+id,parent:{board_id:parent,...structuredClone(next)},snapshots:[{board_id:parent,...structuredClone(next)}],archived_board_ids:[receipt.child],applied_versions:{[parent]:next.version,[receipt.child]:records.get(receipt.child).version}});
   }
+  // 每次创建新子 ID 和事务回执，记录创建前父快照，供后续撤销与重做参与者检查。
   if(suffix==='subgraphs'&&method==='POST'){
    const input=JSON.parse(options.body).frame;const newChild=crypto.randomUUID();const tx='tx-create-'+(++createCount);const beforeCreate=structuredClone(snapshot);assert.equal(options.headers['If-Match'],`"${snapshot.version}"`);
    const node=makeCanvasNode('frame',input.position);node.id=input.id;node.data.title=input.title;node.data.subgraph={boardId:newChild};snapshot.document.nodes.push(node);snapshot.version++;
@@ -81,6 +97,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
   }
   throw new Error(`Unhandled V2 API ${method} ${url}`);
  });
+ // 用非整数 viewport 检查加载、测量与缩放都不写内容；视图状态仅记本地 viewport key。
  const readOnly=structuredClone(records.get(parent));readOnly.document.viewport={x:132.834729193,y:-73.098456241,zoom:0.637185392};
  await act(async()=>{root.render(h(GraphCanvas,{key:'read-only',board:{id:parent,workspace_id:'w',kind:'board',title:'V2 read only',version:1},snapshot:readOnly}));await tick();});
  await act(async()=>{await new Promise(resolve=>setTimeout(resolve,1100));});
@@ -94,10 +111,12 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
  await act(async()=>{root.render(null);await tick();});
  await act(async()=>{root.render(h(GraphCanvas,{key:'v2',board:{id:parent,workspace_id:'w',kind:'board',title:'V2 test',version:1},snapshot:structuredClone(records.get(parent))}));await tick();});
  await act(async()=>{await tick();});
+ // 通过 child::localId 查展开投影；只读挂载不得 PATCH，子节点必须只出现一次。
  const node=()=>document.querySelector(`.react-flow__node[data-id="${child}::child-text"]`);
  await act(async()=>{await new Promise(resolve=>setTimeout(resolve,1100));});
  assert.equal(saves.length,0,'Opening a root and its child without edits must not PATCH');
  assert.ok(node(),'Child is expanded from its own snapshot');assert.equal(document.querySelectorAll(`.react-flow__node[data-id="${child}::child-text"]`).length,1);
+ // 选择子节点进入 AI 模式，加载文本模型并开启下游传播；拖动与事件写回交错。
  await event(node(),'click');await event(document.querySelector('[aria-label="AI 模式"]'),'click');await act(async()=>{await tick();});
  assert.ok(document.querySelector('[aria-label="元素 AI 工具"]'));assert.ok(document.querySelector('[aria-label="AI 模型"]').textContent.includes('测试文本模型'));
  await event(document.querySelector('[aria-label="继续向下传播"]'),'click');
@@ -105,6 +124,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
  assert.ok(job);assert.equal(document.querySelector('[aria-label="AI 模式"]').getAttribute('aria-pressed'),'true');
  // Move a child while the run executes. Its original owner receives the save.
  await event(node(),'mousedown',{clientX:200,clientY:200,button:0,buttons:1});await event(window,'mousemove',{clientX:210,clientY:200,buttons:1});await event(window,'mousemove',{clientX:240,clientY:215,buttons:1});await event(window,'mouseup',{clientX:240,clientY:215,button:0});
+ // 有限轮询真实组件消费替身事件的结果；通过 act 推进 effect，而非直接替组件改 DOM。
  const waitUntil=async(check,label)=>{for(let i=0;i<100;i++){if(check())return;await act(async()=>{await new Promise(r=>setTimeout(r,80));});}throw new Error('Timed out: '+label);};
  await waitUntil(()=>node()?.querySelector('textarea')?.value==='生成后的子图内容','child AI result');
  assert.ok(document.querySelector('.react-flow__edge[data-id="boundary"] animateMotion'),'Actual edge.active event starts execution-only animation');
@@ -112,6 +132,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
  await waitUntil(()=>document.querySelector('.react-flow__node[data-id="outside"] textarea')?.value==='向下传播结果','downstream AI result');
  assert.equal(document.querySelector('.react-flow__edge[data-id="boundary"] animateMotion'),null,'Completed run stops execution-only animation');
  assert.ok(saves.some(save=>save.board===child),'Child edits save to child canvas');
+ // 折叠隐藏投影、展开恢复，子局部位置应保持；随后新建分区并反复 undo/redo，检查新子参与者。
  const childPosition=structuredClone(records.get(child).document.nodes[0].position);
  await event(document.querySelector('.react-flow__node[data-id="linked-frame"]'),'click');
  await event(document.querySelector('[aria-label="收起子画布"]'),'click');assert.equal(node(),null);assert.ok(document.querySelector('[aria-label="展开子画布"]'));
@@ -127,17 +148,20 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
  await event(node(),'click');
  const fromHandle=node().querySelector('[data-handleid="bottom"]');
  const toHandle=document.querySelector('.react-flow__node[data-id="outside"] [data-handleid="left"]');
+ // JSDOM 没有真实命中布局，临时将 elementFromPoint 指向目标 handle，驱动连线事件后恢复。
  const originalHitTest=document.elementFromPoint;document.elementFromPoint=()=>toHandle;
  await event(fromHandle,'mousedown',{clientX:250,clientY:250,button:0,buttons:1});
  await event(document,'mousemove',{clientX:500,clientY:250,buttons:1});
  await event(document,'mouseup',{clientX:500,clientY:250,button:0});
  document.elementFromPoint=originalHitTest;
  await waitUntil(()=>records.get(parent).document.nodes.find(node=>node.id==='linked-frame').data.ports.some(port=>port.id==='generated-port'),'cross-canvas connection transaction');
+ // 等待不确定结果提示再点击重试；两次请求最终只产生一条额外边。
  await waitUntil(()=>[...document.querySelectorAll('button')].some(button=>button.textContent==='重试同步'),'uncertain transaction recovery');
  await event([...document.querySelectorAll('button')].find(button=>button.textContent==='重试同步'),'click');
  assert.equal(connectionRequests,2);assert.equal(document.querySelector('.react-flow__edge[data-id="'+connectionReceipt.parent.document.edges.at(-1).id+'"]')!==null,true);
  assert.equal(records.get(parent).document.edges.length,2);
  console.log('PASS connections: real handle gesture, capability gate, LCA transaction and exact participant versions');
+ // AI 模式保持开启但按新图片目标筛选模型；生成只更新资源，尺寸/标题保持，下一次 run 可取消。
  await event(document.querySelector('.react-flow__node[data-id="image-target"]'),'click');
  await act(async()=>{await tick();});
  assert.ok(document.querySelector('[aria-label="AI 模型"]').textContent.includes('测试图片模型'),'Sticky AI mode selects models for the newly selected image');
@@ -151,6 +175,7 @@ export async function canvasV2Scenario({root,act,h,GraphCanvas,window,makeCanvas
  await waitUntil(()=>document.querySelector('[aria-label="元素 AI 工具"]')?.textContent.includes('已取消生成'),'cancelled image run');
  assert.equal(records.get(parent).document.nodes.find(node=>node.id==='image-target').data.src,generated.data.src);
  console.log('PASS AI images: sticky mode, modality filtering, original-node asset output and cancellation');
+ // 现有 inline 图片不触发隐式后台上传或引用改写；受管图片继续使用 preview 渲染。
  assert.equal([...document.querySelectorAll('button')].some(button=>button.textContent==='优化图片加载'),false,'Temporary migration controls are absent even with an inline image');
  assert.equal(assetUploads,0,'Existing inline images do not trigger background uploads');
  assert.ok(records.get(parent).document.nodes.find(node=>node.id==='legacy-image').data.src.startsWith('data:image/'),'Existing image references are not rewritten');

tests/canvas-v2.test.mjs

@@ -1,3 +1,7 @@
+/**
+ * 旧 schema_version=2 linked-board 快照的兼容与投影测试。schema_version、headless 文档格式和增量协议版本不是同一编号。
+ * 检查展开分区、曲线/样式/执行配置、owner 投影与最低共同祖先；不把任意远程 AI 请求实际执行。
+ */
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { decodeCanvas, emptyCanvas, makeCanvasNode } from '../src/lib/canvas.ts';
@@ -5,7 +9,9 @@ import { curveSegments, cubicPoint, insertCurveKnot } from '../src/lib/canvas-cu
 import { mergeCanvasDocuments, projectCanvasTree, transformEdgeData } from '../src/lib/canvas-tree.ts';
 import { resizeFromPointer } from '../src/lib/canvas-geometry.ts';
 import { managedImageSource } from '../src/lib/canvas-v2.ts';
+// 固定子 board 身份，投影时与符号节点 ID 组合，避免把 renderer ID 当作持久节点身份。
 const childId = '11111111-1111-4111-8111-111111111111';
+// 大尺寸 frame 引用子 board 和输出 port，父文字含 AI 配置，边包含完整曲线/动画/marker 数据。
 function fixture() {
  const frame = makeCanvasNode('frame', {x:100,y:100}); frame.id='frame'; frame.width=5000;
  frame.data={...frame.data,subgraph:{boardId:childId},presentation:{collapsed:false,contentScale:.2,expandedSize:{width:5000,height:400},collapsedSize:{width:240,height:140}},ports:[{id:'output',direction:'output',nodeId:'inside',handle:'right'}]};
@@ -14,33 +20,40 @@ function fixture() {
  const edge={id:'edge',source:'frame',target:'outside',sourceHandle:'port:output',targetHandle:'left',data:{appearance:{color:'#123456',width:2,line:'dashed',head:{type:'triangle',filled:false,size:12},tail:{type:'circle',size:8}},animation:{mode:'executing',effect:'flow',direction:'forward',durationMs:1200,color:'#ffffff'},path:{type:'bezier-chain',knots:[{id:'k',position:{x:700,y:150},in:{x:-30,y:0},out:{x:30,y:0},mode:'smooth'}]},execution:{enabled:true}}};
  return {frame,text,inside,root:{...emptyCanvas(),schema_version:2,nodes:[frame,text],edges:[edge]},child:{...emptyCanvas(),schema_version:2,nodes:[inside]}};
 }
+// V2 JSON 往返保留 subgraph、AI 与全部边 data，且已解码对象再次解码结果稳定。
 test('V2 roundtrip preserves linked frames, all curve/animation/marker data and AI config',()=>{
  const {root}=fixture(); const decoded=decodeCanvas(JSON.stringify(root));
  assert.deepEqual(decoded.edges[0].data,root.edges[0].data); assert.deepEqual(decoded.nodes[0].data.subgraph,root.nodes[0].data.subgraph); assert.deepEqual(decoded.nodes[1].data.ai,root.nodes[1].data.ai);assert.equal(decoded.nodes[0].width,5000);
  assert.deepEqual(decodeCanvas(JSON.stringify(decoded)),decoded);
 });
+// 逐项破坏平滑控制向量、动画、线宽、端口方向、普通元素尺寸或 AI 参数容器，解码均失败。
 test('V2 rejects bad control data, wrong port directions and oversized ordinary elements',()=>{
  for(const mutate of [d=>d.edges[0].data.path.knots[0].out.x=-30,d=>d.edges[0].data.animation.mode='random',d=>d.edges[0].data.appearance.width=100,d=>d.nodes[0].data.ports[0].direction='input',d=>d.nodes[1].width=5000,d=>d.nodes[1].data.ai.parameters=[]]){
   const {root}=fixture();mutate(root);assert.throws(()=>decodeCanvas(JSON.stringify(root)));
  }
 });
+// 展开时子节点只投影一次且边解析到真实内部端点；折叠改画到 frame，不改父子原文档或子局部坐标。
 test('expanded child nodes are projected once and boundary edges resolve to their actual nodes',()=>{
  const {root,child}=fixture(), documents=new Map([['root',root],[childId,child]]);const view=projectCanvasTree('root',documents);
  assert.equal(view.nodes.length,3);const projected=view.nodes.find(n=>n.id===childId+'::inside');assert.deepEqual(projected.position,{x:126,y:140});assert.equal(projected.width,52);assert.equal(view.nodeRefs.get(projected.id).boardId,childId);assert.equal(view.edges[0].source,projected.id);assert.equal(root.nodes.length,2);assert.equal(child.nodes.length,1);
  root.nodes[0].data.presentation.collapsed=true;const collapsed=projectCanvasTree('root',documents);assert.equal(collapsed.nodes.length,2);assert.equal(collapsed.edges[0].source,'frame');assert.deepEqual(child.nodes[0].position,{x:10,y:20});
 });
+// 边的点与向量经 owner→projected→owner 转换应精确返回原 data。
 test('curve coordinates and vectors invert exactly between owner and projected canvases',()=>{
  const {root}=fixture();const ref={boardId:'b',id:'e',origin:{x:100,y:-40},scale:.2};assert.deepEqual(transformEdgeData(transformEdgeData(root.edges[0].data,ref),ref,true),root.edges[0].data);
 });
+// 插入中点把一段 cubic 拆为两段；101 个参数样本与原曲线距离小于 1e-8，验证形状而非仅端点。
 test('adding a curve point preserves both halves of the original cubic',()=>{
  const from={point:{x:0,y:0},normal:{x:1,y:0}},to={point:{x:500,y:200},normal:{x:-1,y:0}};
  const old=curveSegments(from,to)[0], split=insertCurveKnot(from,to,undefined), next=curveSegments(from,to,split.path);
  assert.equal(next.length,2);for(let i=0;i<=100;i++){const t=i/100,a=cubicPoint(old,t),b=cubicPoint(next[t<=.5?0:1],t<=.5?t*2:(t-.5)*2);assert.ok(Math.hypot(a.x-b.x,a.y-b.y)<1e-8);}
 });
+// 远程生成文字可与本地几何三方合并，但同字段本地文字冲突必须抛 version_conflict。
 test('AI remote output merges with local geometry but conflicts with locally edited text',()=>{
  const base=fixture().child,local=structuredClone(base),remote=structuredClone(base);local.nodes[0].position={x:200,y:300};remote.nodes[0].data.text='generated';
  const merged=mergeCanvasDocuments(base,local,remote);assert.deepEqual(merged.nodes[0].position,{x:200,y:300});assert.equal(merged.nodes[0].data.text,'generated');local.nodes[0].data.text='user typing';assert.throws(()=>mergeCanvasDocuments(base,local,remote),/version_conflict/);
 });
+// 五类节点乘八方向在显式比例锁定时保持原比例；自由模式仅右侧拉伸不改图高，frame 可大于普通卡片上限。
 test('eight-direction resize is free by default in resize mode and Shift locks the aspect',()=>{
  for(const kind of ['plain-text','plain-image','text','image','frame']){
   const node=makeCanvasNode(kind,{x:10,y:20});const oldRatio=node.width/node.height;
@@ -51,10 +64,12 @@ test('eight-direction resize is free by default in resize mode and Shift locks t
  const image=makeCanvasNode('plain-image',{x:0,y:0});assert.equal(resizeFromPointer(image,'right',{x:100,y:0},false).height,image.height);
  const frame=makeCanvasNode('frame',{x:0,y:0});assert.ok(resizeFromPointer(frame,'right',{x:10000,y:0},false).width>3000);
 });
+// 受管资产显示转认证同源代理，普通外部 URL 保留；这里只检查地址转换，不验证实际认证请求。
 test('managed assets render through the authenticated same-origin proxy',()=>{
  assert.equal(managedImageSource('https://api.foundry.entroia.com/projects/endoleap/workspaces/w/assets/a'),'/api/foundry/workspaces/w/assets/a');assert.equal(managedImageSource('https://example.com/a.png'),'https://example.com/a.png');
 });
 
+// 连线持久 owner 是最低共同祖先，事务参与者恰为两条 owner 路径的并集；祖先本身不需要重复登记。
 test('connection plan uses the lowest common ancestor and exactly both ownership paths',async()=>{
  const {connectionTransactionPlan}=await import('../src/lib/canvas-subgraphs.ts');const {root,child}=fixture();
  const nested='33333333-3333-4333-8333-333333333333';const frame=makeCanvasNode('frame',{x:0,y:0});frame.data.subgraph={boardId:nested};child.nodes.push(frame);
@@ -63,10 +78,12 @@ test('connection plan uses the lowest common ancestor and exactly both ownership
  assert.equal(result.boardId,'root');assert.deepEqual(new Set(result.participants),new Set(['root',childId,nested]));assert.equal(result.source.node_id,'a');
  const inner=connectionTransactionPlan(docs,{boardId:nested,id:'a',handle:'bottom'},{boardId:childId,id:'b',handle:'top'});assert.equal(inner.boardId,childId);assert.deepEqual(new Set(inner.participants),new Set([childId,nested]));
 });
+// 旧 schema 或 subgraph owner 绑定不同的草稿不能恢复到已迁移 V2；等价深拷贝才可作为候选。
 test('incompatible drafts cannot overwrite migrated V2 ownership',async()=>{
  const {canRestoreCanvasDraft}=await import('../src/lib/canvas-sync.ts');const {root}=fixture();const old={...structuredClone(root),schema_version:1};assert.equal(canRestoreCanvasDraft(old,root),false);
  const changed=structuredClone(root);changed.nodes[0].data.subgraph.boardId='55555555-5555-4555-8555-555555555555';assert.equal(canRestoreCanvasDraft(changed,root),false);assert.equal(canRestoreCanvasDraft(structuredClone(root),root),true);
 });
+// 同时拖选父 frame 与 child 的投影结果，只应用共同位移一次，反推 owner 局部坐标保持原值。
 test('selecting both parent frame and child applies a shared drag once',async()=>{
  const {referenceAfterMoves}=await import('../src/lib/canvas-tree.ts');const {root,child}=fixture();const docs=new Map([['root',root],[childId,child]]),view=projectCanvasTree('root',docs);
  const projected=view.nodes.find(node=>node.id===childId+'::inside');const delta={x:50,y:80};const moved={x:projected.position.x+delta.x,y:projected.position.y+delta.y};

tests/canvas.test.mjs

@@ -1,7 +1,12 @@
+/**
+ * 旧画布快照 reducer 的基本历史、节点/边、序列化与分支规则测试。past/present/future 是旧版完整快照结构。
+ * 这里的 checkpoint/replace 不能当作 headless 操作账本、条件增量请求或项目恢复协议的验证。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { branchCanvasNode, canvasReducer, canvasStorageKey, decodeCanvas, emptyCanvas, makeCanvasNode } from "../src/lib/canvas.ts";
 
+// 构造两张不同卡片及一条边，返回空 past/future 的独立历史，用于比较编辑前后内容和 viewport。
 function seeded() {
   const document = emptyCanvas();
   document.nodes = [makeCanvasNode("text", { x: 20, y: 30 }), makeCanvasNode("script", { x: 400, y: 30 })];
@@ -9,6 +14,7 @@ function seeded() {
   return { past: [], present: document, future: [] };
 }
 
+// checkpoint 后拖动形成一个历史起点；undo/redo 改内容位置但保留当前 viewport，视图导航不跟着旧快照回退。
 test("node dragging updates its position; undo and redo retain the current viewport", () => {
   let state = seeded();
   const id = state.present.nodes[0].id;
@@ -23,6 +29,7 @@ test("node dragging updates its position; undo and redo retain the current viewp
   assert.deepEqual(state.present.nodes[0].position, { x: 220, y: -30 });
 });
 
+// 删节点连同附边一起删除，随后重复边删除通知不应再追加历史；一次 undo 恢复节点与边。
 test("deleting a node removes attached edges and undo restores both", () => {
   const initial = seeded();
   const removed = canvasReducer(initial, { type: "nodes", changes: [{ id: initial.present.nodes[0].id, type: "remove" }] });
@@ -35,6 +42,7 @@ test("deleting a node removes attached edges and undo restores both", () => {
   assert.equal(restored.present.edges.length, 1);
 });
 
+// 同一 checkpoint 内多次文字修改只留一个 past，undo 回到开始编辑前文字。
 test("a text editing session is undoable as one operation", () => {
   let state = seeded();
   const id = state.present.nodes[0].id;
@@ -45,6 +53,7 @@ test("a text editing session is undoable as one operation", () => {
   assert.equal(canvasReducer(state, { type: "undo" }).present.nodes[0].data.text, "");
 });
 
+// JSON 往返保留文本、图片、连线与 viewport，selected 作为临时 UI 字段不恢复。
 test("export/import retains nodes, edges, text, images and the viewport", () => {
   const document = seeded().present;
   const image = makeCanvasNode("image", { x: 80, y: 90 }, "data:image/png;base64,YQ==");
@@ -60,6 +69,7 @@ test("export/import retains nodes, edges, text, images and the viewport", () =>
   assert.deepEqual(restored.viewport, document.viewport);
 });
 
+// 悬空端点、重复 ID、不安全图片 URL 和非法 zoom 分别构造非法输入，任一项都使整个 decode 失败。
 test("import rejects dangling connections, duplicate nodes, unsafe images and invalid zoom", () => {
   for (const mutate of [
     (doc) => { doc.edges[0].target = "missing"; },
@@ -73,11 +83,13 @@ test("import rejects dangling connections, duplicate nodes, unsafe images and in
   }
 });
 
+// 旧草稿 key 包含 workspace 与 board，不能因同名图谱跨作用域覆盖。
 test("draft storage is isolated by workspace and graph", () => {
   assert.notEqual(canvasStorageKey("workspace-a", "board"), canvasStorageKey("workspace-b", "board"));
   assert.notEqual(canvasStorageKey("workspace", "board-a"), canvasStorageKey("workspace", "board-b"));
 });
 
+// 50 次 replace 后 past 受限为 40；undo 产生 redo，新 add 必须清空 redo。
 test("undo history is bounded and new edits clear the redo stack", () => {
   let state = seeded();
   for (let i = 0; i < 50; i++) state = canvasReducer(state, { type: "replace", document: { ...state.present, edges: [] } });
@@ -89,6 +101,7 @@ test("undo history is bounded and new edits clear the redo stack", () => {
 });
 
 
+// 四方向分支检查相对位置、选中切换、source/target ID 和相反 handle；快照可恢复，整组可撤销。
 test("selected nodes can branch in all four directions with matching connection handles", () => {
   const opposite = { top: "bottom", right: "left", bottom: "top", left: "right" };
   for (const direction of Object.keys(opposite)) {
@@ -114,6 +127,7 @@ test("selected nodes can branch in all four directions with matching connection
   }
 });
 
+// 同侧重复添加要避开已有节点，第二个新节点不能占据第一次相同位置。
 test("repeated additions on the same side avoid existing nodes", () => {
   const document = emptyCanvas();
   const parent = makeCanvasNode("text", { x: 0, y: 0 });

tests/feedback-scenario.mjs

@@ -1,16 +1,25 @@
+/**
+ * 应用反馈组件的 JSDOM 场景：原生 title 回退、provider tooltip、通知更新及画布成功/错误提示。
+ * 只断言 DOM 属性、事件和状态，不证明真实屏幕阅读器播报或浏览器浮层排版。
+ */
 import assert from "node:assert/strict";
 
+// 复用外层 React root，先验证独立控件，再验证带 AppFeedback 的画布交互。
 export async function feedbackScenario({ root, act, h, AppFeedback, IconButton, notify, dismissNotification, GraphCanvas, window, makeCanvasNode, emptyCanvas, event, tick }) {
   await act(async () => { root.render(null); await tick(); });
   let button, clicks = 0;
+  // 最小 SVG 图标替身只满足 IconButton 接口，不依赖真实图标资源。
   const icon = () => h("svg", { "aria-hidden": true });
+  // ref 必须直接指向业务 button；点击计数用于检查 tooltip 不吞掉原操作。
   const control = () => h(IconButton, { icon, label: "旋转工具", title: "旋转选中元素", ref: (value) => { button = value; }, onClick: () => { clicks++; } });
+  // 没有 provider 时保留原生 title；加入 provider 后不增加包裹层，改用关联 tooltip。
   await act(async () => { root.render(control()); await tick(); });
   assert.equal(button.title, "旋转选中元素", "Standalone controls retain native explanations");
   await act(async () => { root.render(h(AppFeedback, null, h("div", { id: "controls" }, control()))); await tick(); });
   assert.ok(document.querySelector("#controls").firstElementChild === button, "Tooltip does not wrap the button or alter toolbar geometry");
   assert.equal(button.tagName, "BUTTON", "Forwarded ref still points at the actual button");
   assert.equal(button.title, "", "A provider avoids duplicate native and Radix tooltips");
+  // 键盘聚焦应出现说明并建立 aria-describedby，Escape 隐藏说明后点击仍能触发业务回调。
   await act(async () => { button.focus(); await tick(); });
   const tooltip = document.querySelector('[role="tooltip"]');
   assert.ok(tooltip?.textContent.includes("旋转选中元素"), "Keyboard focus exposes the explanation");
@@ -18,6 +27,7 @@ export async function feedbackScenario({ root, act, h, AppFeedback, IconButton,
   await event(document, "keydown", { key: "Escape" });
   assert.ok(!document.querySelector('[role="tooltip"]'), "Escape dismisses the tooltip");
   await event(button, "click"); assert.equal(clicks, 1, "Tooltips preserve business clicks");
+  // 同一通知 ID 更新内容，只保留一个 toast；随后显式 dismiss 并等待退出清理。
   await act(async () => {
     notify({ id: "feedback-check", title: "正在处理" }); await tick();
     notify({ id: "feedback-check", title: "已完成", level: "success" }); await tick();
@@ -30,12 +40,14 @@ export async function feedbackScenario({ root, act, h, AppFeedback, IconButton,
   assert.ok(!document.querySelector('[data-sonner-toast]'), "Dismissed notifications are removed");
   console.log("PASS feedback: native fallback, forwarded ref, keyboard tooltip/Escape, clicks and stable notification IDs");
 
+  // 播种旧版 demo 本地草稿，包含文本与分区；这不是服务端成员迁移测试。
   const id = "feedback-board";
   const node = { ...makeCanvasNode("text", { x: 100, y: 100 }), id: "feedback-text" };
   const frame = { ...makeCanvasNode("frame", { x: 500, y: 100 }), id: "feedback-frame" };
   frame.data.title = "提示分区";
   localStorage.setItem(`endoleap_canvas_v1:w:${id}`, JSON.stringify({ ...emptyCanvas(), nodes: [node, frame] }));
   await act(async () => { root.render(h(AppFeedback, null, h(GraphCanvas, { board: { id, workspace_id: "w", title: "反馈测试", kind: "board", version: 1 } }))); await tick(); });
+  // 拖入分区后同时核对成功提示和实际归属徽标，不能只看到 toast 就算操作生效。
   const textNode = document.querySelector('.react-flow__node[data-id="feedback-text"]');
   await event(textNode, "mousedown", { clientX: 200, clientY: 200, button: 0, buttons: 1 });
   await event(window, "mousemove", { clientX: 210, clientY: 200, buttons: 1 });
@@ -43,12 +55,14 @@ export async function feedbackScenario({ root, act, h, AppFeedback, IconButton,
   await event(window, "mouseup", { clientX: 700, clientY: 200, button: 0 });
   assert.ok(document.querySelector('[data-sonner-toast][data-type="success"]')?.textContent.includes("已加入「提示分区」"));
   assert.ok(document.querySelector('[title="属于：提示分区"]'), "Notifications do not replace actual membership state");
+  // 用 PDF MIME 模拟不支持的图片选择，错误通知出现后继续创建文本，检查错误不阻塞编辑。
   const fileInput = document.querySelector('input[type="file"][accept^="image/"]');
   Object.defineProperty(fileInput, "files", { configurable: true, value: [new File(["test"], "test.pdf", { type: "application/pdf" })] });
   await act(async () => { fileInput.dispatchEvent(new window.Event("change", { bubbles: true })); await tick(); });
   assert.ok(document.querySelector('[data-sonner-toast][data-type="error"]')?.textContent.includes("演示模式请选择"));
   await event(document.querySelector('[aria-label="添加文本卡片"]'), "click");
   assert.equal(document.querySelectorAll('.react-flow__node').length, 3, "An error notification never blocks editing");
+  // 关闭此画布错误通知并卸载组件，避免影响后续共享 root 的场景。
   await act(async () => { dismissNotification(`canvas:${id}:error`); root.render(null); await tick(); });
   console.log("PASS canvas feedback: membership success, input errors and continued local editing through the application provider");
 }

tests/headless/blob-checkpoint-browser-cases.mjs

@@ -1,30 +1,54 @@
+/**
+ * 真实浏览器存储的 Blob checkpoint 场景，由 browser-storage-cases 调用并注入断言函数。
+ * 分别处理 DB schema 4→5、checkpoint 编码版本与恢复镜像格式版本，三个版本号不是同一时钟。
+ * 覆盖旧行升级、精确字节校验、未来格式、事务回滚、owner 失效与被旧连接阻挡的升级。
+ */
 import {createBrowserStorage} from '../../src/lib/canvas-runtime/storage.ts';
 import {sealRecoveryImage} from '../../src/lib/canvas-runtime/recovery-encoding.ts';
+// 手工建立旧数据库后再通过生产 storage 升级，直接观察持久化行及重新打开后的恢复结果。
 export async function blobCheckpointCase(assert){
+ // 随机数据库名隔离场景；镜像含 Unicode、大量文本和固定请求字节，用来检查序列化保持精确内容。
  const name=`blob-checkpoint-${crypto.randomUUID()}`,scope={accountId:'a',workspaceId:'w',projectId:'p'},key=JSON.stringify(['a','w','p']),image=revision=>({formatVersion:1,rootRevision:revision,localRevision:revision,payload:{rows:Array.from({length:250},(_,i)=>({id:i,text:`版本 ${revision} 👀 ${'x'.repeat(100)}`})),request:{id:'frozen',body:'{"exact":"original bytes"}'}}});
+ // 三个 Promise 工具分别等待 IDB 请求、事务完成/abort 和原始 Blob SHA-256；事务成功不能只看单个 put 成功。
  const read=req=>new Promise((resolve,reject)=>{req.onsuccess=()=>resolve(req.result);req.onerror=()=>reject(req.error);}),done=tx=>new Promise((resolve,reject)=>{tx.oncomplete=resolve;tx.onabort=()=>reject(tx.error);}),hash=async blob=>[...new Uint8Array(await crypto.subtle.digest('SHA-256',await blob.arrayBuffer()))].map(n=>n.toString(16).padStart(2,'0')).join('');
+ // 手工打开 DB v4 并创建旧表，绕开新适配器自动建库，保证后面确实经历旧 checkpoint 升级。
  let raw=await new Promise((resolve,reject)=>{const request=indexedDB.open(name,4);request.onupgradeneeded=()=>{for(const store of ['metadata','checkpoints','journal','files'])request.result.createObjectStore(store);};request.onsuccess=()=>resolve(request.result);request.onerror=()=>reject(request.error);});
+ // 把旧对象镜像与其 checksum 一起写入 revision 0，并关闭旧连接后再启动新适配器。
  const initial=image(0),checksum=await hash(new Blob([JSON.stringify(initial)]));let tx=raw.transaction(['metadata','checkpoints'],'readwrite'),terminal=done(tx);tx.objectStore('metadata').put({fence:0,throughRevision:0,checkpointRevision:0},key);tx.objectStore('checkpoints').put({image:initial,checksum},[key,0]);await terminal;raw.close();let storage=createBrowserStorage({name,checkpointEvery:1}),leader;
  try{
+  // 先核对旧对象恢复不变，再提交带 sealed 镜像与文件的首个新切点。
   leader=await storage.claim(scope);assert(JSON.stringify(await storage.recover(leader))===JSON.stringify(initial),'DB v4 legacy checkpoint changed during upgrade');const first=image(1);await storage.commit(leader,{image:sealRecoveryImage(1,1,1,first.payload),files:[{id:'kept',bytes:new Blob(['kept bytes'])}]});
+  // DB 应升级为 5；新 checkpoint 存 Blob 而非克隆文档对象，文本和 checksum 覆盖精确序列化字节。
   raw=await read(indexedDB.open(name));assert(raw.version===5,'Blob cuts did not fence old DB clients');const saved=await read(raw.transaction('checkpoints').objectStore('checkpoints').get([key,1]));assert(saved.checkpointVersion===1&&saved.bytes instanceof Blob&&!saved.image,'full cut is still a cloned document object');assert(await saved.bytes.text()===JSON.stringify(first),'Blob checkpoint changed serialized bytes');assert(saved.checksum===await hash(saved.bytes),'Blob checksum did not cover exact source bytes');
+  // 旧 DB v4 客户端再打开必须得到 VersionError，防止老解释器接受新 Blob 行。
   const old=await new Promise(resolve=>{const request=indexedDB.open(name,4);request.onerror=event=>{event.preventDefault();resolve(request.error.name);};request.onsuccess=()=>{request.result.close();resolve('accepted');};});assert(old==='VersionError','DB v4 reader accepted Blob checkpoint rows');
+  // 用原始 IDB 连接替换指定 checkpoint 行，构造损坏输入后仍等待事务真正完成。
   const write=async value=>{const tx=raw.transaction('checkpoints','readwrite'),terminal=done(tx);tx.objectStore('checkpoints').put(value,[key,1]);await terminal;};
+  // 分别破坏字节、header、编码版本和 UTF-8；每次恢复检查对应错误，并还原原行供下一场景继续。
   for(const [kind,expected]of [['bytes','recovery_checksum_mismatch'],['header','recovery_checksum_mismatch'],['future','recovery_checkpoint_interpreter_unavailable'],['utf8','corrupt_recovery_image']]){
    const damaged=structuredClone(saved);if(kind==='bytes')damaged.bytes=new Blob([JSON.stringify(image(9))]);else if(kind==='header')damaged.header.formatVersion=2;else if(kind==='future')damaged.checkpointVersion=2;else{damaged.bytes=new Blob([new Uint8Array([123,34,120,34,58,34,255,34,125])]);damaged.checksum=await hash(damaged.bytes);}
    await write(damaged);let code;try{await storage.recover(leader);}catch(error){code=error.code;}assert(code===expected,`${kind} cut was accepted: ${code}`);if(kind==='future'){code=undefined;try{await storage.commit(leader,{image:image(2)});}catch(error){code=error.code;}assert(code===expected,'writer replaced a future checkpoint');}await write(saved);
   }
+  // 暂时包装原生 put：先排入写请求再抛错，把故障放在事务已安排部分写入的窗口。
   const nativePut=IDBObjectStore.prototype.put;let injected=false,error;
+  // 只在 revision 2 的新 Blob checkpoint 写入点注入异常；其他表/版本继续调用真实 IndexedDB。
   IDBObjectStore.prototype.put=function(value,k){const request=nativePut.call(this,value,k);if(this.name==='checkpoints'&&value?.checkpointVersion===1&&value.header.rootRevision===2){injected=true;throw Error('abort_blob_checkpoint');}return request;};
+  // 带新文件的提交失败后恢复原 put，再验证旧 Root 仍可读且新文件字节没有泄漏。
   try{await storage.commit(leader,{image:image(2),files:[{id:'orphan',bytes:new Blob(['must rollback'])}]});}catch(cause){error=cause.message;}finally{IDBObjectStore.prototype.put=nativePut;}
   assert(injected&&error==='abort_blob_checkpoint','checkpoint fault was not injected after put');assert((await storage.recover(leader)).rootRevision===1&&await storage.readFile(leader,'orphan')===undefined,'aborted Blob cut leaked head or file bytes');
+  // 释放并重建适配器，检查 Blob 与同批文件在新 owner 下仍能恢复。
   await leader.release();storage.close();storage=createBrowserStorage({name,checkpointEvery:1});leader=await storage.claim(scope);assert(JSON.stringify(await storage.recover(leader))===JSON.stringify(first),'fresh adapter lost Blob content');assert(await(await storage.readFile(leader,'kept')).text()==='kept bytes','Blob reopening lost atomic file');
+  // 大切点准备期间释放 owner，完成结果必须是 storage_leader_lost；重新 claim 后不得看到新切点或晚到文件。
   const large=sealRecoveryImage(1,2,2,{rows:Array.from({length:16000},(_,i)=>({id:i,text:'x'.repeat(100)}))});let failure;const pending=storage.commit(leader,{image:large,files:[{id:'late',bytes:new Blob(['late'])}]}).catch(error=>{failure=error.code;});await Promise.resolve();await leader.release();await pending;assert(failure==='storage_leader_lost','released owner published or changed its cancellation error');leader=await storage.claim(scope);assert((await storage.recover(leader)).rootRevision===1&&await storage.readFile(leader,'late')===undefined,'released owner advanced Blob checkpoint');
+ // 关闭原始连接、释放 owner 和 adapter，再发起删除数据库；这里不等待删除完成事件。
  }finally{raw?.close();await leader?.release();storage.close();indexedDB.deleteDatabase(name);}
 }
 
+// 保持旧 DB 连接打开以阻挡升级；同一失败 adapter 保留原错误，旧连接退场后需新 adapter 才能成功。
 export async function blockedUpgradeCase(assert){
+ // 本场景只需一个仍打开的 v4 数据库，不依赖上一个升级场景留下的数据。
  const name=`blocked-upgrade-${crypto.randomUUID()}`,scope={accountId:'a',workspaceId:'w',projectId:'p'},read=req=>new Promise((resolve,reject)=>{req.onsuccess=()=>resolve(req.result);req.onerror=()=>reject(req.error);});let raw=await read(indexedDB.open(name,4)),storage=createBrowserStorage({name}),leader;
+ // 重复 claim 都应报告 storage_upgrade_blocked；丢弃的升级请求不能在稍后悄悄升级，关旧连接并新建 adapter 后才升到 5。
  try{let code;try{await storage.claim(scope);}catch(error){code=error.code;}assert(code==='storage_upgrade_blocked','active old connection did not reject the upgrade');code=undefined;try{await storage.claim(scope);}catch(error){code=error.code;}assert(code==='storage_upgrade_blocked','blocked adapter lost the original failure reason');raw.close();raw=await read(indexedDB.open(name));assert(raw.version===4,'abandoned upgrade changed database version after rejection');raw.close();storage.close();storage=createBrowserStorage({name});leader=await storage.claim(scope);assert(await storage.recover(leader)===null,'fresh adapter could not open after blocked request was retired');raw=await read(indexedDB.open(name));assert(raw.version===5,'fresh upgrade failed after abandoned open');}
  finally{raw?.close();await leader?.release();storage.close();indexedDB.deleteDatabase(name);}
 }

tests/headless/browser-storage.mjs

@@ -1,4 +1,8 @@
-/** Real Chromium IndexedDB/Web Locks checks, in an isolated temporary browser profile. */
+/**
+ * 使用隔离 Chrome profile 运行真实 IndexedDB/Web Locks 场景，或以 --package 消费构建后的浏览器 ESM。
+ * 本地 HTTP server 只提供测试页面、源码/发布文件和可控 NDJSON 流；普通模式通过 Node 去除 .ts 类型，不运行应用 bundler。
+ * 此入口内联了一套简化 CDP 请求表，未使用 cdp-client 的连接级超时/故障保护，不能把 Runtime.evaluate 的 timeout 当作所有命令的截止时间。
+ */
 import { createServer } from 'node:http';
 import { readFile, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -7,18 +11,24 @@ import { spawn } from 'node:child_process';
 import { stripTypeScriptTypes } from 'node:module';
 import { setTimeout as pause } from 'node:timers/promises';
 
+// 从脚本位置定位仓库，随机临时 profile 保证测试不读写日常 Chrome 会话。
 const root = resolve(import.meta.dirname, '../..'), profile = await mkdtemp(join(tmpdir(), 'endoleap-storage-browser-'));
+// --package 只影响发布文件服务和页面导入入口；它不会在这里自动构建 .headless-dist。
 const packageMode=process.argv.includes('--package');
+// 按 key 保留挂起的响应与读取次数，供页面测试控制共享读取的首块、尾块和失败尾部。
 const readStreams=new Map();
+// 只在回环地址提供 fixture；源码读取或类型去除失败时返回 500 供页面检查报告。
 const server = createServer(async (request, response) => {
   try {
     const path = new URL(request.url, 'http://localhost').pathname;
+    // 同一 key 每次读取计数增加，立即发送第一行并保持连接；由独立 release 请求决定何时结束。
     if(path==='/loader-stream'){
       const url=new URL(request.url,'http://localhost'),key=url.searchParams.get('key');
       if(!key){response.writeHead(400).end();return;}
       const state=readStreams.get(key)??{reads:0};state.reads++;state.response=response;readStreams.set(key,state);
       response.writeHead(200,{'Content-Type':'application/x-ndjson'});response.write(JSON.stringify({part:0,complete:false})+'\n');return;
     }
+    // 查找挂起流，可发送合法完成行或非法 JSON 尾部；返回读次数用于核对共享加载没有重复 fetch。
     if(path==='/loader-release'){
       const url=new URL(request.url,'http://localhost'),state=readStreams.get(url.searchParams.get('key'));
       if(!state){response.writeHead(404).end();return;}
@@ -26,30 +36,39 @@ const server = createServer(async (request, response) => {
       response.setHeader('Content-Type','application/json');response.end(JSON.stringify({reads:state.reads}));return;
     }
     if (path === '/') { response.setHeader('Content-Type', 'text/html'); response.end('<title>Headless storage checks</title>'); return; }
+    // 包模式从 .headless-dist 读取，其余只允许 src/lib 和 tests/headless；resolve 后再检查目录前缀。
     const isPackage=packageMode&&path.startsWith('/package/');
     const filename = isPackage?resolve(root,'.headless-dist',path.slice('/package/'.length)):resolve(root, `.${path}`);
     if (!(isPackage&&filename.startsWith(`${root}/.headless-dist/`)) && !filename.startsWith(`${root}/src/lib/`) && !filename.startsWith(`${root}/tests/headless/`)) { response.writeHead(404).end(); return; }
+    // 仅对 .ts 去除类型后提供 JavaScript；.mjs 和编译包文件保持读取内容，不进行应用级转换。
     let source = await readFile(filename, 'utf8');
     if (filename.endsWith('.ts')) source = stripTypeScriptTypes(source);
     response.setHeader('Content-Type', 'text/javascript'); response.end(source);
   } catch (error) { response.writeHead(500).end(String(error)); }
 });
+// 先绑定随机本地端口，再用独立 profile 启动 headless Chrome；CHROME_BIN 可覆盖默认安装路径。
 await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
 const chrome = spawn(process.env.CHROME_BIN ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', ['--headless=new', '--no-first-run', '--disable-background-networking', '--disable-component-update', '--remote-debugging-port=0', `--user-data-dir=${profile}`, `http://127.0.0.1:${server.address().port}/`], { stdio: 'ignore' });
 let socket;
 try {
+  // 最多轮询 100 次 DevToolsActivePort，每次间隔 100 毫秒；未找到端口即失败，不连接用户现有浏览器。
   let port;
   for (let attempt = 0; attempt < 100; attempt++) {
     try { port = Number((await readFile(join(profile, 'DevToolsActivePort'), 'utf8')).split('\n')[0]); break; } catch { await pause(100); }
   }
   if (!port) throw new Error('isolated Chromium did not start');
+  // 从本次 Chrome 的调试服务查找 page，建立 WebSocket 后才发送 CDP 命令。
   const tabs = await fetch(`http://127.0.0.1:${port}/json/list`).then(response => response.json());
   socket = new WebSocket(tabs.find(tab => tab.type === 'page').webSocketDebuggerUrl);
   await new Promise((resolve, reject) => { socket.onopen = resolve; socket.onerror = reject; });
+  // pending 仅按 ID 路由 Promise；这里没有每条命令的本地截止定时器。
   let next = 0; const pending = new Map();
+  // 只处理带 ID 的响应，协议错误拒绝相应 Promise；没有转发无 ID 事件或整连接失败处理。
   socket.onmessage = event => { const message = JSON.parse(event.data); if (message.id) { const callbacks = pending.get(message.id); pending.delete(message.id); if (message.error) callbacks.reject(new Error(JSON.stringify(message.error))); else callbacks.resolve(message.result); } };
+  // 登记递增 ID 后发送命令，等待对应响应；其行为不同于独立 createCdpCalls 的有界调用器。
   const call = (method, params) => new Promise((resolve, reject) => { const id = ++next; pending.set(id, { resolve, reject }); socket.send(JSON.stringify({ id, method, params })); });
   const origin = `http://127.0.0.1:${server.address().port}`;
+  // 导航到本次 fixture origin，随后最多 100 次检查页面 origin 与 readyState，避免误在空白页执行。
   await call('Page.navigate', { url: `${origin}/` });
   let loaded = false;
   for (let attempt = 0; attempt < 100; attempt++) {
@@ -58,10 +77,13 @@ try {
     await pause(50);
   }
   if (!loaded) throw new Error('browser test origin did not finish loading');
+  // 页面动态导入普通存储场景或编译包场景并等待 run；30 秒 timeout 是该 evaluate 的协议参数。
   const result = await call('Runtime.evaluate', { expression: `import('/tests/headless/${packageMode?'package-browser-cases':'browser-storage-cases'}.mjs').then(module => module.run())`, awaitPromise: true, returnByValue: true, timeout: 30000 });
+  // 页面异常直接使 runner 失败，只有成功返回的场景消息才逐条打印 PASS。
   if (result.exceptionDetails) throw new Error(result.exceptionDetails.exception?.description ?? result.exceptionDetails.text);
   for (const message of result.result.value) console.log(`PASS ${message}`);
 } finally {
+  // 清理连接并请求 Chrome 退出，等待进程 exit 后再关闭 HTTP server 和删除 profile；此等待没有额外强杀截止时间。
   socket?.close();
   const exited = new Promise(resolve => { if (chrome.exitCode !== null) resolve(); else chrome.once('exit', resolve); });
   chrome.kill(); await exited;

tests/headless/cdp-client.mjs

@@ -1,19 +1,32 @@
-/** Bounded protocol calls for isolated browser fixtures, never product code. */
+/**
+ * 隔离浏览器 fixture 专用的有界 CDP 请求路由器，不作为产品运行时代码。
+ * 每个正整数 ID 对应一个 Promise 和截止定时器；连接/目标级故障是整个实例的终态。
+ * 本函数不负责建立或关闭 socket，也不提供独立 dispose；外层 runner 持有连接。
+ */
+// 接收已连接 socket 和可替换定时器；默认给每个调用设置 30 秒截止定时器，事件由 onEvent 转发。
 export function createCdpCalls(socket,{timeoutMs=30000,onEvent=()=>{},setTimer=setTimeout,clearTimer=clearTimeout}={}){
+ // pending 是未回应调用的唯一查找表；failure 保留首个致命错误，使未来调用立刻拒绝。
  let serial=0,failure;const pending=new Map();
+ // 全局失败清除每个截止定时器并拒绝所有 Promise；重复故障不覆盖最初原因。
  const fail=error=>{failure??=error;for(const row of pending.values()){clearTimer(row.timer);row.reject(failure);}pending.clear();};
+ // 连接关闭和传输错误都不再允许继续发命令。
  socket.addEventListener('close',()=>fail(Error('CDP connection closed')));
  socket.addEventListener('error',()=>fail(Error('CDP connection failed')));
+ // 收到消息先解析 JSON；解析或事件回调异常同样会进入全局失败。
  socket.addEventListener('message',event=>{
   try{
    const message=JSON.parse(event.data);
+   // 无请求 ID 的消息是事件；先通知观察者，再把崩溃、脱离或对话框视为目标不可继续使用。
    if(!message.id){onEvent(message);if(['Inspector.targetCrashed','Inspector.detached','Target.targetCrashed','Page.javascriptDialogOpening'].includes(message.method))fail(Error('CDP target unavailable: '+message.method+' '+JSON.stringify(message.params??{})));return;}
+   // 已超时/完成的响应无对应 row 时忽略；普通协议 error 只拒绝该请求，不使整个连接失效。
    const row=pending.get(message.id);if(!row)return;pending.delete(message.id);clearTimer(row.timer);message.error?row.reject(Error(JSON.stringify(message.error))):row.resolve(message.result);
   }catch(error){fail(error);}
  });
+ // 为新命令分配递增 ID，先登记 pending 与定时器再发送；send 同步抛错也会拒绝全部在途工作。
  return(method,params={})=>new Promise((resolve,reject)=>{
   if(failure){reject(failure);return;}
   const id=++serial,row={resolve,reject,timer:undefined};pending.set(id,row);
+  // 任意一个调用超时都使整个调用器失败，避免测试随后无限挂在另一个依赖命令。
   row.timer=setTimer(()=>fail(Error(`CDP ${method} timed out after ${timeoutMs}ms`)),timeoutMs);
   try{socket.send(JSON.stringify({id,method,params}));}catch(error){fail(error);}
  });

tests/headless/cdp-client.test.mjs

@@ -1,8 +1,17 @@
+/**
+ * 浏览器测试专用 CDP 调用器的单元测试。用 socket/定时器替身验证请求 ID 路由、截止时间及致命故障，不启动浏览器。
+ * 单个协议命令错误只拒绝对应请求；连接或目标级故障则拒绝整个调用器及未来调用。
+ */
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
 import {createCdpCalls} from './cdp-client.mjs';
+// 把 socket 事件、已发送命令和定时器保存在 Map/数组，测试可直接投递乱序响应或手动触发超时。
 function fixture(){const handlers=new Map(),sent=[],timers=new Map();let id=0;const socket={addEventListener:(event,callback)=>handlers.set(event,callback),send:text=>sent.push(JSON.parse(text))},events=[],call=createCdpCalls(socket,{timeoutMs:30,onEvent:event=>events.push(event),setTimer:callback=>{timers.set(++id,callback);return id;},clearTimer:key=>timers.delete(key)});return{call,sent,timers,events,event:(name,data)=>handlers.get(name)({data:JSON.stringify(data)})};}
+// 两个响应反序返回仍按 ID 完成各自 Promise；无 ID 事件交给 onEvent，成功响应清除对应定时器。
 test('CDP responses route by request ID, forward events and release deadline timers',async()=>{const f=fixture(),one=f.call('one'),two=f.call('two');f.event('message',{method:'Runtime.event'});f.event('message',{id:2,result:{value:'two'}});f.event('message',{id:1,result:{value:'one'}});assert.deepEqual(await one,{value:'one'});assert.deepEqual(await two,{value:'two'});assert.equal(f.events.length,1);assert.equal(f.timers.size,0);});
+// 一个调用超时即终止全部 pending 和未来调用；迟到响应被忽略，不产生额外报告读取来掩盖超时。
 test('a stalled CDP call rejects all pending work and cannot hide behind another unbounded report read',async()=>{const f=fixture(),one=assert.rejects(f.call('Runtime.evaluate'),/timed out/),two=assert.rejects(f.call('Page.captureScreenshot'),/timed out/);[...f.timers.values()][0]();await Promise.all([one,two]);assert.equal(f.timers.size,0);f.event('message',{id:1,result:{late:true}});await assert.rejects(f.call('Runtime.evaluate'),/timed out/);});
+// 分别注入连接关闭、错误、目标崩溃、脱离和对话框事件；所有情况清空 pending，调用器不会自动接受对话框。
 test('connection loss and fatal target events reject pending calls without accepting dialogs',async()=>{for(const event of ['close','error','Inspector.targetCrashed','Target.targetCrashed','Inspector.detached','Page.javascriptDialogOpening']){const f=fixture(),result=assert.rejects(f.call('Runtime.evaluate'),/CDP/);event.includes('.')?f.event('message',{method:event}):f.event(event);await result;assert.equal(f.timers.size,0);assert.deepEqual(f.sent.map(row=>row.method),['Runtime.evaluate']);}});
+// 普通命令错误只拒绝它自己，另一命令仍可成功且两者都清除定时器。
 test('one protocol command error does not corrupt another request or leak its timer',async()=>{const f=fixture(),one=assert.rejects(f.call('bad'),/invalid/),two=f.call('good');f.event('message',{id:1,error:{message:'invalid'}});f.event('message',{id:2,result:{ok:true}});await one;assert.deepEqual(await two,{ok:true});assert.equal(f.timers.size,0);});

tests/headless/pointer-capture.test.mjs

@@ -1,4 +1,10 @@
+/**
+ * 指针捕获辅助函数的对象替身测试，不分派真实 DOM PointerEvent。
+ * 指针 ID 与捕获目标共同决定归属，旧 lostpointercapture 不能取消新目标或重新捕获后的手势。
+ */
 import {test} from 'node:test';import assert from 'node:assert/strict';
 import {ownsPointerCapture,acquirePointerCapture,releasePointerCapture} from '../../src/lib/canvas-bindings/pointer-capture.ts';
+// move/up/cancel 检查 pointerId；lostpointercapture 还检查事件 target 与当前捕获状态，空 owner 不匹配。
 test('pointer move/up/cancel only match their owner and old lost-capture cannot cancel a replacement target',()=>{const capture={},other={},owner={pointerId:7,capture};for(const type of ['pointermove','pointerup','pointercancel']){assert.equal(ownsPointerCapture(owner,{pointerId:8,type}),false);assert.equal(ownsPointerCapture(owner,{pointerId:7,type}),true);}assert.equal(ownsPointerCapture(owner,{pointerId:7,type:'lostpointercapture',target:other}),false);assert.equal(ownsPointerCapture(owner,{pointerId:7,type:'lostpointercapture',target:capture}),true);assert.equal(ownsPointerCapture(null,{pointerId:7}),false);const recaptured={hasPointerCapture:()=>true};assert.equal(ownsPointerCapture({pointerId:7,capture:recaptured},{pointerId:7,type:'lostpointercapture',target:recaptured}),false);});
+// 成功捕获只释放一次；节点脱离导致的 set/hasPointerCapture 异常作为捕获失败或安全清理处理，不升级为业务错误。
 test('failed capture and detached release stay transport failures, while a held capture releases once',()=>{let held=false,releases=0;const target={setPointerCapture(){held=true;},hasPointerCapture(){return held;},releasePointerCapture(){held=false;releases++;}};assert.equal(acquirePointerCapture(target,1),true);releasePointerCapture(target,1);releasePointerCapture(target,1);assert.equal(releases,1);assert.equal(acquirePointerCapture({...target,setPointerCapture(){throw Error('detached');}},2),false);assert.doesNotThrow(()=>releasePointerCapture({...target,hasPointerCapture(){throw Error('detached');}},2));});

tests/headless/react-hooks-fixture.tsx

@@ -1,3 +1,8 @@
+/**
+ * 供真实浏览器页面调用的 React hooks 场景。组件挂在隐藏容器中，在 StrictMode 下检查订阅路由、手势租约和资源句柄。
+ * engine 与 hooks 使用生产实现，存储、上传和文档服务为内存替身；此处不验证远程授权、数据库或图片解码。
+ * 断言通过页面全局入口返回文字报告，由外层浏览器 runner 收集；不会在组件导入时自动运行全部场景。
+ */
 "use client";
 import {StrictMode,memo,useEffect,useLayoutEffect} from 'react';
 import {createRoot} from 'react-dom/client';import {flushSync} from 'react-dom';
@@ -5,54 +10,93 @@ import {CanvasProvider,useCanvas,useElement,useActions,useMode,useGestureBinding
 import {createRegistry,builtinComponents,createDocument,applyChanges} from '@/lib/canvas-core/index';
 import {openProjectEngine} from '@/lib/canvas-runtime/engine';
 import {equal} from '@/lib/canvas-core/values';
+// 浏览器断言失败直接抛错，使外层 Runtime.evaluate 得到失败；不把失败写成通过报告。
 const assert=(value:unknown,message:string)=>{if(!value)throw Error(message);};
+// 短暂等待浏览器计时器；until 最多轮询 1000 次，观察 React effect/订阅结果，而非假设 flush 后同步可读。
 const tick=()=>new Promise(resolve=>setTimeout(resolve,5));async function until(check:()=>boolean){for(let i=0;i<1000;i++){if(check())return;await tick();}throw Error('hook observation timed out');}
+// 装配两个节点和两个 view；partial 模式只发布 a，但完整来源仍含 b，供 unloaded→present/absent 检查。
 async function fixture(partial=false){
+ // 合法文本节点外壳；版本、身份和 owner 固定，序列号另用于命令/请求 ID。
  const node=(id:string)=>({id,incarnation:1,structure:'node' as const,componentId:'text',dataVersion:1,ownerCanvasId:'canvas',geometry:{x:0,y:0,width:100,height:80,rotation:0},data:{title:id,text:''}});let server=createDocument(partial?'canvas':'hooks',[{id:'canvas',parent:null}],[node('a'),node('b')]),version=1,serial=0,image:any=null,fail=false,readGate:Promise<void>|undefined;
+ // 分别保存本地 Blob、文档回执及异步错误，read 次数用于验证资源 hooks 共享读取。
  const files=new Map<string,Blob>(),receipts=new Map(),errors:unknown[]=[];let reads=0;
+ // 内存存储可注入 quota，readFile 可被 Promise 屏障延迟；不实现真实浏览器锁或 IndexedDB。
  const storage={async claim(scope:any){return{scope,fence:1,active:true,async release(){this.active=false;}};},async recover(){return image;},async commit(_leader:any,batch:any){if(fail)throw Error('quota');for(const file of batch.files??[])files.set(file.id,file.bytes);image=structuredClone(batch.image);return{durableRootRevision:image.rootRevision};},async readFile(_leader:any,id:string){reads++;if(readGate)await readGate;return files.get(id);},close(){}};
+ // 上传替身返回固定 2×1 元数据与资源 URL，不验证图片字节；查询保持 unresolved，accept 直接取 canonical。
  const assets={sourceURL:(id:string)=>`https://assets.test/${id}`,displayURL:(id:string)=>`/assets/${id}`,async upload(request:any,bytes:Blob){const payload=JSON.parse(request.body);return{outcome:'applied' as const,canonical:{id:payload.resource_id,url:assets.sourceURL(payload.resource_id),bytes:bytes.size,mime_type:bytes.type,width:2,height:1}};},async query(){return{outcome:'unresolved' as const};},accept:(_request:any,status:any)=>status.canonical};
+ // 文档替身应用真实 changes 并递增版本，把成功模型放在回执表；不实现真实 HTTP 或请求去重。
  const persistence={compile(intent:any,id:string,snapshot:any){return{payload:{intent},canvasIds:intent.canvasIds,expectedVersions:{canvas:snapshot.runtime.versions.get('canvas')}};},async submit(request:any){server=applyChanges(server,JSON.parse(request.body).intent.changes);receipts.set(request.id,{document:server,versions:new Map([['canvas',++version]])});return{outcome:'applied' as const};},async query(){return{outcome:'unresolved' as const};},canonical:(request:any)=>receipts.get(request.id)};
+ // 装配真实引擎与 loading 状态，显式 attach v/w 后等待本地初始工作收敛。
  const engine=await openProjectEngine({scope:{accountId:'a',workspaceId:'w',projectId:partial?'canvas':'hooks'},document:partial?createDocument('canvas',[{id:'canvas',parent:null}],[node('a')]):server,...(partial?{loading:{version:1 as const,sourceToken:'hook-partial',declaredCanvasIds:['canvas'],receivedElements:1,totalElements:2}}:{}),versions:new Map([['canvas',1]]),registry:createRegistry(builtinComponents()),storage,assets,persistence,createId:()=>`hook-${++serial}`,onError:error=>errors.push(error)});const detachA=engine.sessions.attach('v','canvas'),detachB=engine.sessions.attach('w','canvas');await engine.settle();
+ // 向场景暴露保存故障、读取屏障与读次数；detach 只清理 fixture 自己附加的两个会话。
  return{engine,node,files,errors,full:server,get reads(){return reads;},fail(value:boolean){fail=value;},gate(value?:Promise<void>){readGate=value;},detach(){detachA();detachB();}};
 }
+// 创建隐藏 React root 并串行运行场景；保留组件读到的最新 hook 结果和渲染/选择器计数供断言。
 async function run(){
  const f=await fixture(),engine=f.engine,container=document.createElement('div');container.style.display='none';document.body.append(container);const root=createRoot(container),reports:string[]=[],counts={title:0,element:0,mode:0,gesture:0,titleOnly:0};let titleOnly:unknown,titleSelections=0;let title:any,element:any,actions:any,mode:any,gesture:any,operation:any,status:any,assetA:any,assetB:any;
+ // 全局选择器只提取 a 的标题，equal 比较结果对象，检查无关 Root 发布不引发重渲染。
  const Title=memo(function Title(){title=useCanvas(snapshot=>({title:snapshot.document.elements.get('a')?.data.title}),equal);counts.title++;return null;});
+ // 完整元素 hook 固定到 a 的第一代身份，稍后用于验证删除恢复后状态变为 stale。
  const Element=memo(function Element(){element=useElement({id:'a',incarnation:1});counts.element++;return null;});
+ // 计数元素选择器实际执行次数，区分“跳过无关目标”与“目标变化但结果相等不渲染”。
  const selectTitle=(view:ElementView)=>{titleSelections++;return view.status==='present'?view.element.data.title:view.status;};
+ // 只订阅目标标题字段；同元素其他字段变化允许重新选择，但不能增加组件渲染次数。
  const ElementTitle=memo(function ElementTitle(){titleOnly=useElement({id:'a',incarnation:1},selectTitle);counts.titleOnly++;return null;});
+ // 捕获绑定到目标身份的命令 facade，检查稳定引用、历史选项和过期身份拒绝。
  const Actions=memo(function Actions(){actions=useActions({id:'a',incarnation:1});return null;});
+ // 观察 v 视图的 mode，另一个 view 的 mode 更新不能使它重渲染。
  const Mode=memo(function Mode(){mode=useMode({id:'a',incarnation:1});counts.mode++;return null;});
+ // 捕获目标绑定手势控制器；beginOnLayout 在替换目标的 layout effect 中立即开启新手势，以暴露旧 cleanup 误取消问题。
  const Gesture=memo(function Gesture({targetId='a',beginOnLayout=false}:{targetId?:string;beginOnLayout?:boolean}){const binding=useGestureBindings({id:targetId,incarnation:1});gesture=binding;counts.gesture++;useLayoutEffect(()=>{if(beginOnLayout){assert(binding.begin().enabled,'replacement gesture did not begin');assert(binding.update({x:88}).enabled,'replacement gesture did not preview');}},[targetId,beginOnLayout]);return null;});
+ // 按逻辑操作 ID 观察操作及其请求；最初 missing 应没有记录，rename 后改绑真实 ID。
  const Operation=memo(function Operation({id}:{id:string}){operation=useOperation(id);return null;});
+ // 独立观察同步、持久化错误和关闭状态，不靠业务文档再次变化触发观察。
  const Status=memo(function Status(){status=useSyncStatus();return null;});
+ // 两个 slot 可同时借用同一资源，分别保存 hook 结果以检查共享 URL 及引用计数释放。
  const Asset=memo(function Asset({id,slot}:{id:string;slot:'a'|'b'}){const value=useAsset(id);if(slot==='a')assetA=value;else assetB=value;return null;});
+ // 每次以 StrictMode 和 CanvasProvider 同步替换子树；owner 可替换成另一个 engine，随后等待 effects。
  const render=async(children:any,owner=engine)=>{flushSync(()=>root.render(<StrictMode><CanvasProvider engine={owner} viewId="v">{children}</CanvasProvider></StrictMode>));await tick();};
  try{
+  // 先等 synced 再记录动态基线；StrictMode 可能重复渲染，因此断言增量而非写死初始次数。
   await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture/><Operation id="missing"/><Status/></>);await until(()=>status?.status==='synced');const baseline={...counts},originalActions=actions,initialTitleSelections=titleSelections;
+  // 改无关 b：窄订阅计数和 action 引用不变，元素标题选择器也不执行。
   engine.editor.dispatch({type:'element.data',target:{id:'b',incarnation:1},patch:{title:'unrelated'}});await engine.settle();await tick();assert(equal(baseline,counts),'unrelated element/ACK rerendered narrow hooks');assert(actions===originalActions,'action facade identity drifted');assert(titleSelections===initialTitleSelections,'unrelated edit/ACK evaluated the element selector');
+  // 改 a 的 text 会执行其标题选择器，但标题没变时不得重渲染 ElementTitle。
   const titleRenders=counts.titleOnly;engine.editor.dispatch({type:'element.data',target:{id:'a',incarnation:1},patch:{text:'other field'}});await engine.settle();await tick();assert(titleSelections>initialTitleSelections&&counts.titleOnly===titleRenders&&titleOnly==='a','field selector did not isolate title from another field on the same target');reports.push('element ID routing skips unrelated selector evaluation; field selectors observe their target without rerendering for other fields');
+  // 经 actions.rename 验证命令历史 label/groupId、canonical 观察及 operation/request 状态。
   const renamed=actions.rename('renamed',{label:'Hook rename',groupId:'hook-rename'});await engine.settle();const renamedHistory=engine.getSnapshot().history.entries.get(engine.getSnapshot().history.undo.at(-1)!);assert(renamedHistory?.label==='Hook rename'&&renamedHistory.groupId==='hook-rename','action facade dropped command history options');await until(()=>title.title==='renamed'&&titleOnly==='renamed');assert(element.status==='present'&&element.element.data.title==='renamed','element did not observe canonical rename');await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture/><Operation id={renamed.operationIds[0]}/><Status/></>);assert(operation?.operation.phase==='resolved'&&operation.request?.phase==='resolved','operation hook did not include its request');reports.push('selectors suppress unrelated element and ACK renders; bound actions share validated history/ledger and operation/request observation');
+  // 手势预览只改变交互状态，不改业务几何、revision 或 history；取消不留撤销记录，mode 仍按 view 隔离。
   const history=engine.getSnapshot().history.undo.length,revision=engine.getSnapshot().revision;assert(gesture.begin().enabled&&gesture.update({x:42}).enabled,'gesture did not acquire/update');await until(()=>gesture.active&&gesture.geometry.x===42);assert(engine.getSnapshot().document.elements.get('a')!.structure==='node'&&(engine.getSnapshot().document.elements.get('a') as any).geometry.x===0,'preview mutated committed geometry');assert(engine.getSnapshot().revision===revision,'preview created an edit');gesture.cancel();await until(()=>!gesture.active);assert(engine.getSnapshot().history.undo.length===history,'canceled preview changed history');assert(mode.setMode('editing').enabled,'view mode rejected');await until(()=>mode.mode==='editing');const modeRenders=counts.mode;engine.sessions.mode('w','a','resize');await tick();assert(counts.mode===modeRenders,'another view changed this view mode');
+  // 第二次手势提交只新增一个历史单元，租约释放后旧 commit 不再可写。
   assert(gesture.begin().enabled,'second gesture did not acquire');gesture.update({x:55});assert(gesture.commit().status==='applied','gesture did not commit');await engine.settle();assert(engine.getSnapshot().history.undo.length===history+1,'gesture did not create exactly one history entry');assert(gesture.commit().status==='rejected','released gesture lease remained writable');reports.push('gesture preview/cancel/commit owns a token and one history unit; modes stay scoped to their view');
+  // 切换 hook 目标后立即在 layout effect 开新租约；旧控制器的 cancel/commit 和 cleanup 都不能碰新目标。
   const previousGesture=gesture,beforeOwnerSwap=engine.getSnapshot();await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture targetId="b" beginOnLayout/><Operation id={renamed.operationIds[0]}/><Status/></>);const replacementToken=engine.sessions.getSnapshot().gesture?.token;assert(!!replacementToken&&engine.sessions.getSnapshot().gesture?.targets[0].id==='b','old target cleanup canceled the new layout gesture');assert(previousGesture.commit().status==='rejected','old controls committed the replacement gesture');previousGesture.cancel();assert(engine.sessions.getSnapshot().gesture?.token===replacementToken,'old controls canceled the replacement gesture');assert(engine.getSnapshot()===beforeOwnerSwap,'owner switch or obsolete callback published document/history work');gesture.cancel();await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture/><Operation id={renamed.operationIds[0]}/><Status/></>);reports.push('gesture controller replacement owns an independent lease; old cleanup, cancel and commit cannot touch a new target gesture');
 
+  // 先检查只有 durability 完成也能清除 dirty，再注入 quota 验证 blocked/dirty，重试成功才恢复 synced。
   engine.editor.updateRuntime(previous=>({...previous}));await engine.persist();await tick();await until(()=>status.status==='synced'&&!status.dirty);assert(!status.dirty,'durable-only metadata completion was not observable');f.fail(true);actions.rename('unsaved');await until(()=>status.status==='blocked'&&status.error==='quota');assert(status.dirty,'failed persistence appeared durable');f.fail(false);await engine.retry();await engine.settle();await until(()=>status.status==='synced'&&!status.dirty);reports.push('sync status observes durable-only completion and quota failure/retry without claiming in-memory edits are synced');
+  // 暂存任意图片类型字节只用于资源引用测试；不是 PNG 解码验证。
   let resource='';engine.stageFiles([{name:'image.png',bytes:new Blob(['image bytes'],{type:'image/png'})}],([ref],tx)=>{resource=ref.id;tx.dispatch({type:'element.create',element:{...f.node('image'),componentId:'image',data:{title:'image',text:'',assetId:ref.id,src:ref.src}}});});await engine.settle();const reads=f.reads;
+  // 两个 hooks 必须共用一次读取和一个 URL；移除一个不影响另一个，最后一个卸载后 URL 才失效。
   await render(<><Asset id={resource} slot="a"/><Asset id={resource} slot="b"/><Status/></>);await until(()=>assetA?.status==='ready'&&assetB?.status==='ready');assert(assetA.url===assetB.url&&f.reads===reads+1,'two resource hooks did not share one display read/URL');const url=assetA.url;assert(await(await fetch(url)).text()==='image bytes','asset hook did not expose original bytes');await render(<><Asset id={resource} slot="a"/><Status/></>);assert(await(await fetch(url)).text()==='image bytes','unmounting one reader revoked the other');await render(<Status/>);let revoked=false;try{await fetch(url);}catch{revoked=true;}assert(revoked,'last resource reader did not release its URL');reports.push('resource hooks share a URL, retain remaining readers and release the last handle on unmount');
+  // 读取尚未返回时卸载 hook，随后才放行；迟到资源结果应释放显示 pin，不能泄漏借用。
   let release!:()=>void;f.gate(new Promise<void>(resolve=>release=resolve));const before=f.reads;await render(<><Asset id={resource} slot="a"/><Status/></>);await until(()=>f.reads>before);await render(<Status/>);release();f.gate();await tick();assert(!engine.getResourcePins().pins.get(resource)?.has('display'),'late resource load leaked a display pin');
+  // 删除并撤销恢复元素后 incarnation 已变化；旧 facade 必须拒绝写入，不能自动改绑同 ID 的新对象。
   await render(<><Element/><Actions/><Gesture/><Status/></>);const staleActions=actions;engine.editor.dispatch({type:'element.remove',target:{id:'a',incarnation:1}});await engine.settle();engine.editor.history.undo();await engine.settle();await until(()=>element.status==='stale');const snapshot=engine.getSnapshot();assert(staleActions.rename('stale').status==='rejected'&&engine.getSnapshot()===snapshot,'old incarnation facade edited a restored element');reports.push('late resource loads release their pins and stale action targets cannot retarget restored incarnations');
+  // 关闭 engine 时 mounted hooks 也要观察到 closed/error 并释放资源。
   await render(<><Asset id={resource} slot="a"/><Status/></>);await until(()=>assetA.status==='ready');await engine.close();await until(()=>status.status==='closed'&&assetA.status==='error');reports.push('engine close is observable and releases mounted resource handles without owning a second project');
+  // 换 Provider 所属引擎后，资源字节和命令目标都必须来自新 owner，不能修改旧引擎快照。
   const other=await fixture();try{
     let otherResource='';other.engine.stageFiles([{name:'other.png',bytes:new Blob(['other identity bytes'],{type:'image/png'})}],([ref],tx)=>{otherResource=ref.id;tx.dispatch({type:'element.create',element:{...other.node('other-image'),componentId:'image',data:{title:'other',text:'',assetId:ref.id,src:ref.src}}});});await other.engine.settle();
     const oldSnapshot=engine.getSnapshot();await render(<><Asset id={otherResource} slot="a"/><Actions/><Status/></>,other.engine);await until(()=>assetA.status==='ready');assert(await(await fetch(assetA.url)).text()==='other identity bytes','Provider change reused another engine resource handle');assert(actions.rename('second owner').status==='applied','new owner action did not dispatch');await other.engine.settle();assert(other.engine.getSnapshot().document.elements.get('a')!.data.title==='second owner'&&engine.getSnapshot()===oldSnapshot,'Provider change routed commands to the old owner');reports.push('Provider owner changes replace resource handles and action targets without writing to the previous engine');
   }finally{await other.engine.close();}
+  // 部分来源完成前 b 和未知 ID 都是 unloaded；loading.complete 后才能分别判断 present 与 absent。
   const partial=await fixture(true);try{
     let b:any,missing:any;function Lookup(){b=useElement('b');missing=useElement('not-in-source');return null;}
     await render(<><Lookup/><Status/></>,partial.engine);assert(b.status==='unloaded'&&missing.status==='unloaded','partial lookup guessed absence');const completed=await partial.engine.loading.complete(partial.full,new Map([['canvas',1]]),{sourceToken:'hook-partial'});assert(completed.status==='applied','hook partial fixture did not complete');await partial.engine.settle();await until(()=>b.status==='present'&&missing.status==='absent');reports.push('element hooks preserve unloaded versus absent until source completion and then expose the newly loaded element');
   }finally{await partial.engine.close();}
+  // 只有所有场景通过才返回报告；finally 卸载 root、移除隐藏容器、恢复故障开关并清理 fixture。
   return reports;
  }finally{flushSync(()=>root.unmount());container.remove();f.fail(false);f.detach();await engine.close();}
 }
+// effect 仅注册页面测试入口；清理时先比较函数身份，防止旧挂载删除新实例注册的入口。
 export function HookChecks(){useEffect(()=>{const host=globalThis as typeof globalThis&{__runCanvasHookChecks?:()=>ReturnType<typeof run>};host.__runCanvasHookChecks=run;return()=>{if(host.__runCanvasHookChecks===run)delete host.__runCanvasHookChecks;};},[]);return null;}

tests/headless/renderer-extension.tsx

@@ -1,3 +1,7 @@
+/**
+ * 浏览器渲染集成专用插件：模型定义与 ReactFlow renderer 一起通过 CanvasRuntimeExtension 注入。
+ * 页面全局计数和 editing facade 仅用于测试观察，数据编辑仍经过生产命令/事务入口。
+ */
 "use client";
 import {useScopedNodeEditing} from '@/components/canvas/node-editing';
 import { Handle, Position, BaseEdge, getBezierPath, type NodeProps, type EdgeProps } from '@xyflow/react';
@@ -5,15 +9,20 @@ import { defineComponent, editable, movable } from '@/lib/canvas-core/index';
 import type {ReactFlowProjectionNode as ProjectionNode,ReactFlowProjectionEdge as ProjectionEdge} from '@/lib/canvas-bindings/react-flow';
 import type { CanvasRuntimeExtension } from '@/lib/canvas-bindings/react-flow';
 import { useCanvasBinding,useElement, useCanvasRendererCommands } from '@/lib/canvas-bindings/react-flow';
+// 按元素 ID 计数真实 renderer 调用，供外层检查无关元素是否重渲染，不以 DOM 数量代替渲染次数。
 function rendered(id:string){const host=globalThis as typeof globalThis&{__fixtureRenders?:Record<string,number>};const counts=host.__fixtureRenders??={};counts[id]=(counts[id]??0)+1;}
+// 通过 useElement 取得当前原记录，捕获有 scoped target 与无绑定两种旧 editing facade，交给外层验证桥接隔离。
 function Meter({data}:NodeProps<ProjectionNode>){
   const commands=useCanvasRendererCommands(),lookup=useElement(data.__headlessRecord!),record=lookup.status==='present'?lookup.element:data.__headlessRecord!;rendered(record.id);const legacy=useScopedNodeEditing(record.id,data.__headlessTarget),unbound=useScopedNodeEditing(record.id),binding=useCanvasBinding();const host=globalThis as typeof globalThis&{__fixtureEngine?:typeof binding.engine;__fixtureLegacy?:Record<string,typeof legacy>;__fixtureUnbound?:Record<string,typeof legacy>};host.__fixtureEngine=binding.engine;(host.__fixtureLegacy??={})[record.id]=legacy;(host.__fixtureUnbound??={})[record.id]=unbound;
+  // Increase 按钮阻止点击冒泡，并在一个事务里修改 metric 与 raw，要求只产生一个历史单元；自定义 Handle ID 供连线端口测试。
   return <div data-renderer-fixture="meter" style={{width:'100%',height:'100%',background:'white',border:'1px solid #ded7ce',padding:16}}>
     <span>Metric {String(record.data.metric)}</span><button className="nodrag" aria-label={`Increase ${record.id}`} onClick={event=>{event.stopPropagation();commands.transaction(tx=>{tx.dispatch({type:'element.data',target:{id:record.id,incarnation:record.incarnation},patch:{metric:Number(record.data.metric)+1}});tx.dispatch({type:'element.data',target:{id:record.id,incarnation:record.incarnation},patch:{raw:{retained:true,edited:true}}});},{label:'Increase metric'});}}>Increase</button>
     <Handle type="source" id="custom-out" position={Position.Right}/><Handle type="source" id="custom-in" position={Position.Left}/>
   </div>;
 }
+// 自定义边记录渲染次数，使用 ReactFlow Bezier path 绘制；标题从原 connection data 读取 metric。
 function MeterEdge(props:EdgeProps<ProjectionEdge>){rendered(props.id);const [path]=getBezierPath(props);return <g data-renderer-fixture="metric-edge"><title>Metric {String(props.data?.__headlessRecord?.data.metric)}</title><BaseEdge id={props.id} path={path}/></g>;}
+// 两种模型分别校验 metric，节点安装编辑/移动能力；renderer 键精确匹配 componentId、dataVersion 与 structure。
 export const fixtureExtension:CanvasRuntimeExtension={
   components:[defineComponent({id:'fixture:meter',dataVersion:1,structure:'node',validate:data=>Number.isSafeInteger(data.metric),features:[editable(),movable()],copy:{references:[],omit:[]}}),defineComponent({id:'fixture:metric-edge',dataVersion:1,structure:'connection',validate:data=>typeof data.metric==='number',features:[],copy:{references:[],omit:[]}})],
   renderers:[{componentId:'fixture:meter',dataVersion:1,structure:'node',rendererId:'fixture-meter',render:Meter},{componentId:'fixture:metric-edge',dataVersion:1,structure:'connection',rendererId:'fixture-metric-edge',render:MeterEdge}],

tests/headless/renderer-performance.mjs

@@ -1,32 +1,46 @@
-/** Actual GraphPage/React Flow + IndexedDB probe; fixture HTTP server, not production service. */
+/**
+ * 实际 GraphPage/ReactFlow 页面与 IndexedDB 的输入、保留和深复制探针，HTTP 后端由 fixture 提供。
+ * 调用者注入 CDP、页面 evaluate、服务文档及报告路径；本文件不独立启动浏览器或构建项目。
+ * 将场景断言与耗时/堆采样分别报告：计时是本次环境的观测，不构成通用 SLA；内嵌页面脚本保持测试输入原字节。
+ */
 import assert from 'node:assert/strict';
 import {editDuringCopy} from './renderer-copy-input.mjs';
 import {writeFile} from 'node:fs/promises';
 import {setTimeout as pause} from 'node:timers/promises';
 import {canvasTransform,toWorld} from '../../src/lib/canvas-core/coordinates.ts';
 
+// 依次验证原生编辑、离屏输入保留、宿主面板、portal 和大分区复制，再写报告与成功截图。
 export async function measureRenderer({call,evaluate,documents,calls=[],root,partition,count,exceptions,reportPath,browserLogs=()=>'',baseline,buildMode='development',bundler='webpack',buildMs}){
+  // 保存测量墙上起点、堆样本及复制状态；target 用于离屏裁剪断言，不是最终服务端元素总数。
   const target=2*count+3,started=Date.now(),heapSamples=[];let copying=false,nextHeap=0;
+  // 每次条件轮询有四分钟墙上截止并检查页面异常；复制中可每十秒取堆与回执保留快照，写 .heap.json。单次 await 仍依赖注入调用器返回。
   const wait=async(expression,label)=>{const deadline=Date.now()+240000;while(Date.now()<deadline){if(exceptions.length)throw Error(exceptions.join('\n'));if(copying&&process.env.HEADLESS_PERFORMANCE_HEAP==='1'&&Date.now()>=nextHeap){const heap=await call('Runtime.getHeapUsage'),retention=await evaluate('window.__fixtureReceiptRetention');heapSamples.push({wallMs:Date.now()-started,serverElements:documents.get(root)?.elements.size,heap,retention});nextHeap=Date.now()+10000;await writeFile(reportPath+'.heap.json',JSON.stringify({baseline,heapSamples},null,2));}if(await evaluate(expression))return;await pause(100);}throw Error(label);};
   let report,duringCopyInput;
+  // 环境开关决定是否在复制期间额外输入；默认仅测复制，报告 scenario 据此区分。
   const concurrentInput=process.env.HEADLESS_PERFORMANCE_EDIT_DURING_COPY==='1';
   try{
+    // 等真实 frame 与至少两个节点挂载；未选择时不应保留空节点工具栏订阅。
     await wait(`!!document.querySelector('.react-flow__node[data-id="perf-frame"]')&&document.querySelectorAll('.react-flow__node').length>=2`,'initial large canvas did not render');
     assert.equal(await evaluate('document.querySelectorAll(".react-flow__node-toolbar").length'),0,'unselected nodes retained empty toolbar subscriptions');
+    // 读取页面 performance.now，是相对页面时间原点的就绪观测，不是函数 Date.now 起点的独立渲染耗时。
     const initialReadyMs=await evaluate('performance.now()');console.log('PERF initial scene ready '+Math.round(initialReadyMs)+' ms');
-    // Use native input: synthetic focus alone misses the editing-mode transition.
+    // 使用原生输入进入编辑；仅脚本 focus 不会覆盖真实编辑模式切换。
     await wait(`!!document.querySelector('.react-flow__node[data-id="perf-0"] [aria-label^="单击选中"]')`,'first visible text card missing');
+    // 记录双击前后 DOM 数量，用于断言进入单卡编辑不会把离屏全集挂载。
     const beforeEditing=await evaluate('document.querySelectorAll(".react-flow__node").length');
     const editPoint=await evaluate(`(()=>{const rect=document.querySelector('.react-flow__node[data-id="perf-0"] [aria-label^="单击选中"]').getBoundingClientRect();return{x:rect.x+60,y:rect.y+30};})()`);
+    // 经 CDP 发送原生双击，随后验证 activeElement 为可写 textarea，避免只用脚本 focus 绕过编辑模式。
     await call('Input.dispatchMouseEvent',{type:'mousePressed',...editPoint,button:'left',buttons:1,clickCount:2});
     await call('Input.dispatchMouseEvent',{type:'mouseReleased',...editPoint,button:'left',buttons:0,clickCount:2});
     await wait(`document.activeElement===document.querySelector('.react-flow__node[data-id="perf-0"] textarea')&&!document.activeElement.readOnly`,'native text editing did not start');
     await evaluate('window.__performanceEditor=document.activeElement;new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
     const duringEditing=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(duringEditing<=beforeEditing+10,'editing one visible card mounted the offscreen canvas');
+    // 输入后同一 DOM、焦点和文本都要保留，再开启 IME 并将目标平移到屏幕外。
     await call('Input.insertText',{text:'Native editing remains responsive'});
     assert.equal(await evaluate('window.__performanceEditor.isConnected&&document.activeElement===window.__performanceEditor&&window.__performanceEditor.value.includes("Native editing remains responsive")'),true,'native input lost its DOM, focus or value');
     await evaluate('window.__editViewport=new DOMMatrix(getComputedStyle(document.querySelector(".react-flow__viewport")).transform);true');
+    // 先建立组合输入再平移；目标确实离屏且仍保留输入 DOM，正常规模下不能因保留一个 editor 挂载全集。
     await call('Input.imeSetComposition',{text:'保',selectionStart:1,selectionEnd:1});
     await evaluate(`document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:20000,deltaY:20000,bubbles:true,cancelable:true}))`);
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
@@ -34,6 +48,7 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     assert.equal(await evaluate('(()=>{const r=window.__performanceEditor.getBoundingClientRect();return r.right<0||r.bottom<0||r.left>innerWidth||r.top>innerHeight;})()'),true,'IME probe did not move its owner offscreen');
     const offscreenEditing=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(offscreenEditing<=10,'retaining one offscreen editor mounted the complete canvas');
+    // 离屏提交组合文本后恢复 viewport 并 blur，等同步完成再开始复制计时，排除上一轮未保存输入干扰。
     await call('Input.insertText',{text:'保留输入'});
     assert.equal(await evaluate('window.__performanceEditor.value.endsWith("保留输入")'),true,'offscreen IME commit lost content');
     await evaluate(`(()=>{const now=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform),before=window.__editViewport;document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:(now.e-before.e)/.5,deltaY:(now.f-before.f)/.5,bubbles:true,cancelable:true}));delete window.__editViewport;})()`);
@@ -41,6 +56,7 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     await wait(`[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'native input did not synchronize before copy measurement');
     const inputCheck={beforeEditing,duringEditing,offscreenEditing};
     console.log('PERF native editing '+JSON.stringify(inputCheck));
+    // 记录 AI 任务 POST 基数；修改面板设置或复制只能改配置/文档，不应启动生成。
     const runStartsBefore=calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length;
     await wait(`!!document.querySelector('[aria-label="AI 创作"]')&&!document.querySelector('[aria-label="AI 创作"]').disabled`,'AI panel action did not become available');
     await evaluate(`document.querySelector('[aria-label="AI 创作"]').click()`);
@@ -48,24 +64,29 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     await evaluate(`(()=>{window.__performancePanel=document.querySelector('[aria-label="AI 指令"]');window.__performancePanel.focus();window.__editViewport=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform);})()`);
     await call('Input.insertText',{text:'Stable host panel draft'});
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+    // 宿主 AI 面板与节点编辑不同：面板持有草稿不应额外保留所有节点。
     inputCheck.panelFocusedNodes=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(inputCheck.panelFocusedNodes<=beforeEditing+10,'host-panel focus mounted the complete canvas');
     await evaluate(`document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:20000,deltaY:20000,bubbles:true,cancelable:true}))`);
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+    // 平移后面板 DOM、焦点和草稿都保留，但画布离屏节点应归零。
     assert.equal(await evaluate('window.__performancePanel.isConnected&&document.activeElement===window.__performancePanel&&window.__performancePanel.value==="Stable host panel draft"'),true,'independent panel lost its focus or draft during pan');
     inputCheck.offscreenPanel=await evaluate('document.querySelectorAll(".react-flow__node").length');
     assert.equal(inputCheck.offscreenPanel,0,'host-panel input pinned unrelated offscreen nodes');
     await evaluate('window.__performancePanel.blur();new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
     await wait(`[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'AI settings did not save before copy');
+    // blur 后从 fixture 服务文档核对配置已经保存，再恢复视口并关闭面板。
     assert.equal(documents.get(root).elements.get('perf-0').data.ai?.prompt,'Stable host panel draft','host-panel blur lost saved settings');
     await evaluate(`(()=>{document.querySelector('[aria-label="关闭 AI 工具"]').click();const now=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform),before=window.__editViewport;document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:(now.e-before.e)/.5,deltaY:(now.f-before.f)/.5,bubbles:true,cancelable:true}));delete window.__performancePanel;delete window.__editViewport;})()`);
     assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length,runStartsBefore,'editing settings started a generation task');
 
+    // 通过 elementFromPoint 搜索真正空白 pane 坐标并原生点击，清空之前编辑选择，避免污染 frame 工具栏计数。
     const panePoint=await evaluate(`(()=>{const pane=document.querySelector('.react-flow__pane'),rect=pane.getBoundingClientRect();for(let y=rect.y+5;y<rect.bottom;y+=20)for(let x=rect.x+5;x<rect.right;x+=20)if(document.elementFromPoint(x,y)===pane)return{x,y};throw Error('no empty native pane point');})()`);
     await call('Input.dispatchMouseEvent',{type:'mousePressed',...panePoint,button:'left',buttons:1,clickCount:1});
     await call('Input.dispatchMouseEvent',{type:'mouseReleased',...panePoint,button:'left',buttons:0,clickCount:1});
     await wait('document.querySelectorAll(".react-flow__node-toolbar").length===0','native edit selection did not clear before frame selection');
 
+    // 选择 frame 后只允许一个工具栏，portal 标题编辑作为新的离屏保留 owner。
     await evaluate(`document.querySelector('.react-flow__node[data-id="perf-frame"]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`);
     await wait(`!!document.querySelector('[aria-label="深复制选中内容"]')&&!document.querySelector('[aria-label="深复制选中内容"]').disabled`,'partition selection did not enable deep copy');
     await evaluate(`new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))`);
@@ -76,13 +97,16 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     await evaluate(`document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:20000,deltaY:20000,bubbles:true,cancelable:true}))`);
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
     assert.equal(await evaluate('window.__performancePortal.isConnected&&document.activeElement===window.__performancePortal&&window.__performancePortal.value==="Retained portal title"'),true,'portal title draft was lost during offscreen pan');
+    // 分区标题 portal 离屏时只保留必要 owner；blur 后应释放全部离屏节点，回到原视口再确认标题保存及重挂载。
     inputCheck.offscreenPortal=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(inputCheck.offscreenPortal<=10,'one portal draft mounted the complete canvas');
     await evaluate('window.__performancePortal.blur();true');
     await wait('document.querySelectorAll(".react-flow__node").length===0','released portal retained offscreen owners');
     await evaluate(`(()=>{const now=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform),before=window.__editViewport;document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:(now.e-before.e)/.5,deltaY:(now.f-before.f)/.5,bubbles:true,cancelable:true}));delete window.__editViewport;delete window.__performancePortal;})()`);
     await wait(`document.querySelector('[aria-label="分区名称"]')?.value==='Retained portal title'&&[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'portal title did not save and remount');
+    // 捕获复制开始前的原文，用来证明并发输入不进入已经捕获的副本。
     const sourceText=documents.get(root).elements.get('perf-0').data.text;
+    // 页面脚本以 rAF 采样新 DOM、进度完成、节点峰值、帧间隔，并在支持时观察 longtask；tick 反复采样，read 汇总，stop 取消并断开 observer。
     await evaluate(`(()=>{
       const originals=new Set(['perf-source','perf-frame',...Array.from({length:${count}},(_,i)=>'perf-'+i)]),start=performance.now(),tasks=[],gaps=[];
       let raf,last=start,sawPreparing=false,firstDOM=null,firstFrame=null,localComplete=null,localCompleteFrame=null,prepared=null,maxNodes=0;
@@ -93,11 +117,15 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
       window.__canvasPerformance={read(){const sorted=[...gaps].sort((a,b)=>a-b),p95=sorted[Math.max(0,Math.ceil(sorted.length*.95)-1)]??0;return{frameGapP95Ms:p95,elapsedMs:performance.now()-start,firstDOMMs:firstDOM,firstPresentedFrameMs:firstFrame,localCompleteMs:localComplete,localCompleteFrameMs:localCompleteFrame,prepareMs:prepared,maxMountedNodes:maxNodes,nodeCount:document.querySelectorAll('.react-flow__node').length,longTasksSupported:supported,longTaskCount:tasks.length,maxLongTaskMs:Math.max(0,...tasks.map(task=>task.duration)),totalLongTaskMs:tasks.reduce((total,task)=>total+task.duration,0),maxFrameGapMs:Math.max(0,...gaps),longTasks:tasks};},stop(){cancelAnimationFrame(raf);if(observer){tasks.push(...observer.takeRecords().map(entry=>({start:entry.startTime-start,duration:entry.duration})));observer.disconnect();}return this.read();}};
       document.querySelector('[aria-label="深复制选中内容"]').click();
     })()`);
+    // 页面脚本安装采样后点击复制；Node 侧此后才启用复制期间的可选堆采样。
     copying=true;console.log('PERF copy requested');
+    // 可选探针通过原生输入继续编辑源卡，校验完整文字增量；副本随后仍须保留复制起点文本。
     if(concurrentInput){duringCopyInput=await editDuringCopy({call,evaluate,wait,count});assert.equal(duringCopyInput.value,sourceText+(count>=10000?'复制期间输入 A B C M T':'复制期间输入 A B C'),'concurrent typing lost pre-existing source text');console.log('PERF concurrent input '+JSON.stringify(duringCopyInput));}
     await wait(`document.querySelectorAll('.react-flow__node').length>0&&document.querySelector('[aria-label="画布导入"]')?.textContent.includes('已加入画布')&&[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'large copy did not finish rendering and synchronization');
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+    // 完成进度与已同步后再等两帧，要求 renderer 测量出现合批；统计批量大小而非只计渲染总数。
     const internalsBatches=await evaluate('window.__fixtureInternalsBatches??[]');assert.ok(internalsBatches.some(size=>size>1),'mounted nodes did not share a renderer measurement batch');
+    // 停止页面采样并验证服务元素数、复制 canvas 和上级连线。firstPresentedFrame 是检测新 DOM 后的下一次 rAF 近似值，不是 compositor 上屏证明。
     const measurements=await evaluate('window.__canvasPerformance.stop()'),document=documents.get(root),copiedCanvas=[...document.canvases.values()].find(canvas=>canvas.parent&&canvas.id!==partition);
     assert.equal(document.elements.size,2*count+5);assert.ok(copiedCanvas);assert.ok([...document.elements.values()].some(element=>element.structure==='connection'&&element.source.elementId==='perf-source'&&element.target.elementId===copiedCanvas.parent.entryElementId));assert.ok(document.elements.has('perf-incoming'));assert.ok(measurements.firstPresentedFrameMs!==null&&measurements.localCompleteFrameMs!==null);if(count>=100)assert.ok(measurements.nodeCount<target,'offscreen DOM was not culled');assert.ok(await evaluate(`document.querySelector('[aria-label="画布导入"]').textContent.includes('${count+3} 项')`),'copy progress did not include all source records');
     if(concurrentInput){
@@ -105,17 +133,26 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
       assert.equal(copiedFirst?.data.text,sourceText,'copy snapshot absorbed a later original edit');
       assert.equal(document.elements.get('perf-0').data.text,duringCopyInput.value,'ACK overwrote concurrent original text');
     }
+    // 再次核对整个配置/复制场景没有启动 AI 任务；生成计费不属于深复制的副作用。
     const runStartsDuringScenario=calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length-runStartsBefore;
     assert.equal(runStartsDuringScenario,0,'deep copy or settings unexpectedly started generation');
+    // 离屏源仍需保留两条可见分区连线，随后把最后一个副本节点平移到屏幕内，检查实际挂载。
     const visibleEdges=await evaluate('document.querySelectorAll(".react-flow__edge").length');assert.equal(visibleEdges,2,'frame connections did not render for the offscreen source');
-    // Completion is a model/progress check. Verify an offscreen copied card actually mounts after panning.
+    // 进度完成只证明模型/作业状态；还要平移后看到副本卡片实际挂载。
+    // 按原节点局部位置找到复制后的末项，而非只依赖进度或服务记录宣称渲染完成。
     const originalLast=document.elements.get(`perf-${count-1}`),copiedLast=[...document.elements.values()].find(element=>element.structure==='node'&&element.ownerCanvasId===copiedCanvas.id&&element.geometry.x===originalLast.geometry.x&&element.geometry.y===originalLast.geometry.y);assert.ok(copiedLast);
+    // 从副本 owner 的局部坐标换算世界中心，给页面 viewport 平移定位使用。
     const world=toWorld(canvasTransform(document,copiedLast.ownerCanvasId),{x:copiedLast.geometry.x+copiedLast.geometry.width/2,y:copiedLast.geometry.y+copiedLast.geometry.height/2});
     await evaluate(`(()=>{const pane=document.querySelector('.react-flow__pane'),rect=pane.getBoundingClientRect(),matrix=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform);pane.dispatchEvent(new WheelEvent('wheel',{deltaX:(${world.x}*matrix.a+matrix.e-rect.width/2)/.5,deltaY:(${world.y}*matrix.a+matrix.f-rect.height/2)/.5,bubbles:true,cancelable:true}));})()`);
     await wait(`!!document.querySelector('.react-flow__node[data-id="${copiedLast.id}"] textarea')`,'offscreen copied card did not mount after viewport pan');
+    // 记录平移后的实际挂载数量，和之前的可见连线数一起写入报告。
     const viewportCheck={visibleEdgesBeforePan:visibleEdges,copiedId:copiedLast.id,mountedAfterPan:await evaluate('document.querySelectorAll(".react-flow__node").length')};
+    // 报告同时保存输入断言上下文、浏览器/构建模式、采样、fixture 文档计数与测量批次，便于跨环境比较。
     report={inputCheck,duringCopyInput,runStartsDuringScenario,baseline,heapSamples,browserLogs:browserLogs(),scenario:concurrentInput?'actual GraphPage deep copy with concurrent native input':'actual GraphPage deep copy of expanded partition',mode:`Next ${buildMode} ${bundler}; isolated fixture HTTP; real Chrome/IndexedDB/Web Locks`,count,initialReadyMs,buildMs,internals:{batches:internalsBatches.length,maxBatch:Math.max(0,...internalsBatches),totalRequests:internalsBatches.reduce((sum,size)=>sum+size,0)},measurements,viewportCheck,browser:await call('Browser.getVersion'),serverElements:document.elements.size,serverCanvases:document.canvases.size,wallMs:Date.now()-started};
+    // 仅成功路径截图，输出到报告同名 PNG；截图是场景结束视口，不是每个计时点的屏幕证据。
     const screenshot=await call('Page.captureScreenshot',{format:'png'});await writeFile(reportPath.endsWith('.json')?reportPath.slice(0,-5)+'.png':reportPath+'.png',Buffer.from(screenshot.data,'base64'));
+  // 失败也尽力停止页面采样并写诊断报告，然后重抛；不能把部分观测输出当作场景通过。
   }catch(error){let measurements;try{measurements=await evaluate('window.__canvasPerformance?.stop()');}catch{}report={duringCopyInput,baseline,heapSamples,browserLogs:browserLogs(),scenario:concurrentInput?'actual GraphPage deep copy with concurrent native input':'actual GraphPage deep copy of expanded partition',count,buildMode,buildMs,error:error.message,measurements,serverElements:documents.get(root)?.elements.size,serverCanvases:documents.get(root)?.canvases.size,wallMs:Date.now()-started};await writeFile(reportPath,JSON.stringify(report,null,2));throw error;}
+  // 成功报告落盘后打印紧凑摘要，长任务明细仍保存在 JSON 文件。
   await writeFile(reportPath,JSON.stringify(report,null,2));console.log('MEASURE '+JSON.stringify({...report,measurements:{...report.measurements,longTasks:undefined}}));console.log('REPORT '+reportPath);
 }

tests/headless/renderer.integration.mjs

@@ -1,8 +1,14 @@
+/**
+ * 复制实际 dashboard/GraphPage/headless renderer/Next proxy 到临时应用，连接本地 HTTP fixture，再用隔离 Chrome 操作真实页面。
+ * 引擎、ReactFlow、IndexedDB 和代理走应用实现，文档/AI/上传/授权响应由下面的内存服务提供，不是远程 Foundry 验证。
+ * 执行会启动 Next 编译/开发服务，性能生产模式还会 build；本文件不是轻量 node:test，也不会在纯注释检查时执行。
+ * 计数与测试入口仅写入临时副本，所有嵌入字符串都是测试输入；finally 释放屏障、连接、进程和临时目录。
+ */
 import {execFileSync} from 'node:child_process';
 import {createCdpCalls} from './cdp-client.mjs';
 import {measureRenderer} from './renderer-performance.mjs';
 import {createRendererMigrationFixture,verifyRendererMigration} from './renderer-migration.mjs';
-/** Actual dashboard, GraphPage, headless renderer, browser storage and Next proxy. */
+
 import assert from 'node:assert/strict';
 import { createServer } from 'node:http';
 import { mkdtemp, cp, copyFile, symlink, readFile, writeFile, rm, realpath } from 'node:fs/promises';
@@ -11,98 +17,137 @@ import { tmpdir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { setTimeout as pause } from 'node:timers/promises';
 import { createDocument, applyChanges } from '../../src/lib/canvas-core/index.ts';
+// 默认 webpack，可显式选择 turbopack；两者在 fixture 放置路径与启动参数上采用不同约束。
 const bundler=process.argv.includes('--turbopack')?'turbopack':'webpack';
+// 生产模式只允许与性能入口组合，防止把功能测试默认为生产构建。
 const productionMode=process.argv.includes('--production');if(productionMode&&!process.argv.includes('--performance'))throw Error('--production requires --performance');
+// migration-only、hooks-only 和 performance 分支各走自己的验证入口；迁移分支禁止混合其他模式。
 const migrationOnly=process.argv.includes('--migration-only');
 const hooksOnly=process.argv.includes('--hooks-only'),performanceMode=process.argv.includes('--performance'),performanceCount=Number(process.env.HEADLESS_PERFORMANCE_COUNT??1000);
 if(migrationOnly&&(hooksOnly||performanceMode))throw Error('migration-only requires its own functional entry');
+// 性能规模必须是 1..10000 的安全整数；复制期间原生输入探针还要求至少 1000 节点。
 if(performanceMode&&(!Number.isSafeInteger(performanceCount)||performanceCount<1||performanceCount>10000))throw Error('invalid performance count');
 if(process.env.HEADLESS_PERFORMANCE_EDIT_DURING_COPY==='1'&&(!performanceMode||performanceCount<1000))throw Error('concurrent input requires --performance and at least 1000 nodes');
+// 诊断 baseline 只接受十六进制 commit 标识；稍后只替换三个指定模块，不表示回放完整历史版本。
 const baseline=process.env.HEADLESS_PERFORMANCE_BASELINE;if(baseline&&!/^[a-f0-9]{7,40}$/.test(baseline))throw Error('invalid diagnostic baseline');
 const source = resolve(import.meta.dirname, '../..');
-// Turbopack fences real dependency paths to its workspace root. Keep its isolated
-// fixture under the physical dependency workspace, then remove this exact path
-// in finally. Webpack fixtures retain their ordinary OS-temp location.
+// Turbopack 要求真实依赖路径位于 workspace root，临时应用放在依赖的物理目录旁；webpack 使用系统临时目录。
 const fixtureRoot=bundler==='turbopack'?dirname(await realpath(join(source,'node_modules'))):tmpdir();
+// 应用和浏览器 profile 分别随机建目录；进程及临时文件归本次检查持有。
 const directory = await mkdtemp(join(fixtureRoot, bundler==='turbopack'?'.headless-renderer-':'endoleap-renderer-')), profile = await mkdtemp(join(tmpdir(), 'endoleap-renderer-browser-'));
+// 稳定 UUID 形式用于测试作用域/任务身份，与业务元素 a/b 等符号 ID 分开。
 const id = n => `10000000-0000-4000-8000-${String(n).padStart(12, '0')}`;
+// 各 Map 是内存服务事实源；calls 记录上游实际收到的字节/头，供断言请求次数与协议传递。
 const account = id(1), workspace = id(2), root = id(3), other = id(4), partition = id(5), calls = [], uploads = [], documents = new Map(), versions = new Map([[root, 1], [other, 1]]), assets = new Map(), assetBytes=new Map(), aiRuns = new Map();
+// 建立合法第一代文本节点；功能模式从两个节点和带可编辑路径的连线开始。
 const node = (id, ownerCanvasId, x) => ({ id, ownerCanvasId, incarnation: 1, componentId: 'text', dataVersion: 1, structure: 'node', data: { title: 'Card ' + x, text: 'Editable content' }, geometry: { x, y: 150, width: 260, height: 200, rotation: 0 } });
 documents.set(root, createDocument(root, [{ id: root, parent: null }], [node('a', root, 80), node('b', root, 450), { id: 'edge', incarnation: 1, componentId: 'connection', dataVersion: 1, structure: 'connection', ownerCanvasId: root, source: { elementId: 'a' }, target: { elementId: 'b' }, data: {}, path: { type: 'bezier-chain', knots: [{ id: 'k', mode: 'corner', position: { x: 400, y: 250 }, in: { x: -20, y: 0 }, out: { x: 20, y: 0 } }] } }]));
 documents.set(other, createDocument(other, [{ id: other, parent: null }], []));
+// 性能模式替换根模型：展开的分区含 count 个网格节点，根锚点与入口连线用于复制和离屏边验证。
 if(performanceMode){
   const frame={...node('perf-frame',root,30),componentId:'frame',data:{title:'Performance partition',text:''},geometry:{x:30,y:50,width:1000,height:600,rotation:0}},children=Array.from({length:performanceCount},(_,index)=>({...node(`perf-${index}`,partition,(index%20)*280),geometry:{x:(index%20)*280,y:Math.floor(index/20)*220,width:260,height:200,rotation:0}})),incoming={id:'perf-incoming',incarnation:1,componentId:'connection',dataVersion:1,structure:'connection',ownerCanvasId:root,source:{elementId:'perf-source'},target:{elementId:'perf-frame'},data:{},path:null};
   versions.set(partition,1);documents.set(root,createDocument(root,[{id:root,parent:null},{id:partition,parent:{canvasId:root,entryElementId:frame.id}}],[node('perf-source',root,-300),frame,...children,incoming]));
 }
+// 应用目录和标题接口返回两个根 board，canvas 规范模型仍由 documents 保存。
 const boards = [root, other].map((id, i) => ({ id, workspace_id: workspace, kind: 'board', version: 1, title: i ? 'Other board' : 'Headless board' }));
+// 固定 PNG 只供显示 URL 返回；上传元数据和原始上传字节另外保存，不能从此图片推导所有资源都做过解码。
 const png = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aB1sAAAAASUVORK5CYII=', 'base64');
+// 某个后续场景在前三项后挂住流，验证完整子 owner 可先写，而其他 owner 继续加载。
 let scopeStreamRoot=null,releaseScopeStream;const scopeStreamGate=new Promise(resolve=>releaseScopeStream=resolve);
+// 分别标记错误尾部与被导航放弃的来源；abandonedGate 可令旧响应晚到。
 let brokenStreamRoot=null,abandonedRoot=null,releaseAbandoned;const abandonedGate=new Promise(resolve=>releaseAbandoned=resolve);
+// 功能模式首读只发第一个元素即等待，给“边加载边编辑”留出可控窗口。
 let releaseFirstModel;const firstModelGate=new Promise(resolve=>{releaseFirstModel=resolve;});let gatedFirstModel=!performanceMode&&!migrationOnly;
+// 包含特定导入标题的文档写入可挂起，editReceipts 按请求 ID 保存规范写入结果。
 let releaseImport;const importGate=new Promise(resolve=>{releaseImport=resolve;});let importWriteSeen=false;const editReceipts=new Map();
+// AI 显式应用先改变服务状态再挂起响应，用于检查本地操作与未确认回执交错。
 let releaseApply;const applyGate=new Promise(resolve=>{releaseApply=resolve;});
+// 上传收到字节后先记录资源，uploadGate 决定何时确认，使本地预览与后端确认可分开观察。
 let releaseUpload; const uploadGate = new Promise(resolve => { releaseUpload = resolve; });
+// 将指定参与 canvas 的完整成员编码为局部/完整规范模型；此替身 removedCanvasIds 固定为空，不涵盖任意删除协议。
 const model = (document, complete = true, participants=[...document.canvases.keys()]) => ({ documentFormatVersion: 1, projectId: document.projectId, complete, canvases: [...document.canvases.values()].filter(canvas=>participants.includes(canvas.id)), elements: [...document.elements.values()].filter(element=>participants.includes(element.ownerCanvasId)), tombstones: Object.fromEntries(document.tombstones), versions: Object.fromEntries(participants.map(id => [id, versions.get(id)])), removedCanvasIds: [] });
+// 后续恢复场景可拒绝下一次编辑，资源采用场景可拒绝或延迟元数据授权。
 let rejectNextEdit=false,rejectedEdit,denyAssetMetadata=false,metadataWait,releaseMetadata;
+// 仅迁移入口装配专用路由/旧数据集；其他模式不运行迁移 fixture。
 const migrationFixture=migrationOnly?createRendererMigrationFixture({id,account,workspace,boards,documents,versions,model}):undefined;
+// 上游在真实 HTTP 上接请求，但内部仅操作 Map；异常转成 500，使页面协议错误可观察。
 const upstream = createServer(async (request, response) => {
   try {
     const url = new URL(request.url, 'http://fixture'), path = url.pathname, chunks = [];
     for await (const chunk of request) chunks.push(chunk);
     const bytes = Buffer.concat(chunks); calls.push({ method: request.method, path, bytes, headers: request.headers });
+    // 统一 JSON 响应助手；登录、个人资料、workspace 和目录路由只满足实际页面装配。
     const reply = (status, body) => { response.writeHead(status, { 'Content-Type': 'application/json' }); response.end(JSON.stringify(body)); };
     if (path.endsWith('/auth/logout')) return reply(204, null);
     if (path.endsWith('/profile')) return reply(200, { id: account, username: 'fixture', display_name: 'Creator', email: null });
     if (path.endsWith('/workspaces')) return reply(200, [{ id: workspace, name: 'Fixture workspace', role: 'admin' }]);
     if (path.endsWith('/materials')) return reply(200, { items: boards, next_offset: null });
     const board = boards.find(board => path.endsWith('/materials/' + board.id)); if (board) return reply(200, board);
+    // 迁移专用处理器先尝试接管，再进入公共模型路由，避免两个 fixture 同时修改一个请求。
     if(await migrationFixture?.handle(request,path,reply,bytes))return;
     const read = path.match(/\/materials\/([^/]+)\/canvas\/model$/);
+    // 只有协商的 Accept 才返回规范 NDJSON；未协商请求走下面的完整 JSON 路径。
     if(read&&request.headers.accept==='application/vnd.foundry.canvas-model+ndjson;version=1'){
       const value=model(documents.get(read[1])),token='fixture-snapshot-'+calls.length;let sequence=0;
       response.writeHead(200,{'Content-Type':'application/vnd.foundry.canvas-model+ndjson;version=1'});
+      // 同一 snapshotToken 内序号递增，每帧为一行 JSON；header 先提供完整 canvas、owner 清单和成员计数。
       const line=record=>response.write(JSON.stringify({streamVersion:1,snapshotToken:token,sequence:sequence++,...record})+'\n');
       line({kind:'header',documentFormatVersion:1,projectId:value.projectId,canvases:value.canvases,versions:value.versions,tombstones:value.tombstones,removedCanvasIds:value.removedCanvasIds,elementCount:value.elements.length,canvasElementCounts:Object.fromEntries(value.canvases.map(canvas=>[canvas.id,value.elements.filter(element=>element.ownerCanvasId===canvas.id).length])),elementOwners:Object.fromEntries(value.elements.map(element=>[element.id,element.ownerCanvasId]))});
+      // 错误尾部先发送有效首元素，再结束为非法 JSON；应保留可见前缀并报告失败。
       if(read[1]===brokenStreamRoot){line({kind:'elements',elements:value.elements.slice(0,1)});response.end('{broken tail}\n');return;}
       let start=0;
+      // 作用域流和被放弃流各有自己的首块大小与 gate；响应已销毁时停止追加尾部。
       if(read[1]===scopeStreamRoot){line({kind:'elements',elements:value.elements.slice(0,3)});start=3;await scopeStreamGate;if(response.destroyed)return;}
       if(read[1]===abandonedRoot){line({kind:'elements',elements:value.elements.slice(0,1)});start=1;await abandonedGate;if(response.destroyed)return;}
+      // 首个根读取只触发一次 gate；其余元素随后每帧最多 64 项，再发送 complete 并结束 HTTP body。
       if(gatedFirstModel&&read[1]===root&&value.elements.length){gatedFirstModel=false;line({kind:'elements',elements:value.elements.slice(0,1)});start=1;await firstModelGate;}
       for(let offset=start;offset<value.elements.length;offset+=64)line({kind:'elements',elements:value.elements.slice(offset,offset+64)});
       line({kind:'complete',elementCount:value.elements.length});return response.end();
     }
     if (read) return reply(200, { model: model(documents.get(read[1])) });
     const write = path.match(/\/materials\/([^/]+)\/canvas\/model\/operations$/);
+    // 规范增量写入路径：检查账户、幂等键与参与版本，在内存服务模型上按顺序应用，再保存回执。此处不实现完整生产幂等数据库。
     if (write) {
       const batch = JSON.parse(bytes.toString()), previous = documents.get(write[1]);
+      // 特定导入写入到达后仅设置观测标记并等待 gate，阻塞发生在文档提交前。
       if(batch.operations.some(operation=>operation.changes.some(change=>change.kind==='element'&&change.after?.data?.title==='Imported NDJSON node'))){importWriteSeen=true;await importGate;}
       assert.equal(request.headers['x-expected-account'], account); assert.equal(request.headers['idempotency-key'], batch.request_id);
+      // 拒绝指定下一编辑时同时模拟远程 b 文字改成 Remote reviewed；返回绑定原请求的 terminal 零写入证据。
       if(rejectNextEdit){rejectNextEdit=false;rejectedEdit=batch;const before=previous.elements.get('b');documents.set(write[1],applyChanges(previous,[{kind:'field',target:{id:'b',incarnation:1},field:'data.text',before:before.data.text,after:'Remote reviewed',beforePresent:true,afterPresent:true}]));versions.set(root,versions.get(root)+1);return reply(409,{protocol_version:2,request_id:batch.request_id,status:'not-applied',terminal:true,error:'version_conflict'});}
       for(const [id,version] of Object.entries(batch.expected_versions))assert.equal(version,versions.get(id)??0);
       let next = previous; for (const operation of batch.operations) next = applyChanges(next, operation.changes);
       documents.set(write[1], next);for(const id of Object.keys(batch.expected_versions))versions.set(id,(versions.get(id)??0)+1);
+      // 一次有序批次只把参与版本各推进一次，回执仍列出全部逻辑 operation IDs，供客户端覆盖检查。
       const receipt={ protocol_version: 2, request_id: batch.request_id, status: 'applied', operation_ids: batch.operations.map(operation => operation.id), model: model(next, false,Object.keys(batch.expected_versions)) };editReceipts.set(batch.request_id,receipt);return reply(200,receipt);
     }
+    // GET 查询原文档请求回执；查不到只给 unknown，不提供未执行证明。
     const editQuery=path.match(/\/canvas\/model\/operations\/([^/]+)$/);if(editQuery)return editReceipts.has(editQuery[1])?reply(200,editReceipts.get(editQuery[1])):reply(404,{request_id:editQuery[1],status:'unknown'});
     if(path.endsWith('/canvas/ai/models'))return reply(200,{models:[{id:'fixture-text',label:'Fixture text',available:true,input_modalities:['text'],output_modalities:['text']}]});
+    // AI 受理检查账户、幂等键、If-Match 和完整预期版本向量；先保存配置再冻结计划，不在受理时自动写生成文字。
     if(path.endsWith('/canvas/ai/runs')&&request.method==='POST'){
       const input=JSON.parse(bytes.toString()),owner=documents.get(root).elements.get(input.node_id).ownerCanvasId;assert.equal(request.headers['x-expected-account'],account);assert.equal(request.headers['idempotency-key'],input.request_id);assert.equal(request.headers['if-match'],'"'+versions.get(owner)+'"');assert.deepEqual(input.expected_versions,Object.fromEntries([...documents.get(root).canvases.keys()].map(id=>[id,versions.get(id)])));
       const previous=documents.get(root),element=previous.elements.get(input.node_id),next=applyChanges(previous,[{kind:'field',target:{id:element.id,incarnation:element.incarnation},field:'data.ai',before:element.data.ai??null,beforePresent:element.data.ai!==undefined,after:{enabled:true,modelId:input.model_id,prompt:input.prompt,parameters:input.parameters,propagate:input.propagate},afterPresent:true}]);documents.set(root,next);versions.set(owner,versions.get(owner)+1);
       const runId=id(700+aiRuns.size*10),plan={steps:[{step_id:'step-b',board_id:owner,node_id:input.node_id,canonical_root:root,target_incarnation:input.target_incarnation,kind:'text',model_id:input.model_id,status:'queued',dependencies:[],static_inputs:[]}],edges:[],frozen_versions:Object.fromEntries([...next.canvases.keys()].map(id=>[id,versions.get(id)]))};
+      // 受理以 202 返回任务/计划/目标 incarnation 及当前 owner 局部模型；事件初始只有 queued。
       const admitted={protocol_version:2,request_id:input.request_id,operation_id:input.operation_id,admission:'accepted',status:'queued',run_id:runId,plan,canvas_version:versions.get(owner),document_format_version:1,target_incarnation:input.target_incarnation,model:model(next,false,[owner])};
       aiRuns.set(runId,{status:'queued',plan,admitted,events:[{seq:1,run_id:runId,type:'run.queued',status:'queued'},{seq:2,run_id:runId,type:'step.queued',step_id:'step-b',board_id:owner,node_id:input.node_id,status:'queued'}]});return reply(202,admitted);
     }
     const aiAction=path.match(/\/canvas\/ai\/runs\/([^/]+)\/(cancel|apply)$/);
+    // 取消与应用回执均携带请求/操作/任务身份；取消只改控制状态，应用则检查当前 owner 与版本后修改文字。
     if(aiAction){
       const run=aiRuns.get(aiAction[1]),input=JSON.parse(bytes.toString()),base={protocol_version:2,request_id:input.request_id,operation_id:input.operation_id,action:'run.'+aiAction[2],status:'applied',run_id:aiAction[1]};
       assert.equal(request.headers['idempotency-key'],input.request_id);assert.equal(request.headers['x-expected-account'],account);
+      // 取消追加 completed(cancelled) 事件并立即回执，不经过 applyGate。
       if(aiAction[2]==='cancel'){run.status='cancelled';run.events.push({seq:run.events.length+1,run_id:aiAction[1],type:'run.completed',status:'cancelled'});return reply(200,{...base,run_status:'cancelled'});}
       const owner=documents.get(root).elements.get(input.node_id).ownerCanvasId;assert.equal(input.target_canvas_id,owner);assert.equal(input.target_incarnation,1);assert.equal(request.headers['if-match'],'"'+versions.get(owner)+'"');
       const output=run.events.find(event=>event.type==='step.output'&&event.output.output_id===input.output_id).output,previous=documents.get(root),element=previous.elements.get(input.node_id),next=applyChanges(previous,[{kind:'field',target:{id:element.id,incarnation:element.incarnation},field:'data.text',before:element.data.text,after:output.text,beforePresent:true,afterPresent:true}]);documents.set(root,next);versions.set(owner,versions.get(owner)+1);
+      // 应用输出先在服务模型中生效并追加 step.applied，再等待回执 gate，模拟成功已发生但客户端仍在途。
       const applied={...base,step_id:'step-b',board_id:owner,origin_board_id:run.plan.steps[0].board_id,canonical_root:root,node_id:input.node_id,output_id:input.output_id,document_format_version:1,target_incarnation:1,canvas_version:versions.get(owner),model:model(next,false,[owner])};run.events.push({...applied,seq:run.events.length+1,type:'step.applied'});await applyGate;return reply(200,applied);
     }
+    // 事件页按 after_seq 过滤，next_seq 为最后返回序号；此 fixture 一页返回全部剩余事件且无后续页。
     const aiPoll=path.match(/\/canvas\/ai\/runs\/([^/]+)$/);
     if(aiPoll){const run=aiRuns.get(aiPoll[1]),after=Number(url.searchParams.get('after_seq')||0),events=run.events.filter(event=>event.seq>after);return reply(200,{run_id:aiPoll[1],status:run.status,plan:run.plan,steps:[],events,next_seq:events.at(-1)?.seq??after,has_more:false,outputs:[]});}
+    // 用真实 Request.formData 解析代理送来的 multipart，按资源 ID 保存字节和元数据；等上传 gate 后才返回 201。
     if (path.endsWith('/assets') && request.method === 'POST') {
       const upload = new Request('http://fixture', { method: 'POST', body: bytes, headers: { 'Content-Type': request.headers['content-type'] } }), form = await upload.formData(), file = form.get('image');
       const asset = { id: request.headers['x-resource-id'], bytes: file.size, mime_type: 'image/png', width: 4, height: 2, url: `https://api.foundry.entroia.com/projects/endoleap/workspaces/${workspace}/assets/${request.headers['x-resource-id']}` };
@@ -110,24 +155,31 @@ const upstream = createServer(async (request, response) => {
       return reply(201, { protocol_version: 2, request_id: request.headers['idempotency-key'], status: 'applied', asset });
     }
     const assetMetadata=path.match(/\/assets\/metadata\/([^/]+)$/);
+    // 元数据可延迟/拒绝；成功时对真实上传字节算 SHA-256，给授权采用与导入检查使用。
     if(assetMetadata){if(metadataWait)await metadataWait;if(denyAssetMetadata||!assets.has(assetMetadata[1]))return reply(404,{error:'not_found'});const original=assetBytes.get(assetMetadata[1]),sha256=[...new Uint8Array(await crypto.subtle.digest('SHA-256',original))].map(n=>n.toString(16).padStart(2,'0')).join('');return reply(200,{metadata_version:1,asset:assets.get(assetMetadata[1]),sha256});}
+    // 普通资产显示路径返回固定 PNG，和上面的原始上传/摘要元数据检查属于不同证据。
     if (/\/assets\/[^/]+$/.test(path)) { response.writeHead(200, { 'Content-Type': 'image/png' }); return response.end(png); }
     reply(404, { error: 'not_found' });
   } catch (error) { response.writeHead(500, { 'Content-Type': 'application/json' }); response.end(JSON.stringify({ error: error.message })); }
 });
+// 先绑定本地上游，短暂监听器再为 Next 选端口；释放保留端口后才启动 Next，不是持续端口占用锁。
 await new Promise(resolve => upstream.listen(0, '127.0.0.1', resolve));
 const reserve = createServer(); await new Promise(resolve => reserve.listen(0, '127.0.0.1', resolve)); const port = reserve.address().port; await new Promise(resolve => reserve.close(resolve));
 let next, chrome, socket, logs = '';
 try {
+  // 所有源码插桩只写入临时副本，原仓库 src 不会被这些 replace 修改。
   await cp(join(source, 'src'), join(directory, 'src'), { recursive: true });
   await cp(join(source, 'public'), join(directory, 'public'), { recursive: true });
+  // baseline 模式只将 engine/scheduler/queries 替换为指定 commit 的文件，属于局部诊断对照。
   if(performanceMode&&baseline)for(const file of ['src/lib/canvas-runtime/engine.ts','src/lib/canvas-runtime/scheduler.ts','src/lib/canvas-core/queries.ts'])await writeFile(join(directory,file),execFileSync('git',['show',`${baseline}:${file}`],{cwd:source}));
+  // 堆诊断仅在临时 storage.commit 注入回执保留计数，记录 Root/文档/回执元素规模，不能直接当作完整保留堆分析。
   if(performanceMode&&process.env.HEADLESS_PERFORMANCE_HEAP==='1'){
     const file=join(directory,'src/lib/canvas-runtime/storage.ts'),text=await readFile(file,'utf8'),marker='async commit(leader: StorageLeader, batch: DurableBatch) {';assert.ok(text.includes(marker));await writeFile(file,text.replace(marker,marker+`const host=globalThis as typeof globalThis&{__fixtureReceiptRetention?:unknown};const payload=batch.image.payload as any;const receipts=payload.runtime?.receipts??[];const counts=receipts.map((row:any)=>Array.isArray(row[1]?.model?.elements)?row[1].model.elements.length:0);host.__fixtureReceiptRetention={rootRevision:batch.image.rootRevision,documentElements:payload.document?.elements?.length,receipts:receipts.length,modelElements:counts.reduce((a:number,b:number)=>a+b,0),maxModelElements:Math.max(0,...counts)};`));
   }
-  // Count delivered measurement batches in the isolated fixture only.
+  // 包装批量测量更新，记录每批 ID 数；assert 源码锚点存在，避免插桩未命中却继续报告。
   const internalsFile=join(directory,'src/lib/canvas-bindings/node-internals.ts'),internals=await readFile(internalsFile,'utf8');assert.ok(internals.includes('if(ids.size)update([...ids]);'));await writeFile(internalsFile,internals.replace('if(ids.size)update([...ids]);',`if(ids.size){const host=globalThis as typeof globalThis&{__fixtureInternalsBatches?:number[]};(host.__fixtureInternalsBatches??=[]).push(ids.size);update([...ids]);}`));
 
+  // 功能模式复制插件、hooks 与选择观察 fixture，并把组件接入临时页面；性能模式不装这些观察者。
   if(!performanceMode){
     await copyFile(join(source,'tests/headless/renderer-extension.tsx'),join(directory,'src/components/canvas/renderer-fixture.tsx'));
     await copyFile(join(source,'tests/headless/react-hooks-fixture.tsx'),join(directory,'src/components/canvas/hooks-fixture.tsx'));
@@ -135,22 +187,25 @@ try {
     const canvasFile=join(directory,'src/components/canvas/headless-graph-canvas.tsx'),canvasSource=await readFile(canvasFile,'utf8');
     await writeFile(canvasFile,canvasSource.replace('"use client";','"use client";\nimport {NativeSelectionFixture} from "./selection-listener-fixture";').replace('<Background variant=','<NativeSelectionFixture/><Background variant='));
 
-    // Count actual scene rebuilds in the isolated fixture copy; production has no diagnostic global.
+    // 只统计完整场景 rebuild；已有 patch 路径不计数，逐元素 projection 另外统计，避免混用两个指标。
     const sceneFile=join(directory,'src/lib/canvas-bindings/scene-projection.ts'),sceneSource=await readFile(sceneFile,'utf8');assert.ok(sceneSource.includes('const result=patched??projectCanvas('));await writeFile(sceneFile,sceneSource.replace('const result=patched??projectCanvas(',`const host=globalThis as typeof globalThis&{__fixtureSceneBuilds?:number};if(!patched)host.__fixtureSceneBuilds=(host.__fixtureSceneBuilds??0)+1;const result=patched??projectCanvas(`));
     const projectionFile=join(directory,'src/lib/canvas-bindings/projection.ts'),projectionSource=await readFile(projectionFile,'utf8');assert.ok(projectionSource.includes(':ProjectionNode{'));await writeFile(projectionFile,projectionSource.replace(':ProjectionNode{',`:ProjectionNode{const host=globalThis as typeof globalThis&{__fixtureProjectedNodes?:Record<string,number>};host.__fixtureProjectedNodes??={};host.__fixtureProjectedNodes[element.id]=(host.__fixtureProjectedNodes[element.id]??0)+1;`));
-    // Delay only the full-source Worker result in the isolated copy, independently of parser I/O.
+    // 摘要 gate 延迟的是 Worker 已算出的全源结果，独立于后续 GatedDocument 的 parser I/O 屏障。
     const digestFile=join(directory,'src/lib/canvas-runtime/browser-digests.ts'),digestSource=await readFile(digestFile,'utf8');assert.ok(digestSource.includes('else finish(undefined,value.sha256);'));await writeFile(digestFile,digestSource.replace('else finish(undefined,value.sha256);',`else {const host=globalThis as typeof globalThis&{__fixtureDigestGate?:Promise<void>;__fixtureDigestWaiting?:boolean};if(host.__fixtureDigestGate){host.__fixtureDigestWaiting=true;void host.__fixtureDigestGate.then(()=>finish(undefined,value.sha256));}else finish(undefined,value.sha256);}`));
-    // A fixture Host action exercises the public engine API; no debug entry point ships in the app.
+    // 通过临时 effect 暴露实际 engine 和公开 collectImportSources 动作；卸载时只清理同一注册函数。
     const importsFile=join(directory,'src/components/canvas/headless-imports.tsx'),importsSource=await readFile(importsFile,'utf8');
     await writeFile(importsFile,importsSource.replace('import { useCallback,','import { useEffect, useCallback,').replace('  const subscribe =',`  useEffect(()=>{const host=globalThis as typeof globalThis&{__headlessCollectSources?:()=>ReturnType<ProjectEngine['collectImportSources']>;__fixtureActualEngine?:ProjectEngine};const collect=()=>engine.collectImportSources({retentionMs:0});host.__headlessCollectSources=collect;host.__fixtureActualEngine=engine;return()=>{if(host.__headlessCollectSources===collect)delete host.__headlessCollectSources;};},[engine]);
   const subscribe =`));
+    // 在 Host 扩展装配点安装自定义 renderer 与 HookChecks，锚点改变则测试准备失败，不静默少测插件。
     const hostFile=join(directory,'src/components/workspace/canvas-runtime-host.tsx'),host=await readFile(hostFile,'utf8');assert.ok(host.includes('extensions=[]'),'host extension installation point changed');await writeFile(hostFile,host.replace('"use client";','"use client";\nimport {fixtureExtension} from "@/components/canvas/renderer-fixture";\nimport {HookChecks} from "@/components/canvas/hooks-fixture";').replace('extensions=[]','extensions=[fixtureExtension]').replace('{children}</Renderers.Provider>','{children}<HookChecks/></Renderers.Provider>'));
   }
 
+  // 临时应用沿用项目配置和 loader，再链接现有 node_modules，不另装依赖。
   for (const file of ['package.json', 'tsconfig.json', 'postcss.config.mjs', 'next.config.ts']) await copyFile(join(source, file), join(directory, file));
   await cp(join(source,'scripts/loaders'),join(directory,'scripts/loaders'),{recursive:true});
   if(!performanceMode){
     const loaderFile=join(directory,'scripts/loaders/xyflow-retained.cjs');
+    // 附加 loader 包装统计 ReactFlow 原生选择 selector 扫描次数；字符串写入临时 loader，不影响产品构建。
     const instrument=`
 const nativeTransform=module.exports;
 module.exports=function(source){return nativeTransform.call(this,source).replace('const selector$l = (s) => {','const selector$l = (s) => { globalThis.__fixtureSelectionScans=(globalThis.__fixtureSelectionScans??0)+1;');};
@@ -159,50 +214,64 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   }
 
   await symlink(join(source, 'node_modules'), join(directory, 'node_modules'));
+  // 统一 Next 子进程启动和日志尾部收集；独立进程组供 finally 一并终止，API origin 指向本次上游。
   const launchNext=args=>{
     const child=spawn(process.execPath,[join(source,'node_modules/next/dist/bin/next'),...args],{cwd:directory,detached:true,env:{...process.env,NEXT_TELEMETRY_DISABLED:'1',FOUNDRY_API_ORIGIN:`http://127.0.0.1:${upstream.address().port}`,NEXT_PUBLIC_FOUNDRY_PROJECT:'endoleap'},stdio:['ignore','pipe','pipe']});
     child.stdout.on('data',chunk=>{logs=(logs+chunk).slice(-16000);});child.stderr.on('data',chunk=>{logs=(logs+chunk).slice(-16000);});return child;
   };
   let buildMs;
+  // 生产性能入口先完成 Next build 并记录耗时，非零退出立即失败；其他入口用 dev，仍可能触发页面编译。
   if(productionMode){
     console.log('BUILD production fixture');const started=Date.now();next=launchNext(['build',`--${bundler}`]);
     await new Promise((resolve,reject)=>{next.once('error',reject);next.once('exit',(code,signal)=>code===0?resolve():reject(Error(`production fixture build failed (${code??signal})\n${logs}`)));});
     buildMs=Date.now()-started;console.log(`BUILD complete ${buildMs} ms`);
   }
   next=launchNext([productionMode?'start':'dev',...productionMode?[]:[`--${bundler}`],'--hostname','127.0.0.1','--port',String(port)]);
+  // 有界探测真实代理 profile，并检查 Next 提前退出；后续页面等待还会验证应用是否实际可用。
   for (let i = 0; i < 120; i++) { if (next.exitCode !== null) throw new Error(logs); try { const r = await fetch(`http://127.0.0.1:${port}/api/foundry/profile`, { signal: AbortSignal.timeout(1000) }); if (r.ok) break; } catch {} await pause(250); }
+  // 只保留本次隔离 Chrome 的日志尾部，CHROME_BIN 可覆盖可执行路径，不连接日常 profile。
   let browserLogs='';
   chrome = spawn(process.env.CHROME_BIN ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', ['--headless=new', '--no-first-run', '--disable-background-networking', '--disable-component-update', '--remote-debugging-port=0', `--user-data-dir=${profile}`, 'about:blank'], { stdio: ['ignore','ignore','pipe'] });
   chrome.stderr.on('data',chunk=>{browserLogs=(browserLogs+chunk).slice(-16000);});
+  // 从本次 profile 的 DevToolsActivePort 发现调试端口，失败则不继续浏览器命令。
   let debugPort;
   for (let i = 0; i < 100; i++) { try { debugPort = Number((await readFile(join(profile, 'DevToolsActivePort'), 'utf8')).split('\n')[0]); break; } catch { await pause(100); } }
   assert.ok(debugPort, 'Chrome did not start');
   const tabs = await fetch(`http://127.0.0.1:${debugPort}/json/list`).then(response => response.json());
   socket = new WebSocket(tabs.find(tab => tab.type === 'page').webSocketDebuggerUrl); await new Promise((resolve, reject) => { socket.onopen = resolve; socket.onerror = reject; });
   const exceptions=[];
+  // 使用有截止时间的共享 CDP 调用器；收集页面异常与 fatal 事件，便于失败时定位。
   const call=createCdpCalls(socket,{onEvent(message){if(['Inspector.targetCrashed','Target.targetCrashed','Inspector.detached','Page.javascriptDialogOpening'].includes(message.method))browserLogs=(browserLogs+'\nCDP '+JSON.stringify(message)).slice(-16000);if(message.method==='Runtime.consoleAPICalled'&&message.params.type==='error')console.log('BROWSER ERROR',message.params.args.map(arg=>arg.description??arg.value).join(' '));if(message.method==='Runtime.exceptionThrown')exceptions.push(message.params.exceptionDetails.exception?.description??message.params.exceptionDetails.text);}});
+  // 页面表达式等待 Promise 并按值返回；exceptionDetails 直接转换为测试失败。
   const evaluate = async expression => { const r = await call('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }); if (r.exceptionDetails) throw new Error(r.exceptionDetails.exception?.description ?? r.exceptionDetails.text); return r.result?.value; };
+  // 最多 200 轮条件检查，先检查页面异常，每轮约隔 100ms；失败附作业摘要、页面文本和 Next 日志，整体等待仍包含各 CDP 调用耗时。
   async function until(expression, label) { for (let i = 0; i < 200; i++) { if (exceptions.length) throw new Error(exceptions.join('\n')); if (await evaluate(expression)) return; await pause(100); } throw new Error(label + '\n' + JSON.stringify(await evaluate(`[...window.__fixtureActualEngine?.imports.getJobs().values()??[]].map(job=>({id:job.id,status:job.status,error:job.error,sourceError:job.source?.integrityError}))`)) + '\n' + await evaluate('document.body.innerText') + '\n' + logs); }
+  // 启用页面/异常事件并固定 1280×900 视口，减少交互坐标和虚拟化断言随屏幕环境漂移。
   await call('Runtime.enable');await call('Page.enable');await call('Target.setDiscoverTargets',{discover:true}); await call('Emulation.setDeviceMetricsOverride', { width: 1280, height: 900, deviceScaleFactor: 1, mobile: false });
   const route = `http://127.0.0.1:${port}/dashboard/${workspace}/${migrationFixture?.states[0].root??root}`;
   await call('Page.navigate', { url: route });
+  // 按模式选择性能、迁移、hooks 或完整交互；每条专用入口成功后都回到公共 finally 清理。
   if(performanceMode){
     await measureRenderer({call,evaluate,documents,calls,root,partition,count:performanceCount,exceptions,browserLogs:()=>browserLogs,baseline,buildMode:productionMode?'production':'development',bundler,buildMs,reportPath:process.env.HEADLESS_PERFORMANCE_REPORT??join(tmpdir(),'headless-renderer-performance.json')});
   }else if(migrationOnly){await verifyRendererMigration({fixture:migrationFixture,call,evaluate,until,port,workspace,account,pause});
   }else if(hooksOnly){await until('typeof window.__runCanvasHookChecks==="function"','hook fixture did not mount');const reports=await evaluate('window.__runCanvasHookChecks()');for(const report of reports)console.log('PASS React hooks: '+report);
   }else{
+  // 完整交互先要求首个元素在尾部 gate 前可编辑，b 尚不存在、创建工具禁用且没有文档 POST。
   await until('!!document.querySelector("[data-headless-canvas][data-model-loading] .react-flow__node[data-id=a]")','first editable model prefix did not open before the gated tail');
   assert.equal(await evaluate('!!document.querySelector(".react-flow__node[data-id=b]")'),false);
   assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/model/operations')).length,0);
   assert.equal(await evaluate('document.querySelector("[aria-label=添加文本卡片]").disabled'),true);
   await until('document.querySelector(".react-flow__node[data-id=a]").getBoundingClientRect().x>300','initial partial node remained under the sidebar');
+  // 使用 CDP 原生双击进入已载入文本，输入 partial-local；来源还不完整时不能发送文档请求。
   const partialTextPoint=await evaluate(`(()=>{const r=document.querySelector('.react-flow__node[data-id=a] [aria-label^="单击选中"]').getBoundingClientRect();return{x:r.x+60,y:r.y+30};})()`);
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...partialTextPoint,button:'left',buttons:1,clickCount:2});await call('Input.dispatchMouseEvent',{type:'mouseReleased',...partialTextPoint,button:'left',buttons:0,clickCount:2});
   await until(`document.activeElement===document.querySelector('.react-flow__node[data-id=a] textarea')&&!document.activeElement.readOnly`,'loaded prefix text did not enter edit mode');
   await call('Input.insertText',{text:' partial-local'});const partialText=await evaluate('document.activeElement.value');assert.ok(partialText.endsWith(' partial-local'));assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/model/operations')).length,0);
   await evaluate(`window.partialTextarea=document.activeElement;void 0`);
+  // 捕获同一个 textarea 和 viewport 后放行来源，完成不得替换焦点 DOM 或重置视口。
   const previewTransform=await evaluate('document.querySelector("[data-headless-canvas] .react-flow__viewport").style.transform');
   await writeFile('/private/tmp/headless-loading-editable.png',Buffer.from((await call('Page.captureScreenshot',{format:'png'})).data,'base64'));
+  // 只有这里才放行首读尾部；随后核对服务文字和 undo，证明前缀编辑的历史继续可用。
   releaseFirstModel();
   await until('!!document.querySelector("[data-headless-canvas]:not([data-model-loading])") && document.querySelectorAll(".react-flow__node").length === 2','full model did not finish the partial editor');
   assert.equal(await evaluate('window.partialTextarea.isConnected&&document.activeElement===window.partialTextarea'),true,'tail completion remounted the active text editor');
@@ -211,11 +280,13 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   await call('Input.dispatchKeyEvent',{type:'keyDown',key:'Escape',code:'Escape',windowsVirtualKeyCode:27});await call('Input.dispatchKeyEvent',{type:'keyUp',key:'Escape',code:'Escape',windowsVirtualKeyCode:27});
   await evaluate(`document.querySelector('[aria-label="撤销"]').click()`);for(let i=0;i<100&&documents.get(root).elements.get('a').data.text!=='Editable content';i++)await pause(20);assert.equal(documents.get(root).elements.get('a').data.text,'Editable content');
   console.log('PASS actual GraphPage edits the first prefix before the gated tail, keeps its active textarea/history/viewport and sends only after durable completion');
+  // 启用原生选择监听后改选 b，停用时事件数和 selector 扫描数都应冻结，再启用后继续收到事件。
   await until('!!window.__fixtureNativeSelection','native selection fixture did not mount');
   await evaluate('window.__priorNativeSelection=window.__fixtureNativeSelection.selected();window.__fixtureNativeSelection.enable(true);new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
   await evaluate('window.__fixtureNativeSelection.select(["b"]);true');await until('window.__fixtureNativeSelectionEvents.at(-1)?.nodes.join() === "b"','native selection hook missed its selected node');
   await evaluate('window.__fixtureNativeSelection.enable(false);new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
   const unsubscribedSelectionEvents=await evaluate('window.__fixtureNativeSelectionEvents.length');
+  // 实际扫描计数必须先大于零，避免“从未装上监听器”也通过卸载后零变化的检查。
   const subscribedSelectionScans=await evaluate('window.__fixtureSelectionScans??0');assert.ok(subscribedSelectionScans>0,'native scan instrumentation did not observe the active hook');
   await evaluate('window.__fixtureNativeSelection.select(["a"]);new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');assert.equal(await evaluate('window.__fixtureNativeSelectionEvents.length'),unsubscribedSelectionEvents,'native selection hook fired after unsubscription');assert.equal(await evaluate('window.__fixtureSelectionScans??0'),subscribedSelectionScans,'unsubscribed native selection still scanned the graph');
   await evaluate('window.__fixtureNativeSelection.enable(true);new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
@@ -227,10 +298,13 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
 
   assert.equal(calls.some(call => call.path.endsWith('/canvas')), false, 'canonical project read the legacy snapshot');
   assert.equal(await evaluate('!!document.querySelector("[aria-label=画布快捷操作]") && !document.querySelector("[aria-label=展开侧边栏]")'), true);
+  // 按钮辅助函数走实际页面 click；下一个键盘脚本只检查事件是否被 canvas 声明消费。
   const click = label => evaluate(`document.querySelector('[aria-label=${JSON.stringify(label)}]').click()`);
+  // Ctrl/Meta、IME 组合态和未知键不被抢占，普通 h/v 工具快捷键应 preventDefault。
   assert.deepEqual(await evaluate(`(()=>{const canvas=document.querySelector('[data-headless-canvas]');const fire=(key,options={})=>{const e=new KeyboardEvent('keydown',{key,bubbles:true,cancelable:true,...options});canvas.dispatchEvent(e);return e.defaultPrevented;};return [fire('h',{ctrlKey:true}),fire('v',{metaKey:true}),fire('h',{isComposing:true}),fire('F9'),fire('h'),fire('v')];})()`),[false,false,false,false,true,true]);
   console.log('PASS canvas keyboard routing leaves modifiers, IME and unknown keys unclaimed and consumes plain tool shortcuts');
 
+  // 创建、undo、redo 同时核对 DOM 节点数与 fixture 文档元素数，后者还含原连线，不能直接把两种计数混用。
   await click('添加文本卡片'); await until('document.querySelectorAll(".react-flow__node").length === 3', 'create did not render');
   for (let i = 0; i < 100 && documents.get(root).elements.size !== 4; i++) await pause(20);
   assert.equal(documents.get(root).elements.size, 4);
@@ -239,15 +313,18 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   assert.equal(documents.get(root).elements.size, 3);
   await click('重做'); await until('document.querySelectorAll(".react-flow__node").length === 3', 'redo did not render');
   for (let i = 0; i < 100 && documents.get(root).elements.size !== 4; i++) await pause(20);
+  // 记录拖动前文档请求数，并在页面收集原生 pointer/mouse/capture 事件供失败诊断。
   const beforeDrag = calls.filter(call => call.method === 'POST' && call.path.endsWith('/model/operations')).length;
   await evaluate(`window.inputEvents=[];for(const type of ['pointerdown','mousedown','pointerup','mouseup','pointercancel','lostpointercapture'])window.addEventListener(type,event=>window.inputEvents.push({type,x:event.clientX,y:event.clientY,target:event.target.outerHTML?.slice(0,120)}),true);`);
   const rect = await evaluate('(()=>{const r=document.querySelector(".react-flow__node[data-id=b]").getBoundingClientRect();return {x:r.x+80,y:r.y+30}})()');
   await call('Input.dispatchMouseEvent', { type: 'mousePressed', x: rect.x, y: rect.y, button: 'left', buttons: 1, clickCount: 1 });
+  // 十帧 pointer move 只更新预览，释放时只允许一个文档请求，最终位置以 pointerup 坐标为准。
   for (let step = 1; step <= 10; step++) await call('Input.dispatchMouseEvent', { type: 'mouseMoved', x: rect.x + step * 5, y: rect.y + step * 3, button: 'left', buttons: 1 });
   await call('Input.dispatchMouseEvent', { type: 'mouseReleased', x: rect.x + 50, y: rect.y + 30, button: 'left', buttons: 0 });
   for (let i = 0; i < 100 && documents.get(root).elements.get('b').geometry.x === 450; i++) await pause(20);
   assert.ok(Math.abs(documents.get(root).elements.get('b').geometry.x - 500) < 1, JSON.stringify({ geometry: documents.get(root).elements.get('b').geometry, rect, writes: calls.filter(call => call.path.endsWith('/model/operations')).map(call => JSON.parse(call.bytes.toString()).operations), inputs: await evaluate('window.inputEvents'), text: await evaluate('document.body.innerText') }));
   assert.equal(calls.filter(call => call.method === 'POST' && call.path.endsWith('/model/operations')).length, beforeDrag + 1, 'pointer frames became document requests');
+  // 再次移动后用 Escape 取消，再发送迟到 mouseReleased；服务几何和请求数都不能变化。
   const beforeCancel = calls.filter(call => call.method === 'POST' && call.path.endsWith('/model/operations')).length;
   const moved = await evaluate('(()=>{const r=document.querySelector(".react-flow__node[data-id=b]").getBoundingClientRect();return {x:r.x+80,y:r.y+30}})()');
   await call('Input.dispatchMouseEvent', { type: 'mousePressed', x: moved.x, y: moved.y, button: 'left', buttons: 1, clickCount: 1 });
@@ -256,6 +333,7 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   await call('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 });
   await call('Input.dispatchMouseEvent', { type: 'mouseReleased', x: moved.x + 35, y: moved.y + 25, button: 'left', buttons: 0 });
   await pause(100); assert.equal(documents.get(root).elements.get('b').geometry.x, 500); assert.equal(calls.filter(call => call.method === 'POST' && call.path.endsWith('/model/operations')).length, beforeCancel);
+  // 拖动中切 H/pan 也必须取消所属预览；后来的 pointerup 不能提交，V 恢复选择工具及已提交位置。
   const toolPoint=await evaluate(`(()=>{const r=document.querySelector('.react-flow__node[data-id=b]').getBoundingClientRect();return {x:r.x+80,y:r.y+30}})()`);
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...toolPoint,button:'left',buttons:1,clickCount:1});
   await call('Input.dispatchMouseEvent',{type:'mouseMoved',x:toolPoint.x+35,y:toolPoint.y+25,button:'left',buttons:1});
@@ -270,6 +348,7 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   await until(`document.querySelector('[aria-label="选择工具（V）"]')?.getAttribute('aria-pressed')==='true'`,'selection tool did not render');
   await until(`(()=>{const n=document.querySelector('.react-flow__node[data-id=b]'),m=new DOMMatrix(n.style.transform);return Math.abs(m.m41-500)<.01&&!n.classList.contains('dragging');})()`,'canceled native node did not return to its committed position');
   console.log('PASS actual drag-to-pan tool switch cancels preview and late pointerup produces no document request');
+  // 用实际 resize handle 开始缩放，期间合成 foreign pointerId=999 事件，不能提交或取消当前手势。
   const corner = await evaluate(`(()=>{const r=document.querySelector('.react-flow__node[data-id=b] [aria-label="拖动右下角调整大小"]').getBoundingClientRect();return {x:r.x+r.width/2,y:r.y+r.height/2}})()`);
   await call('Input.dispatchMouseEvent', { type: 'mousePressed', x: corner.x, y: corner.y, button: 'left', buttons: 1, clickCount: 1 });
   await call('Input.dispatchMouseEvent', { type: 'mouseMoved', x: corner.x + 20, y: corner.y + 10, button: 'left', buttons: 1 });
@@ -279,10 +358,12 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   for (let i=0;i<100&&documents.get(root).elements.get('b').geometry.width!==300;i++)await pause(20);
   assert.equal(documents.get(root).elements.get('b').geometry.width,300,JSON.stringify({geometry:documents.get(root).elements.get('b').geometry,inputs:await evaluate('window.inputEvents'),text:await evaluate('document.body.innerText')}));assert.equal(documents.get(root).elements.get('b').geometry.height,220);
   assert.equal(calls.filter(call => call.method === 'POST' && call.path.endsWith('/model/operations')).length, beforeCancel+1);
+  // resize 模式 Escape 分三种：原生 select 内、子控件已 preventDefault、工具栏自身；只有未被控件接管的工具栏 Escape 清理模式。
   await click('八向拉伸模式');await until(`document.querySelector('[data-resize-toggle="b"]')?.getAttribute('aria-pressed')==='true'`,'resize mode did not open');
   await evaluate(`document.querySelector('[data-node-style="b"] select').dispatchEvent(new KeyboardEvent('keydown',{key:'Escape',bubbles:true,cancelable:true}))`);await pause(50);assert.equal(await evaluate(`document.querySelector('[data-resize-toggle="b"]').getAttribute('aria-pressed')`),'true','native selector Escape dismissed the canvas mode');
   await evaluate(`(()=>{const button=document.querySelector('[data-resize-toggle="b"]');button.addEventListener('keydown',event=>event.preventDefault(),{once:true});button.dispatchEvent(new KeyboardEvent('keydown',{key:'Escape',bubbles:true,cancelable:true}));})()`);await pause(50);assert.equal(await evaluate(`document.querySelector('[data-resize-toggle="b"]').getAttribute('aria-pressed')`),'true','toolbar ignored a child control that had claimed Escape');
   await evaluate(`document.querySelector('[data-resize-toggle="b"]').dispatchEvent(new KeyboardEvent('keydown',{key:'Escape',bubbles:true,cancelable:true}))`);await until(`(()=>{const node=document.querySelector('.react-flow__node[data-id=b]');return !!node&&[...window.__fixtureActualEngine.sessions.getSnapshot().views.values()].every(view=>view.modes.get('b')!=='resize')&&!node.querySelector('[data-resize-handle]')&&!document.querySelector('[data-resize-toggle="b"][aria-pressed="true"]');})()`,'toolbar did not dismiss its own resize mode').catch(async error=>{console.log('MODE DIAGNOSTIC',await evaluate(`JSON.stringify({views:[...window.__fixtureActualEngine.sessions.getSnapshot().views.values()].map(view=>({id:view.id,modes:[...view.modes]})),buttons:[...document.querySelectorAll('[data-resize-toggle="b"]')].map(node=>({pressed:node.getAttribute('aria-pressed'),html:node.outerHTML})),target:document.querySelector('.react-flow__node[data-id=b]')?.outerHTML.slice(0,1500)})`));throw error;});
+  // 真实双击进入文本，IME 组合再提交中文；undo 应只撤销该输入，不回退此前已提交的缩放。
   const textPoint = await evaluate(`(()=>{const r=document.querySelector('.react-flow__node[data-id=b] [aria-label^="单击选中"]').getBoundingClientRect();return {x:r.x+60,y:r.y+30}})()`);
   await call('Input.dispatchMouseEvent', { type: 'mousePressed', ...textPoint, button: 'left', buttons: 1, clickCount: 2 });
   await call('Input.dispatchMouseEvent', { type: 'mouseReleased', ...textPoint, button: 'left', buttons: 0, clickCount: 2 });
@@ -298,15 +379,17 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   assert.equal(documents.get(root).elements.get('b').data.text,'Editable content');assert.equal(documents.get(root).elements.get('b').geometry.width,300);
   await until(`[...document.querySelectorAll('[data-headless-canvas] [role="status"]')].some(element=>element.textContent.trim()==='已同步')`,'edits did not settle before hit-test');
   await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
-  // Hit from the pane beyond the native edge interaction stroke, using screen-space tolerance.
+  // 沿可见曲线法线寻找落在 pane 的点，特意避开节点并超出原生 SVG 交互 stroke，检验屏幕容差命中。
   const nearCurve=await evaluate(`(()=>{const path=document.querySelector('.react-flow__edge[data-id="edge"] .react-flow__edge-path');if(!path)return null;const length=path.getTotalLength(),matrix=path.getScreenCTM();for(let t=.1;t<.99;t+=.01){const a=path.getPointAtLength(length*t),b=path.getPointAtLength(length*t+1),p=new DOMPoint(a.x,a.y).matrixTransform(matrix),q=new DOMPoint(b.x,b.y).matrixTransform(matrix),dx=q.x-p.x,dy=q.y-p.y,d=Math.hypot(dx,dy);for(const sign of [-1,1]){const x=p.x-sign*dy/d*11,y=p.y+sign*dx/d*11;if(document.elementFromPoint(x,y)?.classList.contains('react-flow__pane')&&![...document.querySelectorAll('.react-flow__node')].some(node=>{const r=node.getBoundingClientRect();return x>=r.left-13&&x<=r.right+13&&y>=r.top-13&&y<=r.bottom+13;}))return{x,y};}}return null;})()`);
   assert.ok(nearCurve,'no pane point beyond the SVG interaction stroke');
+  // 边命中是只读选择：出现曲线控制点但不得产生文档 operation。
   const beforeHit=calls.filter(call=>call.method==='POST'&&call.path.endsWith('/model/operations')).length;
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...nearCurve,button:'left',buttons:1,clickCount:1});
   await call('Input.dispatchMouseEvent',{type:'mouseReleased',...nearCurve,button:'left',buttons:0,clickCount:1});
   await until(`!!document.querySelector('[aria-label="曲线点 1"]')`,'pane near-curve hit did not select the edge');
   assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/model/operations')).length,beforeHit,'read-only hit query created a document operation');
   console.log('PASS screen-tolerance pane hit selects the displayed curve beyond native SVG stroke without a model operation');
+  // 重叠区域控制点仍需可命中，拖动末坐标保存为 (440,265)，整个曲线手势只新增一次请求。
   const curveHandle=await evaluate(`(()=>{const r=document.querySelector('[aria-label="曲线点 1"]').getBoundingClientRect();return{x:r.x+r.width/2,y:r.y+r.height/2};})()`);
   assert.equal(await evaluate(`document.elementFromPoint(${curveHandle.x},${curveHandle.y})?.getAttribute('aria-label')`),'曲线点 1','selected curve control must remain hit-testable where a card overlaps');
   const beforeCurve = calls.filter(call => call.method === 'POST' && call.path.endsWith('/model/operations')).length;
@@ -320,6 +403,7 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   await call('Input.dispatchMouseEvent',{type:'mousePressed',x:1050,y:650,button:'left',buttons:1,clickCount:1});await call('Input.dispatchMouseEvent',{type:'mouseReleased',x:1050,y:650,button:'left',buttons:0,clickCount:1});await pause(50);
   await until(`[...document.querySelectorAll('[data-headless-canvas] [role="status"]')].some(element=>element.textContent.trim()==='已同步')`,'curve edit did not settle before opening recovery editor');
   await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+  // 在 b 的实际可见 label 中扫描 elementFromPoint，找未被遮挡的原生双击位置，避免脚本 focus 跳过页面编辑流程。
   const recoveryPoint=await evaluate(`(()=>{const label=document.querySelector('.react-flow__node[data-id=b] [aria-label^="单击选中"]'),r=label.getBoundingClientRect();
     for(let y=Math.max(0,r.top)+8;y<Math.min(innerHeight,r.bottom);y+=8)for(let x=Math.max(0,r.left)+8;x<Math.min(innerWidth,r.right);x+=8)
       if(label.contains(document.elementFromPoint(x,y)))return{x,y};
@@ -327,57 +411,77 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   })()`);
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...recoveryPoint,button:'left',buttons:1,clickCount:2});await call('Input.dispatchMouseEvent',{type:'mouseReleased',...recoveryPoint,button:'left',buttons:0,clickCount:2});
   await until(`document.activeElement===document.querySelector('.react-flow__node[data-id=b] textarea')&&!document.activeElement.readOnly`,'recovery edit did not open');
+  // 下一写入明确拒绝并由 fixture 改出远程值；本地文字保留，页面应显示可进入恢复的动作。
   rejectNextEdit=true;await call('Input.insertText',{text:'Local recovery'});await until(`!!document.querySelector('[aria-label="处理同步修改"]')`,'rejected content did not expose recovery');
+  // 保存本地候选文字和原 rejected requestId；恢复选择必须呈现 Remote reviewed 作为用户审阅基线。
   const localRecoveryText=await evaluate(`document.querySelector('.react-flow__node[data-id=b] textarea').value`),rejectedId=rejectedEdit.request_id;
   await click('处理同步修改');await until(`!!document.querySelector('select[aria-label="处理第1项修改"]')`,'recovery choices did not load');
   assert.ok(await evaluate(`document.querySelector('[role=dialog]').innerText.includes('Remote reviewed')`),'review omitted the server value');
   await evaluate(`(()=>{const select=document.querySelector('select[aria-label="处理第1项修改"]');select.value='keep-local';select.dispatchEvent(new Event('change',{bubbles:true}));})()`);
+  // 选择 keep-local 后先预览，按钮可用才 apply；等待对话框关闭与服务端新内容，不用 UI 关闭代替数据核对。
   await click('预览处理方案');await until(`!document.querySelector('[aria-label="应用处理方案"]').disabled`,'reviewed recovery plan did not become applicable');await click('应用处理方案');
   await until(`!document.querySelector('[role=dialog]')`,'recovery dialog did not close after persistence');
   for(let i=0;i<100&&documents.get(root).elements.get('b').data.text!==localRecoveryText;i++)await pause(20);assert.equal(documents.get(root).elements.get('b').data.text,localRecoveryText);
+  // 替代请求必须有新 requestId/operationId，条件 before 是已审阅远程值；下一次 undo 也必须回到这个远程基线。
   const recompiled=calls.filter(call=>call.method==='POST'&&call.path.endsWith('/model/operations')).at(-1),recompiledBody=JSON.parse(recompiled.bytes.toString());assert.notEqual(recompiledBody.request_id,rejectedId);assert.notEqual(recompiledBody.operations[0].id,rejectedEdit.operations[0].id);assert.equal(recompiledBody.operations[0].changes[0].before,'Remote reviewed');
   await click('撤销');for(let i=0;i<100&&documents.get(root).elements.get('b').data.text!=='Remote reviewed';i++)await pause(20);assert.equal(documents.get(root).elements.get('b').data.text,'Remote reviewed');
   console.log('PASS actual recovery dialog reviews remote/local content, recompiles with new identities, saves before dispatch and preserves the reviewed undo baseline');
+  // 改测结构创建拒绝：界面要标明创建元素和关联结构变更，应用后保留该新元素的撤销能力。
   rejectNextEdit=true;await click('添加文本卡片');await until(`!!document.querySelector('[aria-label="处理同步修改"]')`,'rejected creation did not expose recovery');const createdId=rejectedEdit.operations[0].changes.find(change=>change.kind==='element'&&change.before===null).id;
   await click('处理同步修改');await until(`!!document.querySelector('select[aria-label="处理第1项修改"]')&&document.querySelector('[role=dialog]').innerText.includes('创建元素')`,'creation review omitted the structural change');
   await evaluate(`(()=>{const select=document.querySelector('select[aria-label="处理第1项修改"]');select.value='keep-local';select.dispatchEvent(new Event('change',{bubbles:true}));})()`);await click('预览处理方案');await until(`document.querySelector('[role=dialog]').innerText.includes('关联结构变更')&&!document.querySelector('[aria-label="应用处理方案"]').disabled`,'structural plan did not expose related changes');await click('应用处理方案');await until(`!document.querySelector('[role=dialog]')`,'structural review did not finish');for(let i=0;i<100&&!documents.get(root).elements.has(createdId);i++)await pause(20);assert.ok(documents.get(root).elements.has(createdId));rejectNextEdit=true;await click('撤销');await until(`!!document.querySelector('[aria-label="处理同步修改"]')`,'rejected undo did not expose recovery');
+  // 再拒绝该创建的 undo，恢复文案要识别为未同步撤销，选择保留撤销而不是重新创建普通内容操作。
   await click('处理同步修改');await until(`!!document.querySelector('select[aria-label="处理第1项修改"]')&&document.querySelector('[role=dialog]').innerText.includes('未同步的撤销')`,'undo review did not identify the history action');assert.ok(await evaluate(`document.querySelector('select[aria-label="处理第1项修改"]').innerText.includes('保留这次撤销')`));
   await evaluate(`(()=>{const select=document.querySelector('select[aria-label="处理第1项修改"]');select.value='keep-local';select.dispatchEvent(new Event('change',{bubbles:true}));})()`);await click('预览处理方案');await until(`document.querySelector('[role=dialog]').innerText.includes('重做记录由')&&!document.querySelector('[aria-label="应用处理方案"]').disabled`,'undo recovery omitted its redo stack');await click('应用处理方案');await until(`!document.querySelector('[role=dialog]')`,'undo recovery did not finish');for(let i=0;i<100&&documents.get(root).elements.has(createdId);i++)await pause(20);assert.equal(documents.get(root).elements.has(createdId),false);
+  // 恢复撤销后 redo 以第二代还原，再 undo 删除；检查的是栈方向和生命期，不只是节点是否存在。
   await click('重做');for(let i=0;i<100&&!documents.get(root).elements.has(createdId);i++)await pause(20);assert.equal(documents.get(root).elements.get(createdId).incarnation,2);await click('撤销');for(let i=0;i<100&&documents.get(root).elements.has(createdId);i++)await pause(20);assert.equal(documents.get(root).elements.has(createdId),false);
   console.log('PASS actual rejected undo review labels the traversal, previews both stacks, replans deletion and retains redo with a new lifecycle');
   console.log('PASS actual structural recovery dialog reviews a rejected creation and related changes, applies it with a new identity and retains undo');
+  // 辅助动作先原生点击空白清选择，再选 b 下缘并等 AI 工具可用；避免复用上个场景的选中状态。
   const selectB=async()=>{await call('Input.dispatchMouseEvent',{type:'mousePressed',x:1050,y:650,button:'left',buttons:1,clickCount:1});await call('Input.dispatchMouseEvent',{type:'mouseReleased',x:1050,y:650,button:'left',buttons:0,clickCount:1});await pause(50);const point=await evaluate(`(()=>{const r=document.querySelector('.react-flow__node[data-id=b]').getBoundingClientRect();return {x:r.x+r.width/2,y:r.y+r.height-30}})()`);await call('Input.dispatchMouseEvent',{type:'mousePressed',...point,button:'left',buttons:1,clickCount:1});await call('Input.dispatchMouseEvent',{type:'mouseReleased',...point,button:'left',buttons:0,clickCount:1});await until(`!document.querySelector('[aria-label="AI 创作"]').disabled`,'AI tool did not accept the selected element');};
+  // 从实际 AI 面板读取 fixture 模型，设置 prompt 后执行；受理可见时服务只应创建一个任务。
   await selectB();await click('AI 创作');await until(`!!document.querySelector('[aria-label="AI 模型"] option[value="fixture-text"]')`,'AI catalog did not load through the host');
   await evaluate(`(()=>{const input=document.querySelector('[aria-label="AI 指令"]');Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype,'value').set.call(input,'Summarize this content');input.dispatchEvent(new Event('input',{bubbles:true}));})()`);
   await until(`!document.querySelector('[aria-label="执行 AI"]').disabled`,'AI command did not become executable');await click('执行 AI');
   await until(`document.body.innerText.includes('已受理')`,'AI admission did not persist');assert.equal(aiRuns.size,1);
+  // 记录 CSS zoom、内容宽高和字号，后续比较这些具体样式值；没有在此做完整像素或全部排版属性的等价检查。
   const visualMetric=`(()=>{const node=document.querySelector('.react-flow__node[data-id=b]'),frame=[...node.querySelectorAll('div')].find(element=>element.style.zoom);return {zoom:frame.style.zoom,width:frame.style.width,height:frame.style.height,font:getComputedStyle(node.querySelector('textarea')).fontSize}})()`,beforeVisual=await evaluate(visualMetric);
   await evaluate(`document.querySelector('a[href="/dashboard/${workspace}/${other}"]').click()`);await until(`location.pathname.endsWith('${other}')&&document.querySelectorAll('.react-flow__node').length===0`,'AI view detach failed');
+  // 导航到另一个项目后，由 fixture 在根项目创建缩放分区并移动 b，保留其元素身份，再追加生成结果事件。
   const run=aiRuns.get(id(700)),beforeAI=documents.get(root),beforeNode=beforeAI.elements.get('b');
   const frame={...node('relocation-frame',root,30),componentId:'frame',geometry:{x:30,y:50,width:1000,height:600,rotation:0},data:{title:'Relocated partition',text:'',presentation:{contentScale:2}}};
+  // 按新 owner 的局部坐标换算几何并写 unitScale=.5；这是测试准备的已知变换，不由浏览器拖拽自动产生。
   const movedModel=applyChanges(beforeAI,[{kind:'element',id:frame.id,before:null,after:frame},{kind:'canvas',id:partition,before:null,after:{id:partition,parent:{canvasId:root,entryElementId:frame.id}}},{kind:'field',target:{id:'b',incarnation:1},field:'ownerCanvasId',before:root,after:partition},{kind:'field',target:{id:'b',incarnation:1},field:'geometry',before:beforeNode.geometry,after:{...beforeNode.geometry,x:(beforeNode.geometry.x-54)/2,y:(beforeNode.geometry.y-86)/2,width:beforeNode.geometry.width/2,height:beforeNode.geometry.height/2}},{kind:'field',target:{id:'b',incarnation:1},field:'data.presentation',before:beforeNode.data.presentation??null,beforePresent:Object.hasOwn(beforeNode.data,'presentation'),after:{...beforeNode.data.presentation,unitScale:.5},afterPresent:true}]);
   const generated=applyChanges(movedModel,[{kind:'field',target:{id:'b',incarnation:1},field:'data.text',before:beforeNode.data.text,after:'Generated while another canvas was open',beforePresent:true,afterPresent:true}]);documents.set(root,generated);versions.set(root,versions.get(root)+1);versions.set(partition,2);run.status='succeeded';
   run.events.push({seq:3,run_id:id(700),type:'step.output',step_id:'step-b',board_id:root,node_id:'b',output:{output_id:id(701),kind:'text',text:'Generated while another canvas was open'}},{seq:4,run_id:id(700),type:'step.applied',step_id:'step-b',board_id:partition,origin_board_id:root,canonical_root:root,node_id:'b',canvas_version:versions.get(partition),document_format_version:1,target_incarnation:1,model:model(generated,true)},{seq:5,run_id:id(700),type:'run.completed',status:'succeeded'});
+  // 离开视图后仍应继续轮询持久任务；另一项目页面必须保持无节点，不能显示原项目晚到结果。
   const pollsBefore=calls.filter(call=>call.path.includes('/ai/runs/')).length;
   for(let i=0;i<200&&calls.filter(call=>call.path.includes('/ai/runs/')).length===pollsBefore;i++)await pause(20);
   assert.ok(calls.filter(call=>call.path.includes('/ai/runs/')).length>pollsBefore,'view detach stopped persistent AI polling');await pause(200);
   assert.equal(await evaluate('document.querySelectorAll(".react-flow__node").length'),0,'AI output leaked into a different project view');
   await call('Page.reload');await until(`location.pathname.endsWith('${other}')&&!!document.querySelector('[data-headless-canvas]')`,'other project reload failed');
   await evaluate(`document.querySelector('a[href="/dashboard/${workspace}/${root}"]').click()`);await until(`!!document.querySelector('.react-flow__node[data-id=b]')&&document.querySelector('.react-flow__node[data-id=b] textarea')?.value==='Generated while another canvas was open'`,'AI output did not survive reload');
+  // 重载并返回原项目，面板要恢复 RunRecord；核对仅一个生成 POST、一个 b，以及缩放前后相同视觉采样。
   await selectB();await click('AI 创作');await until(`document.body.innerText.includes('已更新当前元素')`,'durable RunRecord did not recover');await click('关闭 AI 工具');
   assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length,1,'AI recovery invoked generation twice');assert.equal(documents.get(root).elements.get('b').geometry.width,150);assert.equal(documents.get(root).elements.get('b').data.presentation.unitScale,.5);assert.deepEqual(await evaluate(visualMetric),beforeVisual,'normalized units changed actual rendered size or typography');assert.equal(documents.get(root).elements.get('b').ownerCanvasId,partition);assert.equal(await evaluate(`document.querySelectorAll('.react-flow__node[data-id=b]').length`),1);
   console.log('PASS actual AI panel follows a scaled owner move with stable rendered size/typography, polls after navigation, and restores one element/RunRecord without re-execution');
+  // 下一任务走实际取消按钮，完成后保留当前内容，再启动第三个任务构造可显式选择的冲突输出。
   await selectB();await click('AI 创作');await until(`!!document.querySelector('[aria-label="执行 AI"]')&&!document.querySelector('[aria-label="执行 AI"]').disabled`,'AI action did not reopen');await click('执行 AI');await until(`!!document.querySelector('[aria-label="取消生成"]')`,'cancel control did not appear');await click('取消生成');await until(`document.body.innerText.includes('已取消生成')`,'durable cancellation did not finish');assert.equal(documents.get(root).elements.get('b').data.text,'Generated while another canvas was open');
   await until(`!document.querySelector('[aria-label="执行 AI"]').disabled`,'cancelled run did not release execution');await click('执行 AI');
   for(let i=0;i<100&&!aiRuns.has(id(720));i++)await pause(20);assert.ok(aiRuns.has(id(720)));
+  // fixture 注入 output/conflict/completed 事件；冲突只保留结果，不应自动覆盖当前元素。
   const conflicted=aiRuns.get(id(720));conflicted.status='conflict';conflicted.events.push({seq:3,run_id:id(720),type:'step.output',step_id:'step-b',board_id:partition,node_id:'b',output:{output_id:id(721),kind:'text',text:'Chosen conflict result'}},{seq:4,run_id:id(720),type:'step.conflict',step_id:'step-b',board_id:partition,node_id:'b',status:'conflict',error:'target_changed'},{seq:5,run_id:id(720),type:'run.completed',status:'conflict'});
   await until(`[...document.querySelectorAll('button')].some(button=>button.textContent==='使用此结果替换当前内容')`,'conflict result did not expose explicit application');await evaluate(`[...document.querySelectorAll('button')].find(button=>button.textContent==='使用此结果替换当前内容').click()`);
+  // 选择输出后本地立即变化；applyGate 尚未释放时先 undo，应立即恢复旧内容，再允许服务回执协调。
   await until(`document.querySelector('.react-flow__node[data-id=b] textarea').value==='Chosen conflict result'`,'chosen output was not optimistic');await click('撤销');await until(`document.querySelector('.react-flow__node[data-id=b] textarea').value==='Generated while another canvas was open'`,'unknown apply could not be locally undone');releaseApply();
   for(let i=0;i<200&&documents.get(root).elements.get('b').data.text!=='Generated while another canvas was open';i++)await pause(20);assert.equal(documents.get(root).elements.get('b').data.text,'Generated while another canvas was open');await click('重做');
+  // redo 恢复已选择输出，不重新生成或重复 apply；最后精确检查取消一次、应用一次、总受理三次。
   for(let i=0;i<200&&documents.get(root).elements.get('b').data.text!=='Chosen conflict result';i++)await pause(20);assert.equal(documents.get(root).elements.get('b').data.text,'Chosen conflict result');assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/cancel')).length,1);assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/apply')).length,1);assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length,3);await click('关闭 AI 工具');
   console.log('PASS actual AI cancellation and optimistic conflict application use durable actions; undo/redo while awaiting acknowledgment never regenerate');
+  // 在页面生成真实 4×2 PNG 并经 File input 导入；上传 gate 仍挂起，本地 Blob URL 和尺寸应先出现。
   await evaluate(`(async()=>{const canvas=new OffscreenCanvas(4,2);canvas.getContext('2d').fillRect(0,0,4,2);const bytes=await canvas.convertToBlob({type:'image/png'});const transfer=new DataTransfer();transfer.items.add(new File([bytes],'pixel.png',{type:'image/png'}));const input=document.querySelector('[data-headless-canvas] input[type=file]');input.files=transfer.files;input.dispatchEvent(new Event('change',{bubbles:true}));})()`);
   await until(`document.querySelectorAll('.react-flow__node').length === 5 && [...document.querySelectorAll('[data-headless-canvas] img')].some(image=>image.getAttribute('src')?.startsWith('blob:'))`, 'pending image did not appear before upload');
+  // 从 Blob 预览找到新元素，等待 height=130；比例操作可用后，一次 undo 应删除整个已补尺寸创建，redo 恢复尺寸。
   const pendingImageId=await evaluate(`document.querySelector('[data-headless-canvas] img[src^="blob:"]').closest('.react-flow__node').getAttribute('data-id')`);
   await until(`document.querySelector('.react-flow__node[data-id="${pendingImageId}"]').style.height==='130px'`,'default image size did not automatically use locally decoded 4:2 aspect ratio before upload ACK');
   await evaluate(`document.querySelector('.react-flow__node[data-id="${pendingImageId}"]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`);await until(`!document.querySelector('[aria-label="按图片比例调整"]').disabled`,'decoded image dimensions were not available before upload ACK');await click('按图片比例调整');
@@ -385,72 +489,91 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   await click('重做');await until(`document.querySelector('.react-flow__node[data-id="${pendingImageId}"]')?.style.height==='130px'`,'redo lost the enriched creation dimensions');assert.equal(uploads.length<=1,true);
   await until(`(()=>{const node=document.querySelector('.react-flow__node[data-id="${pendingImageId}"]');const content=[...node.querySelectorAll('div')].find(element=>element.style.zoom);return content?.style.height==='130px';})()`,'image content retained a stale measured height after automatic sizing and redo');
   console.log('PASS default image sizing precedes upload ACK; creation undo/redo includes decoded dimensions without a second history unit or upload');
+  // 截图是此时 pending 图片状态的辅助产物，随后另外核对上游上传数与文档元素数。
   const screenshot=await call('Page.captureScreenshot',{format:'png'});await writeFile('/private/tmp/headless-canvas-integration.png',Buffer.from(screenshot.data,'base64'));
   for (let i = 0; i < 100 && !uploads.length; i++) await pause(20);
   assert.equal(uploads.length, 1); assert.equal(documents.get(root).elements.size, 5);
   await evaluate(`document.querySelector('a[href="/dashboard/${workspace}/${other}"]').click()`);
   await until(`location.pathname.endsWith('${other}') && !!document.querySelector('[data-headless-canvas]') && document.querySelectorAll('.react-flow__node').length === 0`, 'other board did not open');
+  // 导航到另一 board 后才确认上传；原项目后台继续写图片，当前页面不得被其晚到响应污染。
   releaseUpload();
   for (let i = 0; i < 200 && documents.get(root).elements.size !== 6; i++) await pause(20);
   assert.equal(documents.get(root).elements.size, 6, 'view detach aborted the upload or document operation');
   assert.equal(await evaluate('document.querySelectorAll(".react-flow__node").length'), 0, 'late result appeared on the wrong board');
+  // 另一项目用资源选择器采用已上传身份；先验证每次采用都重新授权，拒绝时不能创建元素或 undo 单元。
   await click('复用其它画布图片');await until(`!!document.querySelector('[role="dialog"] [aria-label="添加图片：视觉参考"]')`,'other opened project image did not appear in the picker');
   const pickerScreenshot=await call('Page.captureScreenshot',{format:'png'});await writeFile('/private/tmp/headless-resource-picker.png',Buffer.from(pickerScreenshot.data,'base64'));
   denyAssetMetadata=true;await click('添加图片：视觉参考');await until(`document.querySelector('[role="dialog"] [role="alert"]')?.textContent.includes('访问权限')`,'fresh authorization rejection was not readable');assert.equal(documents.get(other).elements.size,0);assert.equal(await evaluate(`document.querySelector('[aria-label="撤销"]').disabled`),true);denyAssetMetadata=false;
+  // 授权读取挂起时按 Escape 关闭选择器，再放行旧响应；已关闭会话不得接纳这个迟到结果。
   metadataWait=new Promise(resolve=>releaseMetadata=resolve);const metadataCalls=calls.filter(call=>call.path.includes('/assets/metadata/')).length;await click('添加图片：视觉参考');for(let i=0;i<100&&calls.filter(call=>call.path.includes('/assets/metadata/')).length===metadataCalls;i++)await pause(20);assert.ok(calls.filter(call=>call.path.includes('/assets/metadata/')).length>metadataCalls,'picker did not start authorization');await call('Input.dispatchKeyEvent',{type:'keyDown',key:'Escape',code:'Escape',windowsVirtualKeyCode:27});await call('Input.dispatchKeyEvent',{type:'keyUp',key:'Escape',code:'Escape',windowsVirtualKeyCode:27});await until(`!document.querySelector('[role="dialog"]')`,'Escape did not close the resource picker');releaseMetadata();metadataWait=undefined;await pause(100);assert.equal(documents.get(other).elements.size,0,'closed picker admitted a late authorization result');
+  // 重新打开后成功采用同一 assetId，比例来自授权元数据且上传总数仍为一；再检查 undo/redo 进入第二代。
   await click('复用其它画布图片');await until(`!!document.querySelector('[role="dialog"] [aria-label="添加图片：视觉参考"]')`,'resource picker did not reopen');await click('添加图片：视觉参考');await until(`!document.querySelector('[role="dialog"]')&&document.querySelectorAll('.react-flow__node').length===1`,'adopted image did not appear');for(let i=0;i<100&&documents.get(other).elements.size!==1;i++)await pause(20);const adopted=[...documents.get(other).elements.values()][0];assert.equal(adopted.data.assetId,uploads[0].id);assert.equal(uploads.length,1,'cross-project picker uploaded a duplicate');assert.equal(adopted.geometry.width/adopted.geometry.height,2);
   await click('撤销');for(let i=0;i<100&&documents.get(other).elements.size;i++)await pause(20);assert.equal(documents.get(other).elements.size,0);await click('重做');for(let i=0;i<100&&documents.get(other).elements.get(adopted.id)?.incarnation!==2;i++)await pause(20);assert.equal(documents.get(other).elements.get(adopted.id).incarnation,2);assert.equal(uploads.length,1);console.log('PASS cross-project resource picker reauthorizes, cancels a late result, creates one shared image and supports undo/redo without uploading again');
 
   await evaluate(`document.querySelector('a[href="/dashboard/${workspace}/${root}"]').click()`);
+  // 返回原项目并重载，文档/资源身份继续存在且没有退回 legacy canvas 读取。
   await until('document.querySelectorAll(".react-flow__node").length === 5', 'returning project lost its engine');
   assert.equal(uploads.length, 1);
   await call('Page.reload'); await until('document.querySelectorAll(".react-flow__node").length === 5', 'page reload did not recover the document');
   assert.equal(uploads.length, 1); assert.equal(calls.some(call => call.path.endsWith('/canvas')), false);
   console.log('PASS pending image displays before upload; navigation preserves work and fences late view updates; reload retains resource identity');
   console.log('PASS canvas floating controls remain visible while the sidebar is expanded');
+  // 完整页面模式也调用独立 HookChecks，报告来自真实 React mount 与内存端口组合，具体步骤在 hooks fixture 中说明。
   const hookReports=await evaluate('window.__runCanvasHookChecks()');for(const report of hookReports)console.log('PASS React hooks: '+report);
+  // 导入 NDJSON 含一条合法记录和一个坏尾行；合法项先本地加入，服务写入仍由 importGate 挂住。
   const beforeImport=documents.get(root).elements.size,importRecord={kind:'element',key:'ui-import',record:{id:'ui-import',incarnation:1,structure:'node',ownerCanvasId:'$target',componentId:'text',dataVersion:1,data:{title:'Imported NDJSON node',text:'Visible before ACK'},geometry:{x:700,y:450,width:240,height:160,rotation:0}}},nativeText=JSON.stringify(importRecord)+'\n{bad}';
   await evaluate(`(()=>{const transfer=new DataTransfer();transfer.items.add(new File([${JSON.stringify(nativeText)}],'canvas.ndjson',{type:'application/x-ndjson'}));const input=document.querySelector('[data-canvas-import]');input.files=transfer.files;input.dispatchEvent(new Event('change',{bubbles:true}));})()`);
   await until(`document.querySelectorAll('.react-flow__node').length===6&&document.body.innerText.includes('部分加入')`,'native import did not show its successful prefix and partial report');
+  // 确认网络已进入屏障但服务元素数未增加，页面却已有新节点和 partial 报告，区分显示与 ACK。
   for(let i=0;i<100&&!importWriteSeen;i++)await pause(20);assert.ok(importWriteSeen);assert.equal(documents.get(root).elements.size,beforeImport,'import waited for its backend before displaying content');
+  // 展开失败详情检查可读原因，截图后才释放文档 gate；重载要同时恢复内容与 partial 作业报告。
   await evaluate(`[...document.querySelectorAll('summary')].find(summary=>summary.textContent.includes('条未加入记录')).click()`);await until(`document.body.innerText.includes('记录格式错误')`,'import failure reason was hidden');
   const importScreenshot=await call('Page.captureScreenshot',{format:'png'});await writeFile('/private/tmp/headless-import-integration.png',Buffer.from(importScreenshot.data,'base64'));releaseImport();
   for(let i=0;i<200&&documents.get(root).elements.size!==beforeImport+1;i++)await pause(20);assert.equal(documents.get(root).elements.size,beforeImport+1);await pause(200);await call('Page.reload');await until(`document.querySelectorAll('.react-flow__node').length===6&&document.querySelector('[aria-label="画布导入"]')?.textContent.includes('部分加入')`,'import task and content did not recover after reload');
+  // 记录模型 POST 基数，通过临时 Host 公开动作清理导入源；UI 状态和重载结果要保留，但清理不能产生内容操作。
   const beforeSourceCollection=calls.filter(call=>call.method==='POST'&&call.path.endsWith('/model/operations')).length;
   await until(`typeof window.__headlessCollectSources==='function'`,'fixture Host action was not installed');const sourceCollection=await evaluate(`window.__headlessCollectSources()`);assert.equal(sourceCollection.purgedIds.length,1);
   await evaluate(`(()=>{const details=document.querySelector('[aria-label="画布导入"] details');if(!details.open)details.querySelector('summary').click();})()`);
   await until(`document.body.innerText.includes('本地源文件已清理')`,'source collection status was not displayed');assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/model/operations')).length,beforeSourceCollection,'source GC created a document operation');
   const sourceScreenshot=await call('Page.captureScreenshot',{format:'png'});await writeFile('/private/tmp/headless-import-source-collection.png',Buffer.from(sourceScreenshot.data,'base64'));await call('Page.reload');await until(`document.querySelectorAll('.react-flow__node').length===6&&document.querySelector('[aria-label="画布导入"]')?.textContent.includes('本地源文件已清理')`,'retired source status/content did not recover');
   console.log('PASS Host-triggered source collection displays its status, survives reload and creates zero model operations');
+  // 源文件已经清理，undo 仍能移除成功前缀；终态导入作业重载后也不能复活已撤销记录。
   await click('撤销');await until(`document.querySelectorAll('.react-flow__node').length===5`,'import undo did not remove its successful content');await pause(200);await call('Page.reload');await until(`document.querySelectorAll('.react-flow__node').length===5`,'import recovered an undone record');
   console.log('PASS actual NDJSON import displays before backend ACK, reports a failed record, restores task/source state and never revives undone content');
   await evaluate(`document.querySelector('.react-flow__node[data-id=b]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`);
   await until(`!document.querySelector('[aria-label="深复制选中内容"]').disabled`,'copy selection button remained disabled');
+  // 工具栏复制走持久导入作业，准备完成后重载保持结果；undo 再重载不能由作业重放补回内容。
   await click('深复制选中内容');await until(`document.querySelectorAll('.react-flow__node').length===6&&document.querySelector('[aria-label="画布导入"]').textContent.includes('复制选中内容')`,'copy did not publish through the durable task pipeline');
   await until(`document.querySelector('[aria-label="深复制选中内容"]')&&!document.querySelector('[aria-label="正在准备复制"]')`,'copy preparation did not finish');
   await pause(300);await call('Page.reload');await until(`document.querySelectorAll('.react-flow__node').length===6&&document.querySelector('[aria-label="画布导入"]').textContent.includes('复制选中内容')`,'copy task did not recover after reload');
   await click('撤销');await until(`document.querySelectorAll('.react-flow__node').length===5`,'copy history did not undo its published content');await pause(200);await call('Page.reload');await until(`document.querySelectorAll('.react-flow__node').length===5`,'copy replay revived an undone record');
   console.log('PASS actual deep copy toolbar action publishes a durable task, survives reload and does not revive its undone content');
 
-  // Portalled frame-title drafts are not represented by a node editing mode.
+  // portal 分区标题草稿由显式 overlay owner 持有，不以节点 mode 代表。
   await evaluate(`document.querySelector('.react-flow__node[data-id="relocation-frame"]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`);
   await until(`!!document.querySelector('[aria-label="分区名称"]')`,'frame title editor did not open');
+  // 折叠只影响投影：b 模型端点仍存在且上级连线仍画到分区锚点；展开后成员重新出现。
   await click('收起子画布');await until(`!document.querySelector('.react-flow__node[data-id=b]')&&document.querySelectorAll('.react-flow__edge').length>0`,'collapsed partition did not render its upper-canvas connection');assert.equal(documents.get(root).elements.get('edge').target.elementId,'b');assert.ok(documents.get(root).elements.has('b'));await click('展开子画布');await until(`!!document.querySelector('.react-flow__node[data-id=b] textarea')`,'expanding partition did not restore the member');
   console.log('PASS collapsed partitions retain model endpoints and render upper-canvas connections through headless frame anchors');
+  // portal 标题需显式注册 view/target；其工具栏按钮的普通 h 键不能被 canvas 工具路由抢走。
   assert.ok(await evaluate(`document.querySelector('[aria-label="分区名称"]').closest('[data-canvas-overlay-target]')?.dataset.canvasOverlayView`),'portalled frame title did not register its explicit view/target placement');
   assert.equal(await evaluate(`(()=>{const overlay=document.querySelector('[aria-label="分区名称"]').closest('[data-canvas-overlay-target]'),button=overlay.querySelector('button'),event=new KeyboardEvent('keydown',{key:'h',bubbles:true,cancelable:true});button.dispatchEvent(event);return event.defaultPrevented;})()`),false,'portalled toolbar button key was claimed by the canvas tool');
   await evaluate(`(()=>{window.pinnedFrameTitle=document.querySelector('[aria-label="分区名称"]');window.pinnedFrameTitle.focus();window.pinnedFrameTitle.select();})()`);await call('Input.insertText',{text:'Pinned partition draft'});
+  // 两个页面脚本分别大幅平移和回到原点，供 portal 与 IME retention 检查共用；不直接写业务几何。
   const panFar=`document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:20000,deltaY:20000,bubbles:true,cancelable:true}))`,panHome=`(()=>{const matrix=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform);document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:matrix.e/.5,deltaY:matrix.f/.5,bubbles:true,cancelable:true}));})()`;
+  // 标题仍在编辑时把所属节点移出视口，要求相同 DOM、焦点和草稿保留；blur 保存后恢复裁剪，回视口再挂载。
   await evaluate(panFar);await pause(250);assert.equal(await evaluate(`window.pinnedFrameTitle.isConnected&&document.activeElement===window.pinnedFrameTitle&&window.pinnedFrameTitle.value==='Pinned partition draft'`),true,'viewport culling discarded an unsaved frame title');
   await evaluate('window.pinnedFrameTitle.blur()');for(let i=0;i<100&&documents.get(root).elements.get('relocation-frame').data.title!=='Pinned partition draft';i++)await pause(20);assert.equal(documents.get(root).elements.get('relocation-frame').data.title,'Pinned partition draft');
   await until(`document.querySelectorAll('.react-flow__node').length===0`,'viewport culling did not resume after title blur');await evaluate(panHome);await until(`!!document.querySelector('.react-flow__node[data-id=b] textarea')`,'panning back did not remount the node');
   await evaluate(`(()=>{const node=document.querySelector('.react-flow__node[data-id=b]');node.dispatchEvent(new MouseEvent('click',{bubbles:true}));node.querySelector('[aria-label^="单击选中"]').dispatchEvent(new MouseEvent('dblclick',{bubbles:true}));})()`);
+  // 文本 IME 组合态也要在离屏时保留同一编辑器；提交后 Escape 释放，再平移回来核对已保存文字。
   await until(`document.activeElement===document.querySelector('.react-flow__node[data-id=b] textarea')&&!document.activeElement.readOnly`,'text editor did not enter pinned mode');await evaluate('window.pinnedText=document.activeElement; void 0');await call('Input.imeSetComposition',{text:'保',selectionStart:1,selectionEnd:1});await evaluate(panFar);await pause(250);
   assert.equal(await evaluate(`window.pinnedText.isConnected&&document.activeElement===window.pinnedText&&window.pinnedText.value.includes('保')`),true,'viewport culling interrupted active IME');await call('Input.insertText',{text:'保留输入'});for(let i=0;i<100&&!documents.get(root).elements.get('b').data.text.endsWith('保留输入');i++)await pause(20);assert.ok(documents.get(root).elements.get('b').data.text.endsWith('保留输入'));
   await call('Input.dispatchKeyEvent',{type:'keyDown',key:'Escape',code:'Escape',windowsVirtualKeyCode:27});await call('Input.dispatchKeyEvent',{type:'keyUp',key:'Escape',code:'Escape',windowsVirtualKeyCode:27});await until(`document.querySelectorAll('.react-flow__node').length===0`,'viewport culling did not resume after IME editing');await evaluate(panHome);await until(`!!document.querySelector('.react-flow__node[data-id=b] textarea')`,'edited node did not remount');assert.ok(await evaluate(`document.querySelector('.react-flow__node[data-id=b] textarea').value.endsWith('保留输入')`));
   console.log('PASS native viewport culling retains unsaved portalled frame titles and active IME across pan, then resumes and remounts saved content');
   await evaluate(`(()=>{const node=document.querySelector('.react-flow__node[data-id=b]');node.dispatchEvent(new MouseEvent('click',{bubbles:true}));node.querySelector('[aria-label^="单击选中"]').dispatchEvent(new MouseEvent('dblclick',{bubbles:true}));})()`);
   await until(`document.activeElement===document.querySelector('.react-flow__node[data-id=b] textarea')&&!document.activeElement.readOnly`,'retiring editor did not focus');
+  // 删除仍有焦点的节点时不能等待 blur 才释放所有权；旧 textarea 脱离后应恢复裁剪，历史可重新还原内容。
   assert.equal(await evaluate(`(()=>{window.__retiredEditor=document.activeElement;const engine=window.__fixtureActualEngine,element=engine.getSnapshot().document.elements.get('b');return engine.editor.dispatch({type:'element.remove',target:{id:element.id,incarnation:element.incarnation}}).status;})()`),'applied');
   await until(`!document.querySelector('.react-flow__node[data-id=b]')`,'focused node did not retire');assert.equal(await evaluate('window.__retiredEditor.isConnected'),false);
   await evaluate(panFar);await until(`document.querySelectorAll('.react-flow__node').length===0`,'detached focus left the graph permanently retained');
@@ -458,7 +581,7 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   console.log('PASS deleting a focused renderer releases detached ownership without requiring blur and history restores its content');
 
 
-  // Exceed the curve-inspection budget without retaining unrelated child cards.
+  // 4097 条边超过曲线检查预算，但仅三个端点/入口 owner 需要挂载；200 个无关离屏子卡应继续裁剪。
   const budgetRoot=id(870),budgetChild=id(871),budgetFrame={...node('budget-frame',budgetRoot,0),componentId:'frame',geometry:{x:0,y:400,width:1000,height:600,rotation:0}},budgetNodes=[node('budget-a',budgetRoot,80),node('budget-b',budgetRoot,450),budgetFrame,...Array.from({length:200},(_,index)=>node('budget-hidden-'+index,budgetChild,12000+index*280))],budgetEdges=Array.from({length:4097},(_,index)=>({id:'budget-edge-'+index,incarnation:1,structure:'connection',componentId:'connection',dataVersion:1,ownerCanvasId:budgetRoot,source:{elementId:'budget-a'},target:{elementId:'budget-b'},data:{},path:null}));
   documents.set(budgetRoot,createDocument(budgetRoot,[{id:budgetRoot,parent:null},{id:budgetChild,parent:{canvasId:budgetRoot,entryElementId:budgetFrame.id}}],[...budgetNodes,...budgetEdges]));versions.set(budgetRoot,1);versions.set(budgetChild,1);boards.push({id:budgetRoot,workspace_id:workspace,kind:'board',version:1,title:'Curve budget board'});
   await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${budgetRoot}`});
@@ -466,21 +589,25 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   assert.equal(await evaluate(`!!document.querySelector('.react-flow__node[data-id="budget-hidden-0"]')`),false);assert.equal(documents.get(budgetRoot).elements.size,4300);assert.equal(await evaluate('window.__fixtureActualEngine.getSnapshot().document.elements.size'),4300);assert.equal(await evaluate(`window.__fixtureActualEngine.getSnapshot().document.elements.get('budget-hidden-199')?.ownerCanvasId`),budgetChild);
   console.log('PASS exhausted curve inspection retains all 4097 edges and their endpoint owners while 200 unrelated offscreen cards stay culled');
 
-  // Read a fresh project whose known envelope contains opaque component/version payloads.
+  // 构造未知 component、未来 dataVersion 和不透明 path/ports/presentation；明确区分已知外壳与无法解释的内部字段。
   const opaqueRoot=id(800),opaqueChild=id(801),opaqueU={...node('opaque-u',opaqueRoot,50),componentId:'plugin:future',dataVersion:9,data:{title:'Opaque source',ports:{find:'future field'},presentation:{unitScale:'future'},assetId:'opaque-asset',__headlessFallback:{handles:'untrusted'},opaque:{preserve:true}}},opaqueV={...node('opaque-v',opaqueRoot,400),dataVersion:99,data:{title:'Future card',text:{preserve:true},ports:'future field'}},opaqueFrame={...node('opaque-frame',opaqueRoot,100),componentId:'frame',dataVersion:99,geometry:{x:100,y:450,width:350,height:220,rotation:0},data:{title:'Future partition',ports:{preserve:true},presentation:{unitScale:'future'}}},opaqueKnown=node('opaque-known',opaqueRoot,800),opaqueMember=node('opaque-member',opaqueChild,20),opaqueEdge={id:'opaque-edge',incarnation:1,structure:'connection',componentId:'plugin:connection',dataVersion:9,ownerCanvasId:opaqueRoot,source:{elementId:opaqueU.id,portId:'custom-out'},target:{elementId:opaqueV.id,portId:'custom-in'},path:{type:'future',preserve:true},data:{appearance:{color:{preserve:true}}}},regularEdge={...opaqueEdge,id:'opaque-regular',componentId:'connection',dataVersion:1,target:{elementId:opaqueKnown.id,portId:'left'},path:null,data:{}},partitionEdge={...regularEdge,id:'opaque-partition',source:{elementId:opaqueKnown.id,portId:'bottom'},target:{elementId:opaqueMember.id}};
   const opaqueOriginal=createDocument(opaqueRoot,[{id:opaqueRoot,parent:null},{id:opaqueChild,parent:{canvasId:opaqueRoot,entryElementId:opaqueFrame.id}}],[opaqueU,opaqueV,opaqueFrame,opaqueKnown,opaqueMember,opaqueEdge,regularEdge,partitionEdge]);documents.set(opaqueRoot,opaqueOriginal);versions.set(opaqueRoot,1);versions.set(opaqueChild,1);boards.push({id:opaqueRoot,workspace_id:workspace,kind:'board',version:1,title:'Compatibility board'});
   await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${opaqueRoot}`});await until(`document.querySelectorAll('[aria-label="暂不支持编辑的元素"]').length===3&&document.querySelectorAll('.react-flow__edge').length===3`,'opaque placeholders or their original connections did not render');
   assert.equal(await evaluate(`document.querySelectorAll('.react-flow__node').length`),4);assert.equal(await evaluate(`!!document.querySelector('.react-flow__node[data-id="opaque-member"]')`),false);assert.equal(await evaluate(`document.querySelector('.react-flow__node[data-id="opaque-u"]').classList.contains('draggable')`),false);assert.equal(await evaluate(`document.querySelector('.react-flow__node[data-id="opaque-u"]').querySelectorAll('textarea,input').length`),0);assert.ok(await evaluate(`[...document.querySelector('.react-flow__node[data-id="opaque-u"]').querySelectorAll('[data-handleid]')].some(handle=>handle.dataset.handleid==='custom-out'&&!handle.classList.contains('connectablestart')&&!handle.classList.contains('connectableend'))`));
+  // 本场景的 opaque-u 占位仍可选且有视觉反馈，但不可拖动/编辑/连线；已知邻居编辑不得改写不透明记录。
   const opaqueBorder=await evaluate(`getComputedStyle(document.querySelector('[data-id="opaque-u"] [role=note]')).borderColor`);await evaluate(`document.querySelector('.react-flow__node[data-id="opaque-u"]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`);await until(`document.querySelector('.react-flow__node[data-id="opaque-u"]').classList.contains('selected')`,'opaque selection did not publish');assert.notEqual(await evaluate(`getComputedStyle(document.querySelector('[data-id="opaque-u"] [role=note]')).borderColor`),opaqueBorder,'placeholder selection was not visible');
   await evaluate(`(()=>{const card=document.querySelector('.react-flow__node[data-id="opaque-known"]');card.dispatchEvent(new MouseEvent('click',{bubbles:true}));card.querySelector('[aria-label^="单击选中"]').dispatchEvent(new MouseEvent('dblclick',{bubbles:true}));})()`);await until(`document.activeElement===document.querySelector('.react-flow__node[data-id="opaque-known"] textarea')&&!document.activeElement.readOnly`,'known neighbour was not editable');await evaluate('document.activeElement.select()');await call('Input.insertText',{text:'Known edit with opaque neighbours'});await evaluate('document.activeElement.blur()');for(let i=0;i<100&&documents.get(opaqueRoot).elements.get('opaque-known').data.text!=='Known edit with opaque neighbours';i++)await pause(20);assert.equal(documents.get(opaqueRoot).elements.get('opaque-known').data.text,'Known edit with opaque neighbours');for(const record of [opaqueU,opaqueV,opaqueFrame,opaqueEdge])assert.deepEqual(documents.get(opaqueRoot).elements.get(record.id),record);assert.equal(calls.some(call=>call.path.endsWith('/assets/opaque-asset')),false);
+  // 重载后占位和连接仍在，未知 frame 的子成员不应递归展示；并核对未请求 opaque-asset 的显示字节。
   await call('Page.reload');await until(`document.querySelectorAll('[aria-label="暂不支持编辑的元素"]').length===3&&document.querySelectorAll('.react-flow__edge').length===3`,'opaque content or connections did not survive recovery');assert.equal(documents.get(opaqueRoot).elements.get('opaque-partition').target.elementId,'opaque-member');
   await click('适应画布');await pause(100);await click('缩小');await pause(100);await click('缩小');await pause(100);await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
   await writeFile(join(tmpdir(),'headless-opaque-renderer.png'),Buffer.from((await call('Page.captureScreenshot',{format:'png'})).data,'base64'));
   console.log('PASS unknown types and future versions render safe read-only placeholders with custom/partition connections, preserve opaque payloads through edits and recovery, and never load opaque asset fields');
 
+  // 宿主扩展安装三个计量节点、两条自定义边和一条内置边，检查自定义端口与原始 data/path 保留。
   const extensionRoot=id(810),meter={...node('meter-one',extensionRoot,350),componentId:'fixture:meter',data:{metric:3,raw:{retained:true}}},meterTwo={...meter,id:'meter-two',geometry:{...meter.geometry,x:750},data:{metric:9}},meterThree={...meter,id:'meter-three',geometry:{...meter.geometry,x:1150},data:{metric:12}},meterEdge={id:'meter-edge',incarnation:1,structure:'connection',componentId:'fixture:metric-edge',dataVersion:1,ownerCanvasId:extensionRoot,source:{elementId:meter.id,portId:'custom-out'},target:{elementId:meterTwo.id,portId:'custom-in'},data:{metric:55},path:{type:'metric-curve',retained:true}};
   documents.set(extensionRoot,createDocument(extensionRoot,[{id:extensionRoot,parent:null}],[meter,meterTwo,meterThree,meterEdge,{...meterEdge,id:'unrelated-meter-edge',source:{elementId:'meter-two',portId:'custom-out'},target:{elementId:'meter-three',portId:'custom-in'}},{...meterEdge,id:'meter-builtin-edge',componentId:'connection',data:{},path:null}]));versions.set(extensionRoot,1);boards.push({id:extensionRoot,workspace_id:workspace,kind:'board',version:1,title:'Extension board'});await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${extensionRoot}`});await until(`document.querySelectorAll('[data-renderer-fixture="meter"]').length===3&&document.querySelectorAll('[data-renderer-fixture="metric-edge"]').length===2`,'host-installed custom node/edge renderers did not mount');await until(`document.querySelectorAll('.react-flow__edge').length===3`,'built-in edge did not connect custom renderer ports');assert.equal(await evaluate(`document.querySelectorAll('[aria-label="暂不支持编辑的元素"]').length`),0);await until(`[...document.querySelectorAll('[role="status"]')].some(item=>item.textContent.trim()==='已同步')`,'extension baseline did not settle');await pause(200);await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');const rendersBefore=await evaluate('({...window.__fixtureRenders})'),projectsBefore=await evaluate('({...window.__fixtureProjectedNodes})');await click('Increase meter-one');for(let i=0;i<100&&documents.get(extensionRoot).elements.get('meter-one').data.metric!==4;i++)await pause(20);assert.deepEqual(documents.get(extensionRoot).elements.get('meter-one').data,{metric:4,raw:{retained:true,edited:true}});assert.deepEqual(documents.get(extensionRoot).elements.get('meter-edge'),meterEdge);await until(`[...document.querySelectorAll('[role="status"]')].some(item=>item.textContent.trim()==='已同步')`,'extension edit/ACK did not settle');await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');const rendersAfter=await evaluate('({...window.__fixtureRenders})');assert.ok(rendersAfter['meter-one']>rendersBefore['meter-one'],'edited custom node did not render');assert.equal(rendersAfter['meter-two'],rendersBefore['meter-two'],'unrelated custom node rendered during edit/ACK');assert.equal(rendersAfter['unrelated-meter-edge'],rendersBefore['unrelated-meter-edge'],'unrelated custom edge rendered during edit/ACK');const projectsAfter=await evaluate('({...window.__fixtureProjectedNodes})');assert.ok(projectsAfter['meter-one']>projectsBefore['meter-one']);assert.equal(projectsAfter['meter-two'],projectsBefore['meter-two'],'unrelated node projection rebuilt during edit/ACK');assert.equal(projectsAfter['meter-three'],projectsBefore['meter-three'],'unrelated node projection rebuilt during edit/ACK');console.log('PASS actual registered renderer updates the edited node while unrelated node/edge render counts remain unchanged through ACK');
   await until(`window.__fixtureActualEngine?.projectId===${JSON.stringify(extensionRoot)}||window.__fixtureActualEngine?.getSnapshot().document.projectId===${JSON.stringify(extensionRoot)}`,'extension engine unavailable');
+  // 完整 scene rebuild 与逐节点 projection 分开计数；viewport/tool/mode 来回变化不应触发整图重建。
   const beforeScene=await evaluate('window.__fixtureSceneBuilds');assert.ok(beforeScene>0);
   await evaluate(`(()=>{const e=window.__fixtureActualEngine,v=[...e.sessions.getSnapshot().views.values()][0];window.__fixtureViewBefore={id:v.id,viewport:v.viewport,tool:v.tool};e.sessions.viewport(v.id,{x:80,y:45,zoom:1.2});e.sessions.tool(v.id,'pan');e.sessions.mode(v.id,'meter-one','projection-check');})()`);
   await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');await pause(100);
@@ -489,23 +616,31 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');assert.equal(await evaluate('window.__fixtureSceneBuilds'),beforeScene);
   console.log('PASS actual CanvasView viewport/tool/mode transitions reuse the scene without projection traversal');
 
+  // 插件按钮的 metric/raw 两次修改属于同一事务历史；undo/redo/reload 均通过公开命令和存储恢复。
   await click('撤销');for(let i=0;i<100&&documents.get(extensionRoot).elements.get('meter-one').data.metric!==3;i++)await pause(20);assert.equal(documents.get(extensionRoot).elements.get('meter-one').data.metric,3);assert.deepEqual(documents.get(extensionRoot).elements.get('meter-one').data.raw,{retained:true});await click('重做');for(let i=0;i<100&&documents.get(extensionRoot).elements.get('meter-one').data.metric!==4;i++)await pause(20);assert.equal(documents.get(extensionRoot).elements.get('meter-one').data.metric,4);await call('Page.reload');await until(`document.querySelector('[data-id="meter-one"] [data-renderer-fixture="meter"]')?.textContent.includes('Metric 4')&&!!document.querySelector('[data-renderer-fixture="metric-edge"]')`,'registered renderer edits did not recover');
   console.log('PASS Host-installed custom model/node/edge definitions render without core type switches; command-backed edits preserve raw fields and recover through undo/redo/reload');
+  // 无 rendered target 的旧 editing facade 必须无效，不能仅凭元素 ID 越过作用域校验。
   assert.equal(await evaluate(`(()=>{const engine=window.__fixtureEngine,before=engine.getSnapshot();window.__fixtureUnbound['meter-one'].rename('meter-one','unbound callback');return engine.getSnapshot()===before;})()`),true,'headless legacy editing without a rendered target was allowed');
+  // 目标按钮先 preventDefault 的 Escape 保留手势；后续另测 shadow textarea、select 和未消费的外部 Escape。
   assert.equal(await evaluate(`(()=>{const engine=window.__fixtureEngine,view=[...engine.sessions.getSnapshot().views.values()][0],record=engine.getSnapshot().document.elements.get('meter-one'),button=document.createElement('button');document.querySelector('[data-headless-canvas]').append(button);button.addEventListener('keydown',event=>event.preventDefault());engine.sessions.begin(view.id,[{id:record.id,incarnation:record.incarnation}]);const token=engine.sessions.getSnapshot().gesture?.token;button.dispatchEvent(new KeyboardEvent('keydown',{key:'Escape',bubbles:true,cancelable:true}));const retained=!!token&&engine.sessions.getSnapshot().gesture?.token===token;button.remove();engine.sessions.cancel('fixture_cleanup');return retained;})()`),true,'capture-phase Escape canceled a gesture before the target could claim it');
   assert.deepEqual(await evaluate(`(()=>{const engine=window.__fixtureEngine,view=[...engine.sessions.getSnapshot().views.values()][0],record=engine.getSnapshot().document.elements.get('meter-one'),canvas=document.querySelector('[data-headless-canvas]'),host=document.createElement('div');canvas.append(host);const shadow=host.attachShadow({mode:'open'}),textarea=document.createElement('textarea');shadow.append(textarea);const select=document.createElement('select');canvas.append(select);const fire=element=>{const event=new KeyboardEvent('keydown',{key:'h',composed:true,bubbles:true,cancelable:true});element.dispatchEvent(event);return event.defaultPrevented;};const protectedKeys=[fire(textarea),fire(select)];host.remove();select.remove();engine.sessions.begin(view.id,[{id:record.id,incarnation:record.incarnation}]);const outside=document.createElement('button');document.body.append(outside);const event=new KeyboardEvent('keydown',{key:'Escape',bubbles:true,cancelable:true});outside.dispatchEvent(event);outside.remove();return{protectedKeys,tool:engine.sessions.getSnapshot().views.get(view.id).tool,canceled:!engine.sessions.getSnapshot().gesture,claimed:event.defaultPrevented};})()`),{protectedKeys:[false,false],tool:'select',canceled:true,claimed:true});
   console.log('PASS keyboard targets claim Escape before canvas cancellation; native selects and shadow text retain their input, while unclaimed outside Escape cancels the owned gesture');
+  // 删除再 undo 后元素进入第二代；捕获的第一代旧 facade 必须拒绝编辑并保持 Root 引用不变。
   const staleEdit=await evaluate(`(()=>{const engine=window.__fixtureEngine,old=window.__fixtureLegacy['meter-one'],target=engine.getSnapshot().document.elements.get('meter-one');window.__fixtureStaleLegacy=old;engine.editor.dispatch({type:'element.remove',target:{id:target.id,incarnation:target.incarnation}});engine.editor.history.undo();const restored=engine.getSnapshot();old.rename('meter-one','stale callback');return{unchanged:engine.getSnapshot()===restored,incarnation:restored.document.elements.get('meter-one').incarnation};})()`);assert.equal(staleEdit.incarnation,2);assert.equal(staleEdit.unchanged,true,'old rendered edit callback modified a restored incarnation');
   console.log('PASS old rendered edit callbacks cannot modify a restored incarnation');
+  // 等待 renderer 绑定新身份后新 facade 才可写；旧目标 resize 清理也不能取消另一个目标的 mode。
   await until(`window.__fixtureLegacy['meter-one']!==window.__fixtureStaleLegacy&&window.__fixtureEngine.getSnapshot().document.elements.get('meter-one').incarnation===2`,'restored renderer did not bind a fresh edit target');await evaluate(`window.__fixtureLegacy['meter-one'].rename('meter-one','fresh callback')`);for(let i=0;i<200&&documents.get(extensionRoot).elements.get('meter-one')?.data.title!=='fresh callback';i++)await pause(20);assert.equal(documents.get(extensionRoot).elements.get('meter-one').data.title,'fresh callback');
   assert.equal(await evaluate(`(()=>{const engine=window.__fixtureEngine,old=window.__fixtureLegacy['meter-one'],other=window.__fixtureLegacy['meter-two'];old.resize('meter-one');other.resize('meter-two');old.resize(null);const view=[...engine.sessions.getSnapshot().views.values()][0],retained=view.modes.get('meter-two')==='resize';other.resize(null);return retained;})()`),true,'old target mode cleanup canceled another target');
   await until(`[...document.querySelectorAll('[role="status"]')].some(item=>item.textContent.trim()==='已同步')`,'extension state did not settle before insertion');await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');const insertionBefore=await evaluate('({projects:{...window.__fixtureProjectedNodes},scenes:window.__fixtureSceneBuilds})'),extensionSize=documents.get(extensionRoot).elements.size;await click('添加文本卡片');
+  // 新增普通文本并等 ACK 后，三个未变化计量节点 projection 计数与完整 scene 计数应都不增加。
   for(let i=0;i<200&&documents.get(extensionRoot).elements.size!==extensionSize+1;i++)await pause(20);assert.equal(documents.get(extensionRoot).elements.size,extensionSize+1);await until(`[...document.querySelectorAll('[role="status"]')].some(item=>item.textContent.trim()==='已同步')`,'inserted card did not synchronize');await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');const insertionAfter=await evaluate('({projects:{...window.__fixtureProjectedNodes},scenes:window.__fixtureSceneBuilds})');for(const id of ['meter-one','meter-two','meter-three'])assert.equal(insertionAfter.projects[id],insertionBefore.projects[id],'ordinary card insertion rebuilt '+id);assert.equal(insertionAfter.scenes,insertionBefore.scenes,'ordinary card insertion rebuilt the whole scene');console.log('PASS actual toolbar card insertion and ACK retain every unrelated node projection and avoid full scene traversal');
+  // 导航前保存旧 editing facade；视图 detach 后项目 engine 可保留，但旧视图回调不得再写。
   await evaluate(`(()=>{window.__detachedEngine=window.__fixtureEngine;window.__detachedEditing=window.__fixtureLegacy['meter-one'];[...document.querySelectorAll('a')].find(link=>link.pathname.endsWith('/${other}')).click();})()`);await until(`location.pathname.endsWith('${other}')&&!!document.querySelector('[data-headless-canvas]')`,'renderer view did not detach on navigation');assert.equal(await evaluate(`(()=>{const before=window.__detachedEngine.getSnapshot();window.__detachedEditing.rename('meter-one','detached callback');return window.__detachedEngine.getSnapshot()===before;})()`),true,'detached renderer wrote into its retained project');
   console.log('PASS restored renderers can edit with fresh bindings and detached views cannot write through old callbacks');
 
 
 
+  // 合法首元素后返回非法流尾，页面保留 partial editor 和可读错误；修复 fixture 后重新加载成为完整编辑器，全程无模型写入。
   brokenStreamRoot=id(830);const brokenRoot=brokenStreamRoot;
   documents.set(brokenRoot,createDocument(brokenRoot,[{id:brokenRoot,parent:null}],[{...node('prefix-visible',brokenRoot,80),data:{title:'Preserved prefix',text:'prefix-kept'}},node('tail-node',brokenRoot,450)]));versions.set(brokenRoot,1);boards.push({id:brokenRoot,workspace_id:workspace,kind:'board',version:1,title:'Interrupted board'});
   await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${brokenRoot}`});
@@ -515,29 +650,37 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   await until(`!!document.querySelector('[data-headless-canvas]:not([data-model-loading])')&&document.querySelectorAll('.react-flow__node').length===2&&!document.querySelector('[role="alert"]')`,'retry did not replace the failed prefix with a complete editor');
   console.log('PASS malformed model tail retains its legal partial editor, reports a readable error and retries into the complete editor without model writes');
 
+  // 首帧包含完整根 owner，却缺子 canvas 一项；下面检查根的编辑、创建、导入、复制和图片可先 ACK，不必等子尾部。
   scopeStreamRoot=id(850);const scopedRoot=scopeStreamRoot,scopedChild=id(851),scopeFrame={...node('scope-frame',scopedRoot,450),componentId:'frame',geometry:{x:450,y:150,width:600,height:450,rotation:0}};
   documents.set(scopedRoot,createDocument(scopedRoot,[{id:scopedRoot,parent:null},{id:scopedChild,parent:{canvasId:scopedRoot,entryElementId:scopeFrame.id}}],[node('scope-node',scopedRoot,80),scopeFrame,node('scope-child',scopedChild,20),node('scope-tail',scopedChild,320)]));versions.set(scopedRoot,1);versions.set(scopedChild,1);boards.push({id:scopedRoot,workspace_id:workspace,kind:'board',version:1,title:'Scope ACK board'});
   await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${scopedRoot}`});await until(`!!document.querySelector('[data-headless-canvas][data-model-loading] .react-flow__node[data-id="scope-node"]')`,'scope fixture did not show its certified owner');
   await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
   await until(`(()=>{const layer=document.querySelector('.react-flow__node[data-id="scope-node"] [aria-label^="单击选中"]');if(!layer)return false;const r=layer.getBoundingClientRect();for(const x of [.25,.5,.75,.9])for(const y of [.25,.5,.75]){const point={x:r.x+r.width*x,y:r.y+r.height*y};if(layer.contains(document.elementFromPoint(point.x,point.y))){window.__scopeEditPoint=point;return true;}}return false;})()`,'scope text remained covered by another surface');const scopePoint=await evaluate('window.__scopeEditPoint');
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...scopePoint,button:'left',buttons:1,clickCount:2});await call('Input.dispatchMouseEvent',{type:'mouseReleased',...scopePoint,button:'left',buttons:0,clickCount:2});await until(`document.activeElement===document.querySelector('.react-flow__node[data-id="scope-node"] textarea')&&!document.activeElement.readOnly`,'certified scope text did not enter editing');await call('Input.insertText',{text:' ACK before tail'});const scopeText=await evaluate('document.activeElement.value');
+  // 完整根作用域先到版本 2，子作用域仍为 1 且 scope-tail 未显示，证明不是等整个项目完成才发送。
   for(let i=0;i<150&&documents.get(scopedRoot).elements.get('scope-node').data.text!==scopeText;i++)await pause(20);assert.equal(documents.get(scopedRoot).elements.get('scope-node').data.text,scopeText,'certified scope edit waited for another owner tail');assert.equal(versions.get(scopedRoot),2);assert.equal(versions.get(scopedChild),1);assert.equal(await evaluate(`!!document.querySelector('[data-headless-canvas][data-model-loading]')`),true);assert.equal(await evaluate(`!!document.querySelector('.react-flow__node[data-id="scope-tail"]')`),false);
   assert.equal(await evaluate(`document.querySelector('button[aria-label="添加文本卡片"]').disabled`),false);await click('添加文本卡片');
+  // 来源未完整时新建卡片的 undo/redo 仍使用新 incarnation；根版本递增到 5，不能把出生与旧源清单混淆。
   for(let i=0;i<150&&documents.get(scopedRoot).elements.size!==5;i++)await pause(20);const born=[...documents.get(scopedRoot).elements.values()].find(element=>!['scope-node','scope-frame','scope-child','scope-tail'].includes(element.id));assert.ok(born,'certified scope did not create a new card before the tail');await click('撤销');for(let i=0;i<150&&documents.get(scopedRoot).elements.has(born.id);i++)await pause(20);assert.equal(documents.get(scopedRoot).elements.has(born.id),false);await click('重做');for(let i=0;i<150&&documents.get(scopedRoot).elements.get(born.id)?.incarnation!==2;i++)await pause(20);assert.equal(documents.get(scopedRoot).elements.get(born.id)?.incarnation,2);assert.equal(versions.get(scopedRoot),5);
   assert.equal(await evaluate(`document.querySelector('button[aria-label="导入画布记录"]').disabled`),false);
+  // 在认证根内从文件输入加入记录，再复制已闭合的 scope-node；每项都检查尾部到达前服务模型已增加。
   await evaluate(`(()=>{const input=document.querySelector('input[data-canvas-import]'),transfer=new DataTransfer();transfer.items.add(new File([JSON.stringify({kind:'element',key:'partial-import',record:{id:'partial-import',incarnation:1,ownerCanvasId:'$target',componentId:'text',dataVersion:1,structure:'node',data:{title:'Imported before tail',text:'streaming'},geometry:{x:0,y:0,width:100,height:80,rotation:0}}})+'\\n'],'partial.ndjson',{type:'application/x-ndjson'}));input.files=transfer.files;input.dispatchEvent(new Event('change',{bubbles:true}));return true;})()`);
   for(let i=0;i<200&&![...documents.get(scopedRoot).elements.values()].some(element=>element.data.title==='Imported before tail');i++)await pause(20);assert.ok([...documents.get(scopedRoot).elements.values()].some(element=>element.data.title==='Imported before tail'),'partial page import did not reach server before tail');
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...scopePoint,button:'left',buttons:1,clickCount:1});await call('Input.dispatchMouseEvent',{type:'mouseReleased',...scopePoint,button:'left',buttons:0,clickCount:1});await until(`!document.querySelector('button[aria-label="深复制选中内容"]').disabled`,'closed source copy stayed disabled during loading');const copyCount=documents.get(scopedRoot).elements.size;await click('深复制选中内容');
   for(let i=0;i<200&&documents.get(scopedRoot).elements.size===copyCount;i++)await pause(20);assert.equal(documents.get(scopedRoot).elements.size,copyCount+1,'page copy did not publish before tail');await until(`!!document.querySelector('button[aria-label="深复制选中内容"]')`,'copy did not finish');assert.equal(await evaluate(`document.querySelector('button[aria-label="添加图片"]').disabled`),false);const beforeImage=documents.get(scopedRoot).elements.size,uploadsBefore=uploads.length;
   await evaluate(`(async()=>{const canvas=new OffscreenCanvas(4,2);canvas.getContext('2d').fillRect(0,0,4,2);const bytes=await canvas.convertToBlob({type:'image/png'}),transfer=new DataTransfer();transfer.items.add(new File([bytes],'loading-pixel.png',{type:'image/png'}));const input=document.querySelector('[data-headless-canvas] input[type=file]');input.files=transfer.files;input.dispatchEvent(new Event('change',{bubbles:true}));})()`);
+  // 真实 PNG 在同一认证根上传并自动定高 130，loading 标志仍在；保存此时版本供尾部合并检查。
   for(let i=0;i<200&&documents.get(scopedRoot).elements.size===beforeImage;i++)await pause(20);const loadingImage=[...documents.get(scopedRoot).elements.values()].find(element=>element.componentId==='image');assert.ok(loadingImage,'scoped image waited for the unrelated tail');assert.equal(uploads.length,uploadsBefore+1);assert.equal(loadingImage.geometry.height,130,'scoped image lost default sizing');assert.equal(await evaluate(`!!document.querySelector('[data-headless-canvas][data-model-loading]')`),true);const scopeVersion=versions.get(scopedRoot);
 
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...scopePoint,button:'left',buttons:1,clickCount:2});await call('Input.dispatchMouseEvent',{type:'mouseReleased',...scopePoint,button:'left',buttons:0,clickCount:2});await until(`document.activeElement===document.querySelector('.react-flow__node[data-id="scope-node"] textarea')&&!document.activeElement.readOnly`,'original text focus did not return after structural history');
+  // 放行最初捕获尾部后保留同一 textarea/焦点/文字、第二代出生记录和已推进版本，不能重复发送旧来源。
   await evaluate('window.__scopeTextarea=document.activeElement;true');releaseScopeStream();await until(`!!document.querySelector('[data-headless-canvas]:not([data-model-loading])')&&!!document.querySelector('.react-flow__node[data-id="scope-tail"]')`,'original stream did not complete after a scoped ACK');assert.equal(await evaluate('window.__scopeTextarea.isConnected&&document.activeElement===window.__scopeTextarea'),true);assert.equal(await evaluate('window.__scopeTextarea.value'),scopeText);assert.equal(versions.get(scopedRoot),scopeVersion,'old tail caused a duplicate write');assert.equal(documents.get(scopedRoot).elements.get(born.id)?.incarnation,2);console.log('PASS certified owner image/import/copy, edits and create/undo/redo ACK before another canvas tail, then original-source completion preserves content, focus, history and advanced versions');
 
+  // 另一个 partial 项目在未完整 owner 上有本地编辑；导航离开后由 project owner 采用新完整读取完成保存和同步。
   abandonedRoot=id(840);const backgroundRoot=abandonedRoot;
   documents.set(backgroundRoot,createDocument(backgroundRoot,[{id:backgroundRoot,parent:null}],[node('background-node',backgroundRoot,80),node('background-tail',backgroundRoot,450)]));versions.set(backgroundRoot,1);boards.push({id:backgroundRoot,workspace_id:workspace,kind:'board',version:1,title:'Background loading board'});
   await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${backgroundRoot}`});await until(`!!document.querySelector('[data-headless-canvas][data-model-loading] .react-flow__node[data-id="background-node"]')`,'background fixture did not open the prefix');
+  // 先原生编辑前缀并断言无 POST，再导航另一项目；检查后台取得非 NDJSON 新完整读且晚到旧流不能改当前路由。
   const backgroundPoint=await evaluate(`(()=>{const r=document.querySelector('.react-flow__node[data-id="background-node"] [aria-label^="单击选中"]').getBoundingClientRect();return{x:r.x+60,y:r.y+30};})()`);
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...backgroundPoint,button:'left',buttons:1,clickCount:2});await call('Input.dispatchMouseEvent',{type:'mouseReleased',...backgroundPoint,button:'left',buttons:0,clickCount:2});await until(`document.activeElement===document.querySelector('.react-flow__node[data-id="background-node"] textarea')&&!document.activeElement.readOnly`,'background prefix did not enter editing');await call('Input.insertText',{text:' background-local'});const backgroundText=await evaluate('document.activeElement.value');
   assert.equal(calls.filter(call=>call.method==='POST'&&call.path.includes('/'+backgroundRoot+'/canvas/model/operations')).length,0);
@@ -545,56 +688,70 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   for(let i=0;i<150&&documents.get(backgroundRoot).elements.get('background-node').data.text!==backgroundText;i++)await pause(20);assert.equal(documents.get(backgroundRoot).elements.get('background-node').data.text,backgroundText,'leaving the view stranded a local edit behind the loading hold');assert.ok(calls.some(call=>call.method==='GET'&&call.path.endsWith('/'+backgroundRoot+'/canvas/model')&&call.headers.accept!=='application/vnd.foundry.canvas-model+ndjson;version=1'));
   releaseAbandoned();await pause(100);assert.ok((await evaluate('location.pathname')).endsWith(other));console.log('PASS leaving a partial editor hands completion to the project owner, persists and synchronizes its edit through a fresh read without reopening the view');
 
+  // JSON 数组通过真实 file input 进入原生记录导入，既核对页面和服务内容，也在 reload 后检查来源文件名与作业。
   await evaluate(`(()=>{const transfer=new DataTransfer(),record={kind:'element',key:'json-ui',record:{id:'json-ui',incarnation:1,ownerCanvasId:'$target',componentId:'text',dataVersion:1,structure:'node',data:{title:'JSON array UI',text:'JSON array UI text'},geometry:{x:80,y:100,width:240,height:160,rotation:0}}};transfer.items.add(new File([JSON.stringify([record])],'records.json',{type:'application/json'}));const input=document.querySelector('input[data-canvas-import]');input.files=transfer.files;input.dispatchEvent(new Event('change',{bubbles:true}));})()`);
   await until(`document.querySelector('[aria-label="画布导入"]').textContent.includes('已加入画布')&&[...document.querySelectorAll('[data-headless-canvas] textarea')].some(input=>input.value==='JSON array UI text')`,'JSON array did not render through the file picker');
   for(let i=0;i<200&&![...documents.get(other).elements.values()].some(e=>e.data.title==='JSON array UI');i++)await pause(20);assert.ok([...documents.get(other).elements.values()].some(e=>e.data.title==='JSON array UI'));
   await call('Page.reload');await until(`[...document.querySelectorAll('[data-headless-canvas] textarea')].some(input=>input.value==='JSON array UI text')&&document.querySelector('[aria-label="画布导入"]').textContent.includes('records.json')`,'JSON array task/content did not recover after reload');
   console.log('PASS JSON array file picker imports and synchronizes native records then recovers its original task and content after reload');
+  // 临时拦截带 download 的 anchor，只读取 Blob 导出文本；随即恢复原 click，不真的发起下载。
   await evaluate(`(()=>{const original=HTMLAnchorElement.prototype.click;HTMLAnchorElement.prototype.click=function(){if(this.download){window.__exportedDocument=fetch(this.href).then(response=>response.text());return;}return original.call(this);};document.querySelector('[aria-label="导出图谱"]').click();HTMLAnchorElement.prototype.click=original;})()`);
+  // 完整文档导出格式为 1，重导入应增加与源元素数相同的新元素；parserVersion=5 核对使用流式文档解释器。
   const exported=await evaluate('window.__exportedDocument');assert.equal(JSON.parse(exported).documentFormatVersion,1);const beforeDocumentImport=documents.get(other).elements.size,roundTripElementCount=JSON.parse(exported).elements.length;
   await evaluate(`(()=>{const transfer=new DataTransfer();transfer.items.add(new File([${JSON.stringify(exported)}],'round-trip.json',{type:'application/json'}));const input=document.querySelector('input[data-canvas-import]');input.files=transfer.files;input.dispatchEvent(new Event('change',{bubbles:true}));})()`);
   await until(`document.querySelector('[aria-label="画布导入"]')?.textContent.includes('round-trip.json')&&[...document.querySelectorAll('[data-headless-canvas] textarea')].filter(input=>input.value==='JSON array UI text').length===2`,'exported document did not reimport');
   for(let i=0;i<200&&documents.get(other).elements.size!==beforeDocumentImport+roundTripElementCount;i++)await pause(20);assert.equal(documents.get(other).elements.size,beforeDocumentImport+roundTripElementCount);await call('Page.reload');await until(`document.querySelector('[aria-label="画布导入"]')?.textContent.includes('round-trip.json')&&[...document.querySelectorAll('[data-headless-canvas] textarea')].filter(input=>input.value==='JSON array UI text').length===2`,'document round trip task/content did not recover');
   assert.equal(await evaluate(`(()=>{const job=[...window.__fixtureActualEngine.imports.getJobs().values()].find(job=>job.source?.name==='round-trip.json');return job?.parserVersion;})()`),5,'document picker did not recover the streaming interpreter');
   console.log('PASS actual toolbar JSON export reimports through file picker with fresh elements and recovers after reload');
+  // 文档图片故意带现有 assetId 与不可信旧 src，导入必须重新授权并重建显示引用，不重复上传。
   const importedAssetId=[...assets.keys()][0],uploadsBeforeDocumentImage=uploads.length,imageImportDocument={documentFormatVersion:1,projectId:'image-source',canvases:[{id:'image-source',parent:null}],elements:[{id:'image-from-file',incarnation:1,ownerCanvasId:'image-source',componentId:'image',dataVersion:1,structure:'node',geometry:{x:400,y:100,width:200,height:100,rotation:0},data:{title:'Document imported image',text:'',assetId:importedAssetId,src:'https://untrusted.test/stale'}}],tombstones:{}};
   const beforeImageImport=documents.get(other).elements.size;
   await evaluate(`(()=>{const transfer=new DataTransfer();transfer.items.add(new File([${JSON.stringify(JSON.stringify(imageImportDocument))}],'image-document.json',{type:'application/json'}));const input=document.querySelector('input[data-canvas-import]');input.files=transfer.files;input.dispatchEvent(new Event('change',{bubbles:true}));})()`);
   for(let i=0;i<200&&![...documents.get(other).elements.values()].some(e=>e.data.title==='Document imported image');i++)await pause(20);assert.equal(documents.get(other).elements.size,beforeImageImport+1);const importedImage=[...documents.get(other).elements.values()].find(e=>e.data.title==='Document imported image');assert.equal(importedImage.data.assetId,importedAssetId);assert.notEqual(importedImage.data.src,'https://untrusted.test/stale');assert.equal(uploads.length,uploadsBeforeDocumentImage);
   await call('Page.reload');await until(`document.querySelector('[aria-label="画布导入"]')?.textContent.includes('image-document.json')&&!!document.querySelector('.react-flow__node[data-id="${importedImage.id}"] img')`,'authorized document image did not recover after reload');assert.equal(uploads.length,uploadsBeforeDocumentImage);
   console.log('PASS document image import reauthorizes existing resource, ignores stale URL and recovers without reuploading');
+  // 分别控制 parser I/O 与全源摘要：先挂住摘要 Worker 结果，让解析完成和来源验证可以独立观察。
   await evaluate(`(()=>{window.__fixtureDigestWaiting=false;window.__fixtureDigestGate=new Promise(resolve=>{window.__releaseSourceDigest=()=>{delete window.__fixtureDigestGate;resolve();};});})()`);
+  // GatedDocument.slice 只延迟 16KiB 解析读取且偏移至少 32KiB 的尾部；首项可先入画布，摘要由另一 gate 控制。
   await evaluate(`(()=>{const engine=window.__fixtureActualEngine,view=[...engine.sessions.getSnapshot().views.values()][0];let release;const gate=new Promise(resolve=>release=resolve);window.__releaseDocumentTail=()=>{window.__documentTailReleased=true;release();};class GatedDocument extends Blob{slice(start=0,end=this.size,...rest){const part=super.slice(start,end,...rest);if(end-start!==16384||start<32768||window.__documentTailReleased)return part;return{async arrayBuffer(){window.__documentTailWaiting=true;await gate;return part.arrayBuffer();}};}}const element=(id,text)=>({id,incarnation:1,structure:'node',ownerCanvasId:'stream-source',componentId:'text',dataVersion:1,data:{title:id,text},geometry:{x:0,y:0,width:260,height:200,rotation:0}}),input={documentFormatVersion:1,projectId:'stream-source',canvases:[{id:'stream-source',parent:null}],elements:[element('dom-prefix','Document progressive prefix'),element('dom-tail','x'.repeat(100000))],tombstones:{}};window.__streamDocumentJob=engine.imports.startDocument(new GatedDocument([JSON.stringify(input)]),view.canvasId);})()`);
+  // 确认 parser 尾部实际等待且未放开时，第一项 textarea 已挂载；随后原生输入必须能修改该前缀。
   await until(`(()=>{const job=window.__fixtureActualEngine.imports.getJobs().get(window.__streamDocumentJob),id=job.stableIds['element:dom-prefix'];window.__streamDocumentFirst=id;return window.__documentTailWaiting&&!window.__documentTailReleased&&!!document.querySelector('.react-flow__node[data-id="'+id+'"] textarea');})()`,'document prefix did not display while parser tail was blocked');
   await evaluate(`(()=>{const node=document.querySelector('.react-flow__node[data-id="'+window.__streamDocumentFirst+'"]');node.dispatchEvent(new MouseEvent('click',{bubbles:true}));node.querySelector('[aria-label^="单击选中"]').dispatchEvent(new MouseEvent('dblclick',{bubbles:true}));})()`);await until(`document.activeElement===document.querySelector('.react-flow__node[data-id="'+window.__streamDocumentFirst+'"] textarea')&&!document.activeElement.readOnly`,'progressive document prefix did not accept editing');await call('Input.insertText',{text:' edited before tail'});assert.equal(await evaluate(`window.__fixtureActualEngine.getSnapshot().document.elements.get(window.__streamDocumentFirst).data.text.endsWith('edited before tail')`),true);assert.equal(await evaluate('window.__documentTailReleased===true'),false);await evaluate('window.__releaseDocumentTail()');
+  // parser completed 时 sha256 仍缺失且服务还无首项；释放摘要后才同步，并保留摘要/尾部等待期间的用户编辑。
   await until(`window.__fixtureActualEngine.imports.getJobs().get(window.__streamDocumentJob).status==='completed'&&window.__fixtureDigestWaiting`,'streaming document did not complete parsing while full SHA was blocked');const streamFirstId=await evaluate('window.__streamDocumentFirst');assert.equal(await evaluate(`window.__fixtureActualEngine.imports.getJobs().get(window.__streamDocumentJob).source.sha256`),undefined);assert.equal(documents.get(other).elements.has(streamFirstId),false,'unverified source reached backend');await evaluate('window.__releaseSourceDigest()');for(let i=0;i<200&&!documents.get(other).elements.get(streamFirstId)?.data.text.endsWith('edited before tail');i++)await pause(20);assert.ok(documents.get(other).elements.get(streamFirstId).data.text.endsWith('edited before tail'));assert.equal(await evaluate(`window.__fixtureActualEngine.imports.getJobs().get(window.__streamDocumentJob).committedSourceKeys.length`),2);
   console.log('PASS actual document prefix displays and accepts native text edits before full SHA; parser completion cannot sync until verification, then preserves those edits');
 
 
 
 
+  // 两端节点矩形在视口外，但自定义曲线弯入视口；不能只用端点矩形决定把可见边和必要 owner 裁掉。
   const bowRoot=id(75);versions.set(bowRoot,1);boards.push({id:bowRoot,workspace_id:workspace,kind:'board',version:1,title:'Bowed paint board'});documents.set(bowRoot,createDocument(bowRoot,[{id:bowRoot,parent:null}],[{...node('bow-source',bowRoot,0),geometry:{x:0,y:2000,width:260,height:200,rotation:0}},{...node('bow-target',bowRoot,600),geometry:{x:600,y:2000,width:260,height:200,rotation:0}},{id:'bow-edge',incarnation:1,ownerCanvasId:bowRoot,structure:'connection',componentId:'connection',dataVersion:1,data:{},source:{elementId:'bow-source'},target:{elementId:'bow-target'},path:{type:'bezier-chain',knots:[{id:'bow-knot',mode:'corner',position:{x:400,y:0},in:{x:-100,y:0},out:{x:100,y:0}}]}}]));
   await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${bowRoot}`});await until(`!!document.querySelector('.react-flow__edge[data-id="bow-edge"] .react-flow__edge-path')`,'bowed curve fixture did not open');
   await evaluate(`(()=>{const pane=document.querySelector('.react-flow__pane'),r=pane.getBoundingClientRect(),m=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform);pane.dispatchEvent(new WheelEvent('wheel',{deltaX:(400*m.a+m.e-r.width/2)/.5,deltaY:(m.f-r.height/2)/.5,bubbles:true,cancelable:true}));})()`);
   await until(`(()=>{const viewport=document.querySelector('.react-flow__pane').getBoundingClientRect(),nodes=[...document.querySelectorAll('.react-flow__node')];return nodes.length===2&&nodes.every(node=>{const r=node.getBoundingClientRect();return r.bottom<viewport.top||r.top>viewport.bottom;})&&!!document.querySelector('.react-flow__edge[data-id="bow-edge"] .react-flow__edge-path');})()`,'offscreen endpoints caused visible bowed paint to unmount');
   assert.equal(documents.get(bowRoot).elements.size,3);console.log('PASS bowed curve paint remains mounted with both endpoint rectangles outside the viewport');
 
+  // 嵌套节点的拖动预览绑定起点坐标上下文；外部移动其 ancestor 时必须取消该预览。
   const contextRoot=id(852),contextChild=id(853),contextFrame={...node('context-frame',contextRoot,400),componentId:'frame',geometry:{x:400,y:100,width:640,height:400,rotation:0}},contextNode={...node('context-node',contextChild,50),geometry:{x:50,y:60,width:260,height:200,rotation:0}};
   documents.set(contextRoot,createDocument(contextRoot,[{id:contextRoot,parent:null},{id:contextChild,parent:{canvasId:contextRoot,entryElementId:contextFrame.id}}],[contextFrame,contextNode]));versions.set(contextRoot,1);versions.set(contextChild,1);boards.push({id:contextRoot,workspace_id:workspace,kind:'board',version:1,title:'Gesture context board'});
   await call('Page.navigate',{url:`http://127.0.0.1:${port}/dashboard/${workspace}/${contextRoot}`});await until(`!!document.querySelector('.react-flow__node[data-id="context-node"]')&&[...document.querySelectorAll('[role="status"]')].some(item=>item.textContent.trim()==='已同步')`,'nested gesture context board did not settle');
   await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+  // 先 elementFromPoint 证实子节点可点，原生按下/移动后等待实际手势 token，再通过公开命令移动父 frame。
   const contextPoint=await evaluate(`(()=>{const r=document.querySelector('.react-flow__node[data-id="context-node"] [aria-label^="单击选中"]').getBoundingClientRect();return{x:r.x+r.width*.3,y:r.y+Math.min(20,r.height*.2)}})()`);
   assert.equal(await evaluate(`document.elementFromPoint(${contextPoint.x},${contextPoint.y})?.closest('.react-flow__node')?.getAttribute('data-id')`),'context-node','nested test pointer is covered by another surface');
   await call('Input.dispatchMouseEvent',{type:'mousePressed',...contextPoint,button:'left',buttons:1,clickCount:1});await call('Input.dispatchMouseEvent',{type:'mouseMoved',x:contextPoint.x+35,y:contextPoint.y+25,button:'left',buttons:1});
   await until(`window.__fixtureActualEngine?.getSnapshot().document.projectId===${JSON.stringify(contextRoot)}&&window.__fixtureActualEngine.sessions.getSnapshot().gesture?.targets.some(target=>target.id==='context-node')`,'nested node did not acquire its drag');
   assert.equal(await evaluate(`window.__fixtureActualEngine.editor.dispatch({type:'element.geometry',target:{id:'context-frame',incarnation:1},patch:{x:600}}).status`),'applied');
+  // 父变换发布后预览应清空；迟到 mouseReleased 不得写子局部几何，页面改按新父位置投影。
   assert.equal(await evaluate('window.__fixtureActualEngine.sessions.getSnapshot().gesture'),null,'ancestor edit retained the old coordinate preview');
   await call('Input.dispatchMouseEvent',{type:'mouseReleased',x:contextPoint.x+35,y:contextPoint.y+25,button:'left',buttons:0});
   for(let i=0;i<100&&documents.get(contextRoot).elements.get('context-frame').geometry.x!==600;i++)await pause(20);
   assert.equal(documents.get(contextRoot).elements.get('context-frame').geometry.x,600);assert.deepEqual(documents.get(contextRoot).elements.get('context-node').geometry,contextNode.geometry);
   await until(`(()=>{const node=document.querySelector('.react-flow__node[data-id="context-node"]');return node&&Math.abs(new DOMMatrix(node.style.transform).m41-674)<.01&&!node.classList.contains('dragging');})()`,'nested node did not return to its new ancestor projection');
+  // 检查服务收到的 changes 只涉及父移动，不含 context-node，补足单看 DOM 复位无法证明的“未写旧坐标”。
   const contextWrites=calls.filter(call=>call.method==='POST'&&call.path.includes('/'+contextRoot+'/canvas/model/operations')).flatMap(call=>JSON.parse(call.bytes.toString()).operations.flatMap(operation=>operation.changes));assert.ok(contextWrites.length);assert.equal(contextWrites.some(change=>change.target?.id==='context-node'),false,'late nested drag wrote the old coordinate result');
   console.log('PASS ancestor movement cancels the actual nested drag; late pointerup preserves child geometry and renders its new parent position');
+  // 最后走实际账户菜单退出登录，要求安全到 /login 且无 render error；另核对至少有一次真实代理 NDJSON 协商。
   await click('账户和工作空间');await until(`!!document.querySelector('#workspace-account:popover-open')`,'account menu did not open');await evaluate(`[...document.querySelectorAll('button')].find(button=>button.textContent.trim()==='退出登录').click()`);
   await until(`location.pathname==='/login'&&!document.body.innerText.includes('This page couldn’t load')`,'logout did not safely detach the view');
   assert.ok(calls.some(call=>call.path.endsWith('/canvas/model')&&call.headers.accept==='application/vnd.foundry.canvas-model+ndjson;version=1'));
@@ -602,9 +759,13 @@ module.exports=function(source){return nativeTransform.call(this,source).replace
   console.log('PASS logout retires the runtime before dropping its view without a render error');
   }
 } finally {
+  // 统一放开挂起响应并关闭 CDP；不依赖正在等待 gate 的请求自行退出。
   releaseScopeStream();releaseAbandoned();releaseFirstModel();releaseImport();releaseApply();releaseUpload(); socket?.close();
+  // 先请求浏览器退出，三秒仍未结束则 SIGKILL，再等待 exit 并销毁输出流。
   if (chrome) { const exit = new Promise(resolve => { if (chrome.exitCode !== null) resolve(); else chrome.once('exit', resolve); }); chrome.kill(); await Promise.race([exit,pause(3000)]);if(chrome.exitCode===null)chrome.kill('SIGKILL');await exit;chrome.stdin?.destroy();chrome.stdout?.destroy();chrome.stderr?.destroy(); }
+  // 按进程组向 Next 发 SIGTERM，超时用 SIGKILL，避免只杀父进程留下编译子进程。
   if (next?.pid) { const exit = new Promise(resolve => { if (next.exitCode !== null) resolve(); else next.once('exit', resolve); }); try { process.kill(-next.pid, 'SIGTERM'); } catch {} await Promise.race([exit, pause(3000)]); if (next.exitCode === null) try { process.kill(-next.pid, 'SIGKILL'); } catch {} }
+  // 强制关闭上游残留连接再停止监听，最后删除本次应用和 profile 两个确切目录。
   upstream.closeAllConnections(); await new Promise(resolve => upstream.close(resolve));
   await rm(directory, { recursive: true, force: true, maxRetries: 5 }); await rm(profile, { recursive: true, force: true, maxRetries: 5 });
 }

tests/headless/renderers.test.mjs

@@ -1,30 +1,42 @@
+/**
+ * 渲染定义目录与 React 组装的契约测试。模型 registry 定义数据与能力，renderer catalog 定义宿主如何显示，两者按类型/版本/结构匹配。
+ * 这里检查描述捕获、投影记录与函数身份，不挂载真实 ReactFlow 页面。
+ */
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
 import {createRendererCatalog,builtinRendererDefinitions} from '../../src/lib/canvas-bindings/renderers.ts';
 import {createReactRenderers} from '../../src/lib/canvas-bindings/react-renderers.ts';
 import {createDocument,createRegistry,builtinComponents,defineComponent,movable,createEditor} from '../../src/lib/canvas-core/index.ts';
 import {projectCanvas} from '../../src/lib/canvas-bindings/projection.ts';
+// 自定义计量节点的精确渲染键，不允许用同一映射自动兼容未来版本或不同 structure。
 const descriptor={componentId:'plugin:meter',dataVersion:1,structure:'node',rendererId:'meter'};
+// 模型独立声明 metric 校验和移动能力；同一个模型可由多个宿主使用不同渲染器。
 const definition=defineComponent({id:'plugin:meter',dataVersion:1,structure:'node',validate:data=>typeof data.metric==='number',features:[movable()]}),registry=createRegistry([...builtinComponents(),definition]);
+// 保留不透明标题和看似内部字段的数据，用来核对投影注入的可信原记录不会被用户 data 冒充。
 const node={id:'meter',incarnation:1,ownerCanvasId:'root',structure:'node',componentId:'plugin:meter',dataVersion:1,data:{metric:7,title:{opaque:true},__headlessRecord:{untrusted:true}},geometry:{x:0,y:0,width:200,height:100,rotation:0}};
+// 目录只捕获不可变元数据，不持有 React render 值；输入描述后续变化无效，未来版本/不同结构不匹配，重复或保留 ID 被拒绝。
 test('renderer catalog captures exact version/structure mappings without React values or mutable descriptors',()=>{
  const input={...descriptor,render(){}};const catalog=createRendererCatalog([input]);input.rendererId='changed';assert.equal(catalog.resolve(node).rendererId,'meter');assert.equal(catalog.resolve({...node,dataVersion:2}),undefined);assert.equal(catalog.resolve({...node,structure:'connection'}),undefined);assert.equal(catalog.definitions[0].render,undefined);assert.ok(Object.isFrozen(catalog.definitions[0]));assert.throws(()=>createRendererCatalog([descriptor,descriptor]),/duplicate_renderer_definition/);assert.throws(()=>createRendererCatalog([{...descriptor,rendererId:'unsupported'}]),/invalid_renderer_definition/);
 });
+// 组装仅在同一个 render 实现时共享别名包装；拒绝空 renderer、ID 冲突与模型契约不符，getter 只读取一次并保留 memo 对象。
 test('React assembly preserves aliases only for the same component and rejects invalid renderers or model contracts',()=>{
  const render=()=>null,assembly=createReactRenderers([{...descriptor,render}],registry);assert.equal(assembly.nodeTypes.meter.type,render);assert.ok(Object.isFrozen(assembly.nodeTypes));assert.equal(assembly.edgeTypes.meter,undefined);
  assert.throws(()=>createReactRenderers([{...descriptor,render:null}]),/invalid_react_renderer/);assert.throws(()=>createReactRenderers([{...descriptor,render},{...descriptor,componentId:'other',render:()=>null}]),/renderer_id_conflict/);assert.throws(()=>createReactRenderers([{...descriptor,dataVersion:2,render}],registry),/renderer_model_mismatch/);
  let reads=0;const getter=createReactRenderers([{...descriptor,get render(){reads++;return render;}}]);assert.equal(reads,1);assert.equal(getter.definitions[0].render,render);assert.equal(getter.nodeTypes.meter,assembly.nodeTypes.meter);
  const alias=createReactRenderers([{...descriptor,render},{...descriptor,componentId:'other',render}]);assert.equal(alias.nodeTypes.meter,assembly.nodeTypes.meter);const memo={$$typeof:Symbol.for('react.memo'),type:render};assert.equal(createReactRenderers([{...descriptor,render:memo}]).nodeTypes.meter,memo);
 });
+// 自定义节点与边投影携带原记录和 transform，未知 data/path 不丢；未安装映射或未来 schema 走 unsupported。
 test('installed node and edge renderers receive original records and transforms while absent schemas still fall back',()=>{
  const customEdge=defineComponent({id:'plugin:edge',dataVersion:1,structure:'connection',validate:()=>true,features:[]}),r=createRegistry([...builtinComponents(),definition,customEdge]),other={...node,id:'second',geometry:{...node.geometry,x:300}},edge={id:'edge',incarnation:1,structure:'connection',componentId:'plugin:edge',dataVersion:1,ownerCanvasId:'root',source:{elementId:'meter',portId:'custom-out'},target:{elementId:'second',portId:'custom-in'},path:{type:'custom',retained:true},data:{path:{own:true},metric:99}},source=createDocument('project',[{id:'root',parent:null}],[node,other,edge]),catalog=createRendererCatalog([...builtinRendererDefinitions,descriptor,{...descriptor,componentId:'plugin:edge',structure:'connection',rendererId:'meter-edge'}]),p=projectCanvas(source,'root',r,new Set(),()=>undefined,null,catalog);
  assert.equal(p.nodes[0].type,'meter');assert.equal(p.nodes[0].data.__headlessFallback,undefined);assert.equal(p.nodes[0].data.__headlessRecord,source.elements.get('meter'));assert.deepEqual(p.nodes[0].data.__headlessRecord.data.title,{opaque:true});assert.equal(p.nodes[0].data.__headlessTransform.scale,1);assert.equal(p.edges[0].type,'meter-edge');assert.equal(p.edges[0].data.__headlessRecord,source.elements.get('edge'));assert.deepEqual(p.edges[0].data.__headlessRecord.path,{type:'custom',retained:true});
  const missing=projectCanvas(source,'root',r,new Set(),()=>undefined);assert.equal(missing.nodes[0].type,'unsupported');assert.equal(missing.edges[0].type,'unsupported');const future=createDocument('project',[{id:'root',parent:null}],[{...node,dataVersion:2}]);assert.equal(projectCanvas(future,'root',r,new Set(),()=>undefined,null,catalog).nodes[0].type,'unsupported');
 });
+// 加载前预览必须显式提供 preview，实现与正式 renderer 独立捕获；非法 preview 或不一致别名被拒绝。
 test('pre-engine preview renderers are explicit and captured independently from engine-bound renderers',()=>{
  const render=()=>null,preview=()=>null,assembly=createReactRenderers([{...descriptor,render,preview}]);assert.equal(assembly.nodeTypes.meter.type,render);assert.equal(assembly.previewNodeTypes.meter.type,preview);assert.equal(assembly.definitions[0].preview,preview);assert.ok(Object.isFrozen(assembly.previewNodeTypes));assert.equal(createReactRenderers([{...descriptor,render}]).previewNodeTypes.meter,undefined);assert.throws(()=>createReactRenderers([{...descriptor,render,preview:0}]),/invalid_react_preview/);assert.throws(()=>createReactRenderers([{...descriptor,render,preview},{...descriptor,componentId:'other',render}]),/renderer_id_conflict/);
 });
 
+// 两个宿主对同一 component 选择不同 rendererId，但共享同一文档记录与移动结果，命令仍只产生一个历史单元。
 test('independent host renderers for one component share model data and capability behavior',()=>{
  const editor=createEditor({registry,document:createDocument('project',[{id:'root',parent:null}],[node])}),one=createReactRenderers([{...descriptor,rendererId:'host-one',render:()=>null}],registry),two=createReactRenderers([{...descriptor,rendererId:'host-two',render:()=>null}],registry);
  assert.equal(editor.dispatch({type:'element.geometry',target:{id:node.id,incarnation:node.incarnation},patch:{x:42}}).status,'applied');

tests/headless/selection-listener-fixture.tsx

@@ -1,19 +1,30 @@
+/**
+ * 页面专用原生 ReactFlow selection 观察组件。默认不安装监听器，由外层测试 enable 后才挂载 Listener。
+ * 此 fixture 观察 ReactFlow 自己的选择事件和 nodeLookup，不代替业务文档或 headless session 的事实源。
+ */
 "use client";
 import {useCallback,useEffect,useState} from 'react';
 import {useOnSelectionChange,useStoreApi} from '@xyflow/react';
+// 把回调中的节点/边对象收窄成 ID 列表，避免把整个 renderer 对象留在测试事件日志。
 type Event={nodes:string[];edges:string[]};
+// 暴露启用、原生选择命令和当前节点选择查询，供浏览器脚本与 headless 选择行为对照。
 type Control={enable(value:boolean):void;select(ids:string[]):void;selected():string[]};
+// 仅在测试 Window 上声明控制接口与事件日志，不向生产 editor 注入状态。
 declare global{interface Window{__fixtureNativeSelection?:Control;__fixtureNativeSelectionEvents?:Event[];}}
+// 稳定 useCallback 记录 ID，再注册 useOnSelectionChange；组件卸载由 hook 解除观察。
 function Listener(){
  const onChange=useCallback((value:{nodes:{id:string}[];edges:{id:string}[]})=>{window.__fixtureNativeSelectionEvents?.push({nodes:value.nodes.map(node=>node.id),edges:value.edges.map(edge=>edge.id)});},[]);
  useOnSelectionChange({onChange});return null;
 }
-/** Isolated page fixture only; no observer is installed in performance builds. */
+/** 仅在隔离测试页面使用，性能构建不安装此观察器。 */
+// 持有 ReactFlow store 和启用开关；effect 注册控制对象，render 按开关决定是否安装监听器。
 export function NativeSelectionFixture(){
  const store=useStoreApi(),[enabled,setEnabled]=useState(false);
  useEffect(()=>{
+  // select 先清除再添加原生选中节点，selected 从 nodeLookup 查询；日志独立保存已收到的事件。
   const control:Control={enable:setEnabled,select(ids){store.getState().resetSelectedElements();store.getState().addSelectedNodes(ids);},selected(){return [...store.getState().nodeLookup.values()].filter(node=>node.selected).map(node=>node.id);}};
   window.__fixtureNativeSelection=control;window.__fixtureNativeSelectionEvents??=[];
+  // 只移除本 effect 注册的同一控制对象，旧 cleanup 不删除新挂载的控制接口；事件日志不在此清空。
   return()=>{if(window.__fixtureNativeSelection===control)delete window.__fixtureNativeSelection;};
  },[store]);
  return enabled?<Listener/>:null;

tests/headless/service.test.mjs

@@ -53,6 +53,11 @@ test('compiler freezes protocol 2 conditional changes and transports the exact o
   const calls=[],{port,request,compiled}=setup(async input=>{calls.push(input);return{status:200,body:{protocol_version:2,request_id:requestId,status:'applied',operation_ids:[operationId],model:chunk(false)}}});
   assert.equal(compiled.protocolVersion,2);assert.equal(request.protocolVersion,2);
   const body=JSON.parse(request.body);assert.deepEqual(body.operations,[{id:operationId,changes:intent.changes}]);assert.equal(Object.hasOwn(body,'document'),false);
+  // 严格 JSON 夹具的旁注：protocol_version=2 是请求协议，不是组件 dataVersion 或文档格式版本。
+  // request_id 使用本测试冻结请求 ID；expected_versions 只含参与根 canvas 的已确认版本 3。
+  // operations[0].id 是逻辑操作 ID；target.incarnation=1 防止相同元素 ID 的新生命期接收旧修改。
+  // changes 是 data.title 从 a 到 renamed 的条件修改；beforePresent/afterPresent 显式区分缺失字段和有值字段。
+  // 深比较覆盖整个编译请求形状；这个静态样例本身不证明真实后端已接受或持久化请求。
   assert.deepEqual(body,JSON.parse(await readFile(new URL('./fixtures/foundry-model-operation-v2.json',import.meta.url),'utf8')));
   const originalBytes=' \n'+request.body+'  ',frozen={...request,body:originalBytes};
   assert.equal((await port.submit(frozen,new AbortController().signal)).outcome,'applied');

tests/session-cookie.test.mjs

@@ -1,7 +1,12 @@
+/**
+ * 会话 cookie 的期限与属性单元测试。直接调用格式化函数，不连接浏览器 cookie jar 或真实认证后端。
+ * 后端剩余期限与前端 30 天上限取有效结果；数值 0 表示立即过期，非法输入回退默认值。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { sessionCookie, sessionMaxAge, SESSION_IDLE_SECONDS } from "../src/lib/session-cookie.ts";
 
+// 核对秒数常量、可解析整数字符串与最大期限；0 不可误回退，负数、非有限值、非整数等使用默认 30 天。
 test("session cookies respect backend remaining lifetime and a 30-day maximum", () => {
   assert.equal(SESSION_IDLE_SECONDS, 2592000);
   assert.equal(sessionMaxAge(2592000), 2592000);
@@ -12,6 +17,7 @@ test("session cookies respect backend remaining lifetime and a 30-day maximum",
   for (const invalid of [Infinity, "garbage", "1.5", NaN, {}, null]) assert.equal(sessionMaxAge(invalid), 2592000);
 });
 
+// 只检查生成的 Set-Cookie 文本：后端期限、HttpOnly、SameSite=Lax、可选 Secure 和 Max-Age=0；不代表端到端会话续期已验证。
 test("renewed cookies retain HttpOnly/SameSite and use the backend-capped deadline", () => {
   const cookie = sessionCookie("session-token", 42, true);
   assert.match(cookie, /Max-Age=42;/); assert.match(cookie, /HttpOnly/); assert.match(cookie, /SameSite=Lax/); assert.match(cookie, /; Secure$/);

tests/workspace.test.mjs

@@ -1,7 +1,12 @@
+/**
+ * workspace 首页、board 创建/重命名与 URL 的请求契约单元测试。request 替身记录调用次序和 payload，不运行 HTTP 或数据库。
+ * 首次创建 workspace 与 board 不是一个服务端事务：workspace 成功后需先通知调用者保留身份，即使后续 board 失败。
+ */
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { boardHref, createBoard, renameBoard, DEFAULT_BOARD_TITLE, loadWorkspaceHome } from "../src/lib/workspace.ts";
 
+// 把两个请求都挂起后检查启动记录，证明 profile/workspaces 无串行瀑布；分别释放再检查结果整合和头像。
 test("profile and workspace reads both start before either completes", async () => {
   const calls = [];
   const resolve = {};
@@ -20,6 +25,7 @@ test("profile and workspace reads both start before either completes", async ()
   assert.equal(result.workspaces[0].id, "space");
 });
 
+// 没有 workspace 时先创建个人空间并回调选中，再提交 board；标题去首尾空白，不能在通知调用者前继续第二步。
 test("a first board creates its personal workspace before posting the board", async () => {
   const calls = [];
   let selected = "";
@@ -44,6 +50,7 @@ test("a first board creates its personal workspace before posting the board", as
   assert.equal(calls[1][1].title, "周末的灵感");
 });
 
+// 第一次 board 失败仍保留回调给出的 workspace ID；重试只创建 board，个人空间计数仍为一。
 test("a board failure retains the new workspace, so retry creates no duplicate space", async () => {
   let selected = "";
   let spaces = 0;
@@ -68,6 +75,7 @@ test("a board failure retains the new workspace, so retry creates no duplicate s
   assert.equal(spaces, 1);
 });
 
+// 已有 workspace 直接向其 materials 提交，创建空间回调不得执行。
 test("an existing workspace posts a board directly", async () => {
   const calls = [];
   await createBoard(
@@ -83,6 +91,7 @@ test("an existing workspace posts a board directly", async () => {
 });
 
 
+// 空白名称回退默认图谱标题，payload 明确 kind/content schema；返回身份采用服务分配 ID，不能另造本地替代 ID。
 test("new graphs use a default name and retain the Foundry-assigned identity", async () => {
   const created = await createBoard(async (path, options) => {
     assert.equal(path, "workspaces/space/materials");
@@ -97,12 +106,14 @@ test("new graphs use a default name and retain the Foundry-assigned identity", a
   assert.equal(boardHref(created.workspace_id, created.id), "/dashboard/space/server-generated-id");
 });
 
+// workspace 和 board 分段编码，特殊斜线/问号不能改变路由结构；demo 查询参数单独追加。
 test("graph URLs preserve workspace identity and safely encode route segments", () => {
   assert.equal(boardHref("space/a", "id?b"), "/dashboard/space%2Fa/id%3Fb");
   assert.equal(boardHref("demo", "board", true), "/dashboard/demo/board?demo=1");
 });
 
 
+// 重命名前读取最新版本，以 If-Match=7 PATCH，保留 description/content；响应为空时 helper 合成标题及 version=8 返回值，非服务端实际版本证明。
 test("renaming reads the latest version and preserves description and content", async () => {
   const calls = [];
   const content = { schema_version: 1, preserved: { key: "value" } };
@@ -119,12 +130,14 @@ test("renaming reads the latest version and preserves description and content",
   assert.equal(renamed.version, 8);
 });
 
+// 空白或超过 100 字符的标题在请求前拒绝；用 assert.fail 确保没有任何 API 调用。
 test("rename rejects empty or oversized names without any API calls", async () => {
   for (const name of ["   ", "字".repeat(101)]) {
     await assert.rejects(renameBoard(() => assert.fail("unexpected API call"), "space", "board", name), /invalid_title/);
   }
 });
 
+// PATCH 版本冲突原样抛出且只调用一次，不能自动重试覆盖新内容。
 test("rename surfaces a version conflict without retrying or overwriting", async () => {
   let patches = 0;
   await assert.rejects(renameBoard(async (_path, options) => {