docs(tooling): explain SDK packaging and icon build configuration

2026-11-12 02:25:44 +08:00
9 changed files with 88 additions and 164 deletions
@@ -1,3 +1,8 @@
+/**
+ * 独立SDK的第二宿主示例与可执行断言：用自定义counter组件串起命令、事务拒绝、历史、手势、深复制、重开及投影命中。
+ * 包导入只使用core/runtime/bindings/service，验证这条路径不需要React、DOM或Next；示例需在已构建SDK包的解析环境执行。
+ * 存储与协议transport都是进程内模型，用于演示port契约，不实现生产数据库、身份鉴权、跨进程锁或崩溃持久化。
+ */
 /** A second host: no DOM, React, Next, React Flow or network service required.
 * Storage and protocol-2 transport below are in-memory examples, not a disk or
 * production server implementation. Replace them with your host's real ports.
@@ -9,15 +14,24 @@ import { openProjectEngine } from '@endoleap/headless-canvas/runtime';
 import {projectCanvas,createRendererCatalog,builtinRendererDefinitions,createGeometryProjectionCache,hitProjectedCanvas} from '@endoleap/headless-canvas/bindings';
 import { createFoundryPersistence, loadFoundryModel } from '@endoleap/headless-canvas/service';

+// 示例固定账户/工作区/项目作用域；真实宿主应从已验证身份和项目上下文建立隔离范围。
 const scope={accountId:'10000000-0000-4000-8000-000000000001',workspaceId:'10000000-0000-4000-8000-000000000002',projectId:'10000000-0000-4000-8000-000000000003'};
+// 内置组件之外注册counter：count要求非负安全整数，能力与矩形几何显式声明，资源与复制引用列表为空。
 const registry=createRegistry([...builtinComponents(),defineComponent({id:'example.counter',dataVersion:1,structure:'node',validate:data=>typeof data.title==='string'&&Number.isSafeInteger(data.count)&&data.count>=0,features:[editable(),movable(),resizable()],geometry:rectangleGeometry,resourceFields:[],copy:{references:[],omit:[]}})]);
+// 空项目只有根canvas；server/version模拟服务端基线，image模拟本地恢复镜像，两者职责分开。
 const original=createDocument(scope.projectId,[{id:scope.projectId,parent:null}],[]);
 let image=null,leader,fence=0,server=original,version=1;
+// files保存示例字节，requests按requestId保存原body和回执，供相同请求重试查询；均在进程结束后丢失。
 const files=new Map(),requests=new Map();
+/** 通过对象身份及active校验本地leader句柄；仅演示单进程fence，不是数据库条件写。 */
 const check=handle=>{assert.strictEqual(handle,leader);assert.equal(handle.active,true);};
