docs(canvas): explain overlays and loading preview lifetimes

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/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-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/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-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/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/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: "灵感收集" },