docs(config): explain SDK example and compiler configuration

headless/consumer.mjs

@@ -26,6 +26,7 @@ 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先准备镜像/文件再一次同步发布。
+// 文件值直接保存传入 bytes 引用；示例要求宿主提供不可变字节载荷，不演示流式文件读写或增量日志。
 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;},
@@ -59,6 +60,7 @@ const transport=async input=>{
   if(known){assert.equal(known.body,input.body);return{status:200,body:known.receipt};}
   // 示例只含一个canvas版本，先要求版本一致，再应用变更并验证整个文档；每次接受使版本递增一次。
   assert.deepEqual(body.expected_versions,{[scope.projectId]:version});
+  // server 赋值在 validate 之前，断言失败不会恢复旧 server；此替身只用于下方合法协议路径，不是生产事务实现。
   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}};
@@ -96,4 +98,5 @@ try{
   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}));
+// 顺序等待 close 后再检查 Storage；若 close 本身拒绝，storage.close 不会执行，错误向脚本调用者传播。
 }finally{await engine.close();storage.close();}

next.config.ts

@@ -8,6 +8,7 @@ const config: NextConfig = {
   reactStrictMode: true, poweredByHeader: false,
   /** 在现有规则后追加匹配ReactFlow ESM入口的loader，再返回原配置对象，保留框架其它规则。 */
   webpack(config) {
+    // 规则只按路径匹配，不按客户端/服务端分支；loader 自身再检查安装版本和四段源码锚点。
     config.module.rules.push({
       test: /[\\/]@xyflow[\\/]react[\\/]dist[\\/]esm[\\/]index\.(?:mjs|js)$/,
       use: [{ loader: require.resolve("./scripts/loaders/xyflow-retained.cjs") }],
@@ -25,6 +26,7 @@ const config: NextConfig = {
   },
   /** 只给版本目录内带12位十六进制摘要的JSON分片配置一年immutable缓存，文件内容变化应生成新文件名。
    * 不对图标目录manifest、页面或全部JSON一概设置immutable。 */
+  // 这里只匹配 URL 外观，不重新读取文件验证摘要；重生成文件名和旧资源保留由资源脚本/发布流程负责。
   async headers() {
     return [{
       source: "/canvas-icons/:version/:asset([a-z0-9-]+-[a-f0-9]{12}\\.json)",

scripts/build-headless.mjs

@@ -9,6 +9,7 @@ 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'});
@@ -28,6 +29,7 @@ async function declarations(directory){
   }
 }
 // 原生编译器处理运行时import后缀，声明文件仍需此补充；完成后再修URL字面量里的Worker源后缀。
+// 后处理逐文件直接写入，未使用临时目录整体 rename；中途错误可留下部分已改写的输出。
 await declarations(join(output,'modules'));
 // 两个浏览器适配器各应含一个预期Worker URL；要求目标.js文件存在并且源字符串只出现一次才改写。
 for(const [module,worker]of [['browser-digests','digest.worker'],['browser-images','image.worker']]){

scripts/canvas-icon-labels.mjs

@@ -2,6 +2,7 @@
  * 图标资源生成时使用的中文标注表。作为静态元数据输入给generate-canvas-icons，不在运行时逐个请求翻译。
  */
 /** 完整PascalCase图标名到中文标签的人工覆盖表；未列出的图标由生成脚本回退slug拆词名称。 */
+// 两张表都是共享的普通对象，const 不冻结字段；生成器只读取，修改映射后需显式重新生成目录。
 export const chinese = {
   "Star": "星星",
   "Heart": "爱心",

scripts/generate-canvas-icons.mjs

@@ -34,6 +34,7 @@ const categories = [
 /** 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提供路径，尚未在此写最终分片。
+// Map 以 PascalCase 名称去重，同名后项覆盖；不单独报告名称转换碰撞，输入包格式须按固定版本审查。
 const entries = new Map();
 for (const [slug, load] of Object.entries(dynamicIconImports)) {
   const name = pascal(slug);
@@ -67,8 +68,10 @@ const catalog = records.map(({ node, ...entry }) => {
 });
 // 输出目录带两套版本，manifest把分片逻辑key映射到真实文件名；不在运行时猜hash路径。
 const assetDir = "public/canvas-icons/lucide-1.69.0-tabler-3.50.0";
+// 输出在仓库当前工作目录逐文件写入，不是整体原子替换；失败时可能保留新分片和旧 manifest 的组合。
 await mkdir(assetDir, { recursive: true });
 let totalBytes = 0;
+// 文件名摘要用于资源版本命名，不把截断的12位摘要当作完整校验/授权凭据；消费者按 manifest 定位。
 const assets = {};
 // 每个分片用紧凑JSON计算SHA-256前12位作文件名，写文件额外加换行；totalBytes统计未加换行的内容字节。
 for (const [key, nodes] of shards) {

scripts/loaders/xyflow-retained.cjs

@@ -5,6 +5,7 @@
 // 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；库升级必须人工审查目标实现，不能凭相同函数名继续替换。
+// require 在 loader 模块求值时读取一次版本，不在每个输入转换时重新扫描安装目录。
 const version = require('@xyflow/react/package.json').version;
 /** webpack/Turbopack loader接收源码并返回改写后的源码；任何版本或锚点不符立即失败，防止悄悄失去保留能力。 */
 module.exports = function retainVisibility(source) {
@@ -20,6 +21,7 @@ module.exports = function retainVisibility(source) {
   }
   // 节点追加未hidden且显式保留的ID并Set去重；边以保留标记或原可见判断二选一，维持原生索引。
   // 最后一处改为空数组不订阅完整选择集合，减少无选择监听时的不必要全图selector工作。
+  // 返回新字符串，不写磁盘；锚点检查只确认当前四段文本的形状，不证明升级后所有语义仍等价。
   return source
     .replace(nodes, `Array.from(new Set([
       ...${nodes},

src/app/api/foundry/[...path]/route.ts

@@ -41,6 +41,7 @@ async function readBody(req: NextRequest, limit = bodyLimit, binary = false) {
   }
   // 空body普通模式用空对象，binary模式保留空字节；无reader则早已返回空对象。
   if (!size) return binary ? new Uint8Array() : {};
+  // chunks 与合并 Buffer 在此可能同时占内存；limit 约束载荷字节，不是整个请求处理的堆内存上限。
   const bytes = Buffer.concat(chunks);
   return binary ? bytes : JSON.parse(bytes.toString("utf8"));
 }
@@ -67,6 +68,7 @@ async function handler(
       return json({ error: "invalid_origin" }, 403);
     }
   }
+  // Origin 比对只使用 host（含端口），不要求 scheme 相同；也不在代理本地解析会话账户权限。
   const path = (await params).path.join("/");
   if (!allowed.test(path) && !canvasRoute.test(path) && !assetRoute.test(path)) return json({ error: "not_found" }, 404);
   // operations/metadata返回JSON，不能被当成原图流，也不使用图片multipart请求体上限。
@@ -75,6 +77,7 @@ async function handler(
   const asset = assetRoute.test(path) && !assetReceipt && !assetMetadata;
   const canvas = canvasRoute.test(path);
   const canonical = canvas && /\/canvas\/model(?:\/|$)/.test(path);
+  // frozenAI 仅匹配 ai/runs 分支，ai/operations 查询不由此标记；新文档 model 路径整体由 canonical 覆盖。
   const frozenAI = canvas && /\/canvas\/ai\/runs(?:\/|$)/.test(path);
   let requestBody: unknown;
   // 在网络转发前完成请求体限额：原始图片含multipart开销，新模型/AI写入保留原请求字节。
@@ -108,6 +111,7 @@ async function handler(
   const query = new URLSearchParams();
   for (const key of ["kind", "sort", "q", "limit", "offset", "after_seq", "status", "include_descendants", "include_subgraphs", "cursor", "variant", "width"]) {
     const values = req.nextUrl.searchParams.getAll(key);
+    // 不合规则的已知参数和名单外参数都静默不转发，不在这里返回 invalid_request。
     if (values.length === 1 && values[0].length < 300) query.set(key, values[0]);
   }
   const encodingStarted = performance.now();
@@ -119,6 +123,7 @@ async function handler(
   try {
     // 模型/旧快照与图片读取使用分层超时流；其它请求组合15秒总超时和客户端取消。
     const snapshotRead = canvas && (path.endsWith("/canvas") || canonical) && req.method === "GET";
+    // canonical GET 包括操作回执查询；只有这些 GET 使用分层流超时，写入仍用下方15秒总时限。
     const streamedRead = snapshotRead || asset && req.method === "GET";
     const snapshotWrite = canvas && path.endsWith("/canvas") && req.method === "PATCH";
     const traceId = streamedRead || snapshotWrite ? crypto.randomUUID() : "";
@@ -151,12 +156,14 @@ async function handler(
     const renewal = upstream.headers.get(SESSION_EXPIRY_HEADER);
     if (session && upstream.status !== 401 && renewal !== null && /^\d+$/.test(renewal)) {
       const secure = process.env.NODE_ENV === "production" && req.headers.get("x-forwarded-proto") === "https";
+      // 纯数字也可能超出安全整数，sessionMaxAge 此时回退默认30天；续期不代表这里验证了账户资料。
       responseHeaders.set("Set-Cookie", sessionCookie(session, sessionMaxAge(renewal), secure));
     }
     // 成功素材GET只透传允许的图片MIME并加nosniff；不是任意内容的同源文件托管。
     if (asset && upstream.ok && req.method === "GET") {
       const type = upstream.headers.get("content-type") || "";
       if (!/^image\/(png|jpeg|webp|gif)(?:;|$)/i.test(type)) { await upstream.body?.cancel(); return json({ error: "invalid_asset" }, 502); }
+      // MIME 白名单只看响应头，不解码图片或核对实际字节类型；内容权威校验属于上游资源协议。
       responseHeaders.set("Content-Type", type); responseHeaders.set("X-Content-Type-Options", "nosniff");
       const variant = upstream.headers.get("x-asset-variant");
       if (variant === "original" || variant === "preview") responseHeaders.set("X-Asset-Variant", variant);
@@ -173,6 +180,7 @@ async function handler(
       return new NextResponse(upstream.body, { status: upstream.status, headers: responseHeaders });
     }
     // 普通响应整体解JSON，因为登录/交换成功时须把access_token换成HttpOnly Cookie并从body移除。
+    // 普通响应没有预解析字节上限；请求体 limit 不能用来证明上游 JSON 响应也受同样约束。
     const body = upstream.status === 204 ? null : await upstream.json();
     // 旧快照写入trace分出接收/重编码/上游/响应耗时，不输出请求正文；字节数仅对字符串body计算。
     if (snapshotWrite) console.info("[canvas-save]", JSON.stringify({
@@ -190,6 +198,7 @@ async function handler(
     );
     const secure = process.env.NODE_ENV === "production" && req.headers.get("x-forwarded-proto") === "https";
     // 登录/交换令牌只进Set-Cookie，不回到浏览器可读JSON；其它会话响应按上游剩余时间更新。
+    // 按字段存在处理，不仅限定 auth 路径/成功状态；原始流透传分支不进入此令牌移除逻辑。
     if (body?.access_token) {
       responseHeaders.set("Set-Cookie", sessionCookie(body.access_token, sessionMaxAge(body.expires_in), secure));
       delete body.access_token;
@@ -197,6 +206,7 @@ async function handler(
       const renewed = upstream.headers.get(SESSION_EXPIRY_HEADER);
       if (renewed !== null && /^\d+$/.test(renewed)) responseHeaders.set("Set-Cookie", sessionCookie(session, sessionMaxAge(renewed), secure));
     }
+    // 401 不在这里主动清 Cookie；错误响应保持状态，客户端再决定登录/重试流程。
     // 仅上游确认登出成功后清Cookie，不把一次网络失败当成成功退出。
     if (path === "auth/logout" && upstream.ok)
       responseHeaders.set(

src/app/api/oauth/[provider]/route.ts

@@ -12,6 +12,7 @@ export async function GET(
 ) {
   const { provider } = await params;
   const challenges = req.nextUrl.searchParams.getAll("challenge");
+  // 这里只验证 challenge 字符表示，不验证 verifier/登录 state 或交换身份；额外查询参数也不会透传上游。
   const challenge = challenges[0];
   if (
     !["google", "slack"].includes(provider) ||

src/app/dashboard/[workspace]/[board]/page.tsx

@@ -5,7 +5,8 @@
 import { Suspense } from "react";
 import GraphPage from "@/components/workspace/graph-page";
 
-/** params按当前Next版本await；Suspense给客户端画布准备过程提供状态占位，不在此发模型请求。 */
+/** params按当前Next版本await；Suspense为子树渲染时的挂起提供占位，不在此发模型请求。
+ * params 的 await 在此边界外；GraphPage 在 effect 中加载模型时的进度/错误由自身状态呈现。 */
 export default async function Page({ params }: { params: Promise<{ workspace: string; board: string }> }) {
   const { workspace, board } = await params;
   return (

src/app/dashboard/dashboard.tsx

@@ -55,6 +55,7 @@ export default function DashboardSidebar() {
   // 路径workspace优先于查询和本地选择；slug由目录解析，活动board可补充该路由引用的真实ID。
   const workspaceRef = params.workspace || searchParams.get("workspace") || selectedWorkspace;
   const currentWorkspace = workspaces.find((item) => matchesRef(item, workspaceRef));
+  // 目录未解析时可暂用路由 ref；这里的字符串回退不是“空间存在/有权限”的证明，后续服务请求仍需验证。
   const workspace = currentWorkspace?.id || (activeBoard?.workspace_ref === workspaceRef ? activeBoard.workspace_id : workspaceRef);
 
   /** demo用本地资料，真实模式并行加载profile/空间；active+signal阻止卸载后的资料结果写入。 */
@@ -68,6 +69,7 @@ export default function DashboardSidebar() {
     }
     let active = true;
     const controller = new AbortController();
+    // 只切换加载状态，不清空之前 profile/workspaces/error；成功读取也不会在这里自动清除旧 error。
     setStatus("loading");
     loadWorkspaceHome(api, controller.signal)
       .then(({ profile, workspaces }) => {
@@ -89,6 +91,7 @@ export default function DashboardSidebar() {
   /** 每次目录加载先留本空间项，再取完整分页；仅最新listVersion可采用列表，换空间时中断旧请求。 */
   useEffect(() => {
     if (!workspace || status !== "ready") return;
+    // listVersion 只保护目录结果采用，不是网络取消或账号代次；创建成功时也递增它，防较旧列表覆盖新项。
     const version = ++listVersion.current;
     let active = true;
     setBoards((list) => list.filter((board) => board.workspace_id === workspace));
@@ -120,6 +123,7 @@ export default function DashboardSidebar() {
     setCreating(true);
     setError("");
     try {
+      // 捕获触发本次创建的 workspace/demo；await 后不另核对挂载/账户，宿主生命周期应避免旧操作采用到新界面。
       const board = demo
         ? { id: crypto.randomUUID(), workspace_id: workspace, title: DEFAULT_BOARD_TITLE, kind: "board" as const, version: 1 }
         : await createBoard(api, DEFAULT_BOARD_TITLE, workspace, (created) => {
@@ -128,6 +132,7 @@ export default function DashboardSidebar() {
           });
       listVersion.current += 1;
       setBoards((list) => [board, ...list]);
+      // demo 已先更新 React 列表，随后 Storage 写失败也不回滚该列表；错误仅报告在侧栏。
       if (demo) localStorage.setItem("endoleap_demo_boards_" + workspace, JSON.stringify([board, ...readDemoBoards(workspace)]));
       setQuery("");
       router.push(boardHref(currentWorkspace?.slug || board.workspace_id, board.slug || board.id, demo));
@@ -158,6 +163,7 @@ export default function DashboardSidebar() {
   }
 
   /** 真实退出先retireIdentity并完成本地关闭/保存，再请求服务登出；失败留在当前界面报告，不跳过保存。 */
+  // 此函数无独立 busy/ref 互斥；多次点击仍可调用。退休身份成功但上游登出失败时也不会复活旧 runtime。
   async function logout() {
     try {
       if (!demo) { await runtimeHost.retireIdentity(); await api("auth/logout", { method: "POST" }); }
@@ -177,6 +183,7 @@ export default function DashboardSidebar() {
 
   /** 成功后同时更新本地目录与匹配的活动board元数据；错误转换成文案交EditableTitle保留草稿显示。 */
   async function renameTitle(title: string) {
+    // 优先使用 activeBoard.id；编辑按钮先约束路由/空间匹配，此函数本身不重新执行同一组匹配检查。
     const id = activeBoard?.id || params.board;
     if (!id || !workspace) return;
     try {
@@ -184,6 +191,7 @@ export default function DashboardSidebar() {
         const list = readDemoBoards(workspace);
         localStorage.setItem("endoleap_demo_boards_" + workspace, JSON.stringify(list.map((board) => board.id === id ? { ...board, title } : board)));
       } else await renameBoard(api, workspace, id, title);
+      // 目录更新按 ID 匹配，活动元数据更新额外比 workspace；此处不递增 listVersion，旧目录读取仍可能随后到达。
       setBoards((list) => list.map((board) => board.id === id ? { ...board, title } : board));
       setActiveBoard((board) => board?.id === id && board.workspace_id === workspace ? { ...board, title } : board);
     } catch (error) { throw new Error(errorText(error)); }
@@ -196,6 +204,7 @@ export default function DashboardSidebar() {
   const transition = { duration: reduceMotion ? 0 : 0.24, ease: [0.22, 1, 0.36, 1] as const };
   const roleLabel = currentWorkspace?.role === "admin" ? "管理员" : currentWorkspace?.role === "editor" ? "编辑者" : currentWorkspace?.role === "viewer" ? "查看者" : "工作空间";
 
+  // 折叠只改变显示和键盘可达性，侧栏仍挂载，账户/目录状态和 effect 不因收起而销毁。
   // 展示分为浮动条、侧栏目录、共享账户popover和账户面板；路由/空间作为key让标题及目录局部状态重置。
   return (
     <>

src/app/dashboard/layout.tsx

@@ -8,7 +8,8 @@ import { ActiveBoardProvider } from "@/components/workspace/active-board";
 import DashboardSidebar from "./dashboard";
 import styles from "@/components/workspace/workspace.module.css";
 
-/** 当前board信息由ActiveBoardProvider跨侧栏/画布共享；Suspense只包侧栏，fallback保留其布局宽度。 */
+/** 当前board信息由ActiveBoardProvider跨侧栏/画布共享；Suspense只包侧栏，fallback保留其布局宽度。
+ * 该边界响应侧栏渲染期间的 suspend，不自动等待侧栏在 effect 中发起的普通请求。 */
 export default function DashboardLayout({ children }: { children: ReactNode }) {
   return (
     <ActiveBoardProvider>

src/app/layout.tsx

@@ -22,7 +22,8 @@ export const metadata: Metadata = {
   },
 };
 
-/** 服务端布局输出中文html/body壳；客户端反馈Provider包在runtime宿主外侧，供宿主状态提示使用。 */
+/** 服务端布局输出中文html/body壳；客户端反馈Provider包在runtime宿主外侧，供宿主状态提示使用。
+ * children 作为插槽传入客户端宿主，不会因此把所有子页面模块变成客户端代码；宿主的释放逻辑在自身模块。 */
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="zh-CN" data-scroll-behavior="smooth">

src/app/login/page.tsx

@@ -35,6 +35,7 @@ export default function Login() {
       verify = hash.get("verify_email"),
       failure = hash.get("error");
     if (!code && !verify && !failure) return;
+    // 不只删除认证片段，也删除原 query；当前页面没有保留/恢复任意 returnTo 的流程。
     history.replaceState(null, "", location.pathname);
     if (failure) {
       setError("第三方登录未完成，请重新尝试。");
@@ -68,6 +69,7 @@ export default function Login() {
    * HTML输入限制给即时反馈，服务端仍负责真实凭证/注册校验。 */
   async function submit(e: FormEvent) {
     e.preventDefault();
+    // busy 是显示状态，不是函数入口互斥锁；按钮禁用限制常规点击，submit 本身不检查已在执行。
     setBusy(true);
     setError("");
     setMessage("");
@@ -76,6 +78,7 @@ export default function Login() {
         method: "POST",
         body: JSON.stringify({ email, password }),
       });
+      // 使用触发本次提交时 render 闭包里的 register；等待期间切换模式不会改变这次请求的后续分支。
       if (register)
         setMessage("验证邮件已请求发送，请检查邮箱并点击验证链接。");
       else router.push("/dashboard");
@@ -98,6 +101,7 @@ export default function Login() {
       setError("无法启动登录，请重新尝试。");
     }
   }
+  // submit/oauth 同样没有卸载取消或结果代次校验；回调链结束前可继续调用 router/setState。
   // 模式切换只清提示，已有邮箱/密码和可见性独立保留。
   // 渲染分为品牌故事、模式切换、受控凭证表单、OAuth按钮与demo入口；错误用alert，非错误提示用status。
   return (

src/app/page.tsx

@@ -21,12 +21,14 @@ export default async function Home() {
         signal: AbortSignal.timeout(15000),
       });
       // 按响应状态确定是否已认证，再丢弃不需要的body；此处不解析profile字段。
+      // 先保存 HTTP 成功判定；随后 cancel 若抛错，catch 不会把 authenticated 重置为 false。
       authenticated = response.ok;
       await response.body?.cancel();
     } catch {
       // An unverified session must not hide the public landing page.
     }
   }
+  // redirect 放在上方 try/catch 外，避免把框架用于导航的控制流异常当作 profile 请求失败吞掉。
   // 仅在确认成功后跳工作台，未认证时沿用同一静态展示组件。
   if (authenticated) redirect("/dashboard");
   return <LandingPage />;

src/components/canvas/ai-panel.tsx

@@ -14,6 +14,7 @@ import type { CanvasModel, useCanvasAI } from "./use-canvas-ai";
 import styles from "./canvas.module.css";
 /** 以boardId+node.id定位run步骤，列表最后一项作为当前任务；NodeToolbar将面板附着在显示节点下方。 */
 export function AIPanel({ id, node, workspace, boardId, ai, save }: { id: string; node: CanvasNode; workspace: string; boardId: string; ai: ReturnType<typeof useCanvasAI>; save: (patch: NonNullable<CanvasNode["data"]["ai"]>) => void }) {
+  // 配置只用初次挂载的 node 初始化，不随外部 data.ai 自动重置；切换目标时应由宿主重建/隔离面板。
   const [models, setModels] = useState<CanvasModel[]>([]);
   const [model, setModel] = useState(node.data.ai?.modelId || "");
   const [prompt, setPrompt] = useState(node.data.ai?.prompt || "");
@@ -24,6 +25,7 @@ export function AIPanel({ id, node, workspace, boardId, ai, save }: { id: string
   const image = ["image", "plain-image"].includes(node.data.kind);
   const relevant = [...ai.runs.values()].filter((run) => run.steps?.some((step) => step.board_id === boardId && step.node_id === node.id));
   const run = relevant.at(-1), step = run?.steps?.find((step) => step.board_id === boardId && step.node_id === node.id);
+  // starting 是 React 状态，按钮禁用在重渲染后生效，不是函数入口的同步互斥标记。
   // starting防止本地重复启动，之后以步骤queued/running判断生成忙碌；这不是整份画布的同步锁。
   const busy = starting || step?.status === "queued" || step?.status === "running";
   // 演示/非live路径不请求模型；真实路径按输出模态筛选，并保留仍兼容选择或回退到首个可用模型。
@@ -39,6 +41,7 @@ export function AIPanel({ id, node, workspace, boardId, ai, save }: { id: string
     return () => controller.abort();
   }, [workspace, boardId, image, ai.live]);
   /** 构造当前输入配置，参数固定为空对象；状态切换事件需显式替换刚改变的值，避免读取旧React state。 */
+  // 每次保存都显式 parameters:{}，不会保留节点先前的自定义参数。
   const config = () => ({ enabled: true, modelId: model, prompt, propagate, parameters: {} });
   /** 输入blur时，有模型且live才调用save；仅持久化配置，不启动服务端任务。 */
   const persist = () => { if (model && ai.live) save(config()); };

src/components/canvas/branch-menu.tsx

@@ -21,11 +21,14 @@ export function BranchMenu({ request, close, choose }: { request: BranchRequest
     if (!request) return;
     const focus = document.activeElement as HTMLElement | null;
     ref.current?.querySelector<HTMLButtonElement>("button[data-choice]")?.focus();
+    // outside 不阻止事件，关闭后原指针仍可交给被点击的画布/控件；这是非模态浮层，不提供焦点圈定。
     const outside = (event: PointerEvent) => { if (!ref.current?.contains(event.target as Node)) close(); };
     const escape = (event: KeyboardEvent) => { if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); close(); focus?.focus(); } };
     window.addEventListener("pointerdown", outside); window.addEventListener("keydown", escape, true);
     return () => { window.removeEventListener("pointerdown", outside); window.removeEventListener("keydown", escape, true); };
   }, [request, close]);
+  // choose 不在本组件内调用 close；异步创建、异常报告和关闭时机由宿主回调负责。
+  // close 引用或 request 变化会重装监听并重新捕获焦点，不只在空→非空时执行。
   // 无document时不创建Portal。菜单位置按预设宽高限制在视口边距内；上下键循环所有按钮（含关闭）。
   // 减少动态效果偏好禁用位移/缩放动画；退出动画仍通过AnimatePresence管理。
   if (typeof document === "undefined") return null;

src/components/canvas/canvas-edge.tsx

@@ -59,6 +59,7 @@ export function CanvasEdge(props: EdgeProps<CanvasEdgeModel>) {
   const midpoint = cubicPoint(segments[Math.floor(segments.length / 2)], .5);
   const color = appearance.color || "#aa968b", width = appearance.width || 1.5;
   // 清洗边ID供SVG marker引用；动画尊重减少动态效果，executing模式只在active集合含本边时播放。
+  // marker 命名未加入 viewId/实例 ID，且字符替换可能碰撞；调用方须维持当前 SVG 文档内标识可用。
   const markerId = `edge-${props.id.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
   const animated = !reduce && (animation.mode === "always" || animation.mode === "executing" && editing.active.has(props.id));
   const knots = data.path?.knots || [];
@@ -76,6 +77,7 @@ export function CanvasEdge(props: EdgeProps<CanvasEdgeModel>) {
     const capture = event.currentTarget.closest('[data-headless-canvas]') ?? event.currentTarget.closest('.react-flow') ?? event.currentTarget;
     // begin返回false拒绝；返回对象则保存租约，其余返回值走旧接口，控制点选择仍是组件局部状态。
     const lease = editing.begin(props.id); if (lease === false) return;
+    // begin 已执行后才安装监听/取得捕获；后续动作实现应不抛错，否则这里没有总括 try/finally 回滚。
     const controller = new AbortController();
     gesture.current = { id, part, capture, controller, pointerId: event.pointerId, lease: lease && typeof lease === 'object' ? lease : undefined }; setSelectedKnot(id);
     /** 原生监听先按pointerId过滤，再交当前处理器；取消和lostpointercapture仅在手势仍存在时处理。 */
@@ -92,6 +94,7 @@ export function CanvasEdge(props: EdgeProps<CanvasEdgeModel>) {
     if (!ownsPointerCapture(current,event)) return;
     if(!current)return;
     const point = flow.screenToFlowPosition({ x: event.clientX, y: event.clientY });
+    // 读的是最新 render 的 path，不是 pointerdown 快照；需要父层把 preview 更新投影回来以便后续事件继续编辑。
     const next = structuredClone(data.path || { type: "bezier-chain" as const, knots: [] });
     // 端部控制柄保存相对端点的向量；中间点位置为绝对画布点，中间控制柄保存相对knot.position的向量。
     if (current.part === "startControl" || current.part === "endControl") next[current.part] = minus(point, current.part === "startControl" ? from.point : to.point);
@@ -119,6 +122,7 @@ export function CanvasEdge(props: EdgeProps<CanvasEdgeModel>) {
   function stop(event: PointerEvent<SVGCircleElement>) {
     if(!gesture.current)return;event.stopPropagation();
     if (!ownsPointerCapture(gesture.current,event)) return; const current = gesture.current!; move(event); gesture.current = null; current.controller.abort();
+    // 提交/取消动作先于 release，且未用 finally 包裹；动作抛错可能跳过捕获释放，不能称无条件清理。
     if (current.lease) current.lease.commit(); else editing.finish?.();
     releasePointerCapture(current.capture,current.pointerId);
   }
@@ -132,6 +136,7 @@ export function CanvasEdge(props: EdgeProps<CanvasEdgeModel>) {
     if (current.lease) current.lease.cancel(); else editing.cancel?.();
     releasePointerCapture(current.capture,current.pointerId);
   }
+  // 工具栏/键盘 patch 不是拖动 lease 流程，是否形成一次 history 单元仍由 Provider 决定。
   // 每次渲染刷新原生事件转发目标；控制点自身也挂React事件，所有处理器均检查手势/捕获归属。
   pointerHandlers.current = { move, stop, cancel };
   /** 控制点屏幕半径与描边按zoom反向补偿。点击选择点，指针可拖；键盘仅移动曲线点位置或端部柄。
@@ -147,6 +152,7 @@ export function CanvasEdge(props: EdgeProps<CanvasEdgeModel>) {
         editing.patch(props.id, { ...data, path: next });
       }
     }} />;
+  // selectedKnot 不随外部 knots 删除自动重置；工具栏显示模式可退到最后一点，删除回调仍优先使用旧选中 ID。
   // 双击路径按点击位置插点；选中描边和动画不接收指针，BaseEdge提供较宽的交互区域。
   // flow用SVG animateMotion沿path运行；dash/pulse使用CSS动画，方向与时长来自连线数据。
   // 选中时绘制工具栏、所有knot位置和首尾柄，仅被选中knot显示自己的in/out柄。
@@ -178,6 +184,7 @@ export function CanvasEdge(props: EdgeProps<CanvasEdgeModel>) {
 /** 连接拖动中的临时预览线。两端命中Handle时使用兼容连接点，尚未命中时以指针位置作终点并反转起点法向。
  * 只绘制单段connectorBezier，不创建或保存实际连线；调用方样式可覆盖默认线色/线宽。 */
 export function CanvasConnectionLine(props: ConnectionLineComponentProps<CanvasNode>) {
+  // 本临时线仍使用兼容端点算法，与上方已建连线的 __headlessRecord 原生坐标分流不同。
   const from = connector(props.fromNode, props.fromHandle.id, "right");
   const to = props.toNode && props.toHandle ? connector(props.toNode, props.toHandle.id, "left") : { point: { x: props.toX, y: props.toY }, normal: { x: -from.normal.x, y: -from.normal.y } };
   return <path fill="none" className="react-flow__connection-path" d={connectorBezier(from, to)} style={{ stroke: "#aa968b", strokeWidth: 1.5, ...props.connectionLineStyle, strokeLinecap: "round" }} />;

src/components/canvas/canvas-icon.tsx

@@ -19,6 +19,8 @@ export function CanvasIcon({ name = "Star", size = 24, width = size, height = si
   useEffect(() => {
     const controller = new AbortController();
     setResult({ name, paths: peekIcon(name) });
+    // 清理通过订阅 signal 取消，但 then 没有额外 active/代次检查；已兑现 Promise 的回调仍可能运行。
+    // result.name 只能隔离不同名称，同名重试之间不靠此字段区分代次。
     loadIcon(name, controller.signal).then((paths) => setResult({ name, paths }), (error) => {
       if (error.name !== "AbortError") setResult({ name, error: true });
     });
@@ -27,8 +29,10 @@ export function CanvasIcon({ name = "Star", size = 24, width = size, height = si
   // effect可能还没处理新name，故读取结果前再次比对名称；失败标记也必须属于当前图标。
   const paths = result.name === name ? result.paths : undefined;
   const failed = result.name === name && result.error;
+  // retry 不清浏览器 HTTP 缓存；同名已有成功分片时，loadIcon 仍可能直接复用共享缓存。
   // 以24×24为标准坐标；absoluteStrokeWidth在size为数值时按尺寸反向补偿描边宽度。
   // 成功时保留调用方onClick；失败时点击改为停止冒泡并重试，避免同时触发外层节点点击。
+  // props 在默认 SVG 属性之后展开，可覆盖 viewBox 等；data-icon-* 和最终 onClick 在其后固定。
   // 加载中用虚线方框，失败用叉号与title，data-icon-state供样式或检查观察显示状态。
   return <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width={width} height={height} fill="none" stroke="currentColor" strokeWidth={absoluteStrokeWidth && typeof size === "number" ? Number(strokeWidth) * 24 / size : strokeWidth} strokeLinecap="round" strokeLinejoin="round"
     {...props} data-icon-id={name} data-icon-state={paths ? "loaded" : failed ? "error" : "loading"}

src/components/canvas/canvas-image.tsx

@@ -11,7 +11,9 @@ export const ImagePreviews = createContext<{ sources: Map<string,string>; loaded
 export function CanvasImage({ id, src, title, className }: { id: string; src?: string; title: string; className: string }) {
   // 本地源按元素id而非远端URL索引，同一资源在不同节点中可拥有各自的显示交接状态。
   const previews = useContext(ImagePreviews), local = previews.sources.get(id);
+  // onLoad 只携带元素 id，不附带 src/资源代次；迟到加载能否清掉当前预览需由 Provider 的 loaded 实现判定。
   const remote = <img loading="lazy" decoding="async" className={className} src={src} alt={title} draggable={false} referrerPolicy="no-referrer" onLoad={() => previews.loaded(id)} />;
+  // 没有 onError 状态或自动重试；底图失败时若上层仍保留 local，覆盖图可继续显示。
   // 没有预览或预览已等于正式源时，只绘制一张图片，避免冗余叠层。
   if (!local || local === src) return remote;
   // 正式图片继续在底层加载，本地预览绝对定位覆盖在上方；Provider清掉该id后自然移除覆盖。

src/components/canvas/canvas-overlays.tsx

@@ -16,6 +16,7 @@ export function useCanvasOverlay(targetId:string,placement:string){
  const scope=useContext(CanvasOverlays),instance=useId(),refresh=useRef<()=>void>(()=>{}),cleanup=useRef<()=>void>(()=>{});
  // 订阅视口变化触发重渲染，后续layout effect再读取浮层屏幕矩形。
  useViewport();
+ // 此处 getSnapshot 只读取当前 render；不单独订阅元素代次，外层须在元素变化时让节点重新渲染。
  const incarnation=scope?.engine.getSnapshot().document.elements.get(targetId)?.incarnation;
  // 每次换DOM或作用域先清理旧注册；缺少DOM/Provider/元素生命周期时保持空注册。
  const ref=useCallback((element:HTMLElement|null)=>{cleanup.current();refresh.current=()=>{};cleanup.current=()=>{};if(!element||!scope||incarnation===undefined)return;
@@ -26,10 +27,12 @@ export function useCanvasOverlay(targetId:string,placement:string){
   // 注册返回lease，后续测量只更新这一条；composition事件同步更新组合态供快捷键路由参考。
   const lease=scope.index.register(instance,value()),measure=()=>lease.update(value()),start=()=>{composing=true;measure();},end=()=>{composing=false;measure();};refresh.current=measure;
   // focusout后等微任务再测量，让新焦点落定；ResizeObserver与首帧测量补充尺寸/挂载后的变化。
+  // 已排队的 blur 微任务无法取消，清理后仍会测量；索引租约的 token 检查使旧 update 不再发布。
   const blur=()=>queueMicrotask(measure),observer=new ResizeObserver(measure);observer.observe(element);element.addEventListener('focusin',measure);element.addEventListener('focusout',blur);element.addEventListener('compositionstart',start);element.addEventListener('compositionend',end);let frame=requestAnimationFrame(measure);
   // 清除本绑定拥有的DOM标记、首帧任务、观察器和所有监听，再释放索引租约；不删除目标元素。
   cleanup.current=()=>{if(element.dataset.canvasOverlayOwner===marker){delete element.dataset.canvasOverlayView;delete element.dataset.canvasOverlayOwner;delete element.dataset.canvasOverlayTarget;delete element.dataset.canvasOverlayPlacement;}cancelAnimationFrame(frame);observer.disconnect();element.removeEventListener('focusin',measure);element.removeEventListener('focusout',blur);element.removeEventListener('compositionstart',start);element.removeEventListener('compositionend',end);lease.release();};
  },[scope,instance,targetId,incarnation,placement]);
+ // ResizeObserver 只观察尺寸，普通页面滚动/位置动画不一定触发它；边界还依赖视口重渲染与布局提交刷新。
  // 每次布局提交刷新边界；卸载清理使用ref中的最新函数，兼容期间发生的DOM/目标替换。
  useLayoutEffect(()=>{refresh.current();});useLayoutEffect(()=>()=>cleanup.current(),[]);return ref;
 }

src/components/canvas/canvas-renderers.tsx

@@ -21,4 +21,5 @@ const nodes={material:MaterialNode,plainText:PlainTextNode,plainImage:PlainImage
 /** 每项保留原始类型/结构描述，node按rendererId查表，connection绑定CanvasEdge。
  * render与preview目前共用同一个组件；createReactRenderers负责生成供ReactFlow使用的注册结果。
  * 本表没有自定义类型的通配组件，兼容占位由投影/渲染选择链路处理。 */
+// 模块级初始化一次，供多个宿主复用；preview 选择同一组件不代表自动只读，交互权限仍由外层上下文限制。
 export const defaultCanvasRenderers=createReactRenderers(builtinRendererDefinitions.map(definition=>{const render=definition.structure==='node'?nodes[definition.rendererId as keyof typeof nodes]:CanvasEdge;return{...definition,render,preview:render} as ReactRendererDefinition;}));

src/components/canvas/canvas-text-editor.tsx

@@ -29,10 +29,13 @@ export function CanvasTextEditor({ id, data, selected, plain = false }: { id: st
     element?.setSelectionRange(element.value.length, element.value.length);
   }, [editing]);
   /** 通知控制器开始文本编辑会话，再开启本地输入态；真正可写还要求节点保持选中。 */
+  // begin 没有成功返回值约定；即使作用域包装静默拒绝动作，本地 editing 仍被设 true，文档修改仍由动作护栏判定。
   function begin() { actions.begin(id); setEditing(true); }
   // 同时满足editing与selected才允许输入；展示时textarea只读且不进入Tab顺序。
   const active = editing && selected;
   const label = plain ? "纯文本" : data.title;
+  // 本组件未监听 compositionstart/end；正文变化直接转交 edit，输入法合并与 history 分组由 Provider 决定。
+  // textarea 的 Escape 处理也不检查 isComposing，仅用于退出输入态。
   // 输入最多100000字符；onChange立即发动作，blur退出并通知endEditing。Escape只结束编辑，不回滚已输入文本。
   // 非编辑态覆盖层不接管单击逻辑，让外层画布选择/拖动；双击使用浏览器原生时序并按移动标记过滤。
   // 键盘Enter/F2仅在已选中时进入；双击未选中节点会先发select，再开始编辑。

src/components/canvas/content-handles.tsx

@@ -7,5 +7,6 @@ import styles from "./canvas.module.css";
 /** 四边均使用source Handle以配合画布连接模式；selected控制能否开始连线以及读屏可见性。
  * 不在这里创建端点记录，也不判断跨分区连线的归属。 */
 export function ContentHandles({ selected }: { selected: boolean }) {
+  // selected 只设置 isConnectableStart/aria-hidden；未显式设置结束端能力或 tabIndex，仍须遵守外层 ReactFlow 配置。
   return <>{([["top", Position.Top], ["right", Position.Right], ["bottom", Position.Bottom], ["left", Position.Left]] as const).map(([id, position]) => <Handle key={id} id={id} type="source" position={position} className={styles.centerHandle} isConnectableStart={selected} aria-hidden={!selected} aria-label={`从 ${id} 连接元素`} />)}</>;
 }

src/components/canvas/draft-recovery.tsx

@@ -11,6 +11,7 @@ export function DraftRecovery({ restore, discard, canRestore = true, exportDraft
   const dialog = useRef<HTMLDialogElement>(null);
   // 挂载时showModal启用浏览器模态行为，卸载时close；不额外保存一份open状态。
   useEffect(() => { const element = dialog.current; element?.showModal(); return () => element?.close(); }, []);
+  // 点击按钮只同步调用宿主，不自动 close，也没有 busy/重复点击互斥；宿主完成选择后负责卸载对话框。
   // 无document不创建Portal；取消事件阻止默认Escape关闭，要求用户通过明确的版本选择按钮处理。
   if (typeof document === "undefined") return null;
   return createPortal(<dialog ref={dialog} className={styles.recoveryDialog} aria-labelledby="draft-recovery-title" onCancel={(event) => event.preventDefault()}>

src/components/canvas/edge-editing.tsx

@@ -9,5 +9,6 @@ import type { EdgeData } from "@/lib/canvas-v2";
 /** begin可拒绝、使用旧版无返回值模式，或返回绑定手势的EditingLease；patch的transient区分临时预览。
  * finish/cancel可选，active为当前活动连线ID集合；默认Set不代表全项目状态仓库。 */
 const defaultEditing = { finish: undefined as undefined | (() => void), cancel: undefined as undefined | (() => void), begin: (_id?: string): boolean | void | EditingLease<NonNullable<EdgeData['path']>> => {}, patch: (_id: string, _data: EdgeData, _transient = false) => {}, active: new Set<string>() };
+// 默认 active Set 与动作对象是共享引用，未冻结；消费方只能读取，不应通过修改默认对象来发布状态。
 /** Context的类型保留可选结束钩子，兼容旧画布与新版租约式交互，不在此创建编辑任务队列。 */
 export const EdgeEditing = createContext<Omit<typeof defaultEditing, 'finish' | 'cancel'> & Partial<Pick<typeof defaultEditing, 'finish' | 'cancel'>>>(defaultEditing);

src/components/canvas/edge-toolbar.tsx

@@ -12,6 +12,7 @@ import styles from "./canvas.module.css";
 export function EdgeToolbarControls({ id, x, y, data, change, add, remove, count, knotMode, changeKnotMode }: { id: string; x: number; y: number; data: EdgeData; change: (data: EdgeData) => void; add: () => void; remove: () => void; count: number; knotMode?: string; changeKnotMode: (mode: "corner" | "smooth" | "symmetric") => void }) {
   const a = data.appearance || {}, animation = data.animation || {};
   /** 合并appearance子对象并保留其它连线数据；箭头/箭尾各自更新时仍需在事件内保留其嵌套字段。 */
+  // 合并基于本次 render 捕获的 data；change 必须由外层正确采用，不能把旧回调当成读取最新文档的入口。
   const appearance = (patch: NonNullable<EdgeData["appearance"]>) => change({ ...data, appearance: { ...a, ...patch } });
   /** 动画属性单独合并，调整一个设置不覆盖已有方向、效果等其它字段。 */
   const animate = (patch: NonNullable<EdgeData["animation"]>) => change({ ...data, animation: { ...animation, ...patch } });
@@ -20,6 +21,7 @@ export function EdgeToolbarControls({ id, x, y, data, change, add, remove, count
   // 宽度校验0.5—20，端部尺寸4—32，动画时长250—30000ms；透明度范围由range控件给出。
   // head/tail分别合并type/size/filled；传播开关将execution替换为当前enabled对象。
   // 无曲线点时禁用模式和删除，达到64点时禁用添加；外层仍负责相应操作的实际合法性。
+  // 每个控件即时调用回调，不负责 history 分组或持久化；数值范围检查也不要求步长整数倍。
   // 所有指针/键盘冒泡止于工具栏，避免颜色或输入操作同时触发画布编辑。
   return <EdgeToolbar alignY="bottom" edgeId={id} x={x} y={y} isVisible style={{ zIndex: 115, pointerEvents: "auto" }}><div role="toolbar" aria-label="连线编辑" className={`${styles.edgeToolbar} nodrag nopan nowheel`}
     onPointerDown={(event) => event.stopPropagation()} onClick={(event) => event.stopPropagation()} onDoubleClick={(event) => event.stopPropagation()} onKeyDown={(event) => event.stopPropagation()}>

src/components/canvas/editing-lease.ts

@@ -6,7 +6,8 @@
 /** preview产生临时显示，commit结束并提交，cancel撤销本次预览；具体语义由创建租约的编辑器实现。 */
 export type EditingLease<T> = { preview(value: T): void; commit(): void; cancel(): void };
 
-/** 冻结包装后的方法表，每次调用重新检查isCurrent；过期事件静默忽略，不能结束另一场交互。 */
+/** 冻结包装后的方法表，每次调用重新检查isCurrent；过期事件静默忽略。
+ * 是否识别精确交互由 isCurrent 的实现保证；这里只冻结外壳，不复制 actions 或吞掉检查/动作异常。 */
 export function guardEditingLease<T>(isCurrent: () => boolean, actions: EditingLease<T>): EditingLease<T> {
   return Object.freeze({
     // 指针移动可能持续产生事件，必须逐次检查，不能只在创建租约时检查一次。

src/components/canvas/frame-feedback.tsx

@@ -20,6 +20,7 @@ export function MembershipBadge({ id, frameId, selected }: { id: string; frameId
   const name = target ? names.get(target) : undefined;
   if (!drop && !selected) return null;
   // 目标有名称时区分“松开加入”与“属于”；没有目标且原来有归属则提示移出，否则不绘制。
+  // 提示依赖 names 完整：目标有 ID 却缺名称时也会落入下面的移出/空提示分支，不证明真实归属已改变。
   const label = name ? `${drop && drop.to !== drop.from ? "松开加入" : "属于"}：${name}` : drop?.from ? `松开移出：${names.get(drop.from) || "分区"}` : null;
   return label && <div className={styles.membershipBadge} title={label}><Frame size={11} />{label}</div>;
 }

src/components/canvas/frame-label-menu.tsx

@@ -17,7 +17,9 @@ const options = [
 export function FrameLabelMenu({ value, change }: { value: FrameLabelMode; change: (mode: FrameLabelMode) => void }) {
   // 以数组保存三个真实按钮引用，键盘选择后直接聚焦；滑块索引在未知value时回退0。
   const items = useRef<(HTMLButtonElement | null)[]>([]);
+  // 未知值只让视觉索引回退0，下面 radio 的 aria-checked/tabIndex 仍按原 value 比较，不会自动修复模型。
   const current = Math.max(0, options.findIndex((option) => option.value === value));
+  // 键盘计算基于受控 value 而非实际焦点；change 应让宿主及时发布新值，连续按键才沿新索引前进。
   // 左/上为-1，右/下为+1，通过加3再取模实现循环；Home/End直接使用0/2。
   // 阻止默认滚动并停止冒泡，避免选择模式的按键同时移动画布；滑块每项28px。
   return <div className={styles.frameLabelSegments} role="radiogroup" aria-label="分区名称显示模式" onKeyDown={(event) => {

src/components/canvas/frame-node.tsx

@@ -38,15 +38,19 @@ export function FrameNode(props: NodeProps<CanvasNode> & { directAnchors?: boole
   const cancelBlur = useRef(false);
   const mode = data.labelMode || "fixed";
   /** 去除首尾空白，空名称回退“未命名分区”；只有与模型不同才派发修改，再归一化输入显示。 */
+  // 这里只 trim/补默认名，maxLength 是输入控件限制；UTF-8 字节和数据合法性仍由命令/格式层负责。
   function saveTitle() {
     const name = title.trim() || "未命名分区";
     if (name !== data.title) editing.frame(id, { title: name });
     setTitle(name);
   }
+  // title effect 无论是否正编辑都跟随外部值，外部改名可能替换未提交草稿；局部保存后也不等待远端 ACK。
   // 选中时显示设置栏，动画尊重减少动态效果偏好；栏内事件停止冒泡，避免触发画布快捷键或拖动。
   // 折叠切换前按viewScale还原当前尺寸，存入原状态对应的expandedSize/collapsedSize供后续恢复。
   // 概览比例输入限定5%—400%，只更新presentation.contentScale；链接单独打开子画布。
+  // 折叠按钮只提交 presentation 候选，不直接隐藏/删除后代；实际尺寸恢复和投影由动作实现处理。
   // fixed名称与拖放提示用1/(zoom*viewScale)抵消缩放，scaled跟随画布，hidden不绘制名称。
+  // 所有端口都用 source 类型配合外层连接模式；方向差异由 Start/End 能力开关表达。
   // 四侧边框提供拖动命中区域；ports按同方向均匀分布，输出在右侧可起连线，输入在左侧可收连线。
   return <>
     <AnimatePresence>{selected && <NodeToolbar style={{ zIndex: 100, pointerEvents: "auto" }} isVisible={true} position={Position.Top} offset={45}>

src/components/canvas/graph-canvas.tsx

@@ -141,6 +141,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
   // 对成员任务保护节点关闭拖动/删除/连接；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。 */
+  // 这里优先按 local node.id 搜索，未同时限定 owner；旧协议跨 board 重名时取首个匹配，不能当作全局唯一身份。
   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); } };
@@ -190,6 +191,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
   /** 显示ID的选择交tree解析owner；稳定回调通过treeRef避免每次文档更新重建编辑上下文。 */
   const select = useCallback((id: string) => treeRef.current.select(id), []);
   /** 对目标owner建立checkpoint，把后续连续编辑归到同一撤销起点；缺目标时使用根board。 */
+  // checkpoint 只保存起点，没有对应 token 或原子结束动作；取消能力取决于旧节点组件的回退处理。
   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 })), []);
@@ -225,6 +227,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
       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);
       tree.dispatch({ type: "replace", document }, tree.views.nodeRefs.get(request.id)!.boardId);
       const child = document.nodes.at(-1)!;
+      // 使用 child 的 owner 局部坐标，未再投回根场景；Promise 的异步拒绝也不被外围同步 catch 捕获。
       void flow.setCenter(child.position.x + 130, child.position.y + 100, { zoom: flow.getZoom(), duration });
       setBranchRequest(null);
     } catch (error) { setError(error instanceof Error ? error.message : "无法创建节点。"); }
@@ -297,6 +300,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
    * 异步移动失败保留错误提示，不宣称所有跨分区步骤一起回滚。 */
   async function finishDrag(node: CanvasNode, dragged: CanvasNode[]) {
     if (dragSession.current !== "active") return;
+    // 先恢复 idle 才 await 后续成员移动；第二次拖动的防护依赖 tree 的保护节点/队列，而非这个状态持续锁定。
     const origins = new Map(dragOrigins.current);
     dragSession.current = "idle"; dragOrigins.current.clear(); setDraggedIds([]); tree.setDragging(false);
     if (!draggingFrame.current || snapshot && tree.rootDocument.schema_version === 2) {
@@ -330,6 +334,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
               }
             }
             // 不同owner组并行提出任务，每组沿父子路径逐跳等待；tree内部队列仍串行发送成员请求。
+            // Promise.all 任一拒绝不取消其它组，也不回滚已完成的 hop；失败队首还可能保持未决 Promise 等待重试。
             await Promise.all([...byOwner].map(async ([key, group]) => {
               let source = key.split("/")[0];
               for (const hop of subgraphMovePath(tree.current.current, source, group.target)) {
@@ -392,6 +397,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
     if (!["image/png", "image/jpeg", "image/webp", "image/gif"].includes(file.type) || file.size > (snapshot ? 20 * 1024 * 1024 : 2_000_000)) {
       pendingImage.current = null; setError(snapshot ? "请选择小于 20 MiB 的 PNG、JPEG、WebP 或 GIF 图片。" : "演示模式请选择小于 2 MB 的图片。"); return;
     }
+    // 文件选择完成后才消费保存的分支意图；不带源节点代次，实际创建前只按当前显示 ID 查 owner。
     const request = pendingImage.current; pendingImage.current = null;
     const kind = imageKind.current;
     // 真实图片上传先取得本地Blob预览并构造draft，随后把pendingUpload节点及可选分支边发布到owner。
@@ -417,6 +423,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
     // 演示不上传服务端，FileReader读取全部字节为Data URL；纯图片另解码初始尺寸，finally释放读取中UI状态。
     setImageUploading(true);
     try {
+      // 演示 FileReader/Image 没有卸载取消信号或 await 后身份检查；回调仍使用本次调用捕获的创建函数。
       const src = await new Promise<string>((resolve, reject) => {
         const reader = new FileReader();
         reader.onload = () => resolve(String(reader.result));
@@ -447,6 +454,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
     try {
       if (file.size > 5_000_000) throw new Error("请选择小于 5 MB 的图谱文件。");
       if (tree.rootDocument.nodes.some((node) => node.data.subgraph)) throw new Error("当前画布包含真实子图，请先导出备份并通过子图事务恢复，避免覆盖子图关系。");
+      // await 前检查的是本次 render 的根；读完不重新核对子图关系/画布身份，tree.dispatch 准入只能覆盖其自身护栏。
       const document = decodeCanvas(await file.text());
       if (document.nodes.some((node) => node.data.subgraph)) throw new Error("子图备份需要按原始画布关系恢复，不能直接导入到其他画布。");
       dispatch({ type: "replace", document });
@@ -460,6 +468,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
   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; }
+    // 多 board bundle 仅导出文档 JSON；importProject 仍只接收普通单文档，并不是这个 bundle 的对称恢复器。
     const content = JSON.stringify(documents.size > 1 ? { format: "endoleap-canvas-bundle", root: board.id, documents: Object.fromEntries(documents) } : { ...tree.rootDocument, viewport: flow.getViewport() }, null, 2);
     const url = URL.createObjectURL(new Blob([content], { type: "application/json" }));
     const link = document.createElement("a");
@@ -489,10 +498,12 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
     return () => window.removeEventListener("keydown", keydown);
   }, []);
 
+  // 上传失败行的“取消”只尝试移除占位节点，未直接 uploads.remove；任务/文件/预览寿命仍由上传 Hook 和卸载处理。
   // Provider把图片预览、节点动作、分区反馈及活动连线接到renderer；迁移时surface与底部创作栏设inert。
   // ReactFlow删除由onBeforeDelete拦截真实子图/暴露端口节点，避免默认删除破坏结构；普通元素沿tree变化入口。
   // 选择工具允许拖动/连接，抓手只平移；Space临时平移、Shift部分框选，滚轮默认平移、修饰键缩放。
   // 工具栏创建/模板/导入走上述入口，顶部视口操作保存本地viewport；AI只给选中且支持的节点显示。
+  // 迁移准入检查 UI 文件读取与上传；真正排空 writer/本地恢复由 prepareMigration 再检查。
   // 恢复弹窗先根再子，逐项核查canRestore；迁移组件检查草稿、文件IO和未完成上传再排空writer。
   return (
     <div className={`${styles.editor} ${tool === "hand" ? styles.handMode : ""}`}>
@@ -505,6 +516,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
           onBeforeDelete={async ({ nodes: removing }) => {
             if (tree.busy || tree.transactionBusy) return false;
             // 选中分区入口要先dissolve保留内容；内部节点若被父port引用，先移回父board再删，清理边界引用。
+            // 删除流程使用本次回调捕获的 tree 投影；await 后通过内存表补查，但没有全程冻结选择和历史的统一事务。
             const linked = removing.filter((node) => node.data.subgraph);
             const parents = subgraphParents(tree.current.current);
             const referenced = removing.filter((node) => {

src/components/canvas/headless-ai-panel.tsx

@@ -19,11 +19,13 @@ const object = (value: Json | undefined) => value && typeof value === 'object' &
 /** 配置输入从元素当前ai字段初始化；模型输出模态按image/plain-image与其它组件区分。
  * 元素数据来自父层投影，本组件直接读取engine根用于显示任务，不再创建额外轮询器。 */
 export function HeadlessAIPanel({ engine, element, close, viewId }: { engine: ProjectEngine; element: ElementRecord; close(): void; viewId:string }) {
+  // getSnapshot 是本次 render 的读取，不建立订阅；任务状态更新是否触发重渲染由父层负责。
   const saved = object(element.data.ai), root = engine.getSnapshot();
   const [models, setModels] = useState<readonly RunModel[]>([]), [loading, setLoading] = useState(true), [error, setError] = useState('');
   const [model, setModel] = useState(typeof saved.modelId === 'string' ? saved.modelId : '');
   const [prompt, setPrompt] = useState(typeof saved.prompt === 'string' ? saved.prompt : '');
   const [propagate, setPropagate] = useState(saved.propagate === true);
+  // 输入 state 仅从初次 saved 初始化；同一挂载内外部 ai 配置变化不会自动覆盖本地草稿。
   const image = ['image','plain-image'].includes(element.componentId);
   // 用runContainsTarget核对目标身份，选择相关任务列表的最后一项；不是按时间戳重新排序。
   const relevant = [...root.runtime.runs.values()].filter(run => runContainsTarget(run,element));
@@ -60,6 +62,8 @@ export function HeadlessAIPanel({ engine, element, close, viewId }: { engine: Pr
   const appliedOutput=typeof output.output_id==='string'&&run?.appliedOutputIds?.includes(output.output_id);
   // 状态文案先展示未解决取消/采用，再展示拒绝、已采用、等待受理与任务进度，防止把请求排队说成已执行。
   const message = cancelling ? '取消请求已保存，等待确认…' : applying ? '正在应用生成结果…' : rejectedStart ? `生成未受理：${rejectedStart.blockers.join('、')}` : appliedOutput ? '此生成结果已应用' : pending.length ? pending.some(record => record.phase === 'blocked') ? '生成受理需要处理' : '正在等待同步并受理生成…' : run?.blocked ? '生成结果已保留，当前编辑需要协调' : run?.error ? '任务跟踪需要处理，可重试' : run?.hasMore ? '正在同步任务状态…' : run ? ({queued:'已受理，等待生成',running:'正在生成…',succeeded:'已更新当前元素',failed:'生成未完成，原内容已保留',conflict:'内容已改变，生成结果已保留',cancelled:'已取消生成',partially_succeeded:'部分步骤已完成'}[run.status]) : '结果将显示在当前元素';
+  // 保存配置与 startRun 是两个同步命令，没有合成一笔事务；配置成功而启动拒绝时，配置仍已修改。
+  // 命令接受也不等于服务端已受理或已持久确认，后续状态以 ledger/run 为准。
   // 输入blur保存配置，执行按钮再保存一次且成功后startRun；忙碌时锁定配置和启动，关闭按钮仍可用。
   // queued/running提供取消请求入口；冲突输出保留展示，只有事件读完且未采用时才允许显式替换。
   // 跟踪重试调用engine.retry，不新建run.start；pointer/keydown止于面板，避免触发画布手势或快捷键。

src/components/canvas/headless-graph-canvas.tsx

@@ -149,8 +149,10 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
   // 保留调用方renderer表，并显式安装unsupported节点/边占位，未知内容仍可在场景中呈现。
   const nodeTypes=useMemo(()=>({...renderers.nodeTypes,unsupported:UnsupportedNode}),[renderers]),edgeTypes=useMemo(()=>({...renderers.edgeTypes,unsupported:UnsupportedEdge}),[renderers]);
   // 稳定动作闭包从current/engine读取最新状态，runtime-only发布不必重建全部卡片编辑上下文。
+  // current 是最近一次 React render 的快照，frame 合并期间可落后于 engine；需要强身份保证的入口仍须实时查询。
   const current = useRef({ root, projection, view, engine, sessions }); current.current = { root, projection, view, engine, sessions };
   /** 将命令拒绝或能力不可用显示为错误；成功结果无需额外复制进本地state。 */
+  // 这里只呈现 rejected/disabled，不捕获同步异常，也不在成功时自动清除旧错误文案。
   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)));
   }, []);
@@ -204,6 +206,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
     const width = (change.width ?? displayed.width!) / t.scale, height = (change.height ?? displayed.height!) / t.scale;
     const position = change.position ?? displayed.position, center = toLocal(t, { x: position.x + width * t.scale / 2, y: position.y + height * t.scale / 2 });
     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 } : {}) };
+    // 入参 fontSize 未进入这个 Geometry patch；字体大小修改应走单独 data/style 命令，而不是几何租约。
     report(engine.sessions.update(viewId, target(id), patch));
   }
   /** 创建内置节点，可加入调用方已有事务；frame同时创建以节点为入口的子canvas，保证结构一起提交。
@@ -217,6 +220,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
     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 } } }); };
+    // 返回分配的 ID 不代表创建成功：无 tx 时这里只 report 拒绝，调用方若要依赖结果须检查事务状态。
     if (tx) create(tx); else report(engine.editor.transaction(create, { label: 'Add element' }));
     return id;
   }
@@ -229,6 +233,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
     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。
+  // 资源键只反映当前投影的 nodeId/assetId，身份和 URL 可用性由 resourceView/engine 重新核验。
   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(() => {
@@ -245,6 +250,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
   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');
+  // “已同步”文案依据这些 ledger/冲突计数，不是所有资源解码、所有后台任务或远端生成全部完成的证明。
   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(() => {
@@ -286,6 +292,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
   // 单选时才启用图片适配/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;
+  // canFitImage 在显示上因任意视图的 gesture 都禁用；真正命令能否执行仍由 engine.fitImage 再判断。
   const canFitImage=!!selectedResource&&(selectedResource.image?.version===1&&selectedResource.image.status==='ready'||!!selectedResource.stored)&&!sessions.gesture;
   const aiElement = selected?.structure === 'node' && engine.editor.registry.resolve(selected) === 'known' && ['text','plain-text','script','image','plain-image'].includes(selected.componentId) ? selected : undefined;
   // Runtime-only publications must not invalidate every card's editing context.
@@ -301,6 +308,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
       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中切换；开启一个前先清同视图该类旧模式。
+      // data 命令收到的是这次传入的 textStyle 对象；本层不读取并深合并旧样式，合并语义由 editor 定义。
       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'); },
@@ -318,6 +326,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
       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局部空间。 */
+      // owner 的坐标 transform 在 begin 时捕获；token 护栏只核手势身份，归属变化是否合法由 sessions 校验。
       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') });
     },
@@ -338,12 +347,14 @@ 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]);
+  // rendererCommands 直接委托 editor；它不是额外按 viewId/渲染目标绑定的权限层，扩展 renderer 必须遵守调用契约。
   // 本组件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，不含文件字节。
+  // 复制完成回调只比较 engine/viewId，未另设卸载信号；文件暂存、复制和导出均不因关闭面板而自动回滚。
   // 文件选择调用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); } }}
@@ -369,6 +380,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
 
         onMoveEnd={(_, viewport) => engine.sessions.viewport(viewId, viewport)}
         onNodeDragStart={(event, node, nodes) => {
+          // 起始位置表借用投影 position 引用；后续 preview 必须保持不可变更新，不能原地篡改这些起点。
           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); }); });
@@ -419,9 +431,11 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
 /** 挂载期生成稳定viewId并attach，借用initialViewport只初始化一次；detach只释放视图，不关闭engine。
  * 交接视口存在时禁用加载初次fit，避免从只读预览切入后可视位置突然跳变。 */
 export default function HeadlessGraphCanvas({ engine, board, renderers=defaultCanvasRenderers,initialViewport }: { engine: ProjectEngine; board: Board; renderers?:ReactRenderers;initialViewport?:Viewport }) {
+  // 初始视口只捕获一次；同一挂载内 props.initialViewport 变化不会重新定位，切项目应由宿主正确重建/切会话。
   const [handoffViewport]=useState(initialViewport);
   const [viewId] = useState(() => crypto.randomUUID()), [attached, setAttached] = useState(false);
   // attach完成后才挂载CanvasView所需Provider；清理时detach视图，CanvasView卸载清理自身订阅。
+  // attach/viewport 在 effect 中同步执行，未捕获异常；attached 是显示门闩，不负责服务端加载或持久化就绪。
   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>;
 }

src/components/canvas/headless-imports.tsx

@@ -22,13 +22,17 @@ export function HeadlessImports({ engine, canvasId, viewId }: { engine: ProjectE
   const input = useRef<HTMLInputElement>(null), [open, setOpen] = useState(false), [error, setError] = useState("");
   // 每次渲染更新engine/canvas身份，用于异步文件探测和控制回调完成后避免更新另一画布的错误显示。
   const scope = useRef({ engine, canvasId }); scope.current = { engine, canvasId };
+  // scope 只比较 engine/canvas，不带挂载代次；同一目标卸载后的已兑现回调并非由此 ref 自动取消。
   const jobs = [...(snapshot.runtime.imports?.values() ?? [])].filter(job => job.source?.targetCanvasId === canvasId).slice(-3).reverse();
   /** 统一承接runtime控制Promise的成功/失败；这里只更新面板错误，不自行重排或重启任务。 */
   const control = (work: Promise<void>) => { void work.then(() => { if (scope.current.engine === engine && scope.current.canvasId === canvasId) setError(""); }).catch(error => { if (scope.current.engine === engine && scope.current.canvasId === canvasId) setError(errorText(error)); }); };
+  // control 接收已经开始的 Promise：同步调用抛错不在它的 catch 内；这里也不阻止多次点任务按钮。
   // canStart决定文件入口可用性；input每次先清value，允许再次选择同一个文件。
   // .json读取前64KiB探测首个非空白字符：对象走文档导入，数组走记录数组；其它后缀走NDJSON。
   // 探测前捕获canvas父关系及入口生命周期，await后重新核对，防止向已被替换/移走的目标启动任务。
+  // 64KiB 只是后缀为 .json 时的格式探测；真正解析、校验、文件持久保存和逐步加入由 runtime 负责。
   // integrityVersion=1源校验未完成显示校验中；=2允许内容继续编辑，但提示校验完成后同步。
+  // “重试源文件校验/保存”调用 engine.retry，作用于项目待重试工作，不是只重试当前展示的 job。
   // 任务按钮按runtime状态显示；失败详情最多列前10项，停止提示明确已加入内容继续同步。
   return <aside data-canvas-ui-view={viewId} className={styles.importPanel} aria-label="画布导入">
     <div className={styles.importActions}><IconButton icon={FolderInput} label="导入画布记录" disabled={!engine.imports.canStart(canvasId).enabled} onClick={() => input.current?.click()} /><span>NDJSON / JSON 记录数组</span></div>

src/components/canvas/headless-recovery-dialog.tsx

@@ -66,6 +66,7 @@ function PlanStructureReview({plan}:{plan:ConflictPlan}){
  * choices每个operationId一个决定；plan是会话生成的预览，任何选择修改都使旧plan失效。 */
 export function HeadlessRecoveryDialog({engine,close,viewId}:{engine:ProjectEngine;close():void;viewId:string}){
   const owner=useRef<RecoverySession|undefined>(undefined),[session,setSession]=useState<RecoverySession>(),[records,setRecords]=useState<readonly OperationIntent[]>([]);
+  // busy 是 React 状态护栏，不是同步锁；真正的会话互斥与持久屏障仍由 engine 校验。
   // busy防重复动作；frozen在开始应用后锁住选择，保存异常时允许原方案重试，明确拒绝才解除冻结。
   const [choices,setChoices]=useState(new Map<Id,RecoveryChoice>()),[plan,setPlan]=useState<ConflictPlan>(),[error,setError]=useState(''),[busy,setBusy]=useState(true),[frozen,setFrozen]=useState(false);
   // 微任务中准备会话，组件已清理时跳过；会话晚到则立即cancel，不再认领为当前面板。
@@ -75,13 +76,16 @@ export function HeadlessRecoveryDialog({engine,close,viewId}:{engine:ProjectEngi
     // 卸载尝试取消自己取得的会话；失败时engine仍保留持久屏障，后续retry/cancelRecovery继续收尾。
     return()=>{live=false;void owner.current?.cancel().catch(()=>{/* Engine retains the failed durable barrier; retry/cancelRecovery can finish it. */});};
   },[engine]);
+  // cancel/apply 的 await 之后不另核对 live 或 engine 代次；宿主应按 engine 生命周期挂载此面板。
   /** 已有session且正在操作时不允许取消；否则等待engine解除恢复屏障，成功才关闭，失败留窗提示。 */
   async function cancel(){if(busy&&session)return;setBusy(true);try{await engine.cancelRecovery();close();}catch(error){setError(message(error));}finally{setBusy(false);}}
   /** 有plan则resolve逐项方案，无待处理操作则apply采用最新根；拒绝结果展示原因，异常保留冻结方案供重试。 */
   async function apply(){if(!session||busy)return;setBusy(true);setError('');setFrozen(true);try{const result=plan?await session.resolve(plan):await session.apply();if(result.status==='rejected'){setFrozen(false);setError(message({code:result.code}));return;}close();}catch(error){setError(message(error));}finally{setBusy(false);}}
+  // plan 是会话生成的本地预览，不等于已发布/已持久化；只有 resolve/apply 的结果决定是否成功关闭。
   // canonical是恢复会话捕获的服务端基准，不直接读working当成服务端值。
   const canonical=session?.canonical.document;
   // Dialog关闭统一走cancel，session忙碌时抑制Escape；初次准备期间仍可请求恢复编辑。
+  // records 是准备完成时的一次操作清单；面板不逐帧订阅 ledger，恢复屏障负责保持会话前提。
   // 逐项显示服务端、本地与方案值：afterPresent=false明确表示移除字段，不等同undefined值。
   // 仅document.change/run.apply提供保留选项，生成开始/取消等动作可放弃但不能在此自动重新执行。
   // 选择齐全才允许plan，存在本地记录则必须先有plan才允许应用；方案汇总同时显示undo/redo数量变化。

src/components/canvas/headless-resource-picker.tsx

@@ -14,6 +14,7 @@ import { fault } from "@/lib/canvas-core/values";
 import { errorText } from "@/lib/api";
 
 /** 懒加载候选缩略图，失败后以通用图标代替；failed是该预览组件的局部显示状态，不修改资源记录。 */
+// failed 不随 src 变化自动重置；宿主以资源 ID 作 key 隔离不同候选的预览实例。
 function Preview({src}:{src:string}){const [failed,setFailed]=useState(false);return failed?<ImageIcon aria-hidden className="h-8 w-8 opacity-50"/>:<img src={src} alt="" loading="lazy" className="h-full w-full object-contain" onError={()=>setFailed(true)}/>;}
 /** 列表只保存资源ID和展示标题；插入时重新由engine取得资源元数据，不能信任缩略图即代表可访问。 */
 type Candidate = { id: Id; title: string };
@@ -25,6 +26,7 @@ export function HeadlessResourcePicker({engine,workspaceId,canvasId,position,clo
   /** 关闭前发取消信号；已经提交的事务不会由这个UI回调自动撤销。 */
   const dismiss=()=>{lifecycle.current?.abort();close();};
   // 初次挂载捕获目标canvas及父入口记录，异步接纳资源后仍须核对入口身份与生命周期。
+  // target 只在首次挂载捕获；canvasId/engine 更换时不能指望它自动变成新目标，宿主应重建面板。
   const [target]=useState(()=>{const document=engine.getSnapshot().document,canvas=document.canvases.get(canvasId),entry=canvas?.parent?document.elements.get(canvas.parent.entryElementId):undefined;return {canvas,entry};});
   // 记录当前账户代次与工作区，收集已打开/正在打开的其它项目；不扫描服务端全部画布。
   useEffect(()=>{
@@ -48,6 +50,7 @@ export function HeadlessResourcePicker({engine,workspaceId,canvasId,position,clo
           candidates.set(id,{id,title:typeof element.data.title==='string'&&element.data.title.trim()?element.data.title:'未命名图片'});
         }
       }
+      // 候选只在此 effect 扫描一次，不订阅其它项目后续新增/移除的资源；真正插入仍需重新授权校验。
       setItems([...candidates.values()]);setLoading(false);
     })().catch(error=>{if(!controller.signal.aborted){setLoading(false);setError(errorText(error));}});
     return()=>{controller.abort();if(lifecycle.current===controller)lifecycle.current=null;};
@@ -69,6 +72,7 @@ export function HeadlessResourcePicker({engine,workspaceId,canvasId,position,clo
       },{signal});
       // engine拒绝与异常统一进入错误展示；仅在面板仍活跃时通知onAdded并关闭。
       if(result.status==='rejected')throw fault(result.code,result.targets);
+      // 这两个宿主回调仍在 try 内；它们抛错会显示失败，但已经提交的创建事务不会回滚。
       if(!signal.aborted){onAdded(id);close();}
     }catch(error){if(!signal.aborted)setError(error instanceof Error&&error.message==='not_found'?'无法读取这张图片，请确认仍有原画布的访问权限。':errorText(error));}
     finally{requesting.current=false;if(!signal.aborted)setBusy(undefined);}

src/components/canvas/icon-catalog.ts

@@ -17,6 +17,7 @@ export type IconSource = "all" | "lucide" | "tabler";
  * 筛选同时满足来源和分类；common看common标记，other指没有分类，all跳过对应限制。
  * 保留目录原顺序，不计算相关性分数，也不限制结果数量；虚拟列表由调用方实现。 */
 export function searchIcons(query: string, category = "all", source: IconSource = "all") {
+  // 每次扫描全部目录并归一化检索串，无预建倒排索引；返回新数组但条目仍共享静态记录引用。
   const needle = query.trim().toLowerCase().replace(/[-_\s]/g, "");
   return iconCatalog.filter((icon) => (source === "all" || icon.source === source)
     && (category === "all" || (category === "common" ? icon.common : category === "other" ? !icon.categories.length : icon.categories.includes(category)))

src/components/canvas/icon-picker.tsx

@@ -40,6 +40,7 @@ export function IconPicker({ close, choose }: { close: () => void; choose: (name
   const rows = Math.ceil(matches.length / columns);
   const firstRow = Math.max(0, Math.floor(scrollTop / rowHeight) - 1);
   const lastRow = Math.min(rows, Math.ceil((scrollTop + height) / rowHeight) + 1);
+  // 虚拟化只限制挂载按钮，matches 仍保留完整同步筛选结果；不是分批解析/下载目录。
   const visible = matches.slice(firstRow * columns, lastRow * columns);
   /** 先钳制目标索引，再按行把目标滚入视口；等下一帧虚拟按钮挂载后调用focus。
    * 空结果没有可聚焦按钮，最终可选链自然不执行focus；不凭空创建占位项目。 */
@@ -52,8 +53,10 @@ export function IconPicker({ close, choose }: { close: () => void; choose: (name
       else if (top + rowHeight > grid.current.scrollTop + height) grid.current.scrollTop = top + rowHeight - height;
       setScrollTop(grid.current.scrollTop);
     }
+    // 帧未单独取消且不带筛选代次；执行时读最新 grid，筛选变化可能让同一 index 指向另一条结果。
     requestAnimationFrame(() => grid.current?.querySelector<HTMLButtonElement>(`[data-index="${next}"]`)?.focus());
   }
+  // Portal 直接使用 document.body，仅供客户端挂载；dialog 角色不自动提供焦点陷阱或背景 inert。
   // 分类点击同时清空搜索，来源选择保留查询；网格按钮按全局结果索引绝对定位，不按切片局部索引。
   // 左右移动一项、上下移动一行，Home/End跳至结果首尾；只有当前focused项进入Tab顺序。
   // 每个按钮由CanvasIcon加载路径，页脚结果数来自筛选数组；choose后是否关闭由调用方决定。

src/components/canvas/legacy-canvas-migration.tsx

@@ -37,6 +37,7 @@ export function LegacyCanvasMigration(props:Props){
     /** 读取并校验本作用域持久迁移记录；格式/解释版本错误也要走保留记录和暂停路径。 */
     const read=()=>readCanvasMigration(localStorage,scope);
     /** 迁移尝试进行中不抢租约；已有pending或finished就保持hold，正常情形取得共享锁后开放旧编辑。 */
+    // inspect 没有独立的在途 Promise 合并；storage/刷新可重复调用，跨页互斥由 Web Locks 与持久记录保证。
     async function inspect(){
       if(attempt.current||!current())return;
       setChecking(true);
@@ -67,6 +68,7 @@ export function LegacyCanvasMigration(props:Props){
     refresh.current=inspect;void inspect();
     /** 其它页改变同一记录时重新检查；本页迁移中忽略事件，由当前尝试负责收尾。
      * 待确认记录消失只说明外部变化，本页不能丢掉内存内容，先冻结并提示导出/重新打开。 */
+    // storage 事件来自其它文档，本页 setItem 不靠此事件更新 UI；也未按 storageArea 区分其它 Storage 来源。
     const storage=(event:StorageEvent)=>{
       if(event.key!==key&&event.key!==null||!current()||attempt.current)return;
       // Never discard another view's in-memory content because a record vanished.
@@ -78,6 +80,7 @@ export function LegacyCanvasMigration(props:Props){
     };
     window.addEventListener('storage',storage);
     // 卸载取消检查、拆storage监听并释放本页共享锁，不删除尚待确认的迁移记录。
+    // release 在此是尽力异步清理，不等待也不安装 catch；它的拒绝不进入面板 error 状态。
     return()=>{controller.abort();window.removeEventListener('storage',storage);const held=lease.current;lease.current=undefined;void held?.release();};
   // The port ref follows renders without re-acquiring a shared editing lease.
   // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -85,6 +88,7 @@ export function LegacyCanvasMigration(props:Props){
   /** 新尝试先check并hold，在共享锁仍持有时prepare；释放共享锁后由迁移器申请独占锁。
    * pending复用原记录resume，其它情况按rootId重新准备，不能把每次点击都变成新的迁移请求。 */
   async function upgrade(){
+    // attempt 是同步 ref，先于首次 await 设置，区别于仅用于渲染的 running 状态。
     const controller=life.current;if(!controller||controller.signal.aborted||attempt.current)return;
     attempt.current=true;setRunning(true);setError('');
     const current=()=>!controller.signal.aborted&&port.current.context.isCurrentIdentity();

src/components/canvas/loading-graph-canvas.tsx

@@ -20,11 +20,13 @@ function PreparingNode({data}:NodeProps){return <div style={{width:'100%',height
 /** 所有预览命令统一拒绝为model_loading，避免复用的renderer意外修改数据。 */
 const reject=()=>({status:'rejected' as const,code:'model_loading',targets:[]});
 /** 冻结命令接口仅提供拒绝结果；inert与ReactFlow只读设置之外，命令层再提供一道限制。 */
+// transaction 也直接返回拒绝，不执行传入事务函数；这不限制自定义 renderer 自行发起的外部副作用。
 const commands:CanvasRendererCommands=Object.freeze({dispatch:reject,transaction:reject});
 /** 首次存在节点且视口初始化后fitView一次，限制最大缩放为1，并把结果交给外层用于视图交接。 */
 function InitialPreviewViewport({onViewport,nodeCount}:{onViewport(viewport:Viewport):void;nodeCount:number}){
  // fitted是本组件挂载期标记；清理只禁止迟到通知，不取消已经发起的fitView，也不重置fitted。
  const flow=useReactFlow(),fitted=useRef(false),notify=useRef(onViewport);notify.current=onViewport;
+ // fitted 在调用 fitView 前置 true；期间依赖变化会取消迟到通知，但不会重新 fit。拒绝也没有本地 catch/重试。
  useEffect(()=>{if(!flow.viewportInitialized||fitted.current||!nodeCount)return;fitted.current=true;let active=true;void flow.fitView({padding:.2,maxZoom:1}).then(()=>{if(active)notify.current(flow.getViewport());});return()=>{active=false;};},[flow,nodeCount]);
  return null;
 }
@@ -38,12 +40,14 @@ export default function LoadingGraphCanvas({preview,canvasId,registry,renderers,
  // 对已收到文档做只读投影；从现有边补齐各节点Handle描述，不推断尚未读取到的连线。
  const projection=useMemo(()=>{
   const value=projectCanvas(preview.document,canvasId,registry,new Set(),()=>undefined,undefined,catalog);
+  // 每条边端点都追加描述，不按 handleId 去重；PreparingNode 使用临时索引 key，仅供预览定位。
   const handles=new Map<string,{id?:string;type:'source'|'target'}[]>();for(const edge of value.edges)for(const type of ['source','target'] as const){const id=edge[type],rows=handles.get(id)??[];rows.push({type,id:edge[type==='source'?'sourceHandle':'targetHandle']??undefined});handles.set(id,rows);}
   // 节点禁用拖动/选择/焦点/连接及指针，边禁用选择/焦点；已知组件声明assetId资源字段才设置预览URL。
   return{nodes:value.nodes.map(node=>({...node,draggable:false,selectable:false,focusable:false,connectable:false,style:{...node.style,pointerEvents:'none' as const},data:{...node.data,__previewHandles:handles.get(node.id)??[],...(registry.resolve(preview.document.elements.get(node.id)!)==='known'&&typeof node.data.assetId==='string'&&registry.components.get(preview.document.elements.get(node.id)!.componentId)?.resourceFields?.includes('assetId')?{src:`/api/foundry/workspaces/${encodeURIComponent(workspaceId)}/assets/${encodeURIComponent(node.data.assetId)}?variant=preview`}:{})}})),edges:value.edges.map(edge=>({...edge,selectable:false,focusable:false}))};
  },[preview.document,canvasId,workspaceId,registry,catalog]);
  // 普通rendererId优先使用专用preview，否则节点PreparingNode、边UnsupportedEdge；节点再套inert隔离内部控件。
  const nodeTypes=useMemo<NodeTypes>(()=>{const result:NodeTypes={};for(const [id,Renderer]of Object.entries({...Object.fromEntries(Object.keys(renderers.nodeTypes).map(id=>[id,renderers.previewNodeTypes[id]??PreparingNode])),unsupported:UnsupportedNode}))result[id]=props=><div inert style={{width:'100%',height:'100%'}}><Renderer {...props}/></div>;return result;},[renderers]),edgeTypes=useMemo(()=>({...Object.fromEntries(Object.keys(renderers.edgeTypes).map(id=>[id,renderers.previewEdgeTypes[id]??UnsupportedEdge])),unsupported:UnsupportedEdge}),[renderers]);
+ // onMoveEnd 同时记录用户移动；首次 fit 完成通知与用户移动并无额外竞争仲裁，由外层决定交接采用。
  // 仍允许拖动或滚动平移，关闭滚轮缩放和Delete删除；onMoveEnd记录视口，进度只显示读取数量。
  return <div className={styles.editor} data-canvas-loading-preview aria-label="正在加载的画布，只读预览">
   <CanvasRendererCommandsContext.Provider value={commands}>

src/components/canvas/material-node.tsx

@@ -31,12 +31,14 @@ export function MaterialNode(props: NodeProps<CanvasNode>) {
   const editing = useScopedNodeEditing(id,data.__headlessTarget);
   const { zoom } = useViewport();
   // 以卡片宽度（默认260）×视口缩放×设备像素比估算显示成本；1024以内优先预览源。
+  // 像素比在 render 时读取，不单独监听其变化；zoom 订阅或其它重渲染才重新计算此启发式。
   const preview = (props.width || 260) * zoom * (typeof window === "undefined" ? 1 : window.devicePixelRatio || 1) <= 1024;
   // 仅记录连接点按下的屏幕坐标，用小于5px的位移区分点击与拖动；不把它写进文档或history。
   const pointerStart = useRef({ x: 0, y: 0 });
   const Icon = data.kind === "image" ? ImageIcon : data.kind === "script" ? FileText : Type;
   // 旧target/source Handle禁用新连接但保留定位；四向Handle使用方向作ID，选中时允许开始连线。
   // 指针点击还检查branchable能力和位移；键盘Enter/空格使用Handle中心打开菜单，由动作层再处理合法性。
+  // pointerStart 不按 pointerId 分组，属于点击位移辅助；键盘入口也不在这里检查 branchable，由动作实现兜底。
   // 点击/按键停止冒泡，避免分支操作同时触发节点或画布交互；文本内容的编辑生命周期由子组件负责。
   return (
     <TransformableNode {...props} className={`${styles.node} ${selected ? styles.selectedNode : ""}`}>

src/components/canvas/node-editing.ts

@@ -41,12 +41,14 @@ export const NodeEditing = createContext<Omit<typeof defaultEditing, GestureHook
 export function useScopedNodeEditing(id:string,rendered?:RenderedTarget){
  // 只有rendered.id匹配当前节点才采用incarnation；有新版scope却缺少合法rendered身份时拒绝编辑。
  const editing=useContext(NodeEditing),scope=useContext(CanvasOverlays),incarnation=rendered?.id===id?rendered.incarnation:undefined,owner=rendered?.ownerCanvasId,canvas=rendered?.canvasId;
+ // current 在动作触发时读取快照，不建立订阅；后续状态变化不会仅因这个检查而触发组件重渲染。
  // 无新版scope直接返回旧接口；否则只在接口、视图作用域或目标身份变化时重建包装。
  return useMemo(()=>{if(!scope)return editing;
   // 动作当刻检查engine未关闭、视图仍存在且仍在原canvas、元素生命周期与owner未变。
   // candidate必须是本节点（或允许的空参数），阻止一个节点的包装替其它目标发起操作。
   const current=(candidate:string|null|undefined=id)=>{const durability=scope.engine.getDurability(),view=scope.engine.sessions.getSnapshot().views.get(scope.index.viewId),record=scope.engine.getSnapshot().document.elements.get(id);return !durability.closing&&!durability.closed&&!!view&&view.canvasId===canvas&&incarnation!==undefined&&record?.incarnation===incarnation&&record.ownerCanvasId===owner&&(candidate===undefined||candidate===null||candidate===id);};
   // finish/cancel没有id参数，额外确认当前手势属于本视图，且目标列表含本id/incarnation。
+  // 这里不捕获 gesture token；同视图同目标的新手势也能通过，精确手势身份须由创建者的租约保护。
   const ownGesture=()=>scope.engine.sessions.getSnapshot().gesture?.viewId===scope.index.viewId&&scope.engine.sessions.getSnapshot().gesture?.targets.some(target=>target.id===id&&target.incarnation===incarnation);
   // 拷贝展示信息，仅替换动作入口；文本/样式/几何等动作逐次检查，不缓存“曾经有效”的结论。
   const scoped:typeof editing={...editing,
@@ -61,7 +63,7 @@ export function useScopedNodeEditing(id:string,rendered?:RenderedTarget){
   // begin取得的租约由创建者管理；这里不把旧事件转给当前另一个手势。
   if(editing.beginTransform)scoped.beginTransform=candidate=>current(candidate)?editing.beginTransform!(candidate):false;
   if(editing.endEditing)scoped.endEditing=candidate=>{if(current(candidate))editing.endEditing!(candidate);};
-  // 结束手势要同时通过对象有效性与手势归属检查，防止迟到的pointerup结束新交互。
+  // 结束手势要同时通过对象有效性与归属检查；这不是对任意迟到事件的完整 token 隔离。
   if(editing.finishTransform)scoped.finishTransform=()=>{if(current()&&ownGesture())editing.finishTransform!();};
   if(editing.cancelTransform)scoped.cancelTransform=()=>{if(current()&&ownGesture())editing.cancelTransform!();};
   // 包装只负责入口检查；事务合法性、持久化和失败报告仍由Provider对应的动作实现负责。

src/components/canvas/node-internals.ts

@@ -19,9 +19,11 @@ export function useNodeInternalsUpdate(id:string){
  // 首个节点创建store级batch，每次挂载取得本id的owner；清理仅释放该owner。
  useEffect(()=>{
   let batch=batches.get(scope);if(!batch){batch=createNodeInternalsBatch(update);batches.set(scope,batch);}
+  // batch 首次创建时捕获 update；同 store 后续使用者沿用该更新器，不在每次 effect 中替换。
   const owner=batch.acquire(id);lease.current=owner;
   return()=>{owner.dispose();if(lease.current===owner)lease.current=undefined;};
  },[scope,update,id]);
- // 回调通过ref读取当前租约，避免调用方保存旧闭包后继续刷新已卸载节点。
+ // 回调通过ref读取当前租约；旧调用者保存的同一回调，在本组件 id 改变后会转向新 id 的租约。
+ // effect 尚未安装/已清理则无动作；它不把回调永久绑定到最初 id。
  return useCallback(()=>lease.current?.invalidate(),[]);
 }

src/components/canvas/node-style-toolbar.tsx

@@ -24,7 +24,9 @@ export function NodeStyleToolbar({ id, data, selected }: NodeProps<CanvasNode>)
   // 只有text/script/plain-text展示文字排版；图片不展示前景/背景色，图标可调颜色但不展示拉伸开关。
   const text = data.kind === "text" || data.kind === "script" || data.kind === "plain-text";
   /** 统一样式动作入口；字号作为独立可选参数，避免把它混进textStyle的字段空间。 */
+  // 每次控件变化立即派发；没有在本组件合并拖动取色等多次输入为一个 undo 项，也没有等待服务端确认。
   const patch = (value: TextStyle, fontSize?: number) => editing.style(id, value, fontSize);
+  // 显示默认值不写回 data；命令校验仍由 editing 实现，select 的类型断言不是运行时 schema 验证。
   // 颜色输入用现有值或默认色；字号仅提交8—160范围，透明背景在取色器中显示白色但不自动写回模型。
   // 加粗/斜体/下划线按当前值取反，对齐和行高直接提交所选值；清除背景明确写transparent。
   // 常规事件停止冒泡；Escape只在非组合输入、非文本编辑且未被处理时关闭当前节点的变换模式。

src/components/canvas/node-title.tsx

@@ -17,11 +17,13 @@ export function NodeTitle({ id, title, selected,renderedTarget }: { id: string;
   useEffect(() => { if (!selected) setEditing(false); }, [selected]);
   useEffect(() => { if (editing) { input.current?.focus(); input.current?.select(); } }, [editing]);
   /** blur是统一提交入口：忽略取消、空名称与无变化名称，随后复位取消标记并退出输入态。 */
+  // rename 是同步动作入口，不等待远端 ACK；若实现抛错，下方标记复位与退出也不会自动执行。
   function save() {
     if (!cancelled.current) { const name = value.trim(); if (name && name !== title) actions.rename(id, name); }
     cancelled.current = false; setEditing(false);
   }
   // Enter在非输入法组合态触发blur保存，Escape先置取消标记再blur；按键不继续冒泡到画布。
+  // maxLength 是浏览器 UTF-16 长度限制；此 save 只 trim/去空/比旧值，不另做 UTF-8 字节校验。
   // 标题长度限制300字符，nodrag/nopan/nowheel避免文本操作被当成画布手势。
   if (editing) return <input ref={input} className={`${styles.nodeTitleInput} nodrag nopan nowheel`} value={value} maxLength={300} aria-label="节点名称" onChange={(event) => setValue(event.target.value)} onBlur={save}
     onKeyDown={(event) => { event.stopPropagation(); if (event.key === "Enter" && !event.nativeEvent.isComposing) event.currentTarget.blur(); if (event.key === "Escape") { cancelled.current = true; event.currentTarget.blur(); } }} />;

src/components/canvas/plain-image-node.tsx

@@ -14,6 +14,7 @@ export function PlainImageNode(props: NodeProps<CanvasNode>) {
   // 节点宽度未提供时按320估算，再乘zoom与设备像素比；不超过1024时请求预览源。
   // 这是显示宽度启发式，不检查图片原始尺寸；无window时像素比按1处理。
   const preview = (props.width || 320) * zoom * (typeof window === "undefined" ? 1 : window.devicePixelRatio || 1) <= 1024;
+  // 该估算只影响托管 URL 的 variant；不是独立下载任务，不会为普通外部图片生成预览资源。
   // managedImageSource按资源格式选择可用地址，移动/缩放等编辑行为仍由TransformableNode处理。
   return <TransformableNode {...props} className={styles.plainImageFrame}><CanvasImage id={props.id} className={styles.plainImage} src={managedImageSource(props.data.src, preview)} title={props.data.title} /></TransformableNode>;
 }

src/components/canvas/retained-projection.ts

@@ -8,9 +8,11 @@
 export function createRetainedProjection(){
   // 弱引用键避免缓存永久占住已被替换的投影对象；只按对象身份缓存，不监测对象内部原地修改。
   const tagged=new WeakMap<object,object>();
+  // previous 强引用最近一批输入/输出；WeakMap 不等于整个实例完全不持有投影，空 ids 才清这份整批引用。
   let previous:{nodes:readonly object[];edges:readonly object[];ids:Set<string>;result:{nodes:object[];edges:object[]}}|undefined;
   /** 输入数组和保留ID集合生成节点/边数组；ids为空时直接返回原数组并清除整批缓存。 */
   return <N extends {id:string},E extends {id:string}>(nodes:N[],edges:E[],ids:ReadonlySet<string>):{nodes:N[];edges:E[]}=>{
+    // 清 previous 不清 tagged；同一对象日后再次被保留，仍可能复用已有带标记副本。
     if(!ids.size){previous=undefined;return{nodes,edges};}
     // 数组引用及ID成员都相同才复用；快照复制ids，避免调用方之后原地修改Set影响比较基准。
     if(previous?.nodes===nodes&&previous.edges===edges&&previous.ids.size===ids.size&&[...ids].every(id=>previous!.ids.has(id)))return previous.result as {nodes:N[];edges:E[]};

src/components/canvas/text-appearance.ts

@@ -7,6 +7,7 @@ import type { CanvasNodeData } from "@/lib/canvas-elements";
  * 字体家族只识别serif/mono，其它继承外层；颜色、背景、对齐与行高使用各自默认值。
  * 使用||回退，因此0和空字符串也走默认；这里是显示映射，不承担schema校验。 */
 export function textAppearance(data: CanvasNodeData): CSSProperties {
+  // 每次生成新的扁平 CSS 对象；不缓存节点引用，也不会写回默认值到 data。
   const style = data.textStyle || {};
   return { fontSize: data.fontSize || (data.kind === "plain-text" ? 24 : 13), color: style.color || "#37352f", fontWeight: style.bold ? 700 : 400, fontStyle: style.italic ? "italic" : "normal", textDecoration: style.underline ? "underline" : "none", textAlign: style.align || "left", lineHeight: style.lineHeight || 1.5,
     fontFamily: style.fontFamily === "serif" ? 'Georgia, "Songti SC", serif' : style.fontFamily === "mono" ? 'ui-monospace, "SFMono-Regular", monospace' : "inherit", backgroundColor: style.background || "transparent" };

src/components/canvas/transformable-node.tsx

@@ -76,6 +76,7 @@ export function TransformableNode(props: NodeProps<CanvasNode> & { children: Rea
     const lease = editing.beginTransform?.(id); if (lease === false) return;
     if (!editing.beginTransform) editing.begin(id);
     if (!node.selected) editing.select(id);
+    // node 是 flow.getNode 返回的引用，不深克隆；“起点快照”依赖外层不可变更新约定，不能原地修改该节点。
     gesture.current = { lease: lease && typeof lease === 'object' ? lease : undefined, node, direction, capture: event.currentTarget, pointerId: event.pointerId, start: flow.screenToFlowPosition({ x: event.clientX, y: event.clientY }) };
     if(!acquirePointerCapture(event.currentTarget,event.pointerId)){cancelGesture();return;}
     event.preventDefault();event.stopPropagation();
@@ -87,6 +88,7 @@ export function TransformableNode(props: NodeProps<CanvasNode> & { children: Rea
     if (!ownsPointerCapture(gesture.current,event)) return;
     const current = flow.screenToFlowPosition({ x: event.clientX, y: event.clientY });
     const { node, start, direction } = gesture.current!;
+    // resizing 模式显式传 Shift 布尔值，未按 Shift 即解锁比例；普通角落传 undefined 沿用图片/图标默认比例规则。
     const change = direction === "rotate"
       ? { rotation: rotationFromPointer(node, start, current, event.shiftKey) }
       : resizeFromPointer(node, direction, { x: current.x - start.x, y: current.y - start.y }, resizing ? event.shiftKey : undefined);
@@ -100,6 +102,7 @@ export function TransformableNode(props: NodeProps<CanvasNode> & { children: Rea
     if(event&&!ownsPointerCapture(gesture.current,event))return;
     const current = gesture.current; if (!current) return;
     gesture.current = null;
+    // cancel/commit 调用与释放间没有 finally；Provider/lease 抛错时可能跳过 release，需要遵守动作异常契约。
     if (current.lease) current.lease.cancel(); else if (editing.cancelTransform) editing.cancelTransform(); else editing.transform(current.node.id, current.direction === "rotate" ? { rotation: current.node.data.rotation || 0 } : { position: current.node.position, width: current.node.width, height: current.node.height });
     releasePointerCapture(current.capture,current.pointerId);
   }
@@ -107,9 +110,11 @@ export function TransformableNode(props: NodeProps<CanvasNode> & { children: Rea
   function finish(event: PointerEvent<HTMLElement>) {
     if(!gesture.current)return;event.stopPropagation();
     if (!ownsPointerCapture(gesture.current,event)) return; const current = gesture.current!; move(event); gesture.current = null;
+    // 当前手势引用已清空；若 commit 抛错，不会自动恢复引用或执行后面的 capture 释放。
     if (current.lease) current.lease.commit(); else editing.finishTransform?.();
     releasePointerCapture(current.capture,current.pointerId);
   }
+  // 模式关闭/取消选中本身不调用 cancelGesture；实际手势结束还依赖 pointerup/cancel、失焦或卸载。
   // 容器的CSS zoom使用viewScale，宽高同时除以viewScale，保持投影尺寸与内部显示坐标对应。
   // schema=2给纯文本/纯图片补四向连接点，非分区显示成员徽标；普通尺寸调整用右下角，模式内显示八向手柄。
   // 八向手柄的尺寸与边框反向抵消zoom和viewScale，使屏幕上大小稳定；方向决定位置及cursor。
@@ -139,6 +144,7 @@ export function TransformableNode(props: NodeProps<CanvasNode> & { children: Rea
             const delta = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] }[event.key]; if (!delta) return;
             event.preventDefault(); event.stopPropagation(); const node = flow.getNode(id); if (!node) return;
             const lease = editing.beginTransform?.(id); if (lease === false) return; if (!editing.beginTransform) editing.begin(id); const scale = (data.viewScale || 1) * (event.ctrlKey || event.metaKey ? 10 : 1);
+            // 键盘按键没有 pointer capture，也不经过 move；preview/commit 同步连用，失败清理由租约实现承担。
             const change = resizeFromPointer(node, direction, { x: delta[0] * scale, y: delta[1] * scale }, event.shiftKey);
             if (lease && typeof lease === 'object') { lease.preview(change); lease.commit(); } else { editing.transform(id, change); editing.finishTransform?.(); }
           }} />;

src/components/canvas/unsupported-elements.tsx

@@ -17,6 +17,7 @@ const positions={top:Position.Top,right:Position.Right,bottom:Position.Bottom,le
  * 仍绘制已知连接点供现有连线定位，但禁止从这些Handle发起或接收新连接；不推断未知内容字段。 */
 export function UnsupportedNode({data,selected}:NodeProps<ProjectionNode>){
   // fallback来自bindings投影；缺失时仍显示通用提示，不尝试从data猜测组件结构。
+  // 只读取公共投影信封；此组件本身没有 TransformableNode，也不安装任何编辑动作处理器。
   const fallback=data.__headlessFallback;
   return <div className={`${styles.node} ${selected?styles.selectedNode:""}`} style={{width:"100%",height:"100%",padding:14,transform:`rotate(${data.rotation||0}deg)`}} role="note" aria-label="暂不支持编辑的元素">
     <span>{data.title}</span><small style={{display:"block"}}>此元素需要兼容的组件版本才能编辑</small>
@@ -27,6 +28,7 @@ export function UnsupportedNode({data,selected}:NodeProps<ProjectionNode>){
 /** 直接使用ReactFlow推导的端点生成贝塞尔路径，附可访问标题；不调用未知类型的编辑/样式逻辑。
  * BaseEdge绘制统一颜色的可见线条，数据保留与版本兼容仍归模型层负责。 */
 export function UnsupportedEdge(props:EdgeProps<CanvasEdgeModel>){
+  // 采用端点派生的通用曲线，不重放未知模型的自定义 path/marker；保留数据与视觉完全还原是两件事。
   const [path]=getBezierPath(props);
   return <g role="img" aria-label="暂不支持编辑的连线"><title>原始连线内容已保留</title><BaseEdge id={props.id} path={path} style={{stroke:'#aa968b',strokeWidth:1.5}} /></g>;
 }

src/components/canvas/use-canvas-ai.ts

@@ -30,6 +30,7 @@ export function useCanvasAI(workspace: string, root: string, live: boolean, tree
   const reference = useRef(tree); reference.current = tree;
   const wake = useRef<() => void>(() => {});
   // cache是跟踪结果缓存，runs是发布给React的副本；每个run有自己的活动边集合，合并后供连线动画使用。
+  // 这些 ref/state 不因 workspace/root/live 改变而清空；宿主应按作用域重建 Hook 所在视图，避免沿用旧跟踪表。
   const cache = useRef(new Map<string, AIRun>());
   const edgeStates = useRef(new Map<string, Set<string>>());
   // 每个board只保留最高待刷版本，避免同一批step.applied触发多次重复整画布读取。
@@ -45,6 +46,7 @@ export function useCanvasAI(workspace: string, root: string, live: boolean, tree
     /** 所有发现/分页GET共享取消信号并协商旧v2响应格式。 */
     const request = <T,>(path: string) => api<T>(path, { signal: controller.signal, headers: { Accept: CANVAS_ACCEPT } });
     /** 分页发现根和后代活动run，每页50；已跟踪run不覆盖，重复cursor判为协议异常避免无限循环。 */
+    // alive 只控制继续分页/发布等交接点；await 返回后仍可能先写共享 ref，不是每次赋值都有代次护栏。
     async function discover() {
       let cursor = ""; const seen = new Set<string>();
       do {
@@ -77,6 +79,7 @@ export function useCanvasAI(workspace: string, root: string, live: boolean, tree
             }
             if (!active(page.status)) edges.clear(); edgeStates.current.set(id, edges);
             current = { ...page, board_id: previous.board_id, events: [...(current.events || []), ...(page.events || [])].slice(-1000) };
+            // dirty 只比较该 run 原游标和状态；同游标/同状态下其它响应字段变化不一定立即发布给 React。
             if (current.next_seq !== previous.next_seq || current.status !== previous.status) dirty = true;
             cache.current.set(id, current);
           } while (current.has_more && alive);
@@ -115,11 +118,13 @@ export function useCanvasAI(workspace: string, root: string, live: boolean, tree
     const id = result.run_id as string; cache.current.set(id, { run_id: id, board_id: boardId, status: "queued", next_seq: 0, steps: [{ step_id: "pending", board_id: boardId, node_id: node, status: "queued" }] }); changed(); wake.current();
   }
   /** 以新幂等键发送取消命令后继续查询终态；暂记queued用于保持轮询，不表示服务端重新执行任务。 */
+  // 此写请求没有轮询 effect 的 signal，也未检查 live；按键是否可用由调用方和服务端权限共同约束。
   async function cancel(run: AIRun) {
     await api(canvasPath(workspace, run.board_id) + `/ai/runs/${run.run_id}/cancel`, { method: "POST", headers: { Accept: CANVAS_ACCEPT, "Idempotency-Key": crypto.randomUUID() }, body: "{}" });
     const next = cache.current.get(run.run_id); if (next) { next.status = "queued"; } wake.current(); // Poll canonical terminal state, including already applied steps.
   }
   /** 先prepareApply协调目标本地状态，再发显式采用命令；成功后移除冲突提示并继续跟踪服务端最终状态。 */
+  // run/apply 同样不由 effect 清理自动取消；卸载只停跟踪，不撤销已经发起的命令副作用。
   async function apply(run: AIRun, node: string, output: string, targetBoard: string) {
     await reference.current.prepareApply(targetBoard, node);
     await reference.current.command(run.board_id, `ai/runs/${run.run_id}/apply`, { node_id: node, output_id: output }, undefined, false, targetBoard);

src/components/canvas/use-canvas-persistence.ts

@@ -21,10 +21,12 @@ export function useCanvasPersistence(document: CanvasDocument, workspace: string
     if (alive.current) { setSync(next); backup(); }
   }) : null);
   /** 保存规范化document、writer当前版本及内容指纹dirty；回调路径吞掉存储异常，定时effect路径会展示错误。 */
+  // writer 通知捕获创建时的 backup/key；latest 与 pausedRef 保持当前值，key/workspace/board 改变须重建 Hook 所在视图。
   function backup() {
     if (pausedRef.current) return;
     try {
       const current = latest.current;
+      // dirty 使用包含 viewport 的指纹，而 writer.needsSave 忽略 viewport；两者用途不同，不可互换解释。
       localStorage.setItem(key + ":recovery", JSON.stringify({ document: decodeCanvas(JSON.stringify(current)), baseVersion: writer?.version || 1, dirty: writer ? canvasFingerprint(current) !== writer.saved : false }));
     } catch { /* Storage failure is surfaced by the effect below. */ }
   }
@@ -35,6 +37,7 @@ export function useCanvasPersistence(document: CanvasDocument, workspace: string
       try { localStorage.setItem(key + ":recovery", JSON.stringify({ document: decodeCanvas(JSON.stringify(latest.current)), baseVersion: writer?.version || 1, dirty: writer ? canvasFingerprint(latest.current) !== writer.saved : false })); }
       catch { setSync({ status: "error", version: writer?.version || 1, error: "local_backup_failed" }); }
     }, 250);
+    // 此处只入队，不 await/捕获 running 的拒绝；CanvasSync 的通知与回调需遵守它自身的异常约定。
     const remote = writer ? setTimeout(() => void writer.enqueue(latest.current), 800) : null;
     return () => { clearTimeout(local); if (remote) clearTimeout(remote); };
   }, [document, writer, key, paused]);
@@ -48,6 +51,7 @@ export function useCanvasPersistence(document: CanvasDocument, workspace: string
     // Writer and key are stable for this board's mounted editor.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [writer, key]);
+  // 同步 localStorage 写入只保证调用返回时 API 未抛错；没有回读、版本日志或刷盘确认。
   // retry先补本地备份再委托writer重试；没有远端writer时返回undefined，不伪造同步成功。
   return { ...sync, retry: () => { backup(); return writer?.retry(); } };
 }

src/components/canvas/use-canvas-tree.ts

@@ -41,7 +41,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
   /** 同时更新同步门闩与界面状态；只更新state会留下同一事件轮次中的旧写入窗口。 */
   function setMigrationHeld(value:boolean){migrationGate.current=value;setMigrationState(value);}
   /** 旧接口请求护栏：await前后检查账号，写请求受迁移门闩限制；迁移排空时只放行canvas PATCH。
-   * X-Expected-Account要求代理校验目标账号，避免切号后旧请求误用新会话。 */
+   * X-Expected-Account经代理转发，由上游核对目标账号；本地前后检查不能证明已经发出的写入未生效。 */
   const api:CanvasRequest=async <T,>(path:string,options?:RequestInit)=>{
     if(migration&&!migration.isCurrentIdentity())throw new Error('identity_changed');
     if(migrationBlocked()&&options?.method&&options.method!=='GET'&&!(migrationFlush.current&&options.method==='PATCH'&&path.endsWith('/canvas')))throw new Error('canvas_busy');
@@ -88,6 +88,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
   function resolveRecovery(boardId: string, restore: boolean) {
     if(migrationBlocked())return;
     const draft = pendingRecovery.current.get(boardId);
+    // update 没有成功返回值；若其它准入条件拒绝恢复，下面仍会移除候选/记录，宿主须先保证可恢复。
     if (restore && draft) update(boardId, { type: "replace", document: draft });
     const next = new Map(pendingRecovery.current); next.delete(boardId); pendingRecovery.current = next; setRecoveries(next);
     localStorage.removeItem(`endoleap_canvas_v1:${workspace}:${boardId}:recovery`);
@@ -107,6 +108,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
     if (writer) writer.adopt(value);
     else if (snapshot) writers.current.set(boardId, new CanvasSync(api, canvasPath(workspace, boardId), value, (state) => {
       if (!mounted.current) return;
+      // 显示的是最近通知的 writer 状态，不是遍历全部 writer 后算出的项目汇总；错误只在显式路径清除。
       setStatus(state.status); if (state.error) setError(state.error);
     }));
   }
@@ -195,6 +197,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
   /** 按需加载真实快照或演示本地草稿，装writer并检查恢复候选；recursive递归加载子图，祖先集合防环且限制深度。 */
   async function ensure(boardId: string, recursive = false, ancestors = new Set<string>()): Promise<void> {
     if (ancestors.has(boardId) || ancestors.size > 8) throw new Error("subgraph_cycle");
+    // ensure 自身不复用 loading/在途 Promise；并行调用同一缺失 board 可能重复读取。loading 只服务下方可见子图 effect。
     let document = current.current.get(boardId);
     if (!document) {
       const value = snapshot ? await read(boardId) : (() => { const raw = localStorage.getItem(`endoleap_canvas_v1:${workspace}:${boardId}:recovery`); return { version: 1, document: raw ? decodeCanvas(JSON.stringify(JSON.parse(raw).document)) : { schema_version: 2 as const, nodes: [], edges: [], viewport: { x: 0, y: 0, zoom: 1 } } }; })();
@@ -253,6 +256,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
       if(migrationBlocked())return;
       for (const [boardId, document] of current.current) try {
         if (pendingRecovery.current.has(boardId)) continue;
+        // canvasPayload 会过滤未上传占位及其边；此草稿记录不能保存原文件或保证刷新后恢复上传。
         const writer = writers.current.get(boardId);
         localStorage.setItem(`endoleap_canvas_v1:${workspace}:${boardId}:recovery`, JSON.stringify({ document: canvasPayload(document), baseVersion: writer?.version || 1, dirty: writer ? writer.needsSave(document) : false }));
       } catch { setError("local_backup_failed"); }
@@ -334,6 +338,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
   function accept(result: CanvasCommandResult) {
     const next = new Map(current.current);
     const values = [...new Map([...(result.parent ? [result.parent] : []), ...(result.child ? [result.child] : []), ...(result.snapshots || []), ...(result.children || [])].map((value)=>[value.board_id,value])).values()];
+    // 每项 install 都立即改变 writer 基线；后项校验/合并抛错时，先前 writer 不自动回滚，Map 可能还没 publish。
     for (const value of values) {
       const decoded=decodeSnapshot(value),local=current.current.get(value.board_id),base=writers.current.get(value.board_id)?.document;
       const merged=local&&base?mergeCanvasDocuments(base,local,decoded.document):decoded.document;
@@ -356,7 +361,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
     return [...new Set(values.map((value) => value.board_id))];
   }
   /** 结构/AI等旧命令入口：加载参与writer、flush，再冻结expected_versions、If-Match和幂等key。
-   * execute闭包在不确定失败后复用同一body/key/version；这些恢复信息只在内存，不保证刷新后继续。 */
+   * execute闭包复用同一body对象/key/version，但每次发送重新JSON编码；这些恢复信息只在内存，不保证刷新后继续。 */
   async function command(boardId: string, path: string, payload: Record<string, unknown>, participants?: string[], record = true, versionBoard = boardId) {
     if (retryOperation.current) throw new Error("canvas_busy");
     return exclusive(async () => {
@@ -365,11 +370,13 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
       }
       await flush();
       const body = { ...payload, ...(participants ? { expected_versions: Object.fromEntries(participants.map((id) => [id, writers.current.get(id)?.version])) } : {}) };
+      // body 只浅展开 payload，嵌套值仍共享引用；外部原地修改可能改变重试字节，不同于新版 FrozenRequest.body。
       const key = crypto.randomUUID(), version = writers.current.get(versionBoard)?.version || 1;
       /** 发送、采用回执、按需补读目标快照，并把有transaction_id的结果记入服务端事务历史。 */
       const execute = async (): Promise<CanvasCommandResult> => {
         try {
           const result = await api<CanvasCommandResult>(canvasPath(workspace, boardId) + "/" + path, { method: "POST", headers: { Accept: CANVAS_ACCEPT, "If-Match": `"${version}"`, "Idempotency-Key": key }, body: JSON.stringify(body) });
+          // accept 和历史/补读也在这个 try 内；采用中途失败不等于服务端命令未执行，只有下方分类决定是否保留重试。
           const changed = accept(result);
           // 改变子图/事务后通知侧栏刷新目录；没有快照但有版本结果时补读并保留期间的本地编辑。
           if (path.startsWith("subgraphs") || path.startsWith("transactions/")) window.dispatchEvent(new window.CustomEvent("endoleap:board-directory-changed", { detail: { workspace } }));
@@ -464,6 +471,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
       // A definite rejection performed zero writes. A retry may prepare fresh
       // versions; ambiguous transport failures must retain the exact body/key.
       // 确定拒绝可清冻结闭包重新准备；412还需刷新版本。不确定传输失败继续保留原job.run。
+      // 此处把所有 ApiError<500 当确定拒绝，没有核对 terminal 回执身份；它是旧协议假设，不是新版证据判定。
       if (error instanceof ApiError && error.status < 500) { job.run = undefined; job.refresh = error.status === 412; }
       showMembers();
     } finally {
@@ -474,6 +482,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
   /** 检查准入和重叠成员任务后入FIFO队列；返回Promise由成功出队时resolve，错误在memberJobs中供UI重试。 */
   function moveMembers(parent: string, frame: string, source: string, target: string, ids: string[], participants: string[]) {
     if (migrationBlocked() || locked.current || retryOperation.current || pause.current || members.current.some((job) => job.ids.some((id) => ids.includes(id)) && [job.source, job.target].includes(source))) return Promise.reject(new Error("canvas_busy"));
+    // Promise 只有成功出队才 resolve，没有 reject/卸载取消；失败留队或页面离开后不能把它当已完成屏障。
     return new Promise<void>((resolve) => {
       members.current.push({ parent, frame, source, target, ids, participants, resolve }); showMembers(); void runMembers();
     });
@@ -498,6 +507,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
    * 保存双画布before及pendingMove历史，上传完成后若进入服务端，撤销可能需要真实成员事务。 */
   function movePendingImage(source: string, target: string, id: string) {
     if(migrationBlocked())throw new Error("canvas_busy");
+    // 这里仅检查迁移门闩，未复用 exclusive 的 paused/locked/待重试准入；调用者必须先满足更完整的交互条件。
     const from = current.current.get(source)!, to = current.current.get(target)!;
     const node = from.nodes.find((node)=>node.id===id); if (!node?.pendingUpload || to.nodes.length>=500 || to.nodes.some((item)=>item.id===id)) throw new Error("invalid_reference");
     const projected=projectCanvasTree(root,current.current), a=projected.boards.get(source)!,b=projected.boards.get(target)!;
@@ -553,6 +563,7 @@ export function useCanvasTree(root: string, workspace: string, initial: CanvasDo
         stack.pop();destination.push(entry);tick((v)=>v+1);return;
       }
     }
+    // 分支中的多次 await 不持有跨全流程历史锁，也不重新比对 stack 顶项；宿主应串行发起历史动作。
     // 服务端事务撤销调用transactions/{id}/undo；重做执行原命令并保存新的事务ID/参与快照身份。
     if ("id" in entry) {
       if (isRedo) {

src/components/canvas/use-image-uploads.ts

@@ -30,9 +30,11 @@ export function useImageUploads(workspace: string, commit: (draft: ImageUploadDr
     if (job.status === "uploading") return;
     job.status = "uploading"; job.error = undefined; job.controller = new AbortController(); changed();
     try {
+      // Promise.all 不会因 ready 拒绝自动中止上传；失败 UI 可先出现，而底层请求仍可能完成。
       const [asset] = await Promise.all([uploadCanvasImage(api, workspace, job.file, job.file.name, job.controller.signal, job.key), job.ready || Promise.resolve()]);
       // 结果返回后核对挂载、Map内仍是同一个job且未取消，旧任务不能写到后来同ID的新任务。
       if (!mounted.current || pending.current.get(job.node.id) !== job || job.controller.signal.aborted) return;
+      // commit 是同步调用，不等待网络 ACK；抛错不会自动撤销它此前已发布的本地修改。
       job.asset = asset; onCommit.current(job, asset); job.status = "uploaded"; changed();
     } catch (error) { if (mounted.current && pending.current.get(job.node.id) === job && !job.controller.signal.aborted) { job.status = "failed"; job.error = errorText(error); changed(); } }
   }
@@ -42,11 +44,13 @@ export function useImageUploads(workspace: string, commit: (draft: ImageUploadDr
     let value: ImageUploadDraft;
     try { value = draft(localURL); } catch (error) { URL.revokeObjectURL(localURL); throw error; }
     const job: ImageUploadJob = { ...value, file, localURL, key: crypto.randomUUID(), status: "failed", controller: new AbortController() };
+    // 节点 ID 必须由草稿工厂保证唯一；同 ID set 会替换旧任务，但此处不会 abort/revoke 被替换的任务。
     pending.current.set(job.node.id, job); changed();
     // Browser decoding runs locally, concurrently with the original-byte upload.
     // 纯图片并行解码自然尺寸，限制初始长宽不超过480（不主动放大），再分别设置至少24px的显示尺寸。
     if (job.node.data.kind === "plain-image") {
       job.ready = new Promise<void>((resolve,reject) => {
+      // 这个 Image 解码没有接入 controller 的取消，也没有显式移除 onload/onerror；回调以 Map 身份拒绝已移除任务。
       const image = new window.Image(); image.onload = () => {
         if (pending.current.get(job.node.id) !== job) { resolve(); return; }
         // 分别钳制到最小24可能改变极端长宽比；这里只初始化节点和style尺寸，不重编码上传文件。
@@ -60,6 +64,7 @@ export function useImageUploads(workspace: string, commit: (draft: ImageUploadDr
     void run(job);
     return job;
   }
+  // 每次重试仍调用上传接口，不直接采用 job.asset；幂等依赖相同 key，ready 失败也不会自动回滚服务端资源。
   // hasPending包含失败但不包含uploaded，active只看uploading；loaded仅在正式图片加载后移除已上传预览。
   // retry复用job及幂等键；若ready曾拒绝，重试不会在这里重建尺寸解码Promise。
   return { jobs, hasPending:()=>[...pending.current.values()].some(job=>job.status!=="uploaded"), active: jobs.some((job) => job.status === "uploading"), start, retry: (id: string) => { const job = pending.current.get(id); if (job) void run(job); }, remove, loaded: (id: string) => { if (pending.current.get(id)?.status === "uploaded") remove(id); } };

src/components/landing-page.tsx

@@ -28,6 +28,7 @@ export default function LandingPage() {
   const [active, setActive] = useState(0);
   // null表示全部收起；点击当前问题置null，点击其它问题改索引。hidden与aria-expanded/controls对应同一状态。
   const [faq, setFaq] = useState<number | null>(null);
+  // FAQ 的 hidden 只切换可见性，问答节点仍保留在 DOM；页面没有请求型加载或异步清理任务。
   // 页面顺序：导航→首屏交互预览→理念横条→三个功能说明→工作步骤→FAQ→行动入口→页脚。
   // 功能卡与步骤通过静态内容展示；FAQ以问题文本作key，步骤以序号作key，预览以说明作key。
   // 状态仅在本次组件挂载期间保留；切换预览不自动轮播，FAQ展开不发网络请求。

src/components/ui/app-feedback.tsx

@@ -13,7 +13,8 @@ export const FeedbackContext = createContext(false);
 
 /** 包住页面一次即可共享提示延迟；400ms首次出现，200ms内切换提示可跳过等待。
  * Toaster放在右下角，最多展示三条通知，默认4500ms消失并允许关闭；颜色读取主题变量。
- * children正常透传，本组件不订阅文档、队列或服务端状态。 */
+ * children正常透传，本组件不订阅文档、队列或服务端状态。
+ * visibleToasts 限制同时可见数量，不是业务事件队列容量；通知创建/撤销仍通过通知适配器调用。 */
 export function AppFeedback({ children }: { children: ReactNode }) {
   return <FeedbackContext.Provider value={true}>
     <Tooltip.Provider delayDuration={400} skipDelayDuration={200}>

src/components/ui/button.tsx

@@ -53,6 +53,7 @@ export interface ButtonProps
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
   ({ className, variant, size, asChild = false, ...props }, ref) => {
     // 只选择宿主，不另包一层DOM；cn合并变体和调用方样式，业务逻辑不进入这个封装。
+    // asChild 不把链接转换成原生按钮：disabled 属性本身不保证链接无法导航，调用方须按宿主处理行为。
     const Comp = asChild ? Slot : "button";
     return (
       <Comp

src/components/ui/dialog.tsx

@@ -40,7 +40,8 @@ DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
 
 /** 组合Portal、遮罩与居中内容面板，并在children之后固定附带右上角关闭按钮。
  * 面板ref和剩余属性交给Radix Content，保留焦点及外部交互事件；关闭按钮有读屏文字。
- * 本封装没有单独隐藏默认关闭按钮的参数，业务若要阻止关闭应在受控开关/事件层处理。 */
+ * 本封装没有单独隐藏默认关闭按钮的参数，业务若要阻止关闭应在受控开关/事件层处理。
+ * 剩余 props 只传 Content；当前调用没有把 Overlay 的属性入口一并暴露给 DialogContent。 */
 const DialogContent = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>

src/components/ui/icon-button.tsx

@@ -21,6 +21,7 @@ export type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "chi
 export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
   function IconButton({ icon: Icon, label, title = label, className = "", type = "button", ...props }, ref) {
     // Provider存在时由Radix显示提示，移除原生title以免出现两层提示；图标自身对读屏隐藏。
+    // 后置 ...props 可以覆盖 aria-label 等同名属性；label 是默认名称，最终 DOM 语义由调用者共同负责。
     const feedback = useContext(FeedbackContext);
     const button = (
       <button

src/components/workspace/account-panel.tsx

@@ -29,6 +29,7 @@ export function AccountPanel({ mode, profile, demo, onClose, onProfile, onWorksp
    * HTML输入限制是交互提示，服务端仍校验真实资料/空间名称。 */
   async function submit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
+    // busy 是本次 render 的状态值，限制后续渲染后的重复提交；不是同步 ref 互斥或持久操作幂等键。
     if (busy) return;
     const data = new FormData(event.currentTarget);
     setBusy(true);
@@ -38,6 +39,7 @@ export function AccountPanel({ mode, profile, demo, onClose, onProfile, onWorksp
       if (settings) {
         const input = { display_name: String(data.get("display_name")).trim(), username: String(data.get("username")).trim() };
         const updated = demo ? { ...profile, ...input } : await api<Profile>("profile", { method: "PATCH", body: JSON.stringify(input) });
+        // 宿主回调也在 try 内；若回调抛错，会显示失败，但已成功的服务端修改不会因此回滚。
         onProfile(updated);
       } else {
         const name = String(data.get("name")).trim();
@@ -49,6 +51,7 @@ export function AccountPanel({ mode, profile, demo, onClose, onProfile, onWorksp
     finally { setBusy(false); }
   }
 
+  // 请求没有本地 AbortController/结果代次标记；受控 Dialog 阻止普通关闭，父级强制卸载仍由宿主管理。
   // 保存中禁用取消/提交，并拒绝Dialog的关闭状态变化；请求未结束不假装已成功关闭。
   return (
     <Dialog open onOpenChange={(open) => { if (!open && !busy) onClose(); }}>

src/components/workspace/active-board.tsx

@@ -17,6 +17,7 @@ const ActiveBoardContext = createContext<{
 
 /** 在工作台布局内保持元数据，useMemo稳定Context对象，避免只因父渲染就通知全部使用方。 */
 export function ActiveBoardProvider({ children }: { children: ReactNode }) {
+  // Provider 本身不监听路由/登出，也不推断哪条异步结果较新；发布、清空及身份核对由调用方负责。
   const [board, setBoard] = useState<ActiveBoard>(null);
   const value = useMemo(() => ({ board, setBoard }), [board]);
   return <ActiveBoardContext.Provider value={value}>{children}</ActiveBoardContext.Provider>;

src/components/workspace/board-directory.tsx

@@ -13,6 +13,7 @@ import styles from "./workspace.module.css";
 /** branches只随boards/query重算，closed是当前挂载视图局部状态，宿主切工作区可用key重建。 */
 export function BoardDirectory({ boards, workspace, active, query, demo }: { boards: Board[]; workspace: string; active?: string; query: string; demo: boolean }) {
   const [closed, setClosed] = useState(new Set<string>());
+  // memo 按 boards 引用重算；宿主更新条目须提供新数组，不能只原地改标题/父链再期待重新派生。
   const branches = useMemo(() => filterBoardDirectory(boardDirectory(boards), query), [boards, query]);
   /** 活动画布或目录刷新时展开其祖先路径，防当前页藏在折叠树下。 */
   useEffect(() => {
@@ -22,6 +23,7 @@ export function BoardDirectory({ boards, workspace, active, query, demo }: { boa
   /** 递归渲染树，视觉缩进最多8层但不裁掉更深子项；搜索时强制展开匹配路径而不清空用户closed记录。 */
   function render(items: BoardBranch[], depth = 0) {
     return <ul className={styles.directoryList}>{items.map(({ board, children }) => {
+      // 搜索中的切换只修改 closed 记录，当前仍强制展开；清掉搜索后才看到用户折叠记录的效果。
       const expanded = !!query.trim() || !closed.has(board.id);
       return <li key={board.id}><div className={styles.directoryRow} style={{ paddingLeft: Math.min(depth, 8) * 16 }}>
         {children.length ? <button type="button" className={styles.directoryToggle} aria-label={`${expanded ? "收起" : "展开"}${board.title}的子画布`} aria-expanded={expanded} onClick={() => setClosed((previous) => { const next = new Set(previous); if (expanded) next.add(board.id); else next.delete(board.id); return next; })}><ChevronRight size={13} style={{ transform: expanded ? "rotate(90deg)" : undefined }} /></button> : <span className={styles.directorySpacer} />}

src/components/workspace/canvas-runtime-host.tsx

@@ -23,6 +23,7 @@ const Renderers=createContext(defaultCanvasRenderers);
 export function useCanvasRenderers(){return useContext(Renderers);}
 /** extensions仅在useState惰性初始化时捕获；后续prop换引用不会热替换已打开项目的schema/renderer。 */
 export function CanvasRuntimeHost({ children,extensions=[] }: { children: ReactNode;extensions?:readonly CanvasRuntimeExtension[] }) {
+  // 惰性初始化只装配对象/工厂，不在 render 直接打开项目；实际账户绑定和持久化租约由后续调用取得。
   const [{host,renderers}] = useState(() => {
     // 先组合内置与扩展模型，再按精确版本/结构验证renderer，冲突在打开项目之前失败。
     const registry = createRegistry([...builtinComponents(),...extensions.flatMap(extension=>extension.components??[])]),renderers=createReactRenderers([...defaultCanvasRenderers.definitions,...extensions.flatMap(extension=>extension.renderers??[])],registry);
@@ -51,6 +52,7 @@ export function CanvasRuntimeHost({ children,extensions=[] }: { children: ReactN
    * 真正卸载才发起host.close，保存失败由宿主错误回调/日志报告，不在此丢弃根或强行释放leader。 */
   useEffect(() => {
     const generation = ++lifetime.current;
+    // cleanup 不等待 close 完成，也不主动重试；异步失败经 host 的错误通道和此处 catch 报告。
     // Strict Mode replays effects synchronously; only a real detach retires the host.
     return () => { queueMicrotask(() => { if (lifetime.current === generation) void host.close().catch(error => console.error("[canvas-host]", error.message)); }); };
   }, [host]);

src/components/workspace/editable-title.tsx

@@ -53,6 +53,7 @@ export function EditableTitle({ title, editable, onSave, className = "" }: {
     cancelled.current = true;
     setError("");
     setMode("selected");
+    // 不保存帧句柄做卸载取消；执行时通过 ref 可选访问，目标已卸载则不聚焦。
     requestAnimationFrame(() => button.current?.focus());
   }
   /** 同步ref挡重复提交，trim后校验非空及UTF-8≤300字节；同名不发请求。
@@ -70,6 +71,7 @@ export function EditableTitle({ title, editable, onSave, className = "" }: {
     setMode("saving");
     setError("");
     try {
+      // onSave 没有本组件的 signal/代次护栏；切换目标或卸载后的结果隔离需由宿主回调保证。
       await onSave(name);
       cancelled.current = true;
       setMode("idle");
@@ -78,6 +80,7 @@ export function EditableTitle({ title, editable, onSave, className = "" }: {
       setMode("editing");
     } finally { pending.current = false; }
   }
+  // title prop 改变不自动覆盖正在编辑的 draft；同名判断使用本次 save 闭包看到的 title。
   // saving保留input但只读；输入法组合不把Enter当提交，键盘事件停止冒泡避免触发画布快捷键。
   return (
     <div ref={shell} className={`${styles.shell} ${className}`}>

src/components/workspace/graph-page.tsx

@@ -61,6 +61,7 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin
     // latest合并待采用的预览，pumping串行openPartial/persist，防快流把多个partial打开交错到同一项目。
     let latest:{value:LiveModelPreview;board:Board;accountId:string}|undefined,pumping:Promise<void>|undefined,partialEngine:ProjectEngine|undefined,partialRuntime:ReturnType<typeof runtimeHost.workspace>|undefined;
     /** 后台任务失败仅在页面仍活跃时显示，离开页面不再更新本页error。 */
+    // 此错误显示只检查页面 active；它不像结果采用分支那样再核对 currentIdentity。
     const reportBackground=(error:unknown)=>{if(active)setError(errorText(error));};
     /** 已建立partial engine且身份仍有效时，交工作区继续完整读取；视图离开不等于关闭可恢复项目。 */
     const completeInBackground=()=>{if(partialEngine?.loading.getState()&&currentIdentity?.())void partialRuntime?.resumeLoading(partialEngine.getSnapshot().document.projectId).catch(reportBackground);};
@@ -68,6 +69,7 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin
     function pump(){
       if(pumping)return pumping;
       const task=(async()=>{while(latest){const next=latest;latest=undefined;if(!currentIdentity?.())return;const runtime=runtimeHost.workspace(next.accountId,next.board.workspace_id);partialRuntime=runtime;const engine=await runtime.openPartial(next.value.document,next.value.versions,next.value.loading);partialEngine=engine;if(active&&currentIdentity?.()){setLoaded(previous=>previous?.route===route&&previous.engine===engine?previous:{board:next.board,engine,route});setPreview(null);}else{completeInBackground();return;}await engine.persist();}})();
+      // finally 清空运行句柄，再对等待槽续泵；latest 只留最近预览，并非逐块持久操作队列。
       pumping=task.finally(()=>{pumping=undefined;if(latest&&active)void pump().catch(reportBackground);});return pumping;
     }
 
@@ -91,6 +93,7 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin
         catch(error){reportBackground(error);}
       }
       // 完整模型到来先等partial采用链结束，再open同一项目，避免尾部覆盖尚在发布的前缀根。
+      // 任一次泵拒绝会沿外层 catch 显示错误，不继续把完整结果冒充已经成功采用。
       while(pumping)await pumping;
       if(!active||!currentIdentity?.())return;
       const engine = await runtimeHost.workspace(result.profile.id, result.board.workspace_id).open(result.model.document, result.model.versions,{sourceToken:result.model.sourceToken});
@@ -101,12 +104,14 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin
     return () => { active = false;latest=undefined; controller.abort();completeInBackground(); };
   }, [workspaceId, boardId, route, demo, retry, router, runtimeHost]);
   // 即使effect清理/新读取尚未完成，只显示route匹配的结果，不短暂闪出上个board。
+  // route 只包含两个路径参数，不包含 demo/retry/authEpoch；同路由这些值变化时由 effect 清状态和取消护栏处理。
   const current = loaded?.route === route ? loaded : null;
   const currentPreview=preview?.route===route?preview:null;
   const board = current?.board??currentPreview?.board;
   /** 发布当前board元数据供侧栏标题使用，卸载/换board归还该Context显示状态，不删除服务端board。 */
   useEffect(() => {
     if (board) setActiveBoard({ id: board.id, slug: board.slug, workspace_id: board.workspace_id, workspace_ref: workspaceId, title: board.title });
+    // 这是当前页面的无条件清空，不删除 runtime 或目录记录，也不是按 boardId 比对的条件撤回。
     return () => setActiveBoard(null);
   }, [board, workspaceId, setActiveBoard]);
   // 本board在侧栏改名后优先读共享新标题；其它board的活动状态不能覆盖当前名称。

src/components/workspace/user-avatar.tsx

@@ -7,13 +7,15 @@
 import { useState } from "react";
 import styles from "./workspace.module.css";
 
-/** 同一失败URL不反复重载；large仅控制尺寸，图片不发送Referrer，alt保留用户身份文本。 */
+/** 只记住最近一次失败URL；large仅控制尺寸，图片不发送Referrer，alt保留用户身份文本。
+ * 换 URL 可以再试，若之后回到较早失败的 URL 也可能重试；不是永久失败地址集合。 */
 export function UserAvatar({ name, url, large = false }: {
   name: string;
   url?: string | null;
   large?: boolean;
 }) {
   const [failedUrl, setFailedUrl] = useState<string | null>(null);
+  // fallback 用 slice(0,1) 取首个 UTF-16 代码单元，并非完整 Unicode 字素；空名字得到空占位。
   const showImage = Boolean(url && url !== failedUrl);
   return (
     <span className={`${styles.avatar} ${large ? styles.avatarLarge : ""}`}>

src/lib/canvas-assets.ts

@@ -4,7 +4,7 @@
  */
 /** 由应用注入JSON/FormData请求端口，凭证与错误形状沿用宿主API封装。 */
 type Request = <T>(path: string, options?: RequestInit) => Promise<T>;
-/** 旧上传接口的素材响应形状，原件规范URL与尺寸由返回前校验。 */
+/** 旧上传接口的素材响应形状；返回前检查 ID、URL 的源站/路径/查询和尺寸，不完整验证所有字段。 */
 export type CanvasAsset = { id: string; url: string; width: number; height: number; bytes: number; mime_type: string };
 /** 上传原文件大小上限20MiB，空文件同样拒绝。 */
 export const ASSET_LIMIT = 20 * 1024 * 1024;
@@ -12,6 +12,7 @@ export const ASSET_LIMIT = 20 * 1024 * 1024;
  * 调用方可提供key以跨尝试复用；默认key只在这次函数调用开始时生成，不是持久恢复记录。 */
 export async function uploadCanvasImage(request: Request, workspace: string, file: Blob, name: string, signal?: AbortSignal, key = crypto.randomUUID()): Promise<CanvasAsset> {
   if (!file.size || file.size > ASSET_LIMIT) throw new Error("asset_too_large");
+  // 文件大小是本地发送前检查；不在这里解码图片、计算内容摘要或确认 mime_type。
   const form = new FormData(); form.append("image", file, name);
   /** 两次发送共用同一字节、文件名和key，避免丢响应后新建第二份素材。 */
   const send = () => request<CanvasAsset>(`workspaces/${encodeURIComponent(workspace)}/assets`, { method: "POST", headers: { "Idempotency-Key": key }, body: form, signal });
@@ -25,5 +26,6 @@ export async function uploadCanvasImage(request: Request, workspace: string, fil
   let url: URL;
   try { url = new URL(asset.url); } catch { throw new Error("invalid_asset_response"); }
   if (!/^[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i.test(asset.id) || url.origin !== "https://api.foundry.entroia.com" || url.pathname !== `/projects/${process.env.NEXT_PUBLIC_FOUNDRY_PROJECT || "endoleap"}/workspaces/${workspace}/assets/${asset.id}` || url.search || !Number.isFinite(asset.width) || asset.width < 1 || !Number.isFinite(asset.height) || asset.height < 1) throw new Error("invalid_asset_response");
+  // bytes/mime_type 未在此逐项核验，URL hash/用户名密码也未另设拒绝条件；不能视为新版资源权威证明。
   return asset;
 }

src/lib/canvas-curves.ts

@@ -26,6 +26,7 @@ export function curvePath(segments: Cubic[]) { return `M ${segments[0][0].x},${s
 export function insertCurveKnot(from: Connector, to: Connector, path: EdgeData["path"], point?: XYPosition) {
   const segments = curveSegments(from, to, path);
   let selected = Math.floor(segments.length / 2), t = .5, distance = Infinity;
+  // 只采内部参数 .025～.975；距离相同时保留先遇到的段/采样点，不会选择端点 t=0 或1。
   if (point) segments.forEach((segment, index) => { for (let step = 1; step < 40; step++) {
     const p = cubicPoint(segment, step / 40), d = Math.hypot(p.x - point.x, p.y - point.y);
     if (d < distance) { distance = d; selected = index; t = step / 40; }
@@ -33,6 +34,7 @@ export function insertCurveKnot(from: Connector, to: Connector, path: EdgeData["
   // 逐层插值求左右子曲线，anchor成为新结点，abc/bcd决定其两侧相对切线。
   const [a, b, c, d] = segments[selected];
   const ab = lerp(a, b, t), bc = lerp(b, c, t), cd = lerp(c, d, t), abc = lerp(ab, bc, t), bcd = lerp(bc, cd, t), anchor = lerp(abc, bcd, t);
+  // clone 隔离已有 knots；返回的 knot 同时就是 next.knots 中插入的对象，二者并非独立副本。
   const next = structuredClone(path || { type: "bezier-chain" as const, knots: [] });
   const knot = { id: crypto.randomUUID(), position: anchor, in: minus(abc, anchor), out: minus(bcd, anchor), mode: "smooth" as const };
   // 同时调整相邻旧结点或首尾控制向量，否则插入后无法保留原曲线。

src/lib/canvas-elements.ts

@@ -25,11 +25,13 @@ export abstract class CanvasElement {
   readonly src?: string;
   /** 构造业务创建参数；position在toNode输出时复制，尚未创建节点身份或渲染对象。 */
   constructor(position: XYPosition, text = "", src?: string) {
+    // 构造器暂借调用者的位置对象；若转换前被外部修改，toNode 会采用修改后的坐标。
     this.position = position;
     this.text = text;
     this.src = src;
   }
   /** 每次转换都生成新UUID与独立position/data/style，字体默认随plain-text与卡片类型选择。 */
+  // 同一个业务实例多次 toNode 也会生成不同节点身份，并非按实例 ID 幂等转换。
   toNode(): CanvasNode {
     return {
       id: crypto.randomUUID(), type: this.nodeType, position: { ...this.position },
@@ -87,6 +89,7 @@ export class PlainImageElement extends CanvasElement {
 /** 封闭内置kind→构造器表，是旧元素工厂入口，不接受任意未知kind动态执行。 */
 export const elementClasses = { text: TextCardElement, image: ImageCardElement, script: ScriptCardElement, "plain-text": PlainTextElement, icon: IconElement, frame: FrameElement, "plain-image": PlainImageElement };
 /** 按kind读取静态能力，调用方需先保证kind属于内置枚举。 */
+// readonly 只约束静态属性重新赋值；能力对象仍是共享引用，调用方不能原地改动返回值。
 export function elementCapabilities(kind: ElementKind) { return elementClasses[kind].capabilities; }
 /** 创建指定内置类型的空内容节点，src仅作为创建参数传入；不自动上传文件或登记history。 */
 export function createCanvasElement(kind: ElementKind, position: XYPosition, src?: string): CanvasNode {

src/lib/canvas-frames.ts

@@ -11,6 +11,7 @@ import { nodeCenter, nodeSize } from "./canvas-geometry.ts";
 /** 非frame节点按中心点找包含它的分区，多个重叠候选选面积最小者；frame本身不成为另一frame成员。 */
 export function containingFrame(node: CanvasNode, nodes: CanvasNode[]) {
   if (node.data.kind === "frame") return undefined;
+  // 以未旋转布局矩形判包含，边界算内部；不是对旋转后的可见形状做精确命中。
   const center = nodeCenter(node);
   return nodes.filter((frame) => {
     if (frame.data.kind !== "frame") return false;
@@ -44,8 +45,10 @@ export function assignFrameMembership(nodes: CanvasNode[], droppedIds: string[])
 export function applyFrameNodeChanges(changes: NodeChange<CanvasNode>[], previous: CanvasNode[]) {
   const nodes = applyNodeChanges(changes, previous);
   const before = new Map(previous.map((node) => [node.id, node]));
+  // 仅带实际 position 值的变更计入显式移动；dragging 标记变化本身不触发成员平移。
   const positioned = new Set(changes.flatMap((change) => change.type === "position" && change.position ? [change.id] : []));
   const frames = new Map(nodes.filter((node) => node.data.kind === "frame").map((node) => [node.id, node]));
+  // 单次 map 按原 frameId 计算直接父位移，不递归累积嵌套分区；合法旧数据约定 frame 不归另一 frame。
   return nodes.map((node) => {
     const frameId = node.data.frameId;
     if (!frameId) return node;

src/lib/canvas-geometry.ts

@@ -46,10 +46,12 @@ export function resizeFromPointer(node: CanvasNode, direction: ResizeDirection,
   const rotation = node.data.rotation || 0;
   // 指针位移先消除节点旋转，才能区分拖动的是本地宽还是高。
   const local = rotateVector(delta, -rotation);
+  // delta 是手势起点到当前的场景位移，屏幕缩放换算需由调用者提前完成。
   const horizontal = direction.includes("left") ? -1 : direction.includes("right") ? 1 : 0;
   const vertical = direction.includes("top") ? -1 : direction.includes("bottom") ? 1 : 0;
   const plain = node.data.kind === "plain-text";
   const icon = node.data.kind === "icon" || node.data.kind === "plain-image";
+  // viewScale 只用于尺寸约束；此处不校验正有限值，0 会按 || 回退成1。
   const viewScale = node.data.viewScale || 1;
   // 约束随显示viewScale缩放；frame可更大，普通卡片/文字/图标最小尺寸各有不同。
   const maximum = node.data.kind === "frame" ? 100000 * viewScale : 3000 * viewScale;
@@ -84,6 +86,7 @@ export type Connector = { point: XYPosition; normal: XYPosition };
 export function nodeConnector(node: CanvasNode, side: ConnectorSide): Connector {
   const { width, height } = nodeSize(node);
   const vectors = { top: { x: 0, y: -1 }, right: { x: 1, y: 0 }, bottom: { x: 0, y: 1 }, left: { x: -1, y: 0 } };
+  // side 由联合类型限制，不在运行时回退未知端口；这里的法线假设为四个单位轴向量。
   const local = vectors[side];
   const angle = node.data.rotation || 0;
   const normal = rotateVector(local, angle);

src/lib/canvas-icon-loader.ts

@@ -9,6 +9,7 @@ import { createResourceLoader } from "./resource-loader.ts";
 export type IconPaths = [string, Record<string, string | number>][];
 /** Tabler统一分片，其它名字用稳定31进制散列落入96个Lucide分片；散列仅用于定位而非安全校验。 */
 export function iconAsset(name: string) {
+  // 每步 >>>0 约束为无符号32位；名称大小写参与散列，不能擅自归一化后再查分片。
   let hash = 0;
   for (const char of name) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
   const key = name.startsWith("Tabler") ? "tabler" : `lucide-${hash % 96}`;
@@ -31,9 +32,11 @@ export function validateIconShard(value: unknown): Record<string, IconPaths> {
       }
     }
   }
+  // 校验通过后原对象直接返回，不复制/冻结路径和属性；消费者必须把共享结果当只读数据。
   return value as Record<string, IconPaths>;
 }
-/** 单例分片加载器使用HTTP强缓存，响应失败或校验失败不写入成功缓存。 */
+/** 单例加载器以 force-cache 请求浏览器缓存，并在内存缓存校验后的分片；不保证服务端缓存期限。
+ * 响应失败或校验失败不写入成功缓存；先整体读取 JSON，不限制下载字节数或分片图标总数。 */
 const resources = createResourceLoader(async (url, signal) => {
   const response = await fetch(url, { signal, cache: "force-cache" });
   if (!response.ok) throw new Error("图标加载失败");

src/lib/canvas-subgraphs.ts

@@ -19,6 +19,7 @@ export function subgraphMoveParticipants(documents: Map<string, CanvasDocument>,
     for (const node of documents.get(board)?.nodes || []) if (node.data.subgraph) addDescendants(node.data.subgraph.boardId, seen);
   };
   for (const node of documents.get(source)?.nodes || []) if (ids.includes(node.id) && node.data.subgraph) addDescendants(node.data.subgraph.boardId);
+  // 祖先端口影响只检查 parent 的直接上一层及其一层内端口映射，不是无限上溯的依赖闭包。
   const ancestor = parents.get(parent);
   if (ancestor) {
     const frame = documents.get(ancestor.boardId)?.nodes.find((node) => node.id === ancestor.frameId);
@@ -36,6 +37,7 @@ export function subgraphMovePath(documents: Map<string, CanvasDocument>, source:
   const parents = subgraphParents(documents);
   /** 包含自身的父链，重复board立即拒绝，避免循环遍历。 */
   const chain = (board: string) => { const result = [board]; while (parents.has(board)) { board = parents.get(board)!.boardId; if (result.includes(board)) throw new Error("subgraph_cycle"); result.push(board); } return result; };
+  // 相同 source/target 得到空路径；父索引只反映已加载 documents，缺数据不能据此认定全局无共同根。
   const from = chain(source), to = chain(target), common = from.find((id) => to.includes(id));
   if (!common) throw new Error("ownership_conflict");
   const path: { parent: string; frame: string; source: string; target: string }[] = [];
@@ -56,6 +58,7 @@ export function exposedConnection(documents: Map<string, CanvasDocument>, source
     while (boardId !== owner) {
       const parent = parents.get(boardId)!;
       const frame = documents.get(parent.boardId)?.nodes.find((node) => node.id === parent.frameId);
+      // handle 按 === 精确匹配，包括 undefined 与 null 的差别；不会在这里规范化端口表示。
       const port = frame?.data.ports?.find((port) => port.nodeId === id && port.handle === handle && port.direction === direction);
       if (!port) throw new Error("boundary_port_required");
       id = parent.frameId; handle = `port:${port.id}`; boardId = parent.boardId;
@@ -71,5 +74,6 @@ export function connectionTransactionPlan(documents: Map<string, CanvasDocument>
   const path = (id: string) => { const result = [id]; while (parents.has(id)) { id = parents.get(id)!.boardId; if (result.includes(id)) throw new Error("subgraph_cycle"); result.push(id); } return result; };
   const from = path(source.boardId), to = path(target.boardId), owner = from.find((id) => to.includes(id));
   if (!owner) throw new Error("ownership_conflict");
+  // 参与集按 source→owner、target→owner 首次出现顺序去重；这只是规划，不带服务版本或原子提交证明。
   return { boardId: owner, participants: [...new Set([...from.slice(0, from.indexOf(owner) + 1), ...to.slice(0, to.indexOf(owner) + 1)])], source: { board_id: source.boardId, node_id: source.id, handle: source.handle }, target: { board_id: target.boardId, node_id: target.id, handle: target.handle } };
 }

src/lib/canvas-sync.ts

@@ -73,12 +73,14 @@ export class CanvasSync {
   constructor(request: CanvasRequest, path: string, initial: CanvasSnapshot, notify: (state: SyncState) => void) {
     this.request = request; this.path = path; this.version = initial.version;
     this.saved = canvasFingerprint(initial.document); this.savedContent = canvasFingerprint(initial.document, false); this.notify = notify;
+    // 保留文档引用，不做构造时解码/深复制；宿主须传入合法快照且避免原地修改在途对象。
     this.document = initial.document;
   }
   /** 只有持久内容变化才需PATCH，单纯平移/缩放视口不主动写；内容保存时payload仍携当前viewport。 */
   needsSave(document: CanvasDocument) { return canvasFingerprint(document, false) !== this.savedContent; }
   /** 替换等待槽，有错误时只保留内容而不自动发送；无错误且未运行时启动一个微任务drain。 */
   enqueue(document: CanvasDocument): Promise<void> {
+    // 等待槽借用传入引用；若宿主随后原地修改，drain 读到的内容也会改变，必须以新对象提交编辑。
     this.pending = document;
     if (this.error) return Promise.resolve();
     if (!this.running) this.running = Promise.resolve().then(() => this.drain()).finally(() => { this.running = null; if (this.pending && !this.error) void this.enqueue(this.pending); });
@@ -99,6 +101,7 @@ export class CanvasSync {
   private async drain() {
     while (this.pending) {
       const document = this.pending; this.pending = null;
+      // saving 通知在 try 外；notify 应不抛错，否则 running 会拒绝且本次 document 不进入失败回填。
       this.notify({ status: "saving", version: this.version });
       try {
         const fingerprint = canvasFingerprint(document);
@@ -110,6 +113,7 @@ export class CanvasSync {
         const result = await this.request<{ version: number }>(this.path, { method: "PATCH", headers: { Accept: CANVAS_ACCEPT, "If-Match": `"${this.version}"` }, body });
         if (!Number.isSafeInteger(result?.version) || result.version !== this.version + 1) throw new Error("invalid_canvas_snapshot");
         // 只有通过版本回执后推进保存基线；在途期间新enqueue留在pending供下一轮处理。
+        // 下方保存状态回调仍在 try 内；它若抛错会走 catch，此时版本和部分保存状态已经推进。
         this.version = result.version; this.saved = fingerprint; this.savedContent = canvasFingerprint(document, false);
         this.document = canvasPayload(document);
         this.notify({ status: "saved", version: this.version });
@@ -128,6 +132,7 @@ export class CanvasSync {
  * 格式错误继续抛出，不将损坏草稿当作空白文档自动覆盖。 */
 export function readLocalRecovery(storage: Pick<Storage, "getItem">, key: string, snapshot?: CanvasSnapshot): CanvasDocument | null {
   const record = storage.getItem(key + ":recovery");
+  // 新键存在且内容非空便独占此次恢复判断；即使返回 null 也不再尝试旧键。
   if (record) {
     const value = JSON.parse(record);
     const doc = decodeCanvas(JSON.stringify(value.document));
@@ -144,5 +149,6 @@ export function readLocalRecovery(storage: Pick<Storage, "getItem">, key: string
 export function canRestoreCanvasDraft(draft: CanvasDocument, remote: CanvasDocument) {
   if (draft.schema_version < remote.schema_version) return false;
   const relations = (document: CanvasDocument) => document.nodes.filter((node) => node.data.subgraph).map((node) => ({ id: node.id, subgraph: node.data.subgraph, ports: node.data.ports || [] })).sort((a, b) => a.id.localeCompare(b.id));
+  // 端口数组保留顺序，JSON 表示参与比较；不比较正文、几何或所有跨图端点。
   return JSON.stringify(relations(draft)) === JSON.stringify(relations(remote));
 }

src/lib/canvas-tree.ts

@@ -12,7 +12,7 @@ export type CanvasDocuments = Map<string, CanvasDocument>;
 /** 根board保留原ID，其余加board::前缀，避免旧协议不同board里的同名元素显示碰撞。 */
 export const displayID = (root: string, board: string, id: string) => root === board ? id : `${board}::${id}`;
 /** 路径位置点应用平移+缩放，切线/首尾控制量是向量只缩放；inverse将显示路径转换回owner空间。
- * 没有path时复制data，避免调用方修改投影时改变原始对象。 */
+ * 没有path时深复制data；有path时只重建路径几何层，其余扩展对象仍可能与原data共享引用。 */
 export function transformEdgeData(data: EdgeData | undefined, reference: CanvasReference, inverse = false): EdgeData | undefined {
   if (!data?.path) return data ? structuredClone(data) : undefined;
   const { origin, scale } = reference;
@@ -51,6 +51,7 @@ export function projectCanvasTree(root: string, documents: CanvasDocuments) {
     for (const edge of document.edges) pending.push({ edge, ref: reference });
   }
   visit(root, { x: 0, y: 0 }, 1, new Set());
+  // 仅遍历祖先链防环，不全局去重同一子 board 的多入口；调用方须先保证单父树和显示 ID 合法。
   const visible = new Set(nodes.map((node) => node.id));
   /** 展开入口且端口有效时递归寻内层显示端点；找不到已显示内层就保留外侧入口端口。 */
   function endpoint(board: string, nodeId: string, handle: string | null | undefined, depth = 0): { id: string; handle?: string | null } {
@@ -75,6 +76,7 @@ export function projectCanvasTree(root: string, documents: CanvasDocuments) {
 /** A selected child and its selected parent frame must not receive the same drag twice. */
 /** 父框与子节点同时选中拖动时，先递归取得父框移动后的显示原点，避免同一拖动位移叠加两次。 */
 export function referenceAfterMoves(root: string, documents: CanvasDocuments, boards: Map<string, CanvasReference>, boardId: string, moves: Map<string, { x: number; y: number }>): CanvasReference {
+  // boards 必须来自合法投影；此递归不另建 seen 或深度限制，不接受任意含环父引用表。
   const reference = boards.get(boardId);
   if (!reference) throw new Error("invalid_reference");
   if (boardId === root || !reference.parentBoard || !reference.parentFrame) return reference;
@@ -94,6 +96,7 @@ const equal = (a: unknown, b: unknown) => JSON.stringify(a, (_key, value) => val
 export function mergeCanvasDocuments(base: CanvasDocument, local: CanvasDocument, remote: CanvasDocument): CanvasDocument {
   /** 仅普通对象可逐字段递归，数组/标量两侧不同改动不会“最后写入获胜”，而是抛version_conflict。 */
   const merge = (base: unknown, local: unknown, remote: unknown): unknown => {
+    // 未改变的分支直接借用另一侧对象；本合并不是全图深复制，采用后仍须遵守文档不可变约定。
     if (equal(local, base)) return remote;
     if (equal(remote, base) || equal(local, remote)) return local;
     if ([base, local, remote].every((v) => !!v && typeof v === "object" && !Array.isArray(v))) {
@@ -109,6 +112,7 @@ export function mergeCanvasDocuments(base: CanvasDocument, local: CanvasDocument
   }
   /** 排除选择/拖动/测量/style这些框架字段，它们不该引发业务字段合并冲突。 */
   const strip = <T extends { selected?: boolean; dragging?: boolean; measured?: unknown; style?: unknown }>(value: T) => { const { selected, dragging, measured, style, ...clean } = value; return clean; };
+  // schema 取两侧最大值只选择表示版本，不执行格式迁移或最终整图解码验证。
   const result = {
     schema_version: Math.max(local.schema_version, remote.schema_version) as 1 | 2,
     nodes: collection(base.nodes.map(strip), local.nodes.map(strip), remote.nodes.map(strip)) as CanvasNode[],

src/lib/canvas-v2.ts

@@ -19,9 +19,10 @@ export const pointValid = (value: unknown): value is XYPosition => !!value && ty
 export function fields(value: unknown, keys: string[]): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).every((key) => keys.includes(key));
 }
-/** 所有v2校验失败统一抛invalid_canvas，不返回半份有效扩展。 */
+/** 显式条件校验失败统一抛 invalid_canvas；JSON.stringify/structuredClone 等原生异常仍可能直接传播。 */
 function check(value: boolean) { if (!value) throw new Error("invalid_canvas"); }
 /** 字段缺失可通过，字段存在时必须满足校验；存在但undefined不等同于缺失。 */
+// 使用 in 同时识别继承字段；外部 JSON 解码结果通常是普通自有字段对象，勿把此助手视为原型净化。
 function optional(object: Record<string, unknown>, key: string, valid: (value: unknown) => boolean) { check(!(key in object) || valid(object[key])); }
 /** 构造封闭枚举校验器，不接受任意扩展字符串。 */
 const choice = (...values: unknown[]) => (value: unknown) => values.includes(value);
@@ -76,6 +77,7 @@ export function decodeNodeExtensions(data: Record<string, unknown>, schema: numb
     check(["text", "script", "plain-text", "image", "plain-image"].includes(String(data.kind)) && fields(data.ai, ["enabled", "modelId", "prompt", "propagate", "parameters"])); const ai = data.ai as Record<string, unknown>;
     optional(ai, "enabled", bool); optional(ai, "propagate", bool); optional(ai, "modelId", (v) => typeof v === "string" && v.length > 0 && v.length <= 256 && v.trim() === v);
     optional(ai, "prompt", (v) => typeof v === "string" && [...v].length <= 16000); optional(ai, "parameters", (v) => !!v && typeof v === "object" && !Array.isArray(v) && new TextEncoder().encode(JSON.stringify(v)).length <= 16384);
+    // parameters 这里只检查对象外壳和 JSON 编码大小；不解析各模型参数 schema 或证明服务端支持。
     extensions.ai = structuredClone(ai) as AIConfig;
   }
   if (["subgraph", "ports", "presentation"].some((key) => key in data)) check(data.kind === "frame");
@@ -99,6 +101,7 @@ export function decodeNodeExtensions(data: Record<string, unknown>, schema: numb
  * 内联、demo或其它地址原样返回，不把任意HTTPS资源都伪装成受管资源。 */
 export function managedImageSource(src?: string, preview = false) {
   if (!src) return src;
+  // 此兼容路径固定项目名 endoleap，不读取 NEXT_PUBLIC_FOUNDRY_PROJECT；命中后舍弃原查询/片段。
   try { const url = new URL(src); const match = url.pathname.match(/^\/projects\/endoleap\/(workspaces\/[A-Za-z0-9_-]+\/assets\/[A-Za-z0-9_-]+)$/);
     if (url.origin === "https://api.foundry.entroia.com" && match) return "/api/foundry/" + match[1] + (preview ? "?variant=preview" : "");
   } catch { /* inline and demo images are already browser-readable */ }

src/lib/canvas.ts

@@ -45,12 +45,14 @@ export function canvasStorageKey(workspace: string, board: string) {
   return `endoleap_canvas_v1:${workspace}:${board}`;
 }
 /** 把旧present压入past，截留最近40项并清空redo；checkpoint可记录相同文档对象作为手势起点。 */
+// 仅保存文档引用，不深复制或做相等判断；调用方必须保持历史快照不可变，空修改也可能占一个撤销项。
 function recorded(state: CanvasHistory, present: CanvasDocument): CanvasHistory {
   return { past: [...state.past, state.present].slice(-40), present, future: [] };
 }
 /** 纯快照归约。动作是否产生撤销单元由各分支明确决定，不能假定每次pointermove或字符输入都入栈。 */
 export function canvasReducer(state: CanvasHistory, action: CanvasAction): CanvasHistory {
   switch (action.type) {
+    // patch 直接合入 data 并升级表示版本；reducer 不调用 schema 解码，输入合法性由动作发起方保证。
     case "node-data": return recorded(state, { ...state.present, schema_version: 2, nodes: state.present.nodes.map((node) => node.id === action.id ? { ...node, data: { ...node.data, ...action.patch } } : node) });
     // 连线预览可只改present并清redo，最终逻辑编辑则记录旧快照。
     case "edge-data": {
@@ -58,7 +60,9 @@ export function canvasReducer(state: CanvasHistory, action: CanvasAction): Canva
       return action.transient ? { ...state, present, future: [] } : recorded(state, present);
     }
     // 放下内容才重新算旧frameId归属；拖动/缩放分区本身不在此改变成员关系。
+    // drop 沿用已有 past/future，不清 redo；宿主须将它与实际拖动的 checkpoint/transform 边界配合使用。
     case "drop": return { ...state, present: { ...state.present, nodes: assignFrameMembership(state.present.nodes, action.ids) } };
+    // 重命名/分区/样式动作直接记录，不因目标缺失或值相等自动省略历史。
     case "rename-node": return recorded(state, { ...state.present, nodes: state.present.nodes.map((node) => node.id === action.id ? { ...node, data: { ...node.data, title: action.title } } : node) });
     case "frame": return recorded(state, { ...state.present, nodes: state.present.nodes.map((node) => node.id === action.id && node.data.kind === "frame" ? { ...node, data: { ...node.data, ...(action.title !== undefined ? { title: action.title } : {}), ...(action.labelMode ? { labelMode: action.labelMode } : {}) } } : node) });
     // 交互起点可显式入栈，后续edit/transform不逐帧增加历史项。
@@ -87,6 +91,7 @@ export function canvasReducer(state: CanvasHistory, action: CanvasAction): Canva
     case "style": return recorded(state, { ...state.present, nodes: state.present.nodes.map((node) => node.id === action.id ? { ...node, data: { ...node.data, textStyle: { ...node.data.textStyle, ...action.style }, ...(action.fontSize !== undefined ? { fontSize: action.fontSize } : {}) } } : node) });
     // 连续几何变化同步修改width/height、measured及style；子图frame保存对应展开/折叠尺寸。
     case "transform": {
+      // 宽高必须同时给出才更新尺寸；只给单轴时该轴也不生效，position/rotation/fontSize 各自独立。
       const patch = action.transform;
       return { ...state, future: [], present: { ...state.present, nodes: state.present.nodes.map((node) => node.id !== action.id ? node : {
         ...node,
@@ -146,6 +151,7 @@ export function branchCanvasNode(document: CanvasDocument, id: string, direction
     else position.x += 300;
   }
   // 仅选中新卡片并分配独立边ID；目标handle取旋转后主方向的反侧，源handle仍保留指定方向名。
+  // at 一旦提供便覆盖上述避让位置；指定落点不会再验证重叠，返回文档也不自动登记 history。
   const child = { ...makeCanvasNode(kind, at || position, src), selected: true };
   const opposite: Record<NodeDirection, NodeDirection> = { top: "bottom", bottom: "top", left: "right", right: "left" };
   return {
@@ -158,6 +164,7 @@ export function branchCanvasNode(document: CanvasDocument, id: string, direction
 /** 接受有限长度的允许格式base64内联图或无用户名/密码的HTTPS源，拒绝其它scheme。 */
 function validImage(src: unknown): src is string {
   if (typeof src !== "string") return false;
+  // 只检查字符串表示和长度，不验证 base64 解码字节、图片格式或远端可访问性。
   if (/^data:image\/(png|jpeg|webp|gif);base64,[A-Za-z0-9+/=]+$/.test(src)) return src.length < 3_000_000;
   try { const url = new URL(src); return url.protocol === "https:" && !url.username && !url.password && src.length < 2048; }
   catch { return false; }
@@ -182,6 +189,7 @@ export function decodeTextStyle(value: unknown): import("./canvas-elements.ts").
  * 校验单board内容和其端口外壳，跨board子树/目标存在性需要上层联合加载与事务校验。 */
 export function decodeCanvas(raw: string): CanvasDocument {
   if (new TextEncoder().encode(raw).length > 5 * 1024 * 1024) throw new Error("图谱文件太大，请使用小于 5 MB 的文件。");
+  // JSON.parse 异常直接传播；整个文件先入内存再解释，字节上限不是流式内存预算。
   const value = JSON.parse(raw);
   if (!value || ![1, 2].includes(value.schema_version) || !Array.isArray(value.nodes) || !Array.isArray(value.edges) || value.nodes.length > 500 || value.edges.length > 2000)
     throw new Error("不是有效的啡跃图谱文件。");
@@ -221,6 +229,7 @@ export function decodeCanvas(raw: string): CanvasDocument {
   // frameId仅可引用本board真实frame，不能让旧平面成员关系指向一个普通节点。
   const frameIds = new Set(nodes.filter((node) => node.data.kind === "frame").map((node) => node.id));
   if (nodes.some((node) => node.data.frameId && !frameIds.has(node.data.frameId))) throw new Error("分区归属不存在。");
+  // 以下校验本 board 的端点/端口语法，不检测生成执行图环或加载子 board 验证端口内部目标。
   const nodeKinds = new Map(nodes.map((node) => [node.id, node.data.kind]));
   const edgeIds = new Set<string>();
   // 边身份唯一且两端存在；v2分区必须通过声明的input/output port连接，其它允许节点使用四向handle。

src/lib/demo-workspace.ts

@@ -9,10 +9,12 @@ import type { Board } from "./workspace";
 export function readDemoBoards(workspace: string): Board[] {
   try {
     const stored = JSON.parse(localStorage.getItem("endoleap_demo_boards_" + workspace) || "null");
+    // 合法空数组就是空目录，不触发样例回退；version 用 || 补默认，不验证正安全整数。
     if (Array.isArray(stored)) return stored.map((board) => ({
       ...board, workspace_id: workspace, kind: "board", version: board.version || 1,
     }));
   } catch { /* Fall back to the sample pages when browser storage is invalid. */ }
+  // map 中任一条目读取失败也由外围 catch 回退整份样例，不保留此前已映射的部分结果。
   return [
     { id: "morning", title: "城市清晨" },
     { id: "ideas", title: "灵感收集" },