+// StoragePort示例：claim取得独占句柄，recover读克隆镜像，commit先准备镜像/文件再一次同步发布。
 const storage={
+  /** 只允许一个活跃leader并递增fence；release幂等失效该句柄，不清除已提交镜像。 */
  async claim(requested){assert.equal(leader,undefined);assert.deepEqual(requested,scope);let active=true;const handle={scope:requested,fence:++fence,get active(){return active;},async release(){active=false;if(leader===handle)leader=undefined;}};leader=handle;return handle;},
+  /** 返回镜像克隆，调用方不能直接修改存储事实；空image代表首次打开。 */
  async recover(handle){check(handle);return structuredClone(image);},
+  /** 先检查文件新增不覆盖和删除列表，准备完成才发布；返回实际镜像rootRevision作为本地确认。 */
  async commit(handle,batch){
    check(handle);const cut=structuredClone(batch.image),nextFiles=new Map(files);
    for(const file of batch.files??[]){assert.equal(nextFiles.has(file.id),false);nextFiles.set(file.id,file.bytes);}
@@ -25,11 +39,15 @@ const storage={
    // Prepare before publishing. This is atomic in this process, not crash-durable storage.
    image=cut;files.clear();for(const entry of nextFiles)files.set(...entry);return{durableRootRevision:cut.rootRevision};
  },
+  /** 文件读取也校验leader；close断言所有engine已释放领导权，不负责清理生产存储。 */
  async readFile(handle,id){check(handle);return files.get(id);},close(){assert.equal(leader,undefined);},
 };
+/** 将模拟server的Map转成协议模型数组，带当前版本与墓碑；不把整个engine状态冒充服务端模型。 */
 const model=()=>({documentFormatVersion:1,projectId:scope.projectId,complete:true,canvases:[...server.canvases.values()],elements:[...server.elements.values()],tombstones:Object.fromEntries(server.tombstones),versions:{[scope.projectId]:version},removedCanvasIds:[]});
+/** 最小协议2传输适配：模型GET、请求回执GET及操作POST；未实现任意Foundry端点或HTTP鉴权。 */
 const transport=async input=>{
  input.signal?.throwIfAborted();
+  // 请求身份查询没命中时返回unknown，不伪造确定未应用回执；本示例记录不跨进程保存。
  if(input.method==='GET'){
    if(input.path.endsWith('/canvas/model'))return{status:200,body:{model:model()}};
    const id=input.path.split('/').at(-1),known=requests.get(id);
@@ -37,32 +55,45 @@ const transport=async input=>{
  }
  const body=JSON.parse(input.body),known=requests.get(input.requestId);
  assert.equal(body.protocol_version,2);assert.equal(body.request_id,input.requestId);
+  // 已有requestId只能复用完全相同的body并返回原回执，防止幂等键承载两种意图。
  if(known){assert.equal(known.body,input.body);return{status:200,body:known.receipt};}
+  // 示例只含一个canvas版本，先要求版本一致，再应用变更并验证整个文档；每次接受使版本递增一次。
  assert.deepEqual(body.expected_versions,{[scope.projectId]:version});
  server=applyChanges(server,body.operations.flatMap(operation=>operation.changes));validateDocument(server,registry);version++;
+  // 回执逐一覆盖operations逻辑ID，并携complete=false的模型切片；记录原body方便重试校验。
  const receipt={protocol_version:2,request_id:input.requestId,status:'applied',operation_ids:body.operations.map(operation=>operation.id),model:{...model(),complete:false}};
  requests.set(input.requestId,{body:input.body,receipt});return{status:200,body:receipt};
 };
+// service把transport包成runtime持久化接口；open示例总以初始模型输入，由StoragePort恢复已提交本地状态。
 const persistence=createFoundryPersistence({workspaceId:scope.workspaceId,rootId:scope.projectId,registry,transport});
+/** 新建engine注入scope/registry/storage/persistence与ID生成器，所有宿主依赖显式传入。 */
 const open=()=>openProjectEngine({scope,registry,document:original,versions:new Map([[scope.projectId,1]]),storage,persistence,createId:randomUUID});
 let engine=await open();
 try{
+  // 先创建一个counter并settle，后续断言分别验证本地发布及模拟server状态；元素带独立incarnation。
  const target={id:randomUUID(),incarnation:1};
  const element={...target,ownerCanvasId:scope.projectId,componentId:'example.counter',dataVersion:1,structure:'node',data:{title:'Portable counter',count:1},geometry:{x:0,y:0,width:160,height:80,rotation:0}};
  assert.equal(engine.editor.dispatch({type:'element.create',element}).status,'applied');await engine.settle();
+  // 非法事务先移动再写负count，最终必须整体rejected且根对象不变，不能泄露事务中间结果。
  const before=engine.getSnapshot();
  assert.equal(engine.editor.transaction(tx=>{tx.dispatch({type:'element.geometry',target,patch:{x:32}});tx.dispatch({type:'element.data',target,patch:{count:-1}});}).status,'rejected');assert.strictEqual(engine.getSnapshot(),before);
+  // 合法事务将移动和增量组合成一个历史单元；undo/redo之后均等待同步，再检查server的count。
  assert.equal(engine.editor.transaction(tx=>{tx.dispatch({type:'element.geometry',target,patch:{x:32}});tx.dispatch({type:'element.data',target,patch:{count:2}});},{label:'Move and increment'}).status,'applied');await engine.settle();
  assert.equal(engine.editor.history.undo().status,'applied');await engine.settle();assert.equal(server.elements.get(target.id).data.count,1);
  assert.equal(engine.editor.history.redo().status,'applied');await engine.settle();assert.equal(server.elements.get(target.id).data.count,2);
+  // 临时手势的有效几何可变化，但cancel后文档仍x=32且请求数不增加，证明预览未被当持久编辑发送。
  engine.sessions.attach('headless-view');const writes=requests.size;
  assert.equal(engine.sessions.begin('headless-view',[target]).enabled,true);engine.sessions.update('headless-view',target,{x:90});assert.equal(engine.sessions.effectiveGeometry(target.id).x,90);engine.sessions.cancel('example-cancel');await engine.settle();assert.equal(requests.size,writes);assert.equal(engine.getSnapshot().document.elements.get(target.id).geometry.x,32);
+  // 深复制走imports任务并等待settle，检查任务完成及本地/模拟服务端元素数；随后验证service模型可读。
  const copyId=await engine.imports.duplicate([target],{worldOffset:{x:24,y:24}});await engine.settle();assert.equal(engine.imports.getJobs().get(copyId).status,'completed',JSON.stringify(engine.imports.getJobs().get(copyId)));assert.equal(engine.getSnapshot().document.elements.size,2);assert.equal(server.elements.size,2);
  const loaded=await loadFoundryModel(transport,scope.workspaceId,scope.projectId,registry);assert.equal(loaded.status,'ready');assert.equal(loaded.document.elements.size,2);
+  // 关闭再打开依赖image恢复内容、历史和ledger；视图属于临时session，重开后不恢复。
  const snapshot=engine.getSnapshot(),undoDepth=snapshot.history.undo.length;await engine.close();engine=await open();await engine.settle();
  assert.equal(engine.getSnapshot().document.elements.size,2);assert.equal(engine.getSnapshot().document.elements.get(target.id).data.count,2);assert.equal(engine.getSnapshot().history.undo.length,undoDepth);assert.equal(engine.sessions.getSnapshot().views.size,0);assert.ok([...engine.getSnapshot().runtime.ledger.operations.values()].every(record=>record.phase==='resolved'));
+  // 自定义renderer只声明记录投影，不引入UI组件；配查询与几何缓存生成场景，再验证纯数据命中结果。
  const current=engine.getSnapshot(),queries=engine.editor.getQueries(),renderers=createRendererCatalog([...builtinRendererDefinitions,{componentId:'example.counter',dataVersion:1,structure:'node',rendererId:'counter',projection:'record-v1'}]);
  const projection=projectCanvas(current.document,scope.projectId,registry,new Set(),()=>undefined,null,renderers,{queries,geometry:createGeometryProjectionCache()});assert.equal(projection.nodes.length,2);assert.ok(projection.nodes.every(node=>node.type==='counter'&&node.data.__headlessRecord));
  const hit=hitProjectedCanvas(projection,queries,registry,'portable-view',{space:'scene',point:{x:40,y:10},zoom:1});assert.equal(hit.complete,true);assert.ok(hit.hits.some(hit=>hit.target.id===target.id));
+  // 输出可机器读取的结果摘要；finally即使断言失败也关闭engine并验证存储领导权已释放。
  console.log(JSON.stringify({status:'ok',portableBindings:true,elements:2,count:2,undoDepth,reopened:true,transientViews:0,protocol:2,requests:requests.size,sourceFiles:files.size}));
 }finally{await engine.close();storage.close();}
@@ -1,6 +1,12 @@
+/**
+ * Next应用配置。为webpack与Turbopack安装相同ReactFlow编译扩展，并给带内容摘要的图标分片设置长期缓存。
+ * 此处只配置应用编译/响应头，不改变headless SDK导出或服务端数据协议。
+ */
 import type { NextConfig } from "next";
+/** StrictMode显式开启开发检查，poweredByHeader关闭Next标识响应头；其余保持框架默认行为。 */
 const config: NextConfig = {
  reactStrictMode: true, poweredByHeader: false,
+  /** 在现有规则后追加匹配ReactFlow ESM入口的loader，再返回原配置对象，保留框架其它规则。 */
  webpack(config) {
    config.module.rules.push({
      test: /[\\/]@xyflow[\\/]react[\\/]dist[\\/]esm[\\/]index\.(?:mjs|js)$/,
@@ -8,6 +14,7 @@ const config: NextConfig = {
    });
    return config;
  },
+  // Turbopack使用条件路径匹配同一个入口；单独配置以免切换构建器时丢失保留节点扩展。
  turbopack: {
    rules: {
      "*": {
@@ -16,6 +23,8 @@ const config: NextConfig = {
      },
    },
  },
+  /** 只给版本目录内带12位十六进制摘要的JSON分片配置一年immutable缓存，文件内容变化应生成新文件名。
+   * 不对图标目录manifest、页面或全部JSON一概设置immutable。 */
  async headers() {
    return [{
      source: "/canvas-icons/:version/:asset([a-z0-9-]+-[a-f0-9]{12}\\.json)",
@@ -1 +1,5 @@
+/**
+ * CSS构建入口：启用项目安装的Tailwind PostCSS插件，供Next样式处理链读取。
+ * 插件选项为空对象表示使用默认配置；这里不执行CSS生成，也不在导入时启动构建。
+ */
 export default { plugins: { "@tailwindcss/postcss": {} } };
@@ -1,11 +1,19 @@
+/**
+ * 独立headless SDK的产物生成脚本。先清理.headless-dist，再用tsconfig.headless.json编译四个库目录，修正声明与Worker引用。
+ * 最后复制包清单、无UI宿主示例和验收文档；失败立即抛出，不把半成品报告成可用包。执行会删除并重建该产物目录。
+ */
 import { execFileSync } from 'node:child_process';
 import { cp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { join, resolve } from 'node:path';

+// 路径基于脚本URL而非当前终端目录；tsc仍显式以仓库根作为cwd解析项目依赖。
 const root=resolve(fileURLToPath(new URL('..',import.meta.url))),output=join(root,'.headless-dist');
 await rm(output,{recursive:true,force:true});
+// 同步等待TypeScript生成ESM及声明；继承终端输出，编译失败直接中止后续处理。
 execFileSync(process.execPath,[join(root,'node_modules/typescript/bin/tsc'),'-p',join(root,'tsconfig.headless.json')],{cwd:root,stdio:'inherit'});
+/** 递归只处理.d.ts的相对模块说明符，将源.ts后缀改为.js；普通schema/data字符串不做全局替换。
+ * 这是针对当前输出格式的正则修补，不是任意TypeScript语法的完整重写器。 */
 async function declarations(directory){
  for(const entry of await readdir(directory,{withFileTypes:true})){
    const path=join(directory,entry.name);
@@ -19,12 +27,15 @@ async function declarations(directory){
    }
  }
 }
+// 原生编译器处理运行时import后缀，声明文件仍需此补充；完成后再修URL字面量里的Worker源后缀。
 await declarations(join(output,'modules'));
+// 两个浏览器适配器各应含一个预期Worker URL；要求目标.js文件存在并且源字符串只出现一次才改写。
 for(const [module,worker]of [['browser-digests','digest.worker'],['browser-images','image.worker']]){
  const path=join(output,'modules/canvas-runtime',`${module}.js`),source=await readFile(path,'utf8'),before=`./${worker}.ts`;
  if(source.split(before).length!==2)throw Error(`Unexpected Worker URL in ${module}`);
  await readFile(join(output,'modules/canvas-runtime',`${worker}.js`));
  await writeFile(path,source.replace(before,`./${worker}.js`));
 }
+// 产物保留与headless/package.json的exports/files配套的模块布局；这里复制清单，不执行npm发布或包验收测试。
 for(const name of ['package.json','consumer.mjs','README.md','STEP4_ACCEPTANCE.md','SERVICE_ACCEPTANCE.md','FINAL_ACCEPTANCE.md'])await cp(join(root,'headless',name),join(output,name));
 console.log('Built .headless-dist: ESM, declarations, browser adapters and Worker modules');
@@ -1,3 +1,7 @@
+/**
+ * 图标资源生成时使用的中文标注表。作为静态元数据输入给generate-canvas-icons，不在运行时逐个请求翻译。
+ */
+/** 完整PascalCase图标名到中文标签的人工覆盖表；未列出的图标由生成脚本回退slug拆词名称。 */
 export const chinese = {
  "Star": "星星",
  "Heart": "爱心",
@@ -45,4 +49,5 @@ export const chinese = {
  "Triangle": "三角形",
  "Diamond": "菱形"
 };
+/** slug单词到中文检索词，生成时按连字符拆分并拼接；一个词可扩展多个搜索同义词。 */
 export const keywords = { arrow: "箭头 方向", user: "用户 人物", file: "文件 文档", folder: "文件夹 目录", heart: "爱心 喜欢", calendar: "日历 日期", clock: "时间 时钟", image: "图片 图像", camera: "相机 摄影", video: "视频 电影", music: "音乐 音频", cloud: "云 天气", sun: "太阳 天气", moon: "月亮 夜晚", circle: "圆 圆形", square: "方形 正方形", triangle: "三角形", building: "建筑 公司", book: "书 阅读", code: "代码 编程", chart: "图表 数据", mail: "邮件 信封", message: "消息 对话", map: "地图 位置", search: "搜索 查找", settings: "设置", lock: "锁 安全", key: "钥匙 密钥", star: "星星 收藏", check: "确认 完成", chevron: "箭头 展开", laptop: "电脑 笔记本", monitor: "屏幕 显示器", smartphone: "手机", shopping: "购物 商店", dollar: "货币 金钱", euro: "货币 欧元", zodiac: "星座", tree: "树 植物", flower: "花 植物", leaf: "叶子 植物", dog: "狗 动物", cat: "猫 动物", fish: "鱼 动物", coffee: "咖啡 饮料", food: "食物", smile: "表情 笑脸", angry: "表情 生气", frown: "表情 难过", paint: "绘画 颜色", palette: "调色板 颜色", text: "文本 文字", type: "字体 文字", grip: "拖动", move: "移动", zoom: "缩放", eye: "眼睛 显示", accessibility: "无障碍", audio: "音频 声音", battery: "电池", network: "网络 连接", wifi: "无线 网络", globe: "地球 全球", bell: "铃铛 通知", badge: "徽章", shield: "盾牌 安全", pencil: "铅笔 编辑", pen: "笔 写作", trash: "垃圾 删除", undo: "撤销", redo: "重做", rocket: "火箭", sparkles: "闪光 灵感", lightbulb: "灯泡 灵感" };
@@ -1,3 +1,7 @@
+/**
+ * 重建画布图标目录与路径分片的离线资源脚本。使用已安装Lucide与指定本地Tabler包，写目录JSON、摘要文件名分片和许可证。
+ * 版本检查固定输入格式；不会联网下载包，也不删除旧摘要分片，调用者需按脚本注释准备输入并从仓库根执行。
+ */
 // Reproduce with installed lucide-react 1.69.0 and an extracted @tabler/icons 3.50.0
 // tarball: node scripts/generate-canvas-icons.mjs /path/to/tabler/package
 import { readFile, writeFile, mkdir } from "node:fs/promises";
@@ -6,13 +10,16 @@ import { resolve } from "node:path";
 import dynamicIconImports from "lucide-react/dynamicIconImports";
 import { chinese, keywords } from "./canvas-icon-labels.mjs";

+// 命令行参数是已解压Tabler包目录；同时校验两套依赖版本，防止升级后未经审查改变SVG/导出结构。
 const tablerDir = process.argv[2];
 if (!tablerDir) throw new Error("Pass the extracted @tabler/icons 3.50.0 directory");
 const tablerPackage = JSON.parse(await readFile(resolve(tablerDir, "package.json"), "utf8"));
 if (tablerPackage.version !== "3.50.0") throw new Error("Expected @tabler/icons 3.50.0");
 const lucidePackage = JSON.parse(await readFile("node_modules/lucide-react/package.json", "utf8"));
 if (lucidePackage.version !== "1.69.0") throw new Error("Review generated assets when upgrading Lucide");
+/** slug按连字符转PascalCase；首字符非字母时加Icon前缀，形成稳定的目录ID。 */
 const pascal = (slug) => { const value = slug.split("-").map((word) => word[0].toUpperCase() + word.slice(1)).join(""); return /^[A-Z]/.test(value) ? value : "Icon" + value; };
+/** 用slug正则派生分类，一个图标可匹配多个；未匹配的记录categories为空，UI可归“其他”。 */
 const categories = [
  ["arrows", /arrow|chevron|navigation|corner|undo|redo|move|expand|shrink/],
  ["people", /user|person|baby|smile|frown|angry|laugh|heart|hand|thumb|accessibility/],
@@ -24,17 +31,21 @@ const categories = [
  ["travel", /map|pin|compass|globe|plane|train|car|bus|bike|ship|boat|building|house|home|tent|hotel|lighthouse|rocket|ufo/],
  ["shapes", /circle|square|triangle|hexagon|pentagon|octagon|diamond|star|shape|cube|sphere|box/],
 ];
+/** Lucide常用集合用于默认分类；Tabler试用集稍后全部标记common。 */
 const common = new Set(["Star", "Heart", "Lightbulb", "Sparkles", "Zap", "Target", "Check", "Smile", "Coffee", "Leaf", "Sun", "Moon", "Globe", "MapPin", "ArrowRight", "BookOpen", "FileText", "Folder", "Calendar", "Users", "Image", "Camera", "Music", "Palette"]);
+// Map以唯一name聚合元数据和SVG节点，Lucide加载器的__iconData提供路径，尚未在此写最终分片。
 const entries = new Map();
 for (const [slug, load] of Object.entries(dynamicIconImports)) {
  const name = pascal(slug);
  const { __iconData } = await load();
  entries.set(name, { name, slug, source: "lucide", label: chinese[name] || slug.replaceAll("-", " "), node: __iconData.node });
 }
+// Tabler只引入这24个outline图标，labels按同一索引配对；名称加Tabler前缀避免与Lucide冲突。
 const tabler = ["alien", "ufo", "robot", "brain", "circuit-cell", "cube-3d-sphere", "hexagon-3d", "building-lighthouse", "cat", "dog", "fish", "leaf", "sun", "moon", "rocket", "bulb", "heart", "star", "photo", "movie", "music", "palette", "coffee", "mountain"];
 const tablerLabels = ["外星人", "飞碟", "机器人", "大脑", "电路", "立体球", "立体六边形", "灯塔", "猫", "狗", "鱼", "叶子", "太阳", "月亮", "火箭", "灯泡", "爱心", "星星", "照片", "电影", "音乐", "调色板", "咖啡", "山峰"];
 for (const [index, slug] of tabler.entries()) {
  const svg = await readFile(resolve(tablerDir, "icons/outline", slug + ".svg"), "utf8");
+  // 仅提取已知SVG图形标签与双引号属性，把连字符属性转为React驼峰；不是任意SVG/HTML的通用解析器。
  const node = [...svg.matchAll(/<(path|circle|ellipse|rect|line|polyline|polygon)\s+([^>]+?)\/?\s*>/g)].map((match, index) => [match[1], Object.fromEntries([
    ["key", String(index)], ...[...match[2].matchAll(/([\w-]+)="([^"]*)"/g)].map(([, key, value]) => [key.replace(/-([a-z])/g, (_, char) => char.toUpperCase()), value]),
  ])]);
@@ -42,19 +53,24 @@ for (const [index, slug] of tabler.entries()) {
  const name = "Tabler" + pascal(slug);
  entries.set(name, { name, slug, source: "tabler", label: tablerLabels[index], node });
 }
+// 名称排序固定目录与后续分片插入顺序；相同输入有助于复现内容摘要。
 const records = [...entries.values()].sort((a, b) => a.name.localeCompare(b.name, "en"));
 const shards = new Map();
+/** 简单32位滚动hash模96，把Lucide名称稳定分桶；不是安全摘要，文件内容防缓存混淆另用SHA-256。 */
 const bucket = (name) => { let hash = 0; for (const char of name) hash = (hash * 31 + char.charCodeAt(0)) >>> 0; return hash % 96; };
+// 目录去掉SVG node，仅保留检索元数据；路径放入分片，Lucide分96桶，Tabler集中一个桶。
 const catalog = records.map(({ node, ...entry }) => {
  const key = entry.source === "tabler" ? "tabler" : `lucide-${bucket(entry.name)}`;
  if (!shards.has(key)) shards.set(key, {});
  shards.get(key)[entry.name] = node;
  return { ...entry, categories: categories.filter(([, regex]) => regex.test(entry.slug)).map(([id]) => id), common: common.has(entry.name) || entry.source === "tabler", keywords: entry.slug.split("-").map((word) => keywords[word] || "").join(" ") };
 });
+// 输出目录带两套版本，manifest把分片逻辑key映射到真实文件名；不在运行时猜hash路径。
 const assetDir = "public/canvas-icons/lucide-1.69.0-tabler-3.50.0";
 await mkdir(assetDir, { recursive: true });
 let totalBytes = 0;
 const assets = {};
+// 每个分片用紧凑JSON计算SHA-256前12位作文件名，写文件额外加换行；totalBytes统计未加换行的内容字节。
 for (const [key, nodes] of shards) {
  const content = JSON.stringify(nodes);
  const hash = createHash("sha256").update(content).digest("hex").slice(0, 12);
@@ -63,8 +79,10 @@ for (const [key, nodes] of shards) {
  await writeFile(`${assetDir}/${filename}`, content + "\n");
  totalBytes += Buffer.byteLength(content);
 }
+// 两份生成JSON分别服务搜索目录与按需加载器；严格JSON不能内嵌注释，其结构与生成流程在本脚本说明。
 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");
+// 分发路径数据同时复制原包许可证；最后只打印资源统计，不启动应用或验证浏览器显示。
 await writeFile(`${assetDir}/LUCIDE-LICENSE.txt`, await readFile("node_modules/lucide-react/LICENSE"));
 await writeFile(`${assetDir}/TABLER-LICENSE.txt`, await readFile(resolve(tablerDir, "LICENSE")));
 console.log(`${records.length} icons (${records.filter((item) => item.source === "tabler").length} Tabler), ${shards.size} data shards, ${totalBytes} uncompressed bytes`);
@@ -1,15 +1,25 @@
+/**
+ * 应用编译期的ReactFlow可见性扩展。为视口外但仍有焦点/手势/浮层的显式保留对象扩展原生可见集合。
+ * 只转换匹配到的编译输入字符串，不修改共享node_modules文件，也不进入独立headless SDK的运行逻辑。
+ */
 // App-only extension for the pinned @xyflow/react 12.12.1 ESM renderer. This
 // transforms compiler input; shared node_modules and the headless SDK are untouched.
+// 读取安装包版本，固定12.12.1；库升级必须人工审查目标实现，不能凭相同函数名继续替换。
 const version = require('@xyflow/react/package.json').version;
+/** webpack/Turbopack loader接收源码并返回改写后的源码；任何版本或锚点不符立即失败，防止悄悄失去保留能力。 */
 module.exports = function retainVisibility(source) {
  if (version !== '12.12.1') throw new Error('Review xyflow retained visibility before upgrading @xyflow/react');
+  // 四个精确源码锚点覆盖节点查询、边可见性及选择订阅；依赖上游编译格式，不是通用AST补丁。
  const nodes = 'getNodesInside(s.nodeLookup, { x: 0, y: 0, width: s.width, height: s.height }, s.transform, true).map((node) => node.id)';
  const edges = 'isEdgeVisible({\n                        sourceNode,';
  const selection = 'const changeSelector = (s) => !!s.onSelectionChangeHandlers;';
  const close = 'transform: s.transform,\n                    })) {';
+  // 每个锚点只能出现一次，并拒绝重复处理已含标记的输入；避免替换错位置或把运算括号重复扩展。
  if (source.includes('__endoleapRetain') || source.split(nodes).length !== 2 || source.split(edges).length !== 2 || source.split(close).length !== 2 || source.split(selection).length !== 2) {
    throw new Error('Unsupported xyflow visibility implementation; retained editors must not silently lose virtualization');
  }
+  // 节点追加未hidden且显式保留的ID并Set去重；边以保留标记或原可见判断二选一，维持原生索引。
+  // 最后一处改为空数组不订阅完整选择集合，减少无选择监听时的不必要全图selector工作。
  return source
    .replace(nodes, `Array.from(new Set([
      ...${nodes},
@@ -1,9 +1,3 @@
-/**
- * 旧版主画布的界面装配与交互控制。useCanvasTree拥有旧快照、writer、历史和子图事务，组件把其投影交给ReactFlow。
- * 本地state管理工具、模式、菜单与提示，refs保存拖动/连线起点及文件选择上下文；真实上传与演示Data URL分别处理。
- * 节点/连线组件通过Context调用适配动作，不直接修改投影；子图归属、端口连线和解散优先使用服务端能力与事务。
- * 迁移门闩暂停旧编辑和创作入口，给迁移协调组件提供检查、保存排空与备份；本文件不自行切换到新版engine。
- */
 "use client";
 import { useImageUploads } from "./use-image-uploads";
 import {LegacyCanvasMigration} from "./legacy-canvas-migration";
@@ -47,21 +41,15 @@ import type { NodeTransform } from "@/lib/canvas-geometry";
 import { MaterialNode, NodeEditing } from "./material-node";
 import styles from "./canvas.module.css";

-/** 旧边统一使用可编辑贝塞尔组件，节点按旧type名称分派；类型映射本身不持有元素实例数据。 */
 const edgeTypes = { default: CanvasEdge };
-/** 图标面板延迟在客户端加载，避免首屏加载目录面板及其交互代码；加载中提供可访问状态。 */
 const IconPicker = dynamic(() => import("./icon-picker").then((module) => module.IconPicker), { ssr: false, loading: () => <div role="status" className={styles.iconLoading}>正在加载图标面板…</div> });
-/** ReactFlow type到节点展示组件的固定表，须与makeCanvasNode/投影生成的type保持一致。 */
 const nodeTypes = { material: MaterialNode, plainText: PlainTextNode, icon: IconNode, frame: FrameNode, plainImage: PlainImageNode };

-/** 每个挂载对应一个board身份，初始快照/草稿只在useState初始化时采用；切画布应由上层key重挂载。 */
 function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: CanvasSnapshot; migration?:LegacyMigrationContext }) {
  const flow = useReactFlow<CanvasNode>();
  const { zoom } = useViewport();
  const reduceMotion = useReducedMotion();
  const storageKey = canvasStorageKey(board.workspace_id, board.id);
-  // 服务端快照优先，另有不同本地内容则等待恢复选择；无快照可直接用草稿。
-  // 视口独立读本地键并限制范围，损坏视口不阻断文档；草稿解码失败回退快照/空文档并提示。
  const [initial] = useState(() => {
    try {
      const local = readLocalRecovery(localStorage, storageKey, snapshot);
@@ -74,7 +62,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    } catch { return { document: snapshot?.document || emptyCanvas(), recovery: null, error: "无法读取此浏览器的图谱草稿，可通过导入恢复备份。" }; }
  });

-  // 工具与变换模式是界面状态，不放入文档；draggedIds仅驱动成员预览，membershipNotice短暂展示结果。
  const [tool, setTool] = useState<"select" | "hand">("select");
  const [error, setError] = useState(initial.error);
  const feedback = useContext(FeedbackContext);
@@ -85,35 +72,26 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
  const [rotating, setRotating] = useState<string | null>(null);
  const [draggedIds, setDraggedIds] = useState<string[]>([]);
  const [membershipNotice, setMembershipNotice] = useState("");
-  // 防节点拖动与多选拖动回调重复进入；起点按显示ID保存，连线屏幕起点用于区分点击与拉出新分支。
  const dragSession = useRef<"idle" | "active" | "finishing">("idle");
  const dragOrigins = useRef(new Map<string, XYPosition>());
  const draggingFrame = useRef(false);
  const connectionStart = useRef<{ id: string; direction: NodeDirection; point: XYPosition } | null>(null);
-  // 图片分支先保留源节点/方向/位置，等文件选择返回；cancel事件要清它，不能沿用上次创建意图。
  const pendingImage = useRef<BranchRequest | null>(null);
-  /** 稳定关闭回调供Portal菜单与画布事件共用，避免菜单因每次渲染重新安装监听。 */
  const closeBranch = useCallback(() => setBranchRequest(null), []);
  const imageKind = useRef<"image" | "plain-image">("image");
  const imageInput = useRef<HTMLInputElement>(null);
  const projectInput = useRef<HTMLInputElement>(null);
  const [recovery, setRecovery] = useState(initial.recovery);
-  // 根恢复待决时暂停保存；tree负责真实owner文档，UI显示节点来自其树投影。子图恢复按Map首项逐个处理。
  const tree = useCanvasTree(board.id, board.workspace_id, initial.document, snapshot, Boolean(recovery), board.parent_board_id, migration);
  const childRecovery = [...tree.recoveries][0];
-  /** 下载单份内存文档JSON备份，稍后释放Blob URL；不修改草稿选择，也不保证包含所有子图。 */
  const downloadDraft = (document: import("@/lib/canvas").CanvasDocument) => { const url = URL.createObjectURL(new Blob([JSON.stringify(document, null, 2)], { type: "application/json" })); const link = window.document.createElement("a"); link.href = url; link.download = "画布本地草稿.json"; link.click(); setTimeout(() => URL.revokeObjectURL(url), 1000); };
  const sync = tree;
-  // snapshot存在才执行真实AI；state.present组合根元数据与整树显示节点/边，不能把它当单board持久快照。
  const ai = useCanvasAI(board.workspace_id, board.id, !!snapshot, tree);
  const state = { present: { ...tree.rootDocument, nodes: tree.views.nodes, edges: tree.views.edges } };
  const treeRef = useRef(tree); treeRef.current = tree;
-  // 上传完成回调通过treeRef定位当前归属，并更新当前文档与历史；job.owner可能已不再是最新owner。
  const uploads = useImageUploads(board.workspace_id, (job, asset) => treeRef.current.resolveImageUpload(job.node.id, asset,{width:job.node.width!,height:job.node.height!}));
  const imageUploading = demoImageUploading;
-  // 文件导入等待期间的迁移检查标记；这不是通用导入队列，也不提供并发文件事务锁。
  const ioActive=useRef(false);
-  // 上传任务与文档都可能变化：按pendingUpload重新找owner，补资源或纯图片默认尺寸，避免移动/撤销后遗漏占位。
  useEffect(() => {
    const current = treeRef.current;
    for (const job of uploads.jobs) {
@@ -124,48 +102,38 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
      if (node.data.kind==="plain-image"&&node.width===320&&node.height===240&&(job.node.width!==320||job.node.height!==240)) current.resolveImageUpload(job.node.id,undefined,{width:job.node.width!,height:job.node.height!});
    }
  }, [uploads.jobs,tree.documents]);
-  /** undo/redo走异步树历史接口并显示失败，其余动作走根document reducer；不把服务端事务撤销当普通reducer动作。 */
  function dispatch(action: CanvasAction) {
    if (action.type === "undo" || action.type === "redo") { void treeRef.current[action.type]().catch((error) => setError(error.message)); return; }
    treeRef.current.dispatch(action);
  }
-  // 浏览器文件选择取消不触发普通onChange，单独监听cancel清理待建图片分支；卸载拆监听。
  useEffect(() => {
    const input = imageInput.current;
-    /** 取消本次选择意图，不删除已经存在的图片节点或中止已启动上传。 */
    const cancel = () => { pendingImage.current = null; };
    input?.addEventListener("cancel", cancel);
    return () => input?.removeEventListener("cancel", cancel);
  }, []);
  const { nodes: displayNodes, edges } = state.present;
-  // 对成员任务保护节点关闭拖动/删除/连接；tree.update内部仍保护相应数据，界面禁用不是唯一护栏。
  const nodes = displayNodes.map((node) => { const ref = tree.views.nodeRefs.get(node.id); const blocked = ref && tree.protectedNodes(ref.boardId).has(ref.id); return blocked ? { ...node, draggable: false, deletable: false, connectable: false } : node; });
-  /** 上传任务的本地nodeID映射到当前场景ID；尚无投影时按根/原owner构造兼容显示ID。 */
  const uploadDisplayID = (job: typeof uploads.jobs[number]) => [...tree.views.nodeRefs].find(([,ref])=>ref.id===job.node.id)?.[0] || displayID(board.id,job.owner,job.node.id);
-  // 预览URL按显示ID提供；正式图片onLoad再映射回job，上传完成的任务才回收本地URL。
  const imagePreviews = { sources: new Map(uploads.jobs.map((job) => [uploadDisplayID(job),job.localURL])), loaded: (id: string) => { const job = uploads.jobs.find((job) => uploadDisplayID(job)===id);if(job) uploads.loaded(job.node.id); } };

-  // 从场景节点派生分区名称、已有frameId计数与本次拖入/拖出候选，只作显示，不在此改变owner。
  const frameFeedback = useMemo(() => {
    const names = new Map(nodes.filter((node) => node.data.kind === "frame").map((node) => [node.id, node.data.title]));
    const counts = new Map<string, number>();
    for (const node of nodes) if (node.data.frameId) counts.set(node.data.frameId, (counts.get(node.data.frameId) || 0) + 1);
    return { names, counts, drops: frameDropFeedback(nodes, draggedIds) };
  }, [nodes, draggedIds]);
-  // 成员提示四秒后清理；重新提示重置计时器，卸载取消。
  useEffect(() => {
    if (!membershipNotice) return;
    const timer = setTimeout(() => setMembershipNotice(""), 4000);
    return () => clearTimeout(timer);
  }, [membershipNotice]);
-  // 全局反馈可用时把本地错误转成稳定ID通知并清本地error；无Provider时保留底部内联提示。
  useEffect(() => {
    if (!feedback || !error) return;
    const id = `canvas:${board.id}:error`;
    notify({ id, level: "error", title: error });
    setError("");
  }, [feedback, error, board.id]);
-  // 成员通知使用board级稳定ID，内容变化替换旧通知，清理时显式dismiss。
  useEffect(() => {
    if (!feedback || !membershipNotice) return;
    const id = `canvas:${board.id}:membership`;
@@ -173,40 +141,29 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    return () => dismissNotification(id);
  }, [feedback, membershipNotice, board.id]);
  const duration = reduceMotion ? 0 : 180;
-  /** 视口派发给根并独立写本地键；存储失败不打断浏览，内容writer自行判断是否需要服务端保存。 */
  const rememberViewport = (viewport: import("@xyflow/react").Viewport) => {
    treeRef.current.dispatch({ type: "viewport", viewport });
    try { localStorage.setItem(storageKey + ":viewport", JSON.stringify(viewport)); } catch { /* View changes do not require server writes. */ }
  };
-  /** 工具栏视口动画完成后保存实际视口；错误转界面提示，不提前记录尚未完成的目标值。 */
  const changeView = (operation: () => Promise<boolean>) => {
    void operation().then(() => rememberViewport(flow.getViewport())).catch((error) => setError(error.message));
  };

-  // latest保留当前显示几何，拖动结束基于最新节点计算成员反馈，避免只使用开始时的闭包。
  const latest = useRef(state.present);
  latest.current = state.present;

-  /** 显示ID的选择交tree解析owner；稳定回调通过treeRef避免每次文档更新重建编辑上下文。 */
  const select = useCallback((id: string) => treeRef.current.select(id), []);
-  /** 对目标owner建立checkpoint，把后续连续编辑归到同一撤销起点；缺目标时使用根board。 */
  const beginEdit = useCallback((id?: string) => { const current = treeRef.current; const ref = id ? current.views.nodeRefs.get(id) || current.views.edgeRefs.get(id) : undefined; current.dispatch({ type: "checkpoint" }, ref?.boardId || board.id); }, [board.id]);
-  /** 正文动作按投影ID定位原节点，reducer处理文本值与历史。 */
  const edit = useCallback((id: string, text: string) => treeRef.current.nodeAction(id, (id) => ({ type: "edit", id, text })), []);
-  /** 打开分支类型菜单并退出变换模式，point用于屏幕定位。 */
  const branch = useCallback((id: string, direction: NodeDirection, point: XYPosition) => { setBranchRequest({ id, direction, point }); setRotating(null); setResizing(null); }, []);
-  /** 将场景位置减owner原点再除scale，宽高也除scale；旋转等其余字段直接交旧transform动作。 */
  const transform = useCallback((id: string, transform: NodeTransform) => {
    const ref = treeRef.current.views.nodeRefs.get(id); if (!ref) return;
    treeRef.current.nodeAction(id, (id) => ({ type: "transform", id, transform: { ...transform,
      ...(transform.position ? { position: { x: (transform.position.x - ref.origin.x) / ref.scale, y: (transform.position.y - ref.origin.y) / ref.scale } } : {}),
      ...(transform.width !== undefined ? { width: transform.width / ref.scale, height: transform.height! / ref.scale } : {}) } }));
  }, []);
-  /** 样式适配只构造旧style动作，具体字段合并由reducer处理。 */
  const style = useCallback((id: string, style: TextStyle, fontSize?: number) => treeRef.current.nodeAction(id, (id) => ({ type: "style", id, style, fontSize })), []);
-  /** 节点名称通过owner映射更新，避免将显示复合ID当持久ID。 */
  const rename = useCallback((id: string, title: string) => treeRef.current.nodeAction(id, (id) => ({ type: "rename-node", id, title })), []);
-  /** 分区属性以replace提交；折叠切换从已保存expanded/collapsedSize或默认值恢复尺寸，并写node与style。 */
  const frame = useCallback((id: string, patch: { title?: string; labelMode?: FrameLabelMode; presentation?: import("@/lib/canvas-v2").FramePresentation }) => {
    const current = treeRef.current, ref = current.views.nodeRefs.get(id); if (!ref) return;
    const document = current.documents.get(ref.boardId)!;
@@ -217,9 +174,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
      return { ...node, ...(size ? { ...size, style: { ...node.style, ...size } } : {}), data: { ...node.data, ...patch } };
    }) } }, ref.boardId);
  }, []);
-  // 注入节点动作及本地旋转/拉伸模式，两模式互斥；旧版接口没有新版手势token租约。
  const editing = useMemo(() => ({ begin: beginEdit, select, edit, branch, transform, style, rename, frame, workspace: board.workspace_id, schema: 2 as const, rotating, resizing, resize: (id: string | null) => { setResizing(id); setRotating(null); }, rotate: (id: string | null) => { setRotating(id); setResizing(null); } }), [beginEdit, select, edit, branch, transform, style, rename, frame, rotating, resizing, board.workspace_id, state.present.schema_version]);
-  /** 在源owner文档创建节点与连线，at从场景坐标转局部；发布后尝试把视口移向新节点，异常留作提示。 */
  function createBranch(request: BranchRequest, kind: "text" | "image" | "script", src?: string) {
    try {
      const document = branchCanvasNode(tree.documents.get(tree.views.nodeRefs.get(request.id)!.boardId)!, tree.views.nodeRefs.get(request.id)!.id, request.direction, kind, src, request.at ? { x: (request.at.x - tree.views.nodeRefs.get(request.id)!.origin.x) / tree.views.nodeRefs.get(request.id)!.scale, y: (request.at.y - tree.views.nodeRefs.get(request.id)!.origin.y) / tree.views.nodeRefs.get(request.id)!.scale } : undefined);
@@ -229,13 +184,11 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
      setBranchRequest(null);
    } catch (error) { setError(error instanceof Error ? error.message : "无法创建节点。"); }
  }
-  /** 图片分支需要文件选择才能创建，先保存request并关菜单；文本/脚本立即创建。 */
  function chooseBranch(kind: "text" | "image" | "script") {
    if (!branchRequest) return;
    if (kind === "image") { pendingImage.current = branchRequest; imageKind.current = "image"; setBranchRequest(null); imageInput.current?.click(); }
    else createBranch(branchRequest, kind);
  }
-  /** 无有效目标的连接拖动若移动至少5px并落到空白pane，且源仍选中，则在落点打开分支菜单。 */
  const connectionEnd: OnConnectEnd = (event, connection) => {
    const start = connectionStart.current;
    connectionStart.current = null;
@@ -248,13 +201,11 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    setBranchRequest({ id: start.id, direction: start.direction, point: { x: point.clientX, y: point.clientY }, at });
  };

-  /** 按窗口中心转换为场景点并加六档偏移，减少连续添加完全重叠；不是按编辑器容器中心计算。 */
  const center = () => {
    const point = flow.screenToFlowPosition({ x: window.innerWidth / 2, y: window.innerHeight / 2 });
    const offset = (nodes.length % 6) * 18;
    return { x: point.x - 130 + offset, y: point.y - 80 + offset };
  };
-  /** 根节点上限500；真实分区走subgraphs命令创建子画布，其它节点本地加入，演示frame也走本地模型。 */
  function addNode(kind: CanvasNode["data"]["kind"], src?: string, size?: { width: number; height: number }, title?: string) {
    if (tree.rootDocument.nodes.length >= 500) { setError("当前图谱已达到 500 个节点，请新建图谱继续创作。"); return; }
    const node = makeCanvasNode(kind, center(), src);
@@ -267,7 +218,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    dispatch({ type: "nodes", changes: [{ type: "add", item: node }] });
    setTool("select");
  }
-  /** 一次replace插入三张预填卡片和两条连线，预留三个节点容量并切回选择工具；不触发AI生成。 */
  function addTemplate() {
    if (tree.rootDocument.nodes.length > 497) { setError("当前图谱没有足够空间插入模板。"); return; }
    const position = center();
@@ -283,7 +233,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    ] } });
    setTool("select");
  }
-  /** idle才建立checkpoint与拖动起点；有frame参与则不显示普通拖入预览，防止移动分区误收纳覆盖内容。 */
  function beginDrag(node: CanvasNode, dragged: CanvasNode[]) {
    if (dragSession.current !== "idle") return; dragSession.current = "active"; tree.setDragging(true);
    beginEdit(node.id); closeBranch(); setRotating(null); setResizing(null);
@@ -293,8 +242,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    setDraggedIds(draggingFrame.current ? [] : [...dragOrigins.current.keys()]);
    setMembershipNotice("");
  }
-  /** 只结束active拖动，先清拖动/保存暂停标记，再按真实位移计算归属；真实子图与旧frameId归属分路处理。
-   * 异步移动失败保留错误提示，不宣称所有跨分区步骤一起回滚。 */
  async function finishDrag(node: CanvasNode, dragged: CanvasNode[]) {
    if (dragSession.current !== "active") return;
    const origins = new Map(dragOrigins.current);
@@ -305,23 +252,19 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
      if (ids.length) {
        const positions = new Map(items.map((item) => [item.id, item.position]));
        const dropped = latest.current.nodes.map((item) => positions.has(item.id) ? { ...item, position: positions.get(item.id)! } : item);
-        // 先生成“加入/移出”展示文案；实际owner由下面的真实子图路径重新判定，成功后才显示结果通知。
        const changed = frameDropFeedback(dropped, ids).filter((item) => item.from !== item.to);
        const messages = changed.map((item) => item.to ? `已加入「${frameFeedback.names.get(item.to) || "分区"}」` : `已移出「${frameFeedback.names.get(item.from!) || "分区"}」`);
        const notice = messages.length ? `${changed.length > 1 ? `${changed.length} 项内容：` : ""}${[...new Set(messages)].join("；")}` : "";
        if (snapshot && tree.rootDocument.schema_version === 2) {
          try {
-            // 按source/target分组，同组节点一起迁移；候选分区按面积升序，优先最小包围分区。
            const byOwner = new Map<string, { ids: string[]; target: string }>();
            const parents = subgraphParents(tree.current.current);
            for (const item of items.filter((item) => ids.includes(item.id))) {
              const ref = tree.views.nodeRefs.get(item.id); if (!ref) continue;
              const center = { x: item.position.x + (item.width || 260) / 2, y: item.position.y + (item.height || 200) / 2 };
-              /** 沿子图父链防环检查，不能把分区入口移动进自己的后代，形成结构循环。 */
              const inMovingSubtree = (child: string) => { const seen = new Set<string>(); let cursor: string | undefined = child; while (cursor && !seen.has(cursor)) { if (cursor === item.data.subgraph?.boardId) return true; seen.add(cursor); cursor = parents.get(cursor)?.boardId; } return false; };
              const candidates = dropped.filter((candidate) => candidate.id !== item.id && candidate.data.subgraph && !inMovingSubtree(candidate.data.subgraph.boardId) && center.x >= candidate.position.x && center.y >= candidate.position.y && center.x <= candidate.position.x + (candidate.width || 640) && center.y <= candidate.position.y + (candidate.height || 400)).sort((a, b) => (a.width || 640) * (a.height || 400) - (b.width || 640) * (b.height || 400));
              const target = candidates[0]?.data.subgraph?.boardId || (ref.boardId === board.id ? board.id : parents.get(ref.boardId)?.boardId) || board.id;
-              // 未上传且满足条件的占位图片先走本地迁移；其它节点需要服务端成员事务。
              if (target !== ref.boardId && tree.current.current.get(ref.boardId)?.nodes.find((node)=>node.id===ref.id)?.pendingUpload) {
                tree.movePendingImage(ref.boardId,target,ref.id);continue;
              }
@@ -329,7 +272,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
                const key = ref.boardId + "/" + target, group = byOwner.get(key) || { ids: [], target }; group.ids.push(ref.id); byOwner.set(key, group);
              }
            }
-            // 不同owner组并行提出任务，每组沿父子路径逐跳等待；tree内部队列仍串行发送成员请求。
            await Promise.all([...byOwner].map(async ([key, group]) => {
              let source = key.split("/")[0];
              for (const hop of subgraphMovePath(tree.current.current, source, group.target)) {
@@ -345,12 +287,10 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
      }
    }
  }
-  /** 先把入口端口解析成实际内部节点；同owner本地加边，跨owner优先服务端connections事务，缺能力时尝试暴露端口适配。 */
  async function connect(connection: Connection) {
    const source = tree.views.nodeRefs.get(connection.source), target = tree.views.nodeRefs.get(connection.target);
    if (!source || !target) return;
    try {
-      /** 按深度计数0—8解析子图入口，每层必须找到明确port映射；仍未到实际节点或缺端口则拒绝。 */
      const resolve = async (ref: typeof source, handle: string | null | undefined): Promise<{ boardId: string; id: string; handle: string }> => {
        let endpoint = { boardId: ref!.boardId, id: ref!.id, handle: handle || "right" };
        for (let depth = 0; depth <= 8; depth++) {
@@ -363,7 +303,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
        throw new Error("subgraph_cycle");
      };
      const realSource = await resolve(source, connection.sourceHandle), realTarget = await resolve(target, connection.targetHandle || "left");
-      // 同一canvas快照可直接加边；跨canvas需要共同上层/边界端口关系，不能把显示端点直接写进任一子快照。
      if (realSource.boardId === realTarget.boardId) {
        const document = tree.current.current.get(realSource.boardId)!;
        tree.dispatch({ type: "replace", document: { ...document, schema_version: 2, edges: addEdge({ id: crypto.randomUUID(), source: realSource.id, target: realTarget.id, sourceHandle: realSource.handle, targetHandle: realTarget.handle }, document.edges) } }, realSource.boardId);
@@ -377,13 +316,11 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
          return;
        }
      }
-      // 兼容路径由exposedConnection提供可寻址端点与owner，失败提示跨画布连接暂不可用。
      const exposed = exposedConnection(tree.current.current, realSource, realTarget);
      const document = tree.current.current.get(exposed.boardId)!;
      tree.dispatch({ type: "replace", document: { ...document, schema_version: 2, edges: addEdge({ ...connection, source: exposed.source.id, target: exposed.target.id, sourceHandle: exposed.source.handle, targetHandle: exposed.target.handle, id: crypto.randomUUID() }, document.edges) } }, exposed.boardId);
    } catch (error) { setError(error instanceof Error && error.message === "boundary_port_required" ? "跨画布连接暂不可用，请稍后重试。" : errorText(error)); }
  }
-  /** 校验MIME与大小并清文件input；迁移期间拒绝。真实画布通过上传占位，演示以Data URL直接加入。 */
  async function readImage(event: ChangeEvent<HTMLInputElement>) {
    const file = event.target.files?.[0];
    event.target.value = "";
@@ -394,7 +331,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    }
    const request = pendingImage.current; pendingImage.current = null;
    const kind = imageKind.current;
-    // 真实图片上传先取得本地Blob预览并构造draft，随后把pendingUpload节点及可选分支边发布到owner。
    if (snapshot) {
      try { const job = uploads.start(file, (src) => {
        const current = treeRef.current;
@@ -407,14 +343,12 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
        const node=makeCanvasNode(kind,center(),src);if(kind==='plain-image')node.data.title=file.name.slice(0,300);
        return {owner:board.id,node};
      });
-      // pendingUpload以node.id标记，后续资源完成/跨区移动/历史恢复都按这个身份找到占位。
      const current=treeRef.current,doc=current.current.current.get(job.owner)!;
      const node={...job.node,pendingUpload:job.node.id};
      current.dispatch({type:"replace",document:{...doc,nodes:[...doc.nodes,node],edges:[...doc.edges,...(job.edge?[job.edge]:[])]}},job.owner);
      setTool("select"); } catch(error) {setError(errorText(error));}
      return;
    }
-    // 演示不上传服务端，FileReader读取全部字节为Data URL；纯图片另解码初始尺寸，finally释放读取中UI状态。
    setImageUploading(true);
    try {
      const src = await new Promise<string>((resolve, reject) => {
@@ -436,8 +370,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    } catch (error) { pendingImage.current = null; setError(errorText(error)); }
    finally { setImageUploading(false); }
  }
-  /** 旧版导入最多5MB并全量读取解码，替换当前根快照；任一方含真实子图时拒绝，避免破坏跨board关系。
-   * ioActive用于阻止迁移交接；这条路径不是新版渐进导入，也不会自动重建bundle子图。 */
  async function importProject(event: ChangeEvent<HTMLInputElement>) {
    const file = event.target.files?.[0];
    event.target.value = "";
@@ -455,8 +387,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    } catch (error) { setError(error instanceof Error ? error.message : "导入失败。"); }
    finally{ioActive.current=false;}
  }
-  /** 有上传占位则先等待用户完成；树导出完整可达文档，多board写bundle，单board写当前视口。
-   * 下载名清理文件名非法字符，Blob URL延迟释放；不额外打包File/Blob，已有演示Data URL仍随src导出。 */
  async function exportProject() {
    let documents: Map<string, import("@/lib/canvas").CanvasDocument>;
    try { if([...tree.current.current.values()].some((doc)=>doc.nodes.some((node)=>node.pendingUpload))) throw new Error("图片仍在上传，完成后即可导出。"); documents = await tree.exportDocuments(); } catch (error) { setError(error instanceof Error ? error.message : "导出未完成"); return; }
@@ -469,9 +399,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    setTimeout(() => URL.revokeObjectURL(url), 1000);
  }

-  // 旧版全局快捷键：跳过输入框、文本编辑、对话框和打开的popover，支持撤销/重做与V/H；卸载移除。
  useEffect(() => {
-    /** 按DOM目标过滤后处理键；此旧路径没有新版routeCanvasKey的组合输入/认领优先级模型。 */
    const keydown = (event: KeyboardEvent) => {
      const target = event.target;
      if (!(target instanceof HTMLElement)) return;
@@ -489,11 +417,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    return () => window.removeEventListener("keydown", keydown);
  }, []);

-  // Provider把图片预览、节点动作、分区反馈及活动连线接到renderer；迁移时surface与底部创作栏设inert。
-  // ReactFlow删除由onBeforeDelete拦截真实子图/暴露端口节点，避免默认删除破坏结构；普通元素沿tree变化入口。
-  // 选择工具允许拖动/连接，抓手只平移；Space临时平移、Shift部分框选，滚轮默认平移、修饰键缩放。
-  // 工具栏创建/模板/导入走上述入口，顶部视口操作保存本地viewport；AI只给选中且支持的节点显示。
-  // 恢复弹窗先根再子，逐项核查canRestore；迁移组件检查草稿、文件IO和未完成上传再排空writer。
  return (
    <div className={`${styles.editor} ${tool === "hand" ? styles.handMode : ""}`}>
      <ImagePreviews.Provider value={imagePreviews}>
@@ -504,7 +427,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
        <ReactFlow<CanvasNode> nodes={nodes} edges={edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes}
          onBeforeDelete={async ({ nodes: removing }) => {
            if (tree.busy || tree.transactionBusy) return false;
-            // 选中分区入口要先dissolve保留内容；内部节点若被父port引用，先移回父board再删，清理边界引用。
            const linked = removing.filter((node) => node.data.subgraph);
            const parents = subgraphParents(tree.current.current);
            const referenced = removing.filter((node) => {
@@ -514,7 +436,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
            });
            if (!linked.length && !referenced.length) return true;
            try {
-              // 分区逐个事务解散，参与者包含父、子、孙及需要调整引用的祖先；并非一批选择全体原子操作。
              for (const node of linked) {
                const ref = tree.views.nodeRefs.get(node.id)!;
                await tree.ensure(node.data.subgraph!.boardId);
@@ -524,7 +445,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
                if (ancestor && subgraphMoveParticipants(tree.current.current, ref.boardId, node.data.subgraph!.boardId, ref.boardId, child.nodes.map((item) => item.id)).includes(ancestor)) participants.add(ancestor);
                await tree.command(ref.boardId, `subgraphs/${ref.id}/dissolve`, {}, [...participants]);
              }
-              // 解散后owner可能变化，按原ID重新查唯一归属；找不到唯一目标就跳过，不误删同ID的其它节点。
              for (const node of removing.filter((node) => !node.data.subgraph)) {
                const ref = tree.views.nodeRefs.get(node.id); if (!ref) continue;
                let owner = ref.boardId;
@@ -541,7 +461,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
              }
              if (linked.length) setMembershipNotice("已解散选框，子画布内容已保留");
            } catch (error) { setError(error instanceof Error ? error.message : "删除未完成"); }
-            // 结构分支已自行执行删除/解散，阻止ReactFlow再按旧投影默认删一遍。
            return false;
          }}
          onNodesChange={tree.nodesChanged}
@@ -567,7 +486,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
          defaultEdgeOptions={{ style: { stroke: "#aa968b", strokeWidth: 1.5 } }}>
          <Background variant={BackgroundVariant.Dots} gap={22} size={1} color="#c9bfb5" />
          {ai.enabled && nodes.filter((node) => node.selected && ["text", "script", "plain-text", "image", "plain-image"].includes(node.data.kind)).map((node) => {
-            // AIPanel收到owner原始节点，显示ID仅用于NodeToolbar定位；save仍经tree.nodeAction回写owner。
            const ref = tree.views.nodeRefs.get(node.id)!;
            const owned = tree.documents.get(ref.boardId)?.nodes.find((item) => item.id === ref.id);
            return owned && <AIPanel key={node.id} id={node.id} node={owned} workspace={board.workspace_id} boardId={ref.boardId} ai={ai} save={(config) => tree.nodeAction(node.id, (id) => ({ type: "node-data", id, patch: { ai: config } }))} />;
@@ -640,7 +558,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
        <button onClick={exportProject}>导出当前内容</button><button onClick={() => window.location.reload()}>重新读取</button>
      </div>}
      {tree.memberJobs.map((job, index) => job.ids.map((id) => {
-        // 成员任务提示跟随当前source/target中的场景节点，队首同步、后续等待，失败通过retryMembers继续。
        const node = [...tree.views.nodeRefs].find(([, ref]) => ref.id === id && [job.source, job.target].includes(ref.boardId));
        return node && <NodeToolbar key={`${job.source}/${id}`} nodeId={node[0]} isVisible position={Position.Top}>
          <div className={`${styles.memberSync} nodrag nopan`} role="status" aria-label="元素同步状态" data-node-id={node[0]}>
@@ -660,7 +577,6 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
  );
 }

-/** 为单个旧编辑器建立独立ReactFlow store；board/snapshot身份切换的重挂载由路由调用方负责。 */
 export default function GraphCanvas({ board, snapshot, migration }: { board: Board; snapshot?: CanvasSnapshot; migration?:LegacyMigrationContext }) {
  return <ReactFlowProvider><CanvasEditor board={board} snapshot={snapshot} migration={migration} /></ReactFlowProvider>;
 }
@@ -1,9 +1,3 @@
-/**
- * 新版主画布的React/ReactFlow装配。engine拥有文档、历史和运行事实，sessions拥有每视图选择/工具/手势；组件只保存显示缓存与面板状态。
- * 文档提交先推进场景索引，再按事件类型立即或逐帧发布；几何预览通过session进入投影，提交才产生文档修改。
- * 画布适配层负责DOM测量、命中、裁剪、焦点和资源显示，core不读取DOM；渲染组件通过动作上下文调用editor/runtime。
- * 外层只借用项目engine：挂载attach视图，卸载detach，不关闭工作区持有的项目或持久任务。
- */
 "use client";

 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, type ContextType } from "react";
@@ -46,13 +40,9 @@ import { UnsupportedNode, UnsupportedEdge } from "./unsupported-elements";
 import { ImagePreviews } from "./canvas-image";
 import styles from "./canvas.module.css";

-/** 把适配层样式等可序列化值规范化成JSON Data，去掉undefined等JSON不保留的属性；不处理循环或任意非JSON对象。 */
 const json = (value: unknown): Data => JSON.parse(JSON.stringify(value));
-/** 已attach视图的内容组件；需要外层ReactFlowProvider与CanvasProvider。root/session是发布快照，current供回调读取最新投影。 */
 function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engine: ProjectEngine; board: Board; viewId: Id; renderers:ReactRenderers;fitLoading?:boolean }) {
-  // 场景索引按engine+view复用，提交订阅先advance变更，再通知显示，避免每次渲染重建整图索引。
  const sceneCache=useMemo(()=>createSceneProjection(),[engine,viewId]);
-  /** 用户字段修改/替换删除及undo/redo立即发布，保证受控输入及时回显；批量创建和后台修改允许合并到下一帧。 */
  const subscribe = useCallback((notify: (immediate?:boolean) => void) => {
    let before=engine.getSnapshot().document;
    return engine.editor.subscribe((commit,next)=>{sceneCache.advance(before,next.document,commit.changes);before=next.document;
@@ -62,20 +52,16 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
      notify(immediate);
    });
  }, [engine,sceneCache]);
-  // rootFrames只调度呈现通知，不延迟editor真实提交；sessionFrames独立合并手势/选择等视图变化。
  const rootFrames=useMemo(()=>createFrameSource({subscribe,getSnapshot:engine.getSnapshot},{request:callback=>requestAnimationFrame(callback),cancel:handle=>cancelAnimationFrame(handle as number)}),[engine,subscribe]);
  const root = useSyncExternalStore(rootFrames.subscribe, rootFrames.getSnapshot, rootFrames.getSnapshot);
  const sessionFrames=useMemo(()=>createSessionFrameSource(engine.sessions,{request:callback=>requestAnimationFrame(callback),cancel:handle=>cancelAnimationFrame(handle as number)}),[engine]);
  const sessions = useSyncExternalStore(sessionFrames.subscribe, sessionFrames.getSnapshot, sessionFrames.getSnapshot);
-  // 视图被detach后保留最近view供本轮Hook计算，最终返回“画布已关闭”；不以lastView恢复已关闭会话。
  const liveView = sessions.views.get(viewId), lastView = useRef(liveView);
  const loading=root.runtime.loading,needsLoadingFit=useRef(!!loading&&fitLoading);

  if (liveView) lastView.current = liveView;
  const view = liveView ?? lastView.current!, flow = useReactFlow<ProjectionNode>();
-  // 完整加载后允许普通创建；加载中要求loading版本支持且当前canvas覆盖完整，最终命令层仍再校验准入。
  const canCreate=!loading||loading.version>=4&&engine.editor.getQueries(root.document).coverage.completeCanvasIds.includes(view.canvasId);
-  // 加载预览首次适配只取当前canvas直接节点，避免展开后代把视口拉得过远；有交接视口时不再自动fit。
  useEffect(()=>{
    if(!needsLoadingFit.current||!flow.viewportInitialized||!root.document.canvases.has(view.canvasId))return;
    // Expanded descendants can extend far beyond their partition entry. Initial
@@ -84,9 +70,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
    if(!nodes.length)return;
    needsLoadingFit.current=false;void flow.fitView({nodes,padding:.2,maxZoom:1});
  },[engine,flow,root.document,view.canvasId]);
-  // 复制准备任务来自runtime状态；copying防本地重复点击，两者共同禁用复制入口。
  const preparingCopy = [...(root.runtime.imports?.values() ?? [])].some(job => job.status === 'preparing' && job.source?.targetCanvasId === view.canvasId);
-  // 焦点与epoch用于保留活动输入和排除迟到blur；切engine/view复位，移除renderer未触发blur时另检查isConnected。
  const [focusedEditor, setFocusedEditor] = useState<HTMLElement | null>(null), focusEpoch = useRef(0);
  useEffect(() => { focusEpoch.current++; setFocusedEditor(null); return () => { focusEpoch.current++; }; }, [engine,viewId]);
  // Removing an active renderer need not dispatch a native blur. Retire only
@@ -94,26 +78,19 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
  useEffect(()=>{if(focusedEditor&&!focusedEditor.isConnected)setFocusedEditor(current=>current===focusedEditor?null:current);});
  const [copying, setCopying] = useState(false);
  const [resourcePicker,setResourcePicker]=useState<{canvasId:Id;position:{x:number;y:number}}|null>(null);
-  // 选择转成id/incarnation后查询深复制可用性；渲染时的可用性仅用于UI，点击时再次捕获实际选择交runtime。
  const copyAvailability=useMemo(()=>engine.imports.canDuplicate([...view.selection].map(id=>root.document.elements.get(id)).filter((element):element is ElementRecord=>!!element).map(({id,incarnation})=>({id,incarnation})),{viewCanvasId:view.canvasId}),[engine,root,view.selection,view.canvasId]);
  const [showAI, setShowAI] = useState(false), [showRecovery, setShowRecovery] = useState(false);
  const [error, setError] = useState("");
-  // resource显示状态带engine/view身份，旧显示器迟到回调不能为当前画布提供错误图片；sources不是文档资源表。
  const [displayState, setDisplayState] = useState<{engine:ProjectEngine|null;viewId:Id|null;sources:Map<Id,ResourceViewSource>;failures:number}>({engine:null,viewId:null,sources:new Map(),failures:0});
  const resourceView=useRef<ReturnType<typeof createResourceView>|null>(null);
-  // 拖动保存起始场景坐标、指针ID与会话token，positions只含顶层选中节点，防分区与成员重复位移。
  const pointerStart = useRef<{ x: number; y: number;pointerId?:number } | null>(null), drag = useRef<{ token: number;pointerId?:number; start: { x: number; y: number }; positions: Map<Id, { x: number; y: number }> } | null>(null);
-  // 复用投影对象与测量结果，避免ReactFlow把纯元数据变化误当节点卸载，影响输入及连接点。
  const projectionCache = useRef<ReturnType<typeof createProjectionCache> | null>(null);
  projectionCache.current ??= createProjectionCache();
  const measurements = useRef(new Map<Id, { width: number; height: number; measured: { width: number; height: number } }>());
-  // groups按元素生命周期保存一次文本编辑的history分组ID，元素重建后清旧分组，不能跨incarnation合并编辑。
  const imageInput = useRef<HTMLInputElement>(null), groups = useRef(new Map<Id,{incarnation:number;groupId:Id}>());
  useEffect(()=>{for(const [id,group]of groups.current)if(root.document.elements.get(id)?.incarnation!==group.incarnation)groups.current.delete(id);},[root.document]);
-  // 加载期使用受限renderer catalog，完整后回到正常定义；sceneCache把文档、会话预览与查询组成显示场景。
  const catalog=useMemo(()=>loading?createLoadingRendererCatalog(engine.editor.registry,renderers.catalog):renderers.catalog,[engine,renderers,!!loading]);
  const scene=sceneCache.project(engine,root.document,view,sessions,engine.editor.registry,catalog,engine.editor.getQueries(root.document));
-  // 仅在尺寸一致且投影缓存确认身份/变换允许时复用measured；离开场景的节点清测量条目。
  const projection = useMemo(() => {
    const result = scene;
    // Preserve renderer measurements across metadata/preview updates. Dropping them
@@ -123,50 +100,36 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
    for (const node of result.nodes) { const cached = measurements.current.get(node.id); if (cached && cached.width === node.width && cached.height === node.height && projectionCache.current!.canRetainMeasurement(engine,root.document,view.canvasId,node)) node.measured = cached.measured; }
    return projectionCache.current!.reuse(engine,root.document,view.canvasId,result);
  }, [engine, root.document, scene,view.canvasId]);
-  // 每个view独立OverlayIndex，Portal控件通过索引贡献边界与焦点；不会把浮层几何存入项目文档。
  const surface=useRef<HTMLDivElement>(null),overlays=useMemo(()=>createOverlayIndex(viewId),[engine,viewId]);
  const overlayScope=useMemo(()=>({index:overlays,engine}),[overlays,engine]);
  const overlaySnapshot=useSyncExternalStore(overlays.subscribe,overlays.getSnapshot,overlays.getSnapshot);
  const surfaceBounds=surface.current?.getBoundingClientRect();

-  // 绘制范围索引用于可见性筛选；sceneViewport把ReactFlow平移/缩放反算为场景矩形。
  const paintCache=useMemo(()=>createProjectedPaintIndex(),[engine,view.canvasId]);
  const paint=useMemo(()=>paintCache.sync(projection,engine.editor.registry),[paintCache,projection,engine]);
  const viewport=useViewport(),surfaceWidth=useStore(state=>state.width),surfaceHeight=useStore(state=>state.height);
  const sceneViewport={x:-viewport.x/viewport.zoom,y:-viewport.y/viewport.zoom,width:surfaceWidth/viewport.zoom,height:surfaceHeight/viewport.zoom};
-  // 过滤元素生命周期已变的浮层；缺surface矩形时只按身份保守保留，不凭缺失测量断言不可见。
  const visibleOverlays=overlaySnapshot.length?(surfaceBounds?overlays.visible(surfaceBounds,target=>root.document.elements.get(target.id)?.incarnation===target.incarnation):overlaySnapshot.filter(entry=>root.document.elements.get(entry.target.id)?.incarnation===entry.target.incarnation)):[];
-  // 未知绘制范围必须保留，加上矩形查询命中；不能把unknown当成屏幕外。
  const paintedNodes=[...paint.unknown,...paint.query(sceneViewport)];
  const nativeNodes=useStore(state=>state.nodes);
  const connectionPaintCache=useMemo(()=>createConnectionPaintIndex(),[engine,view.canvasId]);
-  // 连线范围依赖真实Handle测量：新版/未知连线使用measuredConnector，兼容节点使用旧几何适配。
-  // 订阅nativeNodes让测量更新后重算连线路径范围，不把DOM测量要求下放core。
  const connectionPaint=useMemo(()=>connectionPaintCache.sync(projection,engine.editor.registry,{anchor:(node,handle,end,edge)=>{const measured=flow.getInternalNode(node.id);return node.data.__headlessRecord||edge.type==='unsupported'?measuredConnector(measured,handle,end):compatConnector(node,handle,end==='source'?'right':'left');}}),[connectionPaintCache,projection,engine,flow,nativeNodes]);
  // Exhausted geometry work cannot prove any edge invisible. Retain the edge
  // layer and its endpoints, not unrelated nodes or a synthetic sentinel owner.
  const paintedEdges=connectionPaint.unknown.includes('paint_budget')?projection.edges.map(edge=>edge.id):[...connectionPaint.unknown,...connectionPaint.query(sceneViewport)];
-  // 保留调用方renderer表，并显式安装unsupported节点/边占位，未知内容仍可在场景中呈现。
  const nodeTypes=useMemo(()=>({...renderers.nodeTypes,unsupported:UnsupportedNode}),[renderers]),edgeTypes=useMemo(()=>({...renderers.edgeTypes,unsupported:UnsupportedEdge}),[renderers]);
-  // 稳定动作闭包从current/engine读取最新状态，runtime-only发布不必重建全部卡片编辑上下文。
  const current = useRef({ root, projection, view, engine, sessions }); current.current = { root, projection, view, engine, sessions };
-  /** 将命令拒绝或能力不可用显示为错误；成功结果无需额外复制进本地state。 */
  const report = useCallback((result: Result | { enabled: boolean; code?: string }) => {
    if ('status' in result && result.status === 'rejected' || 'enabled' in result && !result.enabled) setError(errorText(new Error(result.code)));
  }, []);
-  /** 发命令前读取当前incarnation，元素缺失即抛错；渲染侧更早的身份检查由useScopedNodeEditing等负责。 */
  const target = (id: Id) => { const element = engine.getSnapshot().document.elements.get(id); if (!element) throw new Error('element_missing'); return { id, incarnation: element.incarnation }; };
-  /** 统一元素data补丁入口，可携history groupId；schema、能力和事务合法性留editor验证。 */
  const data = (id: Id, patch: Data, groupId?: Id) => report(engine.editor.dispatch({ type: 'element.data', target: target(id), patch }, { groupId }));
-  /** 把ReactFlow选择变化合到session当前Set，成员完全相同则不重复发布；不把selected写入文档。 */
  function selectChanges(changes: readonly { id: Id; selected: boolean }[]) {
    const current = engine.sessions.getSnapshot().views.get(viewId)!;
    const ids = new Set(current.selection);
    for (const change of changes) if (change.selected) ids.add(change.id); else ids.delete(change.id);
    if (ids.size !== current.selection.size || [...ids].some(id => !current.selection.has(id))) engine.sessions.select(viewId, [...ids]);
  }
-  /** 空白点击补充core投影命中：12px容差、预览目标及实际Handle/layer适配；只选择confirmed命中。
-   * 命中计算后再次比较document/session快照身份，过期帧不能选中新incarnation；抓手模式点击清选择。 */
  function selectAtPane(event: {clientX:number;clientY:number}) {
    const captured=current.current;
    if(captured.view.tool!=='select'){engine.sessions.select(viewId,[]);return;}
@@ -186,16 +149,12 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
    const hit=result.hits[0];
    engine.sessions.select(viewId,hit?.certainty==='confirmed'?[hit.target.id]:[]);
  }
-  /** session.begin成功后捕获gesture token，以guardEditingLease约束后续preview/commit/cancel只作用于该交互。 */
  function beginTransform(id: Id) {
    const result = engine.sessions.begin(viewId, [target(id)]); report(result); if (!result.enabled) return false;
    const token = engine.sessions.getSnapshot().gesture!.token;
-    /** 每次租约动作实时核对token，旧pointerup不能结束后来新建的手势。 */
    const current = () => engine.sessions.getSnapshot().gesture?.token === token;
    return guardEditingLease(current, { preview: (change: Parameters<typeof transform>[1]) => transform(id, change), commit: () => report(engine.sessions.commit(viewId)), cancel: () => engine.sessions.cancel('pointer_cancel') });
  }
-  /** 将显示空间位置/尺寸转成owner局部Geometry：尺寸除scale，以中心toLocal后再求左上角，旋转减去父旋转。
-   * 这里只更新session预览，不直接dispatch文档；后续commit统一形成history与同步修改。 */
  function transform(id: Id, change: { position?: { x: number; y: number }; width?: number; height?: number; rotation?: number; fontSize?: number }) {
    const { root, projection } = current.current, element = root.document.elements.get(id);
    if (element?.structure !== 'node') return;
@@ -206,21 +165,16 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
    const patch: Partial<Geometry> = { x: center.x - width / 2, y: center.y - height / 2, width, height, ...(change.rotation !== undefined ? { rotation: ((change.rotation - t.rotation) % 360 + 360) % 360 } : {}) };
    report(engine.sessions.update(viewId, target(id), patch));
  }
-  /** 创建内置节点，可加入调用方已有事务；frame同时创建以节点为入口的子canvas，保证结构一起提交。
-   * 默认位置从首个data-headless-canvas的DOM矩形取屏幕中心再转场景坐标，at可显式覆盖。 */
  function add(kind: 'text' | 'plain-text' | 'image' | 'frame', ref?: { id: Id; src: string }, tx?: Parameters<Parameters<typeof engine.editor.transaction>[0]>[0], at?: { x: number; y: number }) {
    const id = crypto.randomUUID(), canvasId = current.current.view.canvasId;
    const rect = window.document.querySelector('[data-headless-canvas]')?.getBoundingClientRect();
    const position = at ?? flow.screenToFlowPosition({ x: (rect?.left ?? 0) + (rect?.width ?? window.innerWidth) / 2, y: (rect?.top ?? 0) + (rect?.height ?? window.innerHeight) / 2 });
-    // 各类型使用固定默认尺寸及初始incarnation/dataVersion；资源引用由已stage/adopt的ref注入，不在这里上传。
    const size = kind === 'frame' ? { width: 640, height: 400 } : kind === 'plain-text' ? { width: 240, height: 72 } : { width: 260, height: 200 };
    const element: ElementRecord = { id, incarnation: 1, structure: 'node', componentId: kind, dataVersion: 1, ownerCanvasId: canvasId, geometry: { ...position, ...size, rotation: 0 }, data: { title: kind === 'frame' ? '未命名分区' : kind === 'image' ? '视觉参考' : '灵感笔记', text: '', ...(ref ? { assetId: ref.id, src: ref.src } : {}) } };
-    /** tx内创建元素及可选canvas关系；无外部tx时包装为一个Add element事务。 */
    const create = (transaction: NonNullable<typeof tx>) => { transaction.dispatch({ type: 'element.create', element }); if (kind === 'frame') transaction.dispatch({ type: 'canvas.create', canvas: { id: crypto.randomUUID(), parent: { canvasId, entryElementId: id } } }); };
    if (tx) create(tx); else report(engine.editor.transaction(create, { label: 'Add element' }));
    return id;
  }
-  /** 选择工具才可建边；拒绝unsupported端点，将owner设为两端所属canvas的共同上级，端口ID来自连接事件。 */
  function connect(connection: Connection) {
    if(engine.sessions.getSnapshot().views.get(viewId)?.tool!=='select')return;
    const document = engine.getSnapshot().document, source = document.elements.get(connection.source), destination = document.elements.get(connection.target);
@@ -228,30 +182,21 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
    if([source.id,destination.id].some(id=>projectionCache.current!.getNode(id)?.type==='unsupported')){setError('此元素暂不支持创建新连线');return;}
    report(engine.editor.dispatch({ type: 'element.create', element: { id: crypto.randomUUID(), incarnation: 1, componentId: 'connection', dataVersion: 1, structure: 'connection', ownerCanvasId: commonCanvas(document, source.ownerCanvasId, destination.ownerCanvasId), source: { elementId: source.id, ...(connection.sourceHandle ? { portId: connection.sourceHandle } : {}) }, target: { elementId: destination.id, ...(connection.targetHandle ? { portId: connection.targetHandle } : {}) }, data: {}, path: null } }));
  }
-  // 用节点ID+assetId序列作为显示订阅键，资源分辨率/URL交资源视图决定；组件不把Blob URL写入元素data。
  const resourceKey = JSON.stringify(projection.nodes.filter(node => typeof node.data.assetId==='string'&&node.data.assetId).map(node => [node.id, node.data.assetId]));
-  // 每个engine/view建立资源显示器，回调只接受当前实例；清理dispose解除订阅及显示资源占用。
  useEffect(() => {
    if (!liveView) return;
    const view=createResourceView({resolve:(id,signal)=>engine.displayResource(id,{signal}),onChange:(sources,failures)=>{if(resourceView.current===view)setDisplayState({engine,viewId,sources,failures});},onError:error=>{if(resourceView.current===view)setError(errorText(error));}});
    resourceView.current=view;
    return ()=>{if(resourceView.current===view)resourceView.current=null;view.dispose();};
  }, [engine,viewId,Boolean(liveView)]);
-  // 资源目标集合变化才sync，映射失败在本面板报错，不擅自修改文档中的assetId。
  useEffect(()=>{try{resourceView.current?.sync(JSON.parse(resourceKey) as [Id,Id][]);}catch(error){setError(errorText(error));}},[engine,viewId,resourceKey,Boolean(liveView)]);
-  // 再按engine/view及当前assetId过滤结果，节点切换资源时不显示上一个资源的迟到URL。
  const sources=useMemo(()=>{if(displayState.engine!==engine||displayState.viewId!==viewId)return new Map<Id,string>();const wanted=new Map(JSON.parse(resourceKey) as [Id,Id][]);return new Map([...displayState.sources].filter(([id,source])=>wanted.get(id)===source.resourceId).map(([id,source])=>[id,source.url]));},[displayState,engine,viewId,resourceKey]);
-  /** 一次事务删除当前选择中仍存在的元素；关联结构处理由editor命令实现，不循环修改投影数组。 */
  function removeSelected() { report(engine.editor.transaction(tx => { for (const id of current.current.view.selection) if (tx.getDocument().elements.has(id)) tx.dispatch({ type: 'element.remove', target: target(id) }); }, { label: 'Delete selection' })); }
-  // 同步显示来自ledger：未resolved算待处理；waiting_digest单独等待不算阻断，无定时重试的错误和conflicts要提示处理。
  const pending = [...root.runtime.ledger.operations.values()].filter(operation => operation.phase !== 'resolved');
  const blocked = pending.some(operation => operation.phase === 'blocked' && operation.blockers.some(reason => reason !== 'waiting_digest')) || [...root.runtime.ledger.requests.values()].some(request => request.phase !== 'resolved' && request.error && request.retryAt === undefined) || root.runtime.conflicts.size > 0;
-  // 全局失焦或Escape仅取消本视图拥有的节点/连接手势；不干扰同engine其它视图的交互。
  useEffect(() => {
-    /** 核对viewId后取消session并清本地拖动记录；window blur不要求指针事件。 */
    const cancel = () => { const state = engine.sessions.getSnapshot(); if (state.gesture?.viewId === viewId || state.connectionGesture?.viewId === viewId) engine.sessions.cancel('view_interrupted'); drag.current = null; };
    // Bubble after the target/React handlers: an input owner can claim Escape first.
-    /** 冒泡阶段让输入控件优先认领Escape，再按统一路由决定是否取消手势。 */
    const escape = (event: KeyboardEvent) => {
      if(event.key!=='Escape')return;
      const claim=routeCanvasKey({key:event.key,composing:event.isComposing,defaultPrevented:event.defaultPrevented,...canvasKeyContext(event)},{gesture:()=>{const state=engine.sessions.getSnapshot();if(state.gesture?.viewId!==viewId&&state.connectionGesture?.viewId!==viewId)return false;cancel();return true;}});
@@ -263,12 +208,10 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
  const modes = view.modes;
  // Retain explicit owners in the native renderer, leaving the full graph in its
  // lookup for edges/queries. No synthetic dragging or altered geometry is used.
-  // 保留模式目标、可见绘制对象、浮层目标和本视图手势；完整图仍留ReactFlow查询表，不以伪造拖动避裁剪。
  const retained=new Set<Id>([...modes.keys(),...paintedNodes,...paintedEdges]);
  for(const entry of visibleOverlays)retained.add(entry.target.id);
  if(sessions.gesture?.viewId===viewId)for(const target of sessions.gesture.targets)retained.add(target.id);
  if(sessions.connectionGesture?.viewId===viewId)retained.add(sessions.connectionGesture.target.id);
-  // 活动输入可来自节点、连线、Portal浮层或独立UI；无法证明其归属时保守关闭可见性裁剪。
  const activeEditor=focusedEditor?.isConnected?focusedEditor:null;
  const focusedOverlay=activeEditor?.closest<HTMLElement>('[data-canvas-overlay-target]');
  const focusedUI=activeEditor?.closest<HTMLElement>('[data-canvas-ui-view]');
@@ -278,12 +221,10 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
  if(focusedId)retained.add(focusedId);
  // Retained connections also keep their measured endpoint owners alive.
  for(const id of [...retained]){const element=root.document.elements.get(id);if(element?.structure==='connection'){retained.add(element.source.elementId);retained.add(element.target.elementId);}}
-  // 所有保留对象仍须存在于文档，且视口尺寸已知，才启用native onlyRenderVisibleElements。
  const scoped=!(activeEditor&&!focusedId&&!independentFocus)&&[...retained].every(id=>root.document.elements.has(id));
  const cullVisible=!!surfaceWidth&&!!surfaceHeight&&scoped;
  const retainedProjection=useMemo(()=>createRetainedProjection(),[engine,viewId]);
  const rendered=retainedProjection(projection.nodes,projection.edges,retained);
-  // 单选时才启用图片适配/AI工具；图片要求已知组件、resize能力和声明的assetId资源字段，不能猜同名业务字段。
  const selected = view.selection.size === 1 ? root.document.elements.get([...view.selection][0]) : undefined;
  const selectedResource=selected?.structure==='node'&&engine.editor.registry.resolve(selected)==='known'&&engine.editor.registry.supports(selected,'geometry.resize')&&typeof selected.data.assetId==='string'&&engine.editor.registry.components.get(selected.componentId)?.resourceFields?.includes('assetId')?root.runtime.resources.get(selected.data.assetId):undefined;
  const canFitImage=!!selectedResource&&(selectedResource.image?.version===1&&selectedResource.image.status==='ready'||!!selectedResource.stored)&&!sessions.gesture;
@@ -292,19 +233,15 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
  // Actions use current.current / engine snapshots instead of captured document projections.
  const rotating = [...modes].find(([, mode]) => mode === 'rotate')?.[0] ?? null;
  const resizing = [...modes].find(([, mode]) => mode === 'resize')?.[0] ?? null;
-  // 新版资源URL寿命由resourceView管理，CanvasImage的loaded回调这里无需删除旧版上传任务。
  const imagePreviews = useMemo<ContextType<typeof ImagePreviews>>(() => ({sources,loaded:()=>{}}),[sources]);
-  // 给旧节点renderer注入新版动作：begin/end维护文本history分组与editing mode，正文按同incarnation使用groupId。
  const nodeEditing = useMemo<ContextType<typeof NodeEditing>>(() => ({ workspace: board.workspace_id, schema: 2,
      begin: id => { if (id) { groups.current.set(id,{incarnation:target(id).incarnation,groupId:crypto.randomUUID()}); engine.sessions.mode(viewId, id, 'editing'); } },
      endEditing: id => { groups.current.delete(id); engine.sessions.mode(viewId, id, null); },
      select: id => engine.sessions.select(viewId, [id]), edit: (id, text) => data(id,{text},groups.current.get(id)?.incarnation===engine.getSnapshot().document.elements.get(id)?.incarnation?groups.current.get(id)?.groupId:undefined), rename: (id, title) => data(id, { title }),
      beginTransform, transform, finishTransform: () => { if (engine.sessions.getSnapshot().gesture?.viewId === viewId) report(engine.sessions.commit(viewId)); }, cancelTransform: () => { if (engine.sessions.getSnapshot().gesture?.viewId === viewId) engine.sessions.cancel('pointer_cancel'); },
-      // 样式和分区补丁走data，模式rotate/resize只在sessions中切换；开启一个前先清同视图该类旧模式。
      style: (id, textStyle, fontSize) => data(id, json({ textStyle, ...(fontSize !== undefined ? { fontSize } : {}) })), frame: (id, patch) => data(id, json(patch)),
      rotating, rotate: id => { for (const [key, mode] of engine.sessions.getSnapshot().views.get(viewId)?.modes ?? []) if (mode === 'rotate') engine.sessions.mode(viewId, key, null); if (id) engine.sessions.mode(viewId, id, 'rotate'); },
      resizing, resize: id => { for (const [key, mode] of engine.sessions.getSnapshot().views.get(viewId)?.modes ?? []) if (mode === 'resize') engine.sessions.mode(viewId, key, null); if (id) engine.sessions.mode(viewId, id, 'resize'); },
-      // 分支直接在当前canvas按方向偏移创建文本，再同一事务创建连线；与旧版弹类型菜单的行为不同。
      branch: (id, direction) => {
        const node = projectionCache.current!.getNode(id); if (!node) return;
        const dx = direction === 'left' ? -340 : direction === 'right' ? 340 : 0, dy = direction === 'top' ? -280 : direction === 'bottom' ? 280 : 0;
@@ -312,23 +249,19 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
      },

  }),[engine,viewId,board.workspace_id,flow,report,rotating,resizing]);
-  // 曲线编辑同样捕获connectionGesture token；active暂为空集合，连线renderer在此不从run状态获取执行动画。
  const edgeEditing = useMemo<ContextType<typeof EdgeEditing>>(() => ({ active: new Set(), begin: id => {
      if (!id) return; const result = engine.sessions.beginConnection(viewId, target(id)); report(result); if (!result.enabled) return false;
      const token = engine.sessions.getSnapshot().connectionGesture!.token, element = engine.getSnapshot().document.elements.get(id)!;
      const transform = current.current.projection.transforms.get(element.ownerCanvasId)!;
-      /** token护栏绑定该条连接手势，预览路径先从场景空间变回owner局部空间。 */
      const ownsGesture = () => engine.sessions.getSnapshot().connectionGesture?.token === token;
      return guardEditingLease(ownsGesture, { preview: (path: NonNullable<import('@/lib/canvas-v2').EdgeData['path']>) => report(engine.sessions.updateConnection(viewId, transformPath(path as Json, transform, true))), commit: () => report(engine.sessions.commitConnection(viewId)), cancel: () => engine.sessions.cancel('pointer_cancel') });
    },
      finish: () => { if (engine.sessions.getSnapshot().connectionGesture?.viewId === viewId) report(engine.sessions.commitConnection(viewId)); }, cancel: () => { if (engine.sessions.getSnapshot().connectionGesture?.viewId === viewId) engine.sessions.cancel('pointer_cancel'); },
-      // 临时path只更新session；正式修改把data和path分开命令，在同一个事务提交，避免把路径写进业务data。
      patch: (id, value, transient) => {
        const element = engine.getSnapshot().document.elements.get(id); if (element?.structure !== 'connection') return;
        const t = current.current.projection.transforms.get(element.ownerCanvasId)!;
        const path = transformPath((value.path ?? null) as Json, t, true);
        const displayedPath = current.current.projection.edges.find(edge => edge.id === id)?.data?.path;
-        // 工具栏可能传回整个显示data；只有显式含path且与显示路径不同才提交connection.path，避免无意重写。
        const changedPath = Object.hasOwn(value, 'path') && !equal(value.path, displayedPath);
        if (transient) { report(engine.sessions.updateConnection(viewId, path)); return; }
        const { path: ignored, ...rest } = value; void ignored;
@@ -336,15 +269,8 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
      },

  }),[engine,viewId,report]);
-  // 自定义renderer的dispatch/transaction也经过editor，并统一report拒绝；选项只传label/groupId。
  const rendererCommands=useMemo<CanvasRendererCommands>(()=>({dispatch(command,options){const result=engine.editor.dispatch(command,{label:options?.label,groupId:options?.groupId});report(result);return result;},transaction(callback,options){const result=engine.editor.transaction(callback,{label:options?.label,groupId:options?.groupId});report(result);return result;}}),[engine,report]);
-  // 本组件Hook全部调用后才判断视图关闭，保留React Hook调用顺序；已detach时不挂载交互surface。
  if (!liveView) return <p role="status">画布已关闭</p>;
-  // surface集中处理焦点epoch、拖动起点和键盘路由：blur微任务只清旧epoch，多触点取消当前手势。
-  // 快捷键按输入上下文优先级处理Escape、H/V、撤销重做及删除；只有认领成功才阻止默认行为。
-  // ReactFlow位移变化只转session预览，测量单独缓存；拖动结束依据起始位置补最后位移后commit。
-  // 工具栏撤销/深复制/导出走各自editor/runtime接口，视口缩放只改view；导出完整文档JSON，不含文件字节。
-  // 文件选择调用stageFiles，引用与图片节点在回调事务里一起创建；导入/AI/资源/恢复面板按加载与选择条件挂载。
  return <div ref={surface} className={`${styles.editor} ${view.tool === 'pan' ? styles.handMode : ''}`} data-headless-canvas data-model-loading={loading?"true":undefined} tabIndex={-1}
    onFocusCapture={event => { if ((event.target as HTMLElement).closest('input,textarea,[contenteditable="true"],[role="textbox"]')) { focusEpoch.current++; setFocusedEditor(event.target as HTMLElement); } }}
    onBlurCapture={() => { const epoch = ++focusEpoch.current; queueMicrotask(() => { if (focusEpoch.current === epoch) setFocusedEditor(null); }); }}
@@ -370,7 +296,6 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
        onMoveEnd={(_, viewport) => engine.sessions.viewport(viewId, viewport)}
        onNodeDragStart={(event, node, nodes) => {
          const ids = new Set((nodes.length ? nodes : [node]).map(node => node.id));
-          // 同时选中分区入口与后代时只对最上层目标启动手势，后代位置由结构投影带动。
          const top = [...ids].filter(id => { const element = current.current.root.document.elements.get(id)!; return !ancestors(current.current.root.document, element.ownerCanvasId).some(canvasId => { const parent = current.current.root.document.canvases.get(canvasId)?.parent; return parent && ids.has(parent.entryElementId); }); });
          const point = 'clientX' in event ? event : event.changedTouches[0];
          drag.current = { token: 0,pointerId:pointerStart.current?.pointerId, start: pointerStart.current ?? flow.screenToFlowPosition({ x: point.clientX, y: point.clientY }), positions: new Map(top.map(id => [id, projectionCache.current!.getNode(id)!.position])) };
@@ -380,7 +305,6 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
        onEdgesChange={changes => selectChanges(changes.filter(change => change.type === 'select'))}
        onNodesChange={changes => { for (const change of changes) if (change.type === 'dimensions' && change.dimensions) { const node = projectionCache.current!.getNode(change.id); if (node) measurements.current.set(change.id, { width: node.width!, height: node.height!, measured: { ...change.dimensions } }); } selectChanges(changes.filter(change => change.type === 'select')); for (const change of changes) if (change.type === 'position' && change.position && engine.sessions.getSnapshot().gesture?.viewId === viewId && drag.current?.token === engine.sessions.getSnapshot().gesture?.token && engine.sessions.getSnapshot().gesture?.targets.some(target => target.id === change.id)) transform(change.id, { position: change.position }); }}
        onNodeDragStop={event => {
-          // 仅结束匹配本视图和token的拖动，迟到dragStop不提交当前其它手势。
          const saved = drag.current; drag.current = null; pointerStart.current = null;
          if (engine.sessions.getSnapshot().gesture?.viewId !== viewId || !saved || engine.sessions.getSnapshot().gesture?.token !== saved.token) return;
          const point = 'clientX' in event ? event : event.changedTouches[0], end = flow.screenToFlowPosition({ x: point.clientX, y: point.clientY });
@@ -394,7 +318,6 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
    <div data-canvas-ui-view={viewId} className={styles.topRight}><div className={`${toolbar.surface} ${styles.toolbar}`} role="toolbar" aria-label="图谱视图控制">
      <IconButton icon={Undo2} label="撤销" disabled={!root.history.undo.length} onClick={() => report(engine.editor.history.undo())} /><IconButton icon={Redo2} label="重做" disabled={!root.history.redo.length} onClick={() => report(engine.editor.history.redo())} />
      <IconButton icon={Copy} label={copying || preparingCopy ? "正在准备复制" : "深复制选中内容"} disabled={copying || preparingCopy || !copyAvailability.enabled} onClick={() => {
-        // 深复制点击时捕获选择身份，异步完成只更新同engine/view的面板；runtime负责进度与已加入内容。
        const captured = current.current, selection = [...captured.view.selection].map(id => captured.root.document.elements.get(id)).filter((item): item is ElementRecord => !!item).map(({id, incarnation}) => ({id, incarnation}));
        setCopying(true); setError("");
        void engine.imports.duplicate(selection, {viewCanvasId: captured.view.canvasId}).catch(error => { if (current.current.engine === engine && current.current.view.id === viewId) setError(errorText(error)); }).finally(() => { if (current.current.engine === engine && current.current.view.id === viewId) setCopying(false); });
@@ -416,12 +339,9 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
    {error && <div className={styles.error} role="alert">{error} {displayState.engine===engine&&displayState.viewId===viewId&&displayState.failures>0&&<button onClick={()=>{setError('');resourceView.current?.retry();}}>重试图片</button>}<button onClick={() => setError('')}>关闭</button></div>}
  </div>;
 }
-/** 挂载期生成稳定viewId并attach，借用initialViewport只初始化一次；detach只释放视图，不关闭engine。
- * 交接视口存在时禁用加载初次fit，避免从只读预览切入后可视位置突然跳变。 */
 export default function HeadlessGraphCanvas({ engine, board, renderers=defaultCanvasRenderers,initialViewport }: { engine: ProjectEngine; board: Board; renderers?:ReactRenderers;initialViewport?:Viewport }) {
  const [handoffViewport]=useState(initialViewport);
  const [viewId] = useState(() => crypto.randomUUID()), [attached, setAttached] = useState(false);
-  // attach完成后才挂载CanvasView所需Provider；清理时detach视图，CanvasView卸载清理自身订阅。
  useEffect(() => { const detach = engine.sessions.attach(viewId, board.id);if(handoffViewport)engine.sessions.viewport(viewId,handoffViewport); setAttached(true); return () => { setAttached(false); detach(); }; }, [engine, viewId, board.id,handoffViewport]);
  return attached ? <ReactFlowProvider><CanvasProvider engine={engine} viewId={viewId}><CanvasView engine={engine} board={board} viewId={viewId} renderers={renderers} fitLoading={!handoffViewport} /></CanvasProvider></ReactFlowProvider> : <p role="status">正在准备画布…</p>;
 }