docs(canvas): explain legacy document and sync state boundaries

src/lib/canvas-subgraphs.ts

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

src/lib/canvas-sync.ts

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

src/lib/canvas-tree.ts

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

src/lib/canvas-v2.ts

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

src/lib/canvas.ts

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

src/lib/demo-workspace.ts

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