docs(canvas): explain headless view and command boundaries

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

@@ -149,8 +149,10 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
   // 保留调用方renderer表，并显式安装unsupported节点/边占位，未知内容仍可在场景中呈现。
   const nodeTypes=useMemo(()=>({...renderers.nodeTypes,unsupported:UnsupportedNode}),[renderers]),edgeTypes=useMemo(()=>({...renderers.edgeTypes,unsupported:UnsupportedEdge}),[renderers]);
   // 稳定动作闭包从current/engine读取最新状态，runtime-only发布不必重建全部卡片编辑上下文。
+  // current 是最近一次 React render 的快照，frame 合并期间可落后于 engine；需要强身份保证的入口仍须实时查询。
   const current = useRef({ root, projection, view, engine, sessions }); current.current = { root, projection, view, engine, sessions };
   /** 将命令拒绝或能力不可用显示为错误；成功结果无需额外复制进本地state。 */
+  // 这里只呈现 rejected/disabled，不捕获同步异常，也不在成功时自动清除旧错误文案。
   const report = useCallback((result: Result | { enabled: boolean; code?: string }) => {
     if ('status' in result && result.status === 'rejected' || 'enabled' in result && !result.enabled) setError(errorText(new Error(result.code)));
   }, []);
@@ -204,6 +206,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
     const width = (change.width ?? displayed.width!) / t.scale, height = (change.height ?? displayed.height!) / t.scale;
     const position = change.position ?? displayed.position, center = toLocal(t, { x: position.x + width * t.scale / 2, y: position.y + height * t.scale / 2 });
     const patch: Partial<Geometry> = { x: center.x - width / 2, y: center.y - height / 2, width, height, ...(change.rotation !== undefined ? { rotation: ((change.rotation - t.rotation) % 360 + 360) % 360 } : {}) };
+    // 入参 fontSize 未进入这个 Geometry patch；字体大小修改应走单独 data/style 命令，而不是几何租约。
     report(engine.sessions.update(viewId, target(id), patch));
   }
   /** 创建内置节点，可加入调用方已有事务；frame同时创建以节点为入口的子canvas，保证结构一起提交。
@@ -217,6 +220,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
     const element: ElementRecord = { id, incarnation: 1, structure: 'node', componentId: kind, dataVersion: 1, ownerCanvasId: canvasId, geometry: { ...position, ...size, rotation: 0 }, data: { title: kind === 'frame' ? '未命名分区' : kind === 'image' ? '视觉参考' : '灵感笔记', text: '', ...(ref ? { assetId: ref.id, src: ref.src } : {}) } };
     /** tx内创建元素及可选canvas关系；无外部tx时包装为一个Add element事务。 */
     const create = (transaction: NonNullable<typeof tx>) => { transaction.dispatch({ type: 'element.create', element }); if (kind === 'frame') transaction.dispatch({ type: 'canvas.create', canvas: { id: crypto.randomUUID(), parent: { canvasId, entryElementId: id } } }); };
+    // 返回分配的 ID 不代表创建成功：无 tx 时这里只 report 拒绝，调用方若要依赖结果须检查事务状态。
     if (tx) create(tx); else report(engine.editor.transaction(create, { label: 'Add element' }));
     return id;
   }
@@ -229,6 +233,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
     report(engine.editor.dispatch({ type: 'element.create', element: { id: crypto.randomUUID(), incarnation: 1, componentId: 'connection', dataVersion: 1, structure: 'connection', ownerCanvasId: commonCanvas(document, source.ownerCanvasId, destination.ownerCanvasId), source: { elementId: source.id, ...(connection.sourceHandle ? { portId: connection.sourceHandle } : {}) }, target: { elementId: destination.id, ...(connection.targetHandle ? { portId: connection.targetHandle } : {}) }, data: {}, path: null } }));
   }
   // 用节点ID+assetId序列作为显示订阅键，资源分辨率/URL交资源视图决定；组件不把Blob URL写入元素data。
