docs(canvas): explain scene projection and conservative paint caches

This commit is contained in:
2026-11-12 01:09:39 +08:00
parent 45309eaf87
commit 3f7f8e4b7c
8 changed files with 146 additions and 0 deletions
+20
View File
@@ -1,3 +1,7 @@
/**
* 场景的受检增量修补。只在能够证明拓扑、身份和坐标关系仍兼容时替换少量显示对象;
* 不确定就返回 undefined,让调用方完整投影。缓存命中率不能高于模型与显示一致性的优先级。
*/
import type {DocumentQueries} from '../canvas-core/queries.ts';
import type {Document,Id,Registry} from '../canvas-core/types.ts';
import type {SessionSnapshot,ViewState} from '../canvas-core/gestures.ts';
@@ -5,10 +9,15 @@ import {equal} from '../canvas-core/values.ts';
import {projectNode,projectEdge,type projectCanvas} from './projection.ts';
import type {RendererCatalog} from './renderers.ts';
/** 与完整 projectCanvas 保持同一结果结构,避免增量路径自行定义另一套显示规则。 */
type Projection=ReturnType<typeof projectCanvas>;
/** 连续发布的可信写集合;from/to 必须恰好连接旧投影与新文档,topology 表示禁止局部修补。 */
export type SceneChangeHint={from:Document;to:Document;ids:Set<Id>;topology:boolean};
/** 几何手势的瞬态预览,不将 pointermove 变成文档修改。 */
type Preview=NonNullable<SessionSnapshot['gesture']>['preview']|undefined;
/** 真正影响场景内容的输入;viewport/tool/mode 等状态由别的显示通道处理。 */
export type SceneInputs={owner:object;document:Document;registry:Registry;catalog:RendererCatalog;canvasId:Id;selection:ViewState['selection'];preview:Preview;edgeId:Id|undefined;path:NonNullable<SessionSnapshot['connectionGesture']>['path']|undefined};
/** 为上一帧建立 ID→数组位置、分区入口及深度索引;发现降级节点/边后禁用快速修补。 */
export function indexScene(projection:Projection){
const nodes=new Map(projection.nodes.map((node,index)=>[node.id,index])),edges=new Map(projection.edges.map((edge,index)=>[edge.id,index])),entries=new Map<Id,Id>(),depths=new Map<Id,number>([[projection.canvasId,0]]);
for(const canvas of projection.document.canvases.values())if(canvas.parent)entries.set(canvas.parent.entryElementId,canvas.id);
@@ -16,12 +25,15 @@ export function indexScene(projection:Projection){
return{nodes,edges,entries,depths,unsupported:projection.nodes.some(node=>!!node.data.__headlessFallback)||projection.edges.some(edge=>edge.type==='unsupported')};
}
/** Reuse existing projections for checked field edits and ordinary node insertions. */
/** 纯候选投影修补:合并文档/选择/预览脏项,先核对全体脏项再构造新数组。
* 允许普通节点新增与受检字段编辑;删除、代次/类型/owner/连线端点变更交给完整路径。 */
export function patchScene(base:Projection,layout:ReturnType<typeof indexScene>,next:SceneInputs,previous:SceneInputs,connection:SessionSnapshot['connectionGesture'],hint?:SceneChangeHint,queries?:DocumentQueries):Projection|undefined{
const {document,selection,preview,registry,catalog,canvasId}=next;
const {selection:oldSelection,preview:oldPreview,edgeId:oldEdgeId,path:oldPath}=previous;
if(layout.unsupported||document.projectId!==base.document.projectId)return;
const dirty=new Set<Id>(),created=new Set<Id>();
if(document!==base.document){
// 可信连续 changes 可直接路由 ID;拓扑提示则立刻放弃。无提示时需要逐项核对表顺序及内容。
if(hint?.from===base.document&&hint.to===document){if(hint.topology)return;for(const id of hint.ids)dirty.add(id);}
else{
// Canonical replacement and missed publications carry no trustworthy write set.
@@ -33,16 +45,21 @@ export function patchScene(base:Projection,layout:ReturnType<typeof indexScene>,
for(const[id,record]of document.elements){if(id!==elementOrder.next().value)return;if(record!==base.document.elements.get(id)&&!equal(record,base.document.elements.get(id)))dirty.add(id);}
}
}
// 选择变化取对称差;预览变化同时检查新旧集合,取消预览也必须重画旧目标。
if(selection!==oldSelection){for(const id of oldSelection)if(!selection.has(id))dirty.add(id);for(const id of selection)if(!oldSelection.has(id))dirty.add(id);}
if(preview!==oldPreview){for(const[id,g]of oldPreview??[])if(!equal(g,preview?.get(id)))dirty.add(id);for(const[id,g]of preview??[])if(!equal(g,oldPreview?.get(id)))dirty.add(id);}
// 连线预览换目标或结束时,把旧边和新边都标脏,以去掉上一条线的预览。
if(connection?.target.id!==oldEdgeId||connection?.path!==oldPath){if(oldEdgeId)dirty.add(oldEdgeId);if(connection)dirty.add(connection.target.id);}
// Validate the whole dirty footprint before constructing or publishing any replacement.
for(const id of dirty){const before=base.document.elements.get(id),after=document.elements.get(id);
// 新节点暂记 created;未改分区拓扑且所属 canvas 已有变换时才可能插入当前场景。
if(!before&&after?.structure==='node'){created.add(id);continue;}
if(!before||!after||before.incarnation!==after.incarnation||before.structure!==after.structure||before.componentId!==after.componentId||before.dataVersion!==after.dataVersion||before.ownerCanvasId!==after.ownerCanvasId)return;
if(before.structure==='connection'&&after.structure==='connection'&&(!equal(before.source,after.source)||!equal(before.target,after.target)))return;
// 入口几何/单位展示或其预览变化会影响整棵子树变换,不能只修补入口本身。
if(before.structure==='node'&&after.structure==='node'&&layout.entries.has(id)&&(!equal(before.geometry,after.geometry)||!equal(before.data.presentation,after.data.presentation)||!equal(oldPreview?.get(id),preview?.get(id))))return;
}
// 懒复制:未受影响的数组与节点/边对象沿用原引用,新对象仍调用完整路径共用的投影函数。
let nodes=base.nodes,edges=base.edges;const inserted=new Map<Id,Projection['nodes'][number]>();
for(const id of dirty){const element=document.elements.get(id)!;
if(element.structure==='node'){
@@ -58,13 +75,16 @@ export function patchScene(base:Projection,layout:ReturnType<typeof indexScene>,
if(edges===base.edges)edges=[...edges];edges[index]=edge;
}
}
// 插入后按显示根的深度优先成员序重排引用,不能直接 append 而破坏嵌套绘制层序。
if(inserted.size){
// Membership order is depth-first, not global insertion order. Reorder references
// without reconstructing unaffected nodes, transforms or edge projections.
const members=new Map<Id,Id[]>();if(!queries)for(const element of document.elements.values()){const list=members.get(element.ownerCanvasId)??[];list.push(element.id);members.set(element.ownerCanvasId,list);}
const ordered:Projection['nodes']=[];let complete=true;
/** 只重排节点引用,不重算未变化节点;任一所需投影缺失就放弃这份候选。 */
const visit=(owner:Id)=>{for(const id of queries?queries.members(owner):members.get(owner)??[]){const element=document.elements.get(id)!;if(element.structure!=='node')continue;const projected=inserted.get(id)??nodes[layout.nodes.get(id)!];if(!projected){complete=false;return;}ordered.push(projected);const child=layout.entries.get(id);if(child&&base.transforms.has(child))visit(child);}};
visit(canvasId);if(!complete)return;nodes=ordered;
}
// 文档及数组均未变化时返回原场景,否则只替换必要字段,不发布任何业务状态。
return nodes===base.nodes&&edges===base.edges&&document===base.document?base:{...base,document,nodes,edges};
}