docs(canvas): clarify legacy tree coordination and retry evidence

docs(dashboard): explain directory and identity lifecycle
docs(api): explain proxy and OAuth validation boundaries
2026-11-12 16:48:59 +08:00 · 2026-11-12 16:45:11 +08:00 · 2026-11-12 16:41:57 +08:00 · 2026-11-12 16:38:57 +08:00 · 2026-11-12 16:36:27 +08:00 · 2026-11-12 16:33:12 +08:00
70 changed files with 225 additions and 15 deletions
@@ -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(
@@ -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) ||
@@ -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 (
@@ -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 (
    <>
@@ -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>
@@ -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">
@@ -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 (
@@ -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 />;
@@ -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()); };
@@ -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;
@@ -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" }} />;
@@ -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"}
@@ -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后自然移除覆盖。
@@ -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;
 }
@@ -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;}));
@@ -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，再开始编辑。
@@ -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} 连接元素`} />)}</>;
 }
@@ -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()}>
@@ -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);
@@ -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()}>
@@ -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({
    // 指针移动可能持续产生事件，必须逐次检查，不能只在创建租约时检查一次。
@@ -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>;
 }
@@ -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) => {
@@ -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}>
@@ -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止于面板，避免触发画布手势或快捷键。
@@ -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>
@@ -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数量变化。
@@ -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);}
@@ -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)))
@@ -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后是否关闭由调用方决定。
@@ -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();
@@ -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}>
@@ -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 : ""}`}>
@@ -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对应的动作实现负责。
@@ -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(),[]);
 }
@@ -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只在非组合输入、非文本编辑且未被处理时关闭当前节点的变换模式。
@@ -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(); } }} />;
@@ -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>;
 }
@@ -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[]};
@@ -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" };
@@ -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?.(); }
          }} />;
@@ -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>;
 }
@@ -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);
@@ -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(); } };
 }
@@ -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) {
@@ -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); } };
@@ -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展开不发网络请求。
@@ -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}>
@@ -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
@@ -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>
@@ -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
@@ -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(); }}>
@@ -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>;
@@ -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} />}
@@ -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]);
@@ -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}`}>
@@ -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的活动状态不能覆盖当前名称。
@@ -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 : ""}`}>
@@ -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;
 }
@@ -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 };
  // 同时调整相邻旧结点或首尾控制向量，否则插入后无法保留原曲线。
@@ -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 {
@@ -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;
@@ -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);
@@ -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("图标加载失败");
@@ -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 } };
 }
@@ -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));
 }
@@ -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[],
@@ -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 */ }
@@ -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。
@@ -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: "灵感收集" },
Author	SHA1	Message	Date
codex-bot	33f870d16a	docs(canvas): clarify legacy tree coordination and retry evidence	2026-11-12 16:48:59 +08:00
codex-bot	c311c7d7f8	docs(dashboard): explain directory and identity lifecycle	2026-11-12 16:45:11 +08:00
codex-bot	923c82f366	docs(api): explain proxy and OAuth validation boundaries	2026-11-12 16:41:57 +08:00
codex-bot	62b41b79dc	docs(canvas): explain legacy persistence and upload cleanup	2026-11-12 16:38:57 +08:00
codex-bot	55d70fe786	docs(canvas): explain pointer editing and capture cleanup	2026-11-12 16:36:27 +08:00
codex-bot	7bd0bf2049	docs(canvas): explain overlays and loading preview lifetimes	2026-11-12 16:33:12 +08:00
codex-bot	3ef07cd00c	docs(canvas): explain AI and resource picker state ownership	2026-11-12 16:29:49 +08:00
codex-bot	d2068d416a	docs(canvas): explain recovery and import UI lifecycle	2026-11-12 16:27:01 +08:00
codex-bot	97fefaa519	docs(canvas): explain menu focus and toolbar update boundaries	2026-11-12 16:24:09 +08:00
codex-bot	c34d0b7ce0	docs(canvas): explain node rendering and resource handoffs	2026-11-12 16:21:06 +08:00
codex-bot	f28d3810d4	docs(canvas): clarify editing guards and projection lifetimes	2026-11-12 16:18:24 +08:00
codex-bot	65c54e7b9e	docs(workspace): explain component state and async ownership	2026-11-12 16:14:21 +08:00
codex-bot	cc2172319e	docs(ui): explain page and shared component lifecycle boundaries	2026-11-12 16:11:24 +08:00
codex-bot	5d82655e0e	docs(canvas): explain legacy document and sync state boundaries	2026-11-12 16:08:02 +08:00
codex-bot	9b24319747	docs(canvas): explain legacy resources and geometry ownership	2026-11-12 16:04:32 +08:00
Zayden-Jung	b995e659a6	Merge pull request 'docs: 完善协议、公共库与画布迁移注释' (#13 ) from codex/foundry-protocol-comments into main Reviewed-on: #13	2026-11-12 08:03:32 +00:00