+  // 资源键只反映当前投影的 nodeId/assetId，身份和 URL 可用性由 resourceView/engine 重新核验。
   const resourceKey = JSON.stringify(projection.nodes.filter(node => typeof node.data.assetId==='string'&&node.data.assetId).map(node => [node.id, node.data.assetId]));
   // 每个engine/view建立资源显示器，回调只接受当前实例；清理dispose解除订阅及显示资源占用。
   useEffect(() => {
@@ -245,6 +250,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
   function removeSelected() { report(engine.editor.transaction(tx => { for (const id of current.current.view.selection) if (tx.getDocument().elements.has(id)) tx.dispatch({ type: 'element.remove', target: target(id) }); }, { label: 'Delete selection' })); }
   // 同步显示来自ledger：未resolved算待处理；waiting_digest单独等待不算阻断，无定时重试的错误和conflicts要提示处理。
   const pending = [...root.runtime.ledger.operations.values()].filter(operation => operation.phase !== 'resolved');
+  // “已同步”文案依据这些 ledger/冲突计数，不是所有资源解码、所有后台任务或远端生成全部完成的证明。
   const blocked = pending.some(operation => operation.phase === 'blocked' && operation.blockers.some(reason => reason !== 'waiting_digest')) || [...root.runtime.ledger.requests.values()].some(request => request.phase !== 'resolved' && request.error && request.retryAt === undefined) || root.runtime.conflicts.size > 0;
   // 全局失焦或Escape仅取消本视图拥有的节点/连接手势；不干扰同engine其它视图的交互。
   useEffect(() => {
@@ -286,6 +292,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
   // 单选时才启用图片适配/AI工具；图片要求已知组件、resize能力和声明的assetId资源字段，不能猜同名业务字段。
   const selected = view.selection.size === 1 ? root.document.elements.get([...view.selection][0]) : undefined;
   const selectedResource=selected?.structure==='node'&&engine.editor.registry.resolve(selected)==='known'&&engine.editor.registry.supports(selected,'geometry.resize')&&typeof selected.data.assetId==='string'&&engine.editor.registry.components.get(selected.componentId)?.resourceFields?.includes('assetId')?root.runtime.resources.get(selected.data.assetId):undefined;
+  // canFitImage 在显示上因任意视图的 gesture 都禁用；真正命令能否执行仍由 engine.fitImage 再判断。
   const canFitImage=!!selectedResource&&(selectedResource.image?.version===1&&selectedResource.image.status==='ready'||!!selectedResource.stored)&&!sessions.gesture;
   const aiElement = selected?.structure === 'node' && engine.editor.registry.resolve(selected) === 'known' && ['text','plain-text','script','image','plain-image'].includes(selected.componentId) ? selected : undefined;
   // Runtime-only publications must not invalidate every card's editing context.
@@ -301,6 +308,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
       select: id => engine.sessions.select(viewId, [id]), edit: (id, text) => data(id,{text},groups.current.get(id)?.incarnation===engine.getSnapshot().document.elements.get(id)?.incarnation?groups.current.get(id)?.groupId:undefined), rename: (id, title) => data(id, { title }),
       beginTransform, transform, finishTransform: () => { if (engine.sessions.getSnapshot().gesture?.viewId === viewId) report(engine.sessions.commit(viewId)); }, cancelTransform: () => { if (engine.sessions.getSnapshot().gesture?.viewId === viewId) engine.sessions.cancel('pointer_cancel'); },
       // 样式和分区补丁走data，模式rotate/resize只在sessions中切换；开启一个前先清同视图该类旧模式。
+      // data 命令收到的是这次传入的 textStyle 对象；本层不读取并深合并旧样式，合并语义由 editor 定义。
       style: (id, textStyle, fontSize) => data(id, json({ textStyle, ...(fontSize !== undefined ? { fontSize } : {}) })), frame: (id, patch) => data(id, json(patch)),
       rotating, rotate: id => { for (const [key, mode] of engine.sessions.getSnapshot().views.get(viewId)?.modes ?? []) if (mode === 'rotate') engine.sessions.mode(viewId, key, null); if (id) engine.sessions.mode(viewId, id, 'rotate'); },
       resizing, resize: id => { for (const [key, mode] of engine.sessions.getSnapshot().views.get(viewId)?.modes ?? []) if (mode === 'resize') engine.sessions.mode(viewId, key, null); if (id) engine.sessions.mode(viewId, id, 'resize'); },
@@ -318,6 +326,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
       const token = engine.sessions.getSnapshot().connectionGesture!.token, element = engine.getSnapshot().document.elements.get(id)!;
       const transform = current.current.projection.transforms.get(element.ownerCanvasId)!;
       /** token护栏绑定该条连接手势，预览路径先从场景空间变回owner局部空间。 */
+      // owner 的坐标 transform 在 begin 时捕获；token 护栏只核手势身份，归属变化是否合法由 sessions 校验。
       const ownsGesture = () => engine.sessions.getSnapshot().connectionGesture?.token === token;
       return guardEditingLease(ownsGesture, { preview: (path: NonNullable<import('@/lib/canvas-v2').EdgeData['path']>) => report(engine.sessions.updateConnection(viewId, transformPath(path as Json, transform, true))), commit: () => report(engine.sessions.commitConnection(viewId)), cancel: () => engine.sessions.cancel('pointer_cancel') });
     },
@@ -338,12 +347,14 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
   }),[engine,viewId,report]);
   // 自定义renderer的dispatch/transaction也经过editor，并统一report拒绝；选项只传label/groupId。
   const rendererCommands=useMemo<CanvasRendererCommands>(()=>({dispatch(command,options){const result=engine.editor.dispatch(command,{label:options?.label,groupId:options?.groupId});report(result);return result;},transaction(callback,options){const result=engine.editor.transaction(callback,{label:options?.label,groupId:options?.groupId});report(result);return result;}}),[engine,report]);
+  // rendererCommands 直接委托 editor；它不是额外按 viewId/渲染目标绑定的权限层，扩展 renderer 必须遵守调用契约。
   // 本组件Hook全部调用后才判断视图关闭，保留React Hook调用顺序；已detach时不挂载交互surface。
   if (!liveView) return <p role="status">画布已关闭</p>;
   // surface集中处理焦点epoch、拖动起点和键盘路由：blur微任务只清旧epoch，多触点取消当前手势。
   // 快捷键按输入上下文优先级处理Escape、H/V、撤销重做及删除；只有认领成功才阻止默认行为。
   // ReactFlow位移变化只转session预览，测量单独缓存；拖动结束依据起始位置补最后位移后commit。
   // 工具栏撤销/深复制/导出走各自editor/runtime接口，视口缩放只改view；导出完整文档JSON，不含文件字节。
+  // 复制完成回调只比较 engine/viewId，未另设卸载信号；文件暂存、复制和导出均不因关闭面板而自动回滚。
   // 文件选择调用stageFiles，引用与图片节点在回调事务里一起创建；导入/AI/资源/恢复面板按加载与选择条件挂载。
   return <div ref={surface} className={`${styles.editor} ${view.tool === 'pan' ? styles.handMode : ''}`} data-headless-canvas data-model-loading={loading?"true":undefined} tabIndex={-1}
     onFocusCapture={event => { if ((event.target as HTMLElement).closest('input,textarea,[contenteditable="true"],[role="textbox"]')) { focusEpoch.current++; setFocusedEditor(event.target as HTMLElement); } }}
@@ -369,6 +380,7 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
 
         onMoveEnd={(_, viewport) => engine.sessions.viewport(viewId, viewport)}
         onNodeDragStart={(event, node, nodes) => {
+          // 起始位置表借用投影 position 引用；后续 preview 必须保持不可变更新，不能原地篡改这些起点。
           const ids = new Set((nodes.length ? nodes : [node]).map(node => node.id));
           // 同时选中分区入口与后代时只对最上层目标启动手势，后代位置由结构投影带动。
           const top = [...ids].filter(id => { const element = current.current.root.document.elements.get(id)!; return !ancestors(current.current.root.document, element.ownerCanvasId).some(canvasId => { const parent = current.current.root.document.canvases.get(canvasId)?.parent; return parent && ids.has(parent.entryElementId); }); });
@@ -419,9 +431,11 @@ function CanvasView({ engine, board, viewId, renderers,fitLoading=true }: { engi
 /** 挂载期生成稳定viewId并attach，借用initialViewport只初始化一次；detach只释放视图，不关闭engine。
  * 交接视口存在时禁用加载初次fit，避免从只读预览切入后可视位置突然跳变。 */
 export default function HeadlessGraphCanvas({ engine, board, renderers=defaultCanvasRenderers,initialViewport }: { engine: ProjectEngine; board: Board; renderers?:ReactRenderers;initialViewport?:Viewport }) {
+  // 初始视口只捕获一次；同一挂载内 props.initialViewport 变化不会重新定位，切项目应由宿主正确重建/切会话。
   const [handoffViewport]=useState(initialViewport);
   const [viewId] = useState(() => crypto.randomUUID()), [attached, setAttached] = useState(false);
   // attach完成后才挂载CanvasView所需Provider；清理时detach视图，CanvasView卸载清理自身订阅。
+  // attach/viewport 在 effect 中同步执行，未捕获异常；attached 是显示门闩，不负责服务端加载或持久化就绪。
   useEffect(() => { const detach = engine.sessions.attach(viewId, board.id);if(handoffViewport)engine.sessions.viewport(viewId,handoffViewport); setAttached(true); return () => { setAttached(false); detach(); }; }, [engine, viewId, board.id,handoffViewport]);
   return attached ? <ReactFlowProvider><CanvasProvider engine={engine} viewId={viewId}><CanvasView engine={engine} board={board} viewId={viewId} renderers={renderers} fitLoading={!handoffViewport} /></CanvasProvider></ReactFlowProvider> : <p role="status">正在准备画布…</p>;
 }