docs(tests): explain browser drivers React fixtures and renderer probes

tests/headless/blob-checkpoint-browser-cases.mjs

@@ -1,30 +1,54 @@
+/**
+ * 真实浏览器存储的 Blob checkpoint 场景，由 browser-storage-cases 调用并注入断言函数。
+ * 分别处理 DB schema 4→5、checkpoint 编码版本与恢复镜像格式版本，三个版本号不是同一时钟。
+ * 覆盖旧行升级、精确字节校验、未来格式、事务回滚、owner 失效与被旧连接阻挡的升级。
+ */
 import {createBrowserStorage} from '../../src/lib/canvas-runtime/storage.ts';
 import {sealRecoveryImage} from '../../src/lib/canvas-runtime/recovery-encoding.ts';
+// 手工建立旧数据库后再通过生产 storage 升级，直接观察持久化行及重新打开后的恢复结果。
 export async function blobCheckpointCase(assert){
+ // 随机数据库名隔离场景；镜像含 Unicode、大量文本和固定请求字节，用来检查序列化保持精确内容。
  const name=`blob-checkpoint-${crypto.randomUUID()}`,scope={accountId:'a',workspaceId:'w',projectId:'p'},key=JSON.stringify(['a','w','p']),image=revision=>({formatVersion:1,rootRevision:revision,localRevision:revision,payload:{rows:Array.from({length:250},(_,i)=>({id:i,text:`版本 ${revision} 👀 ${'x'.repeat(100)}`})),request:{id:'frozen',body:'{"exact":"original bytes"}'}}});
+ // 三个 Promise 工具分别等待 IDB 请求、事务完成/abort 和原始 Blob SHA-256；事务成功不能只看单个 put 成功。
  const read=req=>new Promise((resolve,reject)=>{req.onsuccess=()=>resolve(req.result);req.onerror=()=>reject(req.error);}),done=tx=>new Promise((resolve,reject)=>{tx.oncomplete=resolve;tx.onabort=()=>reject(tx.error);}),hash=async blob=>[...new Uint8Array(await crypto.subtle.digest('SHA-256',await blob.arrayBuffer()))].map(n=>n.toString(16).padStart(2,'0')).join('');
+ // 手工打开 DB v4 并创建旧表，绕开新适配器自动建库，保证后面确实经历旧 checkpoint 升级。
  let raw=await new Promise((resolve,reject)=>{const request=indexedDB.open(name,4);request.onupgradeneeded=()=>{for(const store of ['metadata','checkpoints','journal','files'])request.result.createObjectStore(store);};request.onsuccess=()=>resolve(request.result);request.onerror=()=>reject(request.error);});
+ // 把旧对象镜像与其 checksum 一起写入 revision 0，并关闭旧连接后再启动新适配器。
  const initial=image(0),checksum=await hash(new Blob([JSON.stringify(initial)]));let tx=raw.transaction(['metadata','checkpoints'],'readwrite'),terminal=done(tx);tx.objectStore('metadata').put({fence:0,throughRevision:0,checkpointRevision:0},key);tx.objectStore('checkpoints').put({image:initial,checksum},[key,0]);await terminal;raw.close();let storage=createBrowserStorage({name,checkpointEvery:1}),leader;
  try{
+  // 先核对旧对象恢复不变，再提交带 sealed 镜像与文件的首个新切点。
   leader=await storage.claim(scope);assert(JSON.stringify(await storage.recover(leader))===JSON.stringify(initial),'DB v4 legacy checkpoint changed during upgrade');const first=image(1);await storage.commit(leader,{image:sealRecoveryImage(1,1,1,first.payload),files:[{id:'kept',bytes:new Blob(['kept bytes'])}]});
+  // DB 应升级为 5；新 checkpoint 存 Blob 而非克隆文档对象，文本和 checksum 覆盖精确序列化字节。
   raw=await read(indexedDB.open(name));assert(raw.version===5,'Blob cuts did not fence old DB clients');const saved=await read(raw.transaction('checkpoints').objectStore('checkpoints').get([key,1]));assert(saved.checkpointVersion===1&&saved.bytes instanceof Blob&&!saved.image,'full cut is still a cloned document object');assert(await saved.bytes.text()===JSON.stringify(first),'Blob checkpoint changed serialized bytes');assert(saved.checksum===await hash(saved.bytes),'Blob checksum did not cover exact source bytes');
+  // 旧 DB v4 客户端再打开必须得到 VersionError，防止老解释器接受新 Blob 行。
   const old=await new Promise(resolve=>{const request=indexedDB.open(name,4);request.onerror=event=>{event.preventDefault();resolve(request.error.name);};request.onsuccess=()=>{request.result.close();resolve('accepted');};});assert(old==='VersionError','DB v4 reader accepted Blob checkpoint rows');
+  // 用原始 IDB 连接替换指定 checkpoint 行，构造损坏输入后仍等待事务真正完成。
   const write=async value=>{const tx=raw.transaction('checkpoints','readwrite'),terminal=done(tx);tx.objectStore('checkpoints').put(value,[key,1]);await terminal;};
+  // 分别破坏字节、header、编码版本和 UTF-8；每次恢复检查对应错误，并还原原行供下一场景继续。
   for(const [kind,expected]of [['bytes','recovery_checksum_mismatch'],['header','recovery_checksum_mismatch'],['future','recovery_checkpoint_interpreter_unavailable'],['utf8','corrupt_recovery_image']]){
    const damaged=structuredClone(saved);if(kind==='bytes')damaged.bytes=new Blob([JSON.stringify(image(9))]);else if(kind==='header')damaged.header.formatVersion=2;else if(kind==='future')damaged.checkpointVersion=2;else{damaged.bytes=new Blob([new Uint8Array([123,34,120,34,58,34,255,34,125])]);damaged.checksum=await hash(damaged.bytes);}
    await write(damaged);let code;try{await storage.recover(leader);}catch(error){code=error.code;}assert(code===expected,`${kind} cut was accepted: ${code}`);if(kind==='future'){code=undefined;try{await storage.commit(leader,{image:image(2)});}catch(error){code=error.code;}assert(code===expected,'writer replaced a future checkpoint');}await write(saved);
   }
+  // 暂时包装原生 put：先排入写请求再抛错，把故障放在事务已安排部分写入的窗口。
   const nativePut=IDBObjectStore.prototype.put;let injected=false,error;
+  // 只在 revision 2 的新 Blob checkpoint 写入点注入异常；其他表/版本继续调用真实 IndexedDB。
   IDBObjectStore.prototype.put=function(value,k){const request=nativePut.call(this,value,k);if(this.name==='checkpoints'&&value?.checkpointVersion===1&&value.header.rootRevision===2){injected=true;throw Error('abort_blob_checkpoint');}return request;};
+  // 带新文件的提交失败后恢复原 put，再验证旧 Root 仍可读且新文件字节没有泄漏。
   try{await storage.commit(leader,{image:image(2),files:[{id:'orphan',bytes:new Blob(['must rollback'])}]});}catch(cause){error=cause.message;}finally{IDBObjectStore.prototype.put=nativePut;}
   assert(injected&&error==='abort_blob_checkpoint','checkpoint fault was not injected after put');assert((await storage.recover(leader)).rootRevision===1&&await storage.readFile(leader,'orphan')===undefined,'aborted Blob cut leaked head or file bytes');
+  // 释放并重建适配器，检查 Blob 与同批文件在新 owner 下仍能恢复。
   await leader.release();storage.close();storage=createBrowserStorage({name,checkpointEvery:1});leader=await storage.claim(scope);assert(JSON.stringify(await storage.recover(leader))===JSON.stringify(first),'fresh adapter lost Blob content');assert(await(await storage.readFile(leader,'kept')).text()==='kept bytes','Blob reopening lost atomic file');
+  // 大切点准备期间释放 owner，完成结果必须是 storage_leader_lost；重新 claim 后不得看到新切点或晚到文件。
   const large=sealRecoveryImage(1,2,2,{rows:Array.from({length:16000},(_,i)=>({id:i,text:'x'.repeat(100)}))});let failure;const pending=storage.commit(leader,{image:large,files:[{id:'late',bytes:new Blob(['late'])}]}).catch(error=>{failure=error.code;});await Promise.resolve();await leader.release();await pending;assert(failure==='storage_leader_lost','released owner published or changed its cancellation error');leader=await storage.claim(scope);assert((await storage.recover(leader)).rootRevision===1&&await storage.readFile(leader,'late')===undefined,'released owner advanced Blob checkpoint');
+ // 关闭原始连接、释放 owner 和 adapter，再发起删除数据库；这里不等待删除完成事件。
  }finally{raw?.close();await leader?.release();storage.close();indexedDB.deleteDatabase(name);}
 }
 
+// 保持旧 DB 连接打开以阻挡升级；同一失败 adapter 保留原错误，旧连接退场后需新 adapter 才能成功。
 export async function blockedUpgradeCase(assert){
+ // 本场景只需一个仍打开的 v4 数据库，不依赖上一个升级场景留下的数据。
  const name=`blocked-upgrade-${crypto.randomUUID()}`,scope={accountId:'a',workspaceId:'w',projectId:'p'},read=req=>new Promise((resolve,reject)=>{req.onsuccess=()=>resolve(req.result);req.onerror=()=>reject(req.error);});let raw=await read(indexedDB.open(name,4)),storage=createBrowserStorage({name}),leader;
+ // 重复 claim 都应报告 storage_upgrade_blocked；丢弃的升级请求不能在稍后悄悄升级，关旧连接并新建 adapter 后才升到 5。
  try{let code;try{await storage.claim(scope);}catch(error){code=error.code;}assert(code==='storage_upgrade_blocked','active old connection did not reject the upgrade');code=undefined;try{await storage.claim(scope);}catch(error){code=error.code;}assert(code==='storage_upgrade_blocked','blocked adapter lost the original failure reason');raw.close();raw=await read(indexedDB.open(name));assert(raw.version===4,'abandoned upgrade changed database version after rejection');raw.close();storage.close();storage=createBrowserStorage({name});leader=await storage.claim(scope);assert(await storage.recover(leader)===null,'fresh adapter could not open after blocked request was retired');raw=await read(indexedDB.open(name));assert(raw.version===5,'fresh upgrade failed after abandoned open');}
  finally{raw?.close();await leader?.release();storage.close();indexedDB.deleteDatabase(name);}
 }

tests/headless/browser-storage.mjs

@@ -1,4 +1,8 @@
-/** Real Chromium IndexedDB/Web Locks checks, in an isolated temporary browser profile. */
+/**
+ * 使用隔离 Chrome profile 运行真实 IndexedDB/Web Locks 场景，或以 --package 消费构建后的浏览器 ESM。
+ * 本地 HTTP server 只提供测试页面、源码/发布文件和可控 NDJSON 流；普通模式通过 Node 去除 .ts 类型，不运行应用 bundler。
+ * 此入口内联了一套简化 CDP 请求表，未使用 cdp-client 的连接级超时/故障保护，不能把 Runtime.evaluate 的 timeout 当作所有命令的截止时间。
+ */
 import { createServer } from 'node:http';
 import { readFile, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -7,18 +11,24 @@ import { spawn } from 'node:child_process';
 import { stripTypeScriptTypes } from 'node:module';
 import { setTimeout as pause } from 'node:timers/promises';
 
+// 从脚本位置定位仓库，随机临时 profile 保证测试不读写日常 Chrome 会话。
 const root = resolve(import.meta.dirname, '../..'), profile = await mkdtemp(join(tmpdir(), 'endoleap-storage-browser-'));
+// --package 只影响发布文件服务和页面导入入口；它不会在这里自动构建 .headless-dist。
 const packageMode=process.argv.includes('--package');
+// 按 key 保留挂起的响应与读取次数，供页面测试控制共享读取的首块、尾块和失败尾部。
 const readStreams=new Map();
+// 只在回环地址提供 fixture；源码读取或类型去除失败时返回 500 供页面检查报告。
 const server = createServer(async (request, response) => {
   try {
     const path = new URL(request.url, 'http://localhost').pathname;
+    // 同一 key 每次读取计数增加，立即发送第一行并保持连接；由独立 release 请求决定何时结束。
     if(path==='/loader-stream'){
       const url=new URL(request.url,'http://localhost'),key=url.searchParams.get('key');
       if(!key){response.writeHead(400).end();return;}
       const state=readStreams.get(key)??{reads:0};state.reads++;state.response=response;readStreams.set(key,state);
       response.writeHead(200,{'Content-Type':'application/x-ndjson'});response.write(JSON.stringify({part:0,complete:false})+'\n');return;
     }
+    // 查找挂起流，可发送合法完成行或非法 JSON 尾部；返回读次数用于核对共享加载没有重复 fetch。
     if(path==='/loader-release'){
       const url=new URL(request.url,'http://localhost'),state=readStreams.get(url.searchParams.get('key'));
       if(!state){response.writeHead(404).end();return;}
@@ -26,30 +36,39 @@ const server = createServer(async (request, response) => {
       response.setHeader('Content-Type','application/json');response.end(JSON.stringify({reads:state.reads}));return;
     }
     if (path === '/') { response.setHeader('Content-Type', 'text/html'); response.end('<title>Headless storage checks</title>'); return; }
+    // 包模式从 .headless-dist 读取，其余只允许 src/lib 和 tests/headless；resolve 后再检查目录前缀。
     const isPackage=packageMode&&path.startsWith('/package/');
     const filename = isPackage?resolve(root,'.headless-dist',path.slice('/package/'.length)):resolve(root, `.${path}`);
     if (!(isPackage&&filename.startsWith(`${root}/.headless-dist/`)) && !filename.startsWith(`${root}/src/lib/`) && !filename.startsWith(`${root}/tests/headless/`)) { response.writeHead(404).end(); return; }
+    // 仅对 .ts 去除类型后提供 JavaScript；.mjs 和编译包文件保持读取内容，不进行应用级转换。
     let source = await readFile(filename, 'utf8');
     if (filename.endsWith('.ts')) source = stripTypeScriptTypes(source);
     response.setHeader('Content-Type', 'text/javascript'); response.end(source);
   } catch (error) { response.writeHead(500).end(String(error)); }
 });
+// 先绑定随机本地端口，再用独立 profile 启动 headless Chrome；CHROME_BIN 可覆盖默认安装路径。
 await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
 const chrome = spawn(process.env.CHROME_BIN ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', ['--headless=new', '--no-first-run', '--disable-background-networking', '--disable-component-update', '--remote-debugging-port=0', `--user-data-dir=${profile}`, `http://127.0.0.1:${server.address().port}/`], { stdio: 'ignore' });
 let socket;
 try {
+  // 最多轮询 100 次 DevToolsActivePort，每次间隔 100 毫秒；未找到端口即失败，不连接用户现有浏览器。
   let port;
   for (let attempt = 0; attempt < 100; attempt++) {
     try { port = Number((await readFile(join(profile, 'DevToolsActivePort'), 'utf8')).split('\n')[0]); break; } catch { await pause(100); }
   }
   if (!port) throw new Error('isolated Chromium did not start');
+  // 从本次 Chrome 的调试服务查找 page，建立 WebSocket 后才发送 CDP 命令。
   const tabs = await fetch(`http://127.0.0.1:${port}/json/list`).then(response => response.json());
   socket = new WebSocket(tabs.find(tab => tab.type === 'page').webSocketDebuggerUrl);
   await new Promise((resolve, reject) => { socket.onopen = resolve; socket.onerror = reject; });
+  // pending 仅按 ID 路由 Promise；这里没有每条命令的本地截止定时器。
   let next = 0; const pending = new Map();
+  // 只处理带 ID 的响应，协议错误拒绝相应 Promise；没有转发无 ID 事件或整连接失败处理。
   socket.onmessage = event => { const message = JSON.parse(event.data); if (message.id) { const callbacks = pending.get(message.id); pending.delete(message.id); if (message.error) callbacks.reject(new Error(JSON.stringify(message.error))); else callbacks.resolve(message.result); } };
+  // 登记递增 ID 后发送命令，等待对应响应；其行为不同于独立 createCdpCalls 的有界调用器。
   const call = (method, params) => new Promise((resolve, reject) => { const id = ++next; pending.set(id, { resolve, reject }); socket.send(JSON.stringify({ id, method, params })); });
   const origin = `http://127.0.0.1:${server.address().port}`;
+  // 导航到本次 fixture origin，随后最多 100 次检查页面 origin 与 readyState，避免误在空白页执行。
   await call('Page.navigate', { url: `${origin}/` });
   let loaded = false;
   for (let attempt = 0; attempt < 100; attempt++) {
@@ -58,10 +77,13 @@ try {
     await pause(50);
   }
   if (!loaded) throw new Error('browser test origin did not finish loading');
+  // 页面动态导入普通存储场景或编译包场景并等待 run；30 秒 timeout 是该 evaluate 的协议参数。
   const result = await call('Runtime.evaluate', { expression: `import('/tests/headless/${packageMode?'package-browser-cases':'browser-storage-cases'}.mjs').then(module => module.run())`, awaitPromise: true, returnByValue: true, timeout: 30000 });
+  // 页面异常直接使 runner 失败，只有成功返回的场景消息才逐条打印 PASS。
   if (result.exceptionDetails) throw new Error(result.exceptionDetails.exception?.description ?? result.exceptionDetails.text);
   for (const message of result.result.value) console.log(`PASS ${message}`);
 } finally {
+  // 清理连接并请求 Chrome 退出，等待进程 exit 后再关闭 HTTP server 和删除 profile；此等待没有额外强杀截止时间。
   socket?.close();
   const exited = new Promise(resolve => { if (chrome.exitCode !== null) resolve(); else chrome.once('exit', resolve); });
   chrome.kill(); await exited;

tests/headless/cdp-client.mjs

@@ -1,19 +1,32 @@
-/** Bounded protocol calls for isolated browser fixtures, never product code. */
+/**
+ * 隔离浏览器 fixture 专用的有界 CDP 请求路由器，不作为产品运行时代码。
+ * 每个正整数 ID 对应一个 Promise 和截止定时器；连接/目标级故障是整个实例的终态。
+ * 本函数不负责建立或关闭 socket，也不提供独立 dispose；外层 runner 持有连接。
+ */
+// 接收已连接 socket 和可替换定时器；默认给每个调用设置 30 秒截止定时器，事件由 onEvent 转发。
 export function createCdpCalls(socket,{timeoutMs=30000,onEvent=()=>{},setTimer=setTimeout,clearTimer=clearTimeout}={}){
+ // pending 是未回应调用的唯一查找表；failure 保留首个致命错误，使未来调用立刻拒绝。
  let serial=0,failure;const pending=new Map();
+ // 全局失败清除每个截止定时器并拒绝所有 Promise；重复故障不覆盖最初原因。
  const fail=error=>{failure??=error;for(const row of pending.values()){clearTimer(row.timer);row.reject(failure);}pending.clear();};
+ // 连接关闭和传输错误都不再允许继续发命令。
  socket.addEventListener('close',()=>fail(Error('CDP connection closed')));
  socket.addEventListener('error',()=>fail(Error('CDP connection failed')));
+ // 收到消息先解析 JSON；解析或事件回调异常同样会进入全局失败。
  socket.addEventListener('message',event=>{
   try{
    const message=JSON.parse(event.data);
+   // 无请求 ID 的消息是事件；先通知观察者，再把崩溃、脱离或对话框视为目标不可继续使用。
    if(!message.id){onEvent(message);if(['Inspector.targetCrashed','Inspector.detached','Target.targetCrashed','Page.javascriptDialogOpening'].includes(message.method))fail(Error('CDP target unavailable: '+message.method+' '+JSON.stringify(message.params??{})));return;}
+   // 已超时/完成的响应无对应 row 时忽略；普通协议 error 只拒绝该请求，不使整个连接失效。
    const row=pending.get(message.id);if(!row)return;pending.delete(message.id);clearTimer(row.timer);message.error?row.reject(Error(JSON.stringify(message.error))):row.resolve(message.result);
   }catch(error){fail(error);}
  });
+ // 为新命令分配递增 ID，先登记 pending 与定时器再发送；send 同步抛错也会拒绝全部在途工作。
  return(method,params={})=>new Promise((resolve,reject)=>{
   if(failure){reject(failure);return;}
   const id=++serial,row={resolve,reject,timer:undefined};pending.set(id,row);
+  // 任意一个调用超时都使整个调用器失败，避免测试随后无限挂在另一个依赖命令。
   row.timer=setTimer(()=>fail(Error(`CDP ${method} timed out after ${timeoutMs}ms`)),timeoutMs);
   try{socket.send(JSON.stringify({id,method,params}));}catch(error){fail(error);}
  });

tests/headless/cdp-client.test.mjs

@@ -1,8 +1,17 @@
+/**
+ * 浏览器测试专用 CDP 调用器的单元测试。用 socket/定时器替身验证请求 ID 路由、截止时间及致命故障，不启动浏览器。
+ * 单个协议命令错误只拒绝对应请求；连接或目标级故障则拒绝整个调用器及未来调用。
+ */
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
 import {createCdpCalls} from './cdp-client.mjs';
+// 把 socket 事件、已发送命令和定时器保存在 Map/数组，测试可直接投递乱序响应或手动触发超时。
 function fixture(){const handlers=new Map(),sent=[],timers=new Map();let id=0;const socket={addEventListener:(event,callback)=>handlers.set(event,callback),send:text=>sent.push(JSON.parse(text))},events=[],call=createCdpCalls(socket,{timeoutMs:30,onEvent:event=>events.push(event),setTimer:callback=>{timers.set(++id,callback);return id;},clearTimer:key=>timers.delete(key)});return{call,sent,timers,events,event:(name,data)=>handlers.get(name)({data:JSON.stringify(data)})};}
+// 两个响应反序返回仍按 ID 完成各自 Promise；无 ID 事件交给 onEvent，成功响应清除对应定时器。
 test('CDP responses route by request ID, forward events and release deadline timers',async()=>{const f=fixture(),one=f.call('one'),two=f.call('two');f.event('message',{method:'Runtime.event'});f.event('message',{id:2,result:{value:'two'}});f.event('message',{id:1,result:{value:'one'}});assert.deepEqual(await one,{value:'one'});assert.deepEqual(await two,{value:'two'});assert.equal(f.events.length,1);assert.equal(f.timers.size,0);});
+// 一个调用超时即终止全部 pending 和未来调用；迟到响应被忽略，不产生额外报告读取来掩盖超时。
 test('a stalled CDP call rejects all pending work and cannot hide behind another unbounded report read',async()=>{const f=fixture(),one=assert.rejects(f.call('Runtime.evaluate'),/timed out/),two=assert.rejects(f.call('Page.captureScreenshot'),/timed out/);[...f.timers.values()][0]();await Promise.all([one,two]);assert.equal(f.timers.size,0);f.event('message',{id:1,result:{late:true}});await assert.rejects(f.call('Runtime.evaluate'),/timed out/);});
+// 分别注入连接关闭、错误、目标崩溃、脱离和对话框事件；所有情况清空 pending，调用器不会自动接受对话框。
 test('connection loss and fatal target events reject pending calls without accepting dialogs',async()=>{for(const event of ['close','error','Inspector.targetCrashed','Target.targetCrashed','Inspector.detached','Page.javascriptDialogOpening']){const f=fixture(),result=assert.rejects(f.call('Runtime.evaluate'),/CDP/);event.includes('.')?f.event('message',{method:event}):f.event(event);await result;assert.equal(f.timers.size,0);assert.deepEqual(f.sent.map(row=>row.method),['Runtime.evaluate']);}});
+// 普通命令错误只拒绝它自己，另一命令仍可成功且两者都清除定时器。
 test('one protocol command error does not corrupt another request or leak its timer',async()=>{const f=fixture(),one=assert.rejects(f.call('bad'),/invalid/),two=f.call('good');f.event('message',{id:1,error:{message:'invalid'}});f.event('message',{id:2,result:{ok:true}});await one;assert.deepEqual(await two,{ok:true});assert.equal(f.timers.size,0);});

tests/headless/pointer-capture.test.mjs

@@ -1,4 +1,10 @@
+/**
+ * 指针捕获辅助函数的对象替身测试，不分派真实 DOM PointerEvent。
+ * 指针 ID 与捕获目标共同决定归属，旧 lostpointercapture 不能取消新目标或重新捕获后的手势。
+ */
 import {test} from 'node:test';import assert from 'node:assert/strict';
 import {ownsPointerCapture,acquirePointerCapture,releasePointerCapture} from '../../src/lib/canvas-bindings/pointer-capture.ts';
+// move/up/cancel 检查 pointerId；lostpointercapture 还检查事件 target 与当前捕获状态，空 owner 不匹配。
 test('pointer move/up/cancel only match their owner and old lost-capture cannot cancel a replacement target',()=>{const capture={},other={},owner={pointerId:7,capture};for(const type of ['pointermove','pointerup','pointercancel']){assert.equal(ownsPointerCapture(owner,{pointerId:8,type}),false);assert.equal(ownsPointerCapture(owner,{pointerId:7,type}),true);}assert.equal(ownsPointerCapture(owner,{pointerId:7,type:'lostpointercapture',target:other}),false);assert.equal(ownsPointerCapture(owner,{pointerId:7,type:'lostpointercapture',target:capture}),true);assert.equal(ownsPointerCapture(null,{pointerId:7}),false);const recaptured={hasPointerCapture:()=>true};assert.equal(ownsPointerCapture({pointerId:7,capture:recaptured},{pointerId:7,type:'lostpointercapture',target:recaptured}),false);});
+// 成功捕获只释放一次；节点脱离导致的 set/hasPointerCapture 异常作为捕获失败或安全清理处理，不升级为业务错误。
 test('failed capture and detached release stay transport failures, while a held capture releases once',()=>{let held=false,releases=0;const target={setPointerCapture(){held=true;},hasPointerCapture(){return held;},releasePointerCapture(){held=false;releases++;}};assert.equal(acquirePointerCapture(target,1),true);releasePointerCapture(target,1);releasePointerCapture(target,1);assert.equal(releases,1);assert.equal(acquirePointerCapture({...target,setPointerCapture(){throw Error('detached');}},2),false);assert.doesNotThrow(()=>releasePointerCapture({...target,hasPointerCapture(){throw Error('detached');}},2));});

tests/headless/react-hooks-fixture.tsx

@@ -1,3 +1,8 @@
+/**
+ * 供真实浏览器页面调用的 React hooks 场景。组件挂在隐藏容器中，在 StrictMode 下检查订阅路由、手势租约和资源句柄。
+ * engine 与 hooks 使用生产实现，存储、上传和文档服务为内存替身；此处不验证远程授权、数据库或图片解码。
+ * 断言通过页面全局入口返回文字报告，由外层浏览器 runner 收集；不会在组件导入时自动运行全部场景。
+ */
 "use client";
 import {StrictMode,memo,useEffect,useLayoutEffect} from 'react';
 import {createRoot} from 'react-dom/client';import {flushSync} from 'react-dom';
@@ -5,54 +10,93 @@ import {CanvasProvider,useCanvas,useElement,useActions,useMode,useGestureBinding
 import {createRegistry,builtinComponents,createDocument,applyChanges} from '@/lib/canvas-core/index';
 import {openProjectEngine} from '@/lib/canvas-runtime/engine';
 import {equal} from '@/lib/canvas-core/values';
+// 浏览器断言失败直接抛错，使外层 Runtime.evaluate 得到失败；不把失败写成通过报告。
 const assert=(value:unknown,message:string)=>{if(!value)throw Error(message);};
+// 短暂等待浏览器计时器；until 最多轮询 1000 次，观察 React effect/订阅结果，而非假设 flush 后同步可读。
 const tick=()=>new Promise(resolve=>setTimeout(resolve,5));async function until(check:()=>boolean){for(let i=0;i<1000;i++){if(check())return;await tick();}throw Error('hook observation timed out');}
+// 装配两个节点和两个 view；partial 模式只发布 a，但完整来源仍含 b，供 unloaded→present/absent 检查。
 async function fixture(partial=false){
+ // 合法文本节点外壳；版本、身份和 owner 固定，序列号另用于命令/请求 ID。
  const node=(id:string)=>({id,incarnation:1,structure:'node' as const,componentId:'text',dataVersion:1,ownerCanvasId:'canvas',geometry:{x:0,y:0,width:100,height:80,rotation:0},data:{title:id,text:''}});let server=createDocument(partial?'canvas':'hooks',[{id:'canvas',parent:null}],[node('a'),node('b')]),version=1,serial=0,image:any=null,fail=false,readGate:Promise<void>|undefined;
+ // 分别保存本地 Blob、文档回执及异步错误，read 次数用于验证资源 hooks 共享读取。
  const files=new Map<string,Blob>(),receipts=new Map(),errors:unknown[]=[];let reads=0;
+ // 内存存储可注入 quota，readFile 可被 Promise 屏障延迟；不实现真实浏览器锁或 IndexedDB。
  const storage={async claim(scope:any){return{scope,fence:1,active:true,async release(){this.active=false;}};},async recover(){return image;},async commit(_leader:any,batch:any){if(fail)throw Error('quota');for(const file of batch.files??[])files.set(file.id,file.bytes);image=structuredClone(batch.image);return{durableRootRevision:image.rootRevision};},async readFile(_leader:any,id:string){reads++;if(readGate)await readGate;return files.get(id);},close(){}};
+ // 上传替身返回固定 2×1 元数据与资源 URL，不验证图片字节；查询保持 unresolved，accept 直接取 canonical。
  const assets={sourceURL:(id:string)=>`https://assets.test/${id}`,displayURL:(id:string)=>`/assets/${id}`,async upload(request:any,bytes:Blob){const payload=JSON.parse(request.body);return{outcome:'applied' as const,canonical:{id:payload.resource_id,url:assets.sourceURL(payload.resource_id),bytes:bytes.size,mime_type:bytes.type,width:2,height:1}};},async query(){return{outcome:'unresolved' as const};},accept:(_request:any,status:any)=>status.canonical};
+ // 文档替身应用真实 changes 并递增版本，把成功模型放在回执表；不实现真实 HTTP 或请求去重。
  const persistence={compile(intent:any,id:string,snapshot:any){return{payload:{intent},canvasIds:intent.canvasIds,expectedVersions:{canvas:snapshot.runtime.versions.get('canvas')}};},async submit(request:any){server=applyChanges(server,JSON.parse(request.body).intent.changes);receipts.set(request.id,{document:server,versions:new Map([['canvas',++version]])});return{outcome:'applied' as const};},async query(){return{outcome:'unresolved' as const};},canonical:(request:any)=>receipts.get(request.id)};
+ // 装配真实引擎与 loading 状态，显式 attach v/w 后等待本地初始工作收敛。
  const engine=await openProjectEngine({scope:{accountId:'a',workspaceId:'w',projectId:partial?'canvas':'hooks'},document:partial?createDocument('canvas',[{id:'canvas',parent:null}],[node('a')]):server,...(partial?{loading:{version:1 as const,sourceToken:'hook-partial',declaredCanvasIds:['canvas'],receivedElements:1,totalElements:2}}:{}),versions:new Map([['canvas',1]]),registry:createRegistry(builtinComponents()),storage,assets,persistence,createId:()=>`hook-${++serial}`,onError:error=>errors.push(error)});const detachA=engine.sessions.attach('v','canvas'),detachB=engine.sessions.attach('w','canvas');await engine.settle();
+ // 向场景暴露保存故障、读取屏障与读次数；detach 只清理 fixture 自己附加的两个会话。
  return{engine,node,files,errors,full:server,get reads(){return reads;},fail(value:boolean){fail=value;},gate(value?:Promise<void>){readGate=value;},detach(){detachA();detachB();}};
 }
+// 创建隐藏 React root 并串行运行场景；保留组件读到的最新 hook 结果和渲染/选择器计数供断言。
 async function run(){
  const f=await fixture(),engine=f.engine,container=document.createElement('div');container.style.display='none';document.body.append(container);const root=createRoot(container),reports:string[]=[],counts={title:0,element:0,mode:0,gesture:0,titleOnly:0};let titleOnly:unknown,titleSelections=0;let title:any,element:any,actions:any,mode:any,gesture:any,operation:any,status:any,assetA:any,assetB:any;
+ // 全局选择器只提取 a 的标题，equal 比较结果对象，检查无关 Root 发布不引发重渲染。
  const Title=memo(function Title(){title=useCanvas(snapshot=>({title:snapshot.document.elements.get('a')?.data.title}),equal);counts.title++;return null;});
+ // 完整元素 hook 固定到 a 的第一代身份，稍后用于验证删除恢复后状态变为 stale。
  const Element=memo(function Element(){element=useElement({id:'a',incarnation:1});counts.element++;return null;});
+ // 计数元素选择器实际执行次数，区分“跳过无关目标”与“目标变化但结果相等不渲染”。
  const selectTitle=(view:ElementView)=>{titleSelections++;return view.status==='present'?view.element.data.title:view.status;};
+ // 只订阅目标标题字段；同元素其他字段变化允许重新选择，但不能增加组件渲染次数。
  const ElementTitle=memo(function ElementTitle(){titleOnly=useElement({id:'a',incarnation:1},selectTitle);counts.titleOnly++;return null;});
+ // 捕获绑定到目标身份的命令 facade，检查稳定引用、历史选项和过期身份拒绝。
  const Actions=memo(function Actions(){actions=useActions({id:'a',incarnation:1});return null;});
+ // 观察 v 视图的 mode，另一个 view 的 mode 更新不能使它重渲染。
  const Mode=memo(function Mode(){mode=useMode({id:'a',incarnation:1});counts.mode++;return null;});
+ // 捕获目标绑定手势控制器；beginOnLayout 在替换目标的 layout effect 中立即开启新手势，以暴露旧 cleanup 误取消问题。
  const Gesture=memo(function Gesture({targetId='a',beginOnLayout=false}:{targetId?:string;beginOnLayout?:boolean}){const binding=useGestureBindings({id:targetId,incarnation:1});gesture=binding;counts.gesture++;useLayoutEffect(()=>{if(beginOnLayout){assert(binding.begin().enabled,'replacement gesture did not begin');assert(binding.update({x:88}).enabled,'replacement gesture did not preview');}},[targetId,beginOnLayout]);return null;});
+ // 按逻辑操作 ID 观察操作及其请求；最初 missing 应没有记录，rename 后改绑真实 ID。
  const Operation=memo(function Operation({id}:{id:string}){operation=useOperation(id);return null;});
+ // 独立观察同步、持久化错误和关闭状态，不靠业务文档再次变化触发观察。
  const Status=memo(function Status(){status=useSyncStatus();return null;});
+ // 两个 slot 可同时借用同一资源，分别保存 hook 结果以检查共享 URL 及引用计数释放。
  const Asset=memo(function Asset({id,slot}:{id:string;slot:'a'|'b'}){const value=useAsset(id);if(slot==='a')assetA=value;else assetB=value;return null;});
+ // 每次以 StrictMode 和 CanvasProvider 同步替换子树；owner 可替换成另一个 engine，随后等待 effects。
  const render=async(children:any,owner=engine)=>{flushSync(()=>root.render(<StrictMode><CanvasProvider engine={owner} viewId="v">{children}</CanvasProvider></StrictMode>));await tick();};
  try{
+  // 先等 synced 再记录动态基线；StrictMode 可能重复渲染，因此断言增量而非写死初始次数。
   await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture/><Operation id="missing"/><Status/></>);await until(()=>status?.status==='synced');const baseline={...counts},originalActions=actions,initialTitleSelections=titleSelections;
+  // 改无关 b：窄订阅计数和 action 引用不变，元素标题选择器也不执行。
   engine.editor.dispatch({type:'element.data',target:{id:'b',incarnation:1},patch:{title:'unrelated'}});await engine.settle();await tick();assert(equal(baseline,counts),'unrelated element/ACK rerendered narrow hooks');assert(actions===originalActions,'action facade identity drifted');assert(titleSelections===initialTitleSelections,'unrelated edit/ACK evaluated the element selector');
+  // 改 a 的 text 会执行其标题选择器，但标题没变时不得重渲染 ElementTitle。
   const titleRenders=counts.titleOnly;engine.editor.dispatch({type:'element.data',target:{id:'a',incarnation:1},patch:{text:'other field'}});await engine.settle();await tick();assert(titleSelections>initialTitleSelections&&counts.titleOnly===titleRenders&&titleOnly==='a','field selector did not isolate title from another field on the same target');reports.push('element ID routing skips unrelated selector evaluation; field selectors observe their target without rerendering for other fields');
+  // 经 actions.rename 验证命令历史 label/groupId、canonical 观察及 operation/request 状态。
   const renamed=actions.rename('renamed',{label:'Hook rename',groupId:'hook-rename'});await engine.settle();const renamedHistory=engine.getSnapshot().history.entries.get(engine.getSnapshot().history.undo.at(-1)!);assert(renamedHistory?.label==='Hook rename'&&renamedHistory.groupId==='hook-rename','action facade dropped command history options');await until(()=>title.title==='renamed'&&titleOnly==='renamed');assert(element.status==='present'&&element.element.data.title==='renamed','element did not observe canonical rename');await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture/><Operation id={renamed.operationIds[0]}/><Status/></>);assert(operation?.operation.phase==='resolved'&&operation.request?.phase==='resolved','operation hook did not include its request');reports.push('selectors suppress unrelated element and ACK renders; bound actions share validated history/ledger and operation/request observation');
+  // 手势预览只改变交互状态，不改业务几何、revision 或 history；取消不留撤销记录，mode 仍按 view 隔离。
   const history=engine.getSnapshot().history.undo.length,revision=engine.getSnapshot().revision;assert(gesture.begin().enabled&&gesture.update({x:42}).enabled,'gesture did not acquire/update');await until(()=>gesture.active&&gesture.geometry.x===42);assert(engine.getSnapshot().document.elements.get('a')!.structure==='node'&&(engine.getSnapshot().document.elements.get('a') as any).geometry.x===0,'preview mutated committed geometry');assert(engine.getSnapshot().revision===revision,'preview created an edit');gesture.cancel();await until(()=>!gesture.active);assert(engine.getSnapshot().history.undo.length===history,'canceled preview changed history');assert(mode.setMode('editing').enabled,'view mode rejected');await until(()=>mode.mode==='editing');const modeRenders=counts.mode;engine.sessions.mode('w','a','resize');await tick();assert(counts.mode===modeRenders,'another view changed this view mode');
+  // 第二次手势提交只新增一个历史单元，租约释放后旧 commit 不再可写。
   assert(gesture.begin().enabled,'second gesture did not acquire');gesture.update({x:55});assert(gesture.commit().status==='applied','gesture did not commit');await engine.settle();assert(engine.getSnapshot().history.undo.length===history+1,'gesture did not create exactly one history entry');assert(gesture.commit().status==='rejected','released gesture lease remained writable');reports.push('gesture preview/cancel/commit owns a token and one history unit; modes stay scoped to their view');
+  // 切换 hook 目标后立即在 layout effect 开新租约；旧控制器的 cancel/commit 和 cleanup 都不能碰新目标。
   const previousGesture=gesture,beforeOwnerSwap=engine.getSnapshot();await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture targetId="b" beginOnLayout/><Operation id={renamed.operationIds[0]}/><Status/></>);const replacementToken=engine.sessions.getSnapshot().gesture?.token;assert(!!replacementToken&&engine.sessions.getSnapshot().gesture?.targets[0].id==='b','old target cleanup canceled the new layout gesture');assert(previousGesture.commit().status==='rejected','old controls committed the replacement gesture');previousGesture.cancel();assert(engine.sessions.getSnapshot().gesture?.token===replacementToken,'old controls canceled the replacement gesture');assert(engine.getSnapshot()===beforeOwnerSwap,'owner switch or obsolete callback published document/history work');gesture.cancel();await render(<><Title/><Element/><ElementTitle/><Actions/><Mode/><Gesture/><Operation id={renamed.operationIds[0]}/><Status/></>);reports.push('gesture controller replacement owns an independent lease; old cleanup, cancel and commit cannot touch a new target gesture');
 
+  // 先检查只有 durability 完成也能清除 dirty，再注入 quota 验证 blocked/dirty，重试成功才恢复 synced。
   engine.editor.updateRuntime(previous=>({...previous}));await engine.persist();await tick();await until(()=>status.status==='synced'&&!status.dirty);assert(!status.dirty,'durable-only metadata completion was not observable');f.fail(true);actions.rename('unsaved');await until(()=>status.status==='blocked'&&status.error==='quota');assert(status.dirty,'failed persistence appeared durable');f.fail(false);await engine.retry();await engine.settle();await until(()=>status.status==='synced'&&!status.dirty);reports.push('sync status observes durable-only completion and quota failure/retry without claiming in-memory edits are synced');
+  // 暂存任意图片类型字节只用于资源引用测试；不是 PNG 解码验证。
   let resource='';engine.stageFiles([{name:'image.png',bytes:new Blob(['image bytes'],{type:'image/png'})}],([ref],tx)=>{resource=ref.id;tx.dispatch({type:'element.create',element:{...f.node('image'),componentId:'image',data:{title:'image',text:'',assetId:ref.id,src:ref.src}}});});await engine.settle();const reads=f.reads;
+  // 两个 hooks 必须共用一次读取和一个 URL；移除一个不影响另一个，最后一个卸载后 URL 才失效。
   await render(<><Asset id={resource} slot="a"/><Asset id={resource} slot="b"/><Status/></>);await until(()=>assetA?.status==='ready'&&assetB?.status==='ready');assert(assetA.url===assetB.url&&f.reads===reads+1,'two resource hooks did not share one display read/URL');const url=assetA.url;assert(await(await fetch(url)).text()==='image bytes','asset hook did not expose original bytes');await render(<><Asset id={resource} slot="a"/><Status/></>);assert(await(await fetch(url)).text()==='image bytes','unmounting one reader revoked the other');await render(<Status/>);let revoked=false;try{await fetch(url);}catch{revoked=true;}assert(revoked,'last resource reader did not release its URL');reports.push('resource hooks share a URL, retain remaining readers and release the last handle on unmount');
+  // 读取尚未返回时卸载 hook，随后才放行；迟到资源结果应释放显示 pin，不能泄漏借用。
   let release!:()=>void;f.gate(new Promise<void>(resolve=>release=resolve));const before=f.reads;await render(<><Asset id={resource} slot="a"/><Status/></>);await until(()=>f.reads>before);await render(<Status/>);release();f.gate();await tick();assert(!engine.getResourcePins().pins.get(resource)?.has('display'),'late resource load leaked a display pin');
+  // 删除并撤销恢复元素后 incarnation 已变化；旧 facade 必须拒绝写入，不能自动改绑同 ID 的新对象。
   await render(<><Element/><Actions/><Gesture/><Status/></>);const staleActions=actions;engine.editor.dispatch({type:'element.remove',target:{id:'a',incarnation:1}});await engine.settle();engine.editor.history.undo();await engine.settle();await until(()=>element.status==='stale');const snapshot=engine.getSnapshot();assert(staleActions.rename('stale').status==='rejected'&&engine.getSnapshot()===snapshot,'old incarnation facade edited a restored element');reports.push('late resource loads release their pins and stale action targets cannot retarget restored incarnations');
+  // 关闭 engine 时 mounted hooks 也要观察到 closed/error 并释放资源。
   await render(<><Asset id={resource} slot="a"/><Status/></>);await until(()=>assetA.status==='ready');await engine.close();await until(()=>status.status==='closed'&&assetA.status==='error');reports.push('engine close is observable and releases mounted resource handles without owning a second project');
+  // 换 Provider 所属引擎后，资源字节和命令目标都必须来自新 owner，不能修改旧引擎快照。
   const other=await fixture();try{
     let otherResource='';other.engine.stageFiles([{name:'other.png',bytes:new Blob(['other identity bytes'],{type:'image/png'})}],([ref],tx)=>{otherResource=ref.id;tx.dispatch({type:'element.create',element:{...other.node('other-image'),componentId:'image',data:{title:'other',text:'',assetId:ref.id,src:ref.src}}});});await other.engine.settle();
     const oldSnapshot=engine.getSnapshot();await render(<><Asset id={otherResource} slot="a"/><Actions/><Status/></>,other.engine);await until(()=>assetA.status==='ready');assert(await(await fetch(assetA.url)).text()==='other identity bytes','Provider change reused another engine resource handle');assert(actions.rename('second owner').status==='applied','new owner action did not dispatch');await other.engine.settle();assert(other.engine.getSnapshot().document.elements.get('a')!.data.title==='second owner'&&engine.getSnapshot()===oldSnapshot,'Provider change routed commands to the old owner');reports.push('Provider owner changes replace resource handles and action targets without writing to the previous engine');
   }finally{await other.engine.close();}
+  // 部分来源完成前 b 和未知 ID 都是 unloaded；loading.complete 后才能分别判断 present 与 absent。
   const partial=await fixture(true);try{
     let b:any,missing:any;function Lookup(){b=useElement('b');missing=useElement('not-in-source');return null;}
     await render(<><Lookup/><Status/></>,partial.engine);assert(b.status==='unloaded'&&missing.status==='unloaded','partial lookup guessed absence');const completed=await partial.engine.loading.complete(partial.full,new Map([['canvas',1]]),{sourceToken:'hook-partial'});assert(completed.status==='applied','hook partial fixture did not complete');await partial.engine.settle();await until(()=>b.status==='present'&&missing.status==='absent');reports.push('element hooks preserve unloaded versus absent until source completion and then expose the newly loaded element');
   }finally{await partial.engine.close();}
+  // 只有所有场景通过才返回报告；finally 卸载 root、移除隐藏容器、恢复故障开关并清理 fixture。
   return reports;
  }finally{flushSync(()=>root.unmount());container.remove();f.fail(false);f.detach();await engine.close();}
 }
+// effect 仅注册页面测试入口；清理时先比较函数身份，防止旧挂载删除新实例注册的入口。
 export function HookChecks(){useEffect(()=>{const host=globalThis as typeof globalThis&{__runCanvasHookChecks?:()=>ReturnType<typeof run>};host.__runCanvasHookChecks=run;return()=>{if(host.__runCanvasHookChecks===run)delete host.__runCanvasHookChecks;};},[]);return null;}

tests/headless/renderer-extension.tsx

@@ -1,3 +1,7 @@
+/**
+ * 浏览器渲染集成专用插件：模型定义与 ReactFlow renderer 一起通过 CanvasRuntimeExtension 注入。
+ * 页面全局计数和 editing facade 仅用于测试观察，数据编辑仍经过生产命令/事务入口。
+ */
 "use client";
 import {useScopedNodeEditing} from '@/components/canvas/node-editing';
 import { Handle, Position, BaseEdge, getBezierPath, type NodeProps, type EdgeProps } from '@xyflow/react';
@@ -5,15 +9,20 @@ import { defineComponent, editable, movable } from '@/lib/canvas-core/index';
 import type {ReactFlowProjectionNode as ProjectionNode,ReactFlowProjectionEdge as ProjectionEdge} from '@/lib/canvas-bindings/react-flow';
 import type { CanvasRuntimeExtension } from '@/lib/canvas-bindings/react-flow';
 import { useCanvasBinding,useElement, useCanvasRendererCommands } from '@/lib/canvas-bindings/react-flow';
+// 按元素 ID 计数真实 renderer 调用，供外层检查无关元素是否重渲染，不以 DOM 数量代替渲染次数。
 function rendered(id:string){const host=globalThis as typeof globalThis&{__fixtureRenders?:Record<string,number>};const counts=host.__fixtureRenders??={};counts[id]=(counts[id]??0)+1;}
+// 通过 useElement 取得当前原记录，捕获有 scoped target 与无绑定两种旧 editing facade，交给外层验证桥接隔离。
 function Meter({data}:NodeProps<ProjectionNode>){
   const commands=useCanvasRendererCommands(),lookup=useElement(data.__headlessRecord!),record=lookup.status==='present'?lookup.element:data.__headlessRecord!;rendered(record.id);const legacy=useScopedNodeEditing(record.id,data.__headlessTarget),unbound=useScopedNodeEditing(record.id),binding=useCanvasBinding();const host=globalThis as typeof globalThis&{__fixtureEngine?:typeof binding.engine;__fixtureLegacy?:Record<string,typeof legacy>;__fixtureUnbound?:Record<string,typeof legacy>};host.__fixtureEngine=binding.engine;(host.__fixtureLegacy??={})[record.id]=legacy;(host.__fixtureUnbound??={})[record.id]=unbound;
+  // Increase 按钮阻止点击冒泡，并在一个事务里修改 metric 与 raw，要求只产生一个历史单元；自定义 Handle ID 供连线端口测试。
   return <div data-renderer-fixture="meter" style={{width:'100%',height:'100%',background:'white',border:'1px solid #ded7ce',padding:16}}>
     <span>Metric {String(record.data.metric)}</span><button className="nodrag" aria-label={`Increase ${record.id}`} onClick={event=>{event.stopPropagation();commands.transaction(tx=>{tx.dispatch({type:'element.data',target:{id:record.id,incarnation:record.incarnation},patch:{metric:Number(record.data.metric)+1}});tx.dispatch({type:'element.data',target:{id:record.id,incarnation:record.incarnation},patch:{raw:{retained:true,edited:true}}});},{label:'Increase metric'});}}>Increase</button>
     <Handle type="source" id="custom-out" position={Position.Right}/><Handle type="source" id="custom-in" position={Position.Left}/>
   </div>;
 }
+// 自定义边记录渲染次数，使用 ReactFlow Bezier path 绘制；标题从原 connection data 读取 metric。
 function MeterEdge(props:EdgeProps<ProjectionEdge>){rendered(props.id);const [path]=getBezierPath(props);return <g data-renderer-fixture="metric-edge"><title>Metric {String(props.data?.__headlessRecord?.data.metric)}</title><BaseEdge id={props.id} path={path}/></g>;}
+// 两种模型分别校验 metric，节点安装编辑/移动能力；renderer 键精确匹配 componentId、dataVersion 与 structure。
 export const fixtureExtension:CanvasRuntimeExtension={
   components:[defineComponent({id:'fixture:meter',dataVersion:1,structure:'node',validate:data=>Number.isSafeInteger(data.metric),features:[editable(),movable()],copy:{references:[],omit:[]}}),defineComponent({id:'fixture:metric-edge',dataVersion:1,structure:'connection',validate:data=>typeof data.metric==='number',features:[],copy:{references:[],omit:[]}})],
   renderers:[{componentId:'fixture:meter',dataVersion:1,structure:'node',rendererId:'fixture-meter',render:Meter},{componentId:'fixture:metric-edge',dataVersion:1,structure:'connection',rendererId:'fixture-metric-edge',render:MeterEdge}],

tests/headless/renderer-performance.mjs

@@ -1,32 +1,46 @@
-/** Actual GraphPage/React Flow + IndexedDB probe; fixture HTTP server, not production service. */
+/**
+ * 实际 GraphPage/ReactFlow 页面与 IndexedDB 的输入、保留和深复制探针，HTTP 后端由 fixture 提供。
+ * 调用者注入 CDP、页面 evaluate、服务文档及报告路径；本文件不独立启动浏览器或构建项目。
+ * 将场景断言与耗时/堆采样分别报告：计时是本次环境的观测，不构成通用 SLA；内嵌页面脚本保持测试输入原字节。
+ */
 import assert from 'node:assert/strict';
 import {editDuringCopy} from './renderer-copy-input.mjs';
 import {writeFile} from 'node:fs/promises';
 import {setTimeout as pause} from 'node:timers/promises';
 import {canvasTransform,toWorld} from '../../src/lib/canvas-core/coordinates.ts';
 
+// 依次验证原生编辑、离屏输入保留、宿主面板、portal 和大分区复制，再写报告与成功截图。
 export async function measureRenderer({call,evaluate,documents,calls=[],root,partition,count,exceptions,reportPath,browserLogs=()=>'',baseline,buildMode='development',bundler='webpack',buildMs}){
+  // 保存测量墙上起点、堆样本及复制状态；target 用于离屏裁剪断言，不是最终服务端元素总数。
   const target=2*count+3,started=Date.now(),heapSamples=[];let copying=false,nextHeap=0;
+  // 每次条件轮询有四分钟墙上截止并检查页面异常；复制中可每十秒取堆与回执保留快照，写 .heap.json。单次 await 仍依赖注入调用器返回。
   const wait=async(expression,label)=>{const deadline=Date.now()+240000;while(Date.now()<deadline){if(exceptions.length)throw Error(exceptions.join('\n'));if(copying&&process.env.HEADLESS_PERFORMANCE_HEAP==='1'&&Date.now()>=nextHeap){const heap=await call('Runtime.getHeapUsage'),retention=await evaluate('window.__fixtureReceiptRetention');heapSamples.push({wallMs:Date.now()-started,serverElements:documents.get(root)?.elements.size,heap,retention});nextHeap=Date.now()+10000;await writeFile(reportPath+'.heap.json',JSON.stringify({baseline,heapSamples},null,2));}if(await evaluate(expression))return;await pause(100);}throw Error(label);};
   let report,duringCopyInput;
+  // 环境开关决定是否在复制期间额外输入；默认仅测复制，报告 scenario 据此区分。
   const concurrentInput=process.env.HEADLESS_PERFORMANCE_EDIT_DURING_COPY==='1';
   try{
+    // 等真实 frame 与至少两个节点挂载；未选择时不应保留空节点工具栏订阅。
     await wait(`!!document.querySelector('.react-flow__node[data-id="perf-frame"]')&&document.querySelectorAll('.react-flow__node').length>=2`,'initial large canvas did not render');
     assert.equal(await evaluate('document.querySelectorAll(".react-flow__node-toolbar").length'),0,'unselected nodes retained empty toolbar subscriptions');
+    // 读取页面 performance.now，是相对页面时间原点的就绪观测，不是函数 Date.now 起点的独立渲染耗时。
     const initialReadyMs=await evaluate('performance.now()');console.log('PERF initial scene ready '+Math.round(initialReadyMs)+' ms');
-    // Use native input: synthetic focus alone misses the editing-mode transition.
+    // 使用原生输入进入编辑；仅脚本 focus 不会覆盖真实编辑模式切换。
     await wait(`!!document.querySelector('.react-flow__node[data-id="perf-0"] [aria-label^="单击选中"]')`,'first visible text card missing');
+    // 记录双击前后 DOM 数量，用于断言进入单卡编辑不会把离屏全集挂载。
     const beforeEditing=await evaluate('document.querySelectorAll(".react-flow__node").length');
     const editPoint=await evaluate(`(()=>{const rect=document.querySelector('.react-flow__node[data-id="perf-0"] [aria-label^="单击选中"]').getBoundingClientRect();return{x:rect.x+60,y:rect.y+30};})()`);
+    // 经 CDP 发送原生双击，随后验证 activeElement 为可写 textarea，避免只用脚本 focus 绕过编辑模式。
     await call('Input.dispatchMouseEvent',{type:'mousePressed',...editPoint,button:'left',buttons:1,clickCount:2});
     await call('Input.dispatchMouseEvent',{type:'mouseReleased',...editPoint,button:'left',buttons:0,clickCount:2});
     await wait(`document.activeElement===document.querySelector('.react-flow__node[data-id="perf-0"] textarea')&&!document.activeElement.readOnly`,'native text editing did not start');
     await evaluate('window.__performanceEditor=document.activeElement;new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
     const duringEditing=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(duringEditing<=beforeEditing+10,'editing one visible card mounted the offscreen canvas');
+    // 输入后同一 DOM、焦点和文本都要保留，再开启 IME 并将目标平移到屏幕外。
     await call('Input.insertText',{text:'Native editing remains responsive'});
     assert.equal(await evaluate('window.__performanceEditor.isConnected&&document.activeElement===window.__performanceEditor&&window.__performanceEditor.value.includes("Native editing remains responsive")'),true,'native input lost its DOM, focus or value');
     await evaluate('window.__editViewport=new DOMMatrix(getComputedStyle(document.querySelector(".react-flow__viewport")).transform);true');
+    // 先建立组合输入再平移；目标确实离屏且仍保留输入 DOM，正常规模下不能因保留一个 editor 挂载全集。
     await call('Input.imeSetComposition',{text:'保',selectionStart:1,selectionEnd:1});
     await evaluate(`document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:20000,deltaY:20000,bubbles:true,cancelable:true}))`);
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
@@ -34,6 +48,7 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     assert.equal(await evaluate('(()=>{const r=window.__performanceEditor.getBoundingClientRect();return r.right<0||r.bottom<0||r.left>innerWidth||r.top>innerHeight;})()'),true,'IME probe did not move its owner offscreen');
     const offscreenEditing=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(offscreenEditing<=10,'retaining one offscreen editor mounted the complete canvas');
+    // 离屏提交组合文本后恢复 viewport 并 blur，等同步完成再开始复制计时，排除上一轮未保存输入干扰。
     await call('Input.insertText',{text:'保留输入'});
     assert.equal(await evaluate('window.__performanceEditor.value.endsWith("保留输入")'),true,'offscreen IME commit lost content');
     await evaluate(`(()=>{const now=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform),before=window.__editViewport;document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:(now.e-before.e)/.5,deltaY:(now.f-before.f)/.5,bubbles:true,cancelable:true}));delete window.__editViewport;})()`);
@@ -41,6 +56,7 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     await wait(`[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'native input did not synchronize before copy measurement');
     const inputCheck={beforeEditing,duringEditing,offscreenEditing};
     console.log('PERF native editing '+JSON.stringify(inputCheck));
+    // 记录 AI 任务 POST 基数；修改面板设置或复制只能改配置/文档，不应启动生成。
     const runStartsBefore=calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length;
     await wait(`!!document.querySelector('[aria-label="AI 创作"]')&&!document.querySelector('[aria-label="AI 创作"]').disabled`,'AI panel action did not become available');
     await evaluate(`document.querySelector('[aria-label="AI 创作"]').click()`);
@@ -48,24 +64,29 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     await evaluate(`(()=>{window.__performancePanel=document.querySelector('[aria-label="AI 指令"]');window.__performancePanel.focus();window.__editViewport=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform);})()`);
     await call('Input.insertText',{text:'Stable host panel draft'});
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+    // 宿主 AI 面板与节点编辑不同：面板持有草稿不应额外保留所有节点。
     inputCheck.panelFocusedNodes=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(inputCheck.panelFocusedNodes<=beforeEditing+10,'host-panel focus mounted the complete canvas');
     await evaluate(`document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:20000,deltaY:20000,bubbles:true,cancelable:true}))`);
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+    // 平移后面板 DOM、焦点和草稿都保留，但画布离屏节点应归零。
     assert.equal(await evaluate('window.__performancePanel.isConnected&&document.activeElement===window.__performancePanel&&window.__performancePanel.value==="Stable host panel draft"'),true,'independent panel lost its focus or draft during pan');
     inputCheck.offscreenPanel=await evaluate('document.querySelectorAll(".react-flow__node").length');
     assert.equal(inputCheck.offscreenPanel,0,'host-panel input pinned unrelated offscreen nodes');
     await evaluate('window.__performancePanel.blur();new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
     await wait(`[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'AI settings did not save before copy');
+    // blur 后从 fixture 服务文档核对配置已经保存，再恢复视口并关闭面板。
     assert.equal(documents.get(root).elements.get('perf-0').data.ai?.prompt,'Stable host panel draft','host-panel blur lost saved settings');
     await evaluate(`(()=>{document.querySelector('[aria-label="关闭 AI 工具"]').click();const now=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform),before=window.__editViewport;document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:(now.e-before.e)/.5,deltaY:(now.f-before.f)/.5,bubbles:true,cancelable:true}));delete window.__performancePanel;delete window.__editViewport;})()`);
     assert.equal(calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length,runStartsBefore,'editing settings started a generation task');
 
+    // 通过 elementFromPoint 搜索真正空白 pane 坐标并原生点击，清空之前编辑选择，避免污染 frame 工具栏计数。
     const panePoint=await evaluate(`(()=>{const pane=document.querySelector('.react-flow__pane'),rect=pane.getBoundingClientRect();for(let y=rect.y+5;y<rect.bottom;y+=20)for(let x=rect.x+5;x<rect.right;x+=20)if(document.elementFromPoint(x,y)===pane)return{x,y};throw Error('no empty native pane point');})()`);
     await call('Input.dispatchMouseEvent',{type:'mousePressed',...panePoint,button:'left',buttons:1,clickCount:1});
     await call('Input.dispatchMouseEvent',{type:'mouseReleased',...panePoint,button:'left',buttons:0,clickCount:1});
     await wait('document.querySelectorAll(".react-flow__node-toolbar").length===0','native edit selection did not clear before frame selection');
 
+    // 选择 frame 后只允许一个工具栏，portal 标题编辑作为新的离屏保留 owner。
     await evaluate(`document.querySelector('.react-flow__node[data-id="perf-frame"]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`);
     await wait(`!!document.querySelector('[aria-label="深复制选中内容"]')&&!document.querySelector('[aria-label="深复制选中内容"]').disabled`,'partition selection did not enable deep copy');
     await evaluate(`new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))`);
@@ -76,13 +97,16 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
     await evaluate(`document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:20000,deltaY:20000,bubbles:true,cancelable:true}))`);
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
     assert.equal(await evaluate('window.__performancePortal.isConnected&&document.activeElement===window.__performancePortal&&window.__performancePortal.value==="Retained portal title"'),true,'portal title draft was lost during offscreen pan');
+    // 分区标题 portal 离屏时只保留必要 owner；blur 后应释放全部离屏节点，回到原视口再确认标题保存及重挂载。
     inputCheck.offscreenPortal=await evaluate('document.querySelectorAll(".react-flow__node").length');
     if(count>=100)assert.ok(inputCheck.offscreenPortal<=10,'one portal draft mounted the complete canvas');
     await evaluate('window.__performancePortal.blur();true');
     await wait('document.querySelectorAll(".react-flow__node").length===0','released portal retained offscreen owners');
     await evaluate(`(()=>{const now=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform),before=window.__editViewport;document.querySelector('.react-flow__pane').dispatchEvent(new WheelEvent('wheel',{deltaX:(now.e-before.e)/.5,deltaY:(now.f-before.f)/.5,bubbles:true,cancelable:true}));delete window.__editViewport;delete window.__performancePortal;})()`);
     await wait(`document.querySelector('[aria-label="分区名称"]')?.value==='Retained portal title'&&[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'portal title did not save and remount');
+    // 捕获复制开始前的原文，用来证明并发输入不进入已经捕获的副本。
     const sourceText=documents.get(root).elements.get('perf-0').data.text;
+    // 页面脚本以 rAF 采样新 DOM、进度完成、节点峰值、帧间隔，并在支持时观察 longtask；tick 反复采样，read 汇总，stop 取消并断开 observer。
     await evaluate(`(()=>{
       const originals=new Set(['perf-source','perf-frame',...Array.from({length:${count}},(_,i)=>'perf-'+i)]),start=performance.now(),tasks=[],gaps=[];
       let raf,last=start,sawPreparing=false,firstDOM=null,firstFrame=null,localComplete=null,localCompleteFrame=null,prepared=null,maxNodes=0;
@@ -93,11 +117,15 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
       window.__canvasPerformance={read(){const sorted=[...gaps].sort((a,b)=>a-b),p95=sorted[Math.max(0,Math.ceil(sorted.length*.95)-1)]??0;return{frameGapP95Ms:p95,elapsedMs:performance.now()-start,firstDOMMs:firstDOM,firstPresentedFrameMs:firstFrame,localCompleteMs:localComplete,localCompleteFrameMs:localCompleteFrame,prepareMs:prepared,maxMountedNodes:maxNodes,nodeCount:document.querySelectorAll('.react-flow__node').length,longTasksSupported:supported,longTaskCount:tasks.length,maxLongTaskMs:Math.max(0,...tasks.map(task=>task.duration)),totalLongTaskMs:tasks.reduce((total,task)=>total+task.duration,0),maxFrameGapMs:Math.max(0,...gaps),longTasks:tasks};},stop(){cancelAnimationFrame(raf);if(observer){tasks.push(...observer.takeRecords().map(entry=>({start:entry.startTime-start,duration:entry.duration})));observer.disconnect();}return this.read();}};
       document.querySelector('[aria-label="深复制选中内容"]').click();
     })()`);
+    // 页面脚本安装采样后点击复制；Node 侧此后才启用复制期间的可选堆采样。
     copying=true;console.log('PERF copy requested');
+    // 可选探针通过原生输入继续编辑源卡，校验完整文字增量；副本随后仍须保留复制起点文本。
     if(concurrentInput){duringCopyInput=await editDuringCopy({call,evaluate,wait,count});assert.equal(duringCopyInput.value,sourceText+(count>=10000?'复制期间输入 A B C M T':'复制期间输入 A B C'),'concurrent typing lost pre-existing source text');console.log('PERF concurrent input '+JSON.stringify(duringCopyInput));}
     await wait(`document.querySelectorAll('.react-flow__node').length>0&&document.querySelector('[aria-label="画布导入"]')?.textContent.includes('已加入画布')&&[...document.querySelectorAll('[role=status]')].some(item=>item.textContent.trim()==='已同步')`,'large copy did not finish rendering and synchronization');
     await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');
+    // 完成进度与已同步后再等两帧，要求 renderer 测量出现合批；统计批量大小而非只计渲染总数。
     const internalsBatches=await evaluate('window.__fixtureInternalsBatches??[]');assert.ok(internalsBatches.some(size=>size>1),'mounted nodes did not share a renderer measurement batch');
+    // 停止页面采样并验证服务元素数、复制 canvas 和上级连线。firstPresentedFrame 是检测新 DOM 后的下一次 rAF 近似值，不是 compositor 上屏证明。
     const measurements=await evaluate('window.__canvasPerformance.stop()'),document=documents.get(root),copiedCanvas=[...document.canvases.values()].find(canvas=>canvas.parent&&canvas.id!==partition);
     assert.equal(document.elements.size,2*count+5);assert.ok(copiedCanvas);assert.ok([...document.elements.values()].some(element=>element.structure==='connection'&&element.source.elementId==='perf-source'&&element.target.elementId===copiedCanvas.parent.entryElementId));assert.ok(document.elements.has('perf-incoming'));assert.ok(measurements.firstPresentedFrameMs!==null&&measurements.localCompleteFrameMs!==null);if(count>=100)assert.ok(measurements.nodeCount<target,'offscreen DOM was not culled');assert.ok(await evaluate(`document.querySelector('[aria-label="画布导入"]').textContent.includes('${count+3} 项')`),'copy progress did not include all source records');
     if(concurrentInput){
@@ -105,17 +133,26 @@ export async function measureRenderer({call,evaluate,documents,calls=[],root,par
       assert.equal(copiedFirst?.data.text,sourceText,'copy snapshot absorbed a later original edit');
       assert.equal(document.elements.get('perf-0').data.text,duringCopyInput.value,'ACK overwrote concurrent original text');
     }
+    // 再次核对整个配置/复制场景没有启动 AI 任务；生成计费不属于深复制的副作用。
     const runStartsDuringScenario=calls.filter(call=>call.method==='POST'&&call.path.endsWith('/ai/runs')).length-runStartsBefore;
     assert.equal(runStartsDuringScenario,0,'deep copy or settings unexpectedly started generation');
+    // 离屏源仍需保留两条可见分区连线，随后把最后一个副本节点平移到屏幕内，检查实际挂载。
     const visibleEdges=await evaluate('document.querySelectorAll(".react-flow__edge").length');assert.equal(visibleEdges,2,'frame connections did not render for the offscreen source');
-    // Completion is a model/progress check. Verify an offscreen copied card actually mounts after panning.
+    // 进度完成只证明模型/作业状态；还要平移后看到副本卡片实际挂载。
+    // 按原节点局部位置找到复制后的末项，而非只依赖进度或服务记录宣称渲染完成。
     const originalLast=document.elements.get(`perf-${count-1}`),copiedLast=[...document.elements.values()].find(element=>element.structure==='node'&&element.ownerCanvasId===copiedCanvas.id&&element.geometry.x===originalLast.geometry.x&&element.geometry.y===originalLast.geometry.y);assert.ok(copiedLast);
+    // 从副本 owner 的局部坐标换算世界中心，给页面 viewport 平移定位使用。
     const world=toWorld(canvasTransform(document,copiedLast.ownerCanvasId),{x:copiedLast.geometry.x+copiedLast.geometry.width/2,y:copiedLast.geometry.y+copiedLast.geometry.height/2});
     await evaluate(`(()=>{const pane=document.querySelector('.react-flow__pane'),rect=pane.getBoundingClientRect(),matrix=new DOMMatrix(getComputedStyle(document.querySelector('.react-flow__viewport')).transform);pane.dispatchEvent(new WheelEvent('wheel',{deltaX:(${world.x}*matrix.a+matrix.e-rect.width/2)/.5,deltaY:(${world.y}*matrix.a+matrix.f-rect.height/2)/.5,bubbles:true,cancelable:true}));})()`);
     await wait(`!!document.querySelector('.react-flow__node[data-id="${copiedLast.id}"] textarea')`,'offscreen copied card did not mount after viewport pan');
+    // 记录平移后的实际挂载数量，和之前的可见连线数一起写入报告。
     const viewportCheck={visibleEdgesBeforePan:visibleEdges,copiedId:copiedLast.id,mountedAfterPan:await evaluate('document.querySelectorAll(".react-flow__node").length')};
+    // 报告同时保存输入断言上下文、浏览器/构建模式、采样、fixture 文档计数与测量批次，便于跨环境比较。
     report={inputCheck,duringCopyInput,runStartsDuringScenario,baseline,heapSamples,browserLogs:browserLogs(),scenario:concurrentInput?'actual GraphPage deep copy with concurrent native input':'actual GraphPage deep copy of expanded partition',mode:`Next ${buildMode} ${bundler}; isolated fixture HTTP; real Chrome/IndexedDB/Web Locks`,count,initialReadyMs,buildMs,internals:{batches:internalsBatches.length,maxBatch:Math.max(0,...internalsBatches),totalRequests:internalsBatches.reduce((sum,size)=>sum+size,0)},measurements,viewportCheck,browser:await call('Browser.getVersion'),serverElements:document.elements.size,serverCanvases:document.canvases.size,wallMs:Date.now()-started};
+    // 仅成功路径截图，输出到报告同名 PNG；截图是场景结束视口，不是每个计时点的屏幕证据。
     const screenshot=await call('Page.captureScreenshot',{format:'png'});await writeFile(reportPath.endsWith('.json')?reportPath.slice(0,-5)+'.png':reportPath+'.png',Buffer.from(screenshot.data,'base64'));
+  // 失败也尽力停止页面采样并写诊断报告，然后重抛；不能把部分观测输出当作场景通过。
   }catch(error){let measurements;try{measurements=await evaluate('window.__canvasPerformance?.stop()');}catch{}report={duringCopyInput,baseline,heapSamples,browserLogs:browserLogs(),scenario:concurrentInput?'actual GraphPage deep copy with concurrent native input':'actual GraphPage deep copy of expanded partition',count,buildMode,buildMs,error:error.message,measurements,serverElements:documents.get(root)?.elements.size,serverCanvases:documents.get(root)?.canvases.size,wallMs:Date.now()-started};await writeFile(reportPath,JSON.stringify(report,null,2));throw error;}
+  // 成功报告落盘后打印紧凑摘要，长任务明细仍保存在 JSON 文件。
   await writeFile(reportPath,JSON.stringify(report,null,2));console.log('MEASURE '+JSON.stringify({...report,measurements:{...report.measurements,longTasks:undefined}}));console.log('REPORT '+reportPath);
 }

tests/headless/renderers.test.mjs

@@ -1,30 +1,42 @@
+/**
+ * 渲染定义目录与 React 组装的契约测试。模型 registry 定义数据与能力，renderer catalog 定义宿主如何显示，两者按类型/版本/结构匹配。
+ * 这里检查描述捕获、投影记录与函数身份，不挂载真实 ReactFlow 页面。
+ */
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
 import {createRendererCatalog,builtinRendererDefinitions} from '../../src/lib/canvas-bindings/renderers.ts';
 import {createReactRenderers} from '../../src/lib/canvas-bindings/react-renderers.ts';
 import {createDocument,createRegistry,builtinComponents,defineComponent,movable,createEditor} from '../../src/lib/canvas-core/index.ts';
 import {projectCanvas} from '../../src/lib/canvas-bindings/projection.ts';
+// 自定义计量节点的精确渲染键，不允许用同一映射自动兼容未来版本或不同 structure。
 const descriptor={componentId:'plugin:meter',dataVersion:1,structure:'node',rendererId:'meter'};
+// 模型独立声明 metric 校验和移动能力；同一个模型可由多个宿主使用不同渲染器。
 const definition=defineComponent({id:'plugin:meter',dataVersion:1,structure:'node',validate:data=>typeof data.metric==='number',features:[movable()]}),registry=createRegistry([...builtinComponents(),definition]);
+// 保留不透明标题和看似内部字段的数据，用来核对投影注入的可信原记录不会被用户 data 冒充。
 const node={id:'meter',incarnation:1,ownerCanvasId:'root',structure:'node',componentId:'plugin:meter',dataVersion:1,data:{metric:7,title:{opaque:true},__headlessRecord:{untrusted:true}},geometry:{x:0,y:0,width:200,height:100,rotation:0}};
+// 目录只捕获不可变元数据，不持有 React render 值；输入描述后续变化无效，未来版本/不同结构不匹配，重复或保留 ID 被拒绝。
 test('renderer catalog captures exact version/structure mappings without React values or mutable descriptors',()=>{
  const input={...descriptor,render(){}};const catalog=createRendererCatalog([input]);input.rendererId='changed';assert.equal(catalog.resolve(node).rendererId,'meter');assert.equal(catalog.resolve({...node,dataVersion:2}),undefined);assert.equal(catalog.resolve({...node,structure:'connection'}),undefined);assert.equal(catalog.definitions[0].render,undefined);assert.ok(Object.isFrozen(catalog.definitions[0]));assert.throws(()=>createRendererCatalog([descriptor,descriptor]),/duplicate_renderer_definition/);assert.throws(()=>createRendererCatalog([{...descriptor,rendererId:'unsupported'}]),/invalid_renderer_definition/);
 });
+// 组装仅在同一个 render 实现时共享别名包装；拒绝空 renderer、ID 冲突与模型契约不符，getter 只读取一次并保留 memo 对象。
 test('React assembly preserves aliases only for the same component and rejects invalid renderers or model contracts',()=>{
  const render=()=>null,assembly=createReactRenderers([{...descriptor,render}],registry);assert.equal(assembly.nodeTypes.meter.type,render);assert.ok(Object.isFrozen(assembly.nodeTypes));assert.equal(assembly.edgeTypes.meter,undefined);
  assert.throws(()=>createReactRenderers([{...descriptor,render:null}]),/invalid_react_renderer/);assert.throws(()=>createReactRenderers([{...descriptor,render},{...descriptor,componentId:'other',render:()=>null}]),/renderer_id_conflict/);assert.throws(()=>createReactRenderers([{...descriptor,dataVersion:2,render}],registry),/renderer_model_mismatch/);
  let reads=0;const getter=createReactRenderers([{...descriptor,get render(){reads++;return render;}}]);assert.equal(reads,1);assert.equal(getter.definitions[0].render,render);assert.equal(getter.nodeTypes.meter,assembly.nodeTypes.meter);
  const alias=createReactRenderers([{...descriptor,render},{...descriptor,componentId:'other',render}]);assert.equal(alias.nodeTypes.meter,assembly.nodeTypes.meter);const memo={$$typeof:Symbol.for('react.memo'),type:render};assert.equal(createReactRenderers([{...descriptor,render:memo}]).nodeTypes.meter,memo);
 });
+// 自定义节点与边投影携带原记录和 transform，未知 data/path 不丢；未安装映射或未来 schema 走 unsupported。
 test('installed node and edge renderers receive original records and transforms while absent schemas still fall back',()=>{
  const customEdge=defineComponent({id:'plugin:edge',dataVersion:1,structure:'connection',validate:()=>true,features:[]}),r=createRegistry([...builtinComponents(),definition,customEdge]),other={...node,id:'second',geometry:{...node.geometry,x:300}},edge={id:'edge',incarnation:1,structure:'connection',componentId:'plugin:edge',dataVersion:1,ownerCanvasId:'root',source:{elementId:'meter',portId:'custom-out'},target:{elementId:'second',portId:'custom-in'},path:{type:'custom',retained:true},data:{path:{own:true},metric:99}},source=createDocument('project',[{id:'root',parent:null}],[node,other,edge]),catalog=createRendererCatalog([...builtinRendererDefinitions,descriptor,{...descriptor,componentId:'plugin:edge',structure:'connection',rendererId:'meter-edge'}]),p=projectCanvas(source,'root',r,new Set(),()=>undefined,null,catalog);
  assert.equal(p.nodes[0].type,'meter');assert.equal(p.nodes[0].data.__headlessFallback,undefined);assert.equal(p.nodes[0].data.__headlessRecord,source.elements.get('meter'));assert.deepEqual(p.nodes[0].data.__headlessRecord.data.title,{opaque:true});assert.equal(p.nodes[0].data.__headlessTransform.scale,1);assert.equal(p.edges[0].type,'meter-edge');assert.equal(p.edges[0].data.__headlessRecord,source.elements.get('edge'));assert.deepEqual(p.edges[0].data.__headlessRecord.path,{type:'custom',retained:true});
  const missing=projectCanvas(source,'root',r,new Set(),()=>undefined);assert.equal(missing.nodes[0].type,'unsupported');assert.equal(missing.edges[0].type,'unsupported');const future=createDocument('project',[{id:'root',parent:null}],[{...node,dataVersion:2}]);assert.equal(projectCanvas(future,'root',r,new Set(),()=>undefined,null,catalog).nodes[0].type,'unsupported');
 });
+// 加载前预览必须显式提供 preview，实现与正式 renderer 独立捕获；非法 preview 或不一致别名被拒绝。
 test('pre-engine preview renderers are explicit and captured independently from engine-bound renderers',()=>{
  const render=()=>null,preview=()=>null,assembly=createReactRenderers([{...descriptor,render,preview}]);assert.equal(assembly.nodeTypes.meter.type,render);assert.equal(assembly.previewNodeTypes.meter.type,preview);assert.equal(assembly.definitions[0].preview,preview);assert.ok(Object.isFrozen(assembly.previewNodeTypes));assert.equal(createReactRenderers([{...descriptor,render}]).previewNodeTypes.meter,undefined);assert.throws(()=>createReactRenderers([{...descriptor,render,preview:0}]),/invalid_react_preview/);assert.throws(()=>createReactRenderers([{...descriptor,render,preview},{...descriptor,componentId:'other',render}]),/renderer_id_conflict/);
 });
 
+// 两个宿主对同一 component 选择不同 rendererId，但共享同一文档记录与移动结果，命令仍只产生一个历史单元。
 test('independent host renderers for one component share model data and capability behavior',()=>{
  const editor=createEditor({registry,document:createDocument('project',[{id:'root',parent:null}],[node])}),one=createReactRenderers([{...descriptor,rendererId:'host-one',render:()=>null}],registry),two=createReactRenderers([{...descriptor,rendererId:'host-two',render:()=>null}],registry);
  assert.equal(editor.dispatch({type:'element.geometry',target:{id:node.id,incarnation:node.incarnation},patch:{x:42}}).status,'applied');

tests/headless/selection-listener-fixture.tsx

@@ -1,19 +1,30 @@
+/**
+ * 页面专用原生 ReactFlow selection 观察组件。默认不安装监听器，由外层测试 enable 后才挂载 Listener。
+ * 此 fixture 观察 ReactFlow 自己的选择事件和 nodeLookup，不代替业务文档或 headless session 的事实源。
+ */
 "use client";
 import {useCallback,useEffect,useState} from 'react';
 import {useOnSelectionChange,useStoreApi} from '@xyflow/react';
+// 把回调中的节点/边对象收窄成 ID 列表，避免把整个 renderer 对象留在测试事件日志。
 type Event={nodes:string[];edges:string[]};
+// 暴露启用、原生选择命令和当前节点选择查询，供浏览器脚本与 headless 选择行为对照。
 type Control={enable(value:boolean):void;select(ids:string[]):void;selected():string[]};
+// 仅在测试 Window 上声明控制接口与事件日志，不向生产 editor 注入状态。
 declare global{interface Window{__fixtureNativeSelection?:Control;__fixtureNativeSelectionEvents?:Event[];}}
+// 稳定 useCallback 记录 ID，再注册 useOnSelectionChange；组件卸载由 hook 解除观察。
 function Listener(){
  const onChange=useCallback((value:{nodes:{id:string}[];edges:{id:string}[]})=>{window.__fixtureNativeSelectionEvents?.push({nodes:value.nodes.map(node=>node.id),edges:value.edges.map(edge=>edge.id)});},[]);
  useOnSelectionChange({onChange});return null;
 }
-/** Isolated page fixture only; no observer is installed in performance builds. */
+/** 仅在隔离测试页面使用，性能构建不安装此观察器。 */
+// 持有 ReactFlow store 和启用开关；effect 注册控制对象，render 按开关决定是否安装监听器。
 export function NativeSelectionFixture(){
  const store=useStoreApi(),[enabled,setEnabled]=useState(false);
  useEffect(()=>{
+  // select 先清除再添加原生选中节点，selected 从 nodeLookup 查询；日志独立保存已收到的事件。
   const control:Control={enable:setEnabled,select(ids){store.getState().resetSelectedElements();store.getState().addSelectedNodes(ids);},selected(){return [...store.getState().nodeLookup.values()].filter(node=>node.selected).map(node=>node.id);}};
   window.__fixtureNativeSelection=control;window.__fixtureNativeSelectionEvents??=[];
+  // 只移除本 effect 注册的同一控制对象，旧 cleanup 不删除新挂载的控制接口；事件日志不在此清空。
   return()=>{if(window.__fixtureNativeSelection===control)delete window.__fixtureNativeSelection;};
  },[store]);
  return enabled?<Listener/>:null;