feat: add render graph driven renderer architecture

Amp-Thread-ID: https://ampcode.com/threads/T-019f9d91-77c1-7206-a60f-ed6554ce92ab

Co-authored-by: Heaust Azure <heaust.azure@gmail.com>

tests/demo-loadouts.test.js

@@ -0,0 +1,10 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createCubeGeometry, createUvSphereGeometry, encodeGeometryGlb, isGitLfsPointer, loadDemoLoadout, LoadoutError } from "../static/demo-loadouts.js";
+
+function parseGlb(buffer){const view=new DataView(buffer);assert.equal(view.getUint32(0,true),0x46546c67);assert.equal(view.getUint32(4,true),2);assert.equal(view.getUint32(8,true),buffer.byteLength);const length=view.getUint32(12,true);assert.equal(view.getUint32(16,true),0x4e4f534a);const json=JSON.parse(new TextDecoder().decode(new Uint8Array(buffer,20,length)).trim());const bin=20+length;assert.equal(view.getUint32(bin+4,true),0x004e4942);assert.equal(view.getUint32(bin,true),json.buffers[0].byteLength);return json;}
+test("procedural cube and sphere have complete indexed vertex streams",()=>{const cube=createCubeGeometry(),sphere=createUvSphereGeometry();assert.deepEqual([cube.positions.length/3,cube.indices.length],[24,36]);assert.ok(sphere.positions.length/3>300);for(const geometry of [cube,sphere]){assert.equal(geometry.normals.length,geometry.positions.length);assert.equal(geometry.texcoords.length,geometry.positions.length/3*2);assert.ok(geometry.indices.every(i=>i>=0&&i<geometry.positions.length/3));}});
+test("every cube triangle has counter-clockwise outward winding",()=>{const g=createCubeGeometry();for(let i=0;i<g.indices.length;i+=3){const ids=g.indices.slice(i,i+3),p=ids.map(id=>g.positions.slice(id*3,id*3+3)),a=p[1].map((v,j)=>v-p[0][j]),b=p[2].map((v,j)=>v-p[0][j]),cross=[a[1]*b[2]-a[2]*b[1],a[2]*b[0]-a[0]*b[2],a[0]*b[1]-a[1]*b[0]],normal=g.normals.slice(ids[0]*3,ids[0]*3+3);assert.ok(cross.reduce((sum,v,j)=>sum+v*normal[j],0)>0)}});
+test("loadouts return fresh deterministic GLBs with one mesh and nine nodes",async()=>{for(const name of ["cubes","spheres"]){const a=await loadDemoLoadout(name),b=await loadDemoLoadout(name);assert.notStrictEqual(a,b);assert.deepEqual(new Uint8Array(a),new Uint8Array(b));const json=parseGlb(a);assert.equal(json.meshes.length,1);assert.equal(json.nodes.length,9);assert.ok(json.nodes.every(n=>n.mesh===0));assert.deepEqual(json.meshes[0].primitives[0].attributes,{POSITION:0,NORMAL:1,TEXCOORD_0:2});assert.equal(json.accessors[3].componentType,5125);}});
+test("LFS pointers and HTTP failures are explicit and stable",async()=>{const pointer=new TextEncoder().encode("version https://git-lfs.github.com/spec/v1\noid sha256:abc\n").buffer;assert.equal(isGitLfsPointer(pointer),true);await assert.rejects(loadDemoLoadout("manor",{fetchImpl:async()=>({ok:true,arrayBuffer:async()=>pointer})}),e=>e instanceof LoadoutError&&e.code==="LOADOUT_LFS_POINTER");await assert.rejects(loadDemoLoadout("sponza",{fetchImpl:async()=>({ok:false,status:404})}),e=>e.code==="LOADOUT_HTTP"&&/404/.test(e.message));});
+test("GLB encoder rejects non-finite and out-of-range geometry",()=>{const valid=createCubeGeometry();assert.throws(()=>encodeGeometryGlb({...valid,positions:[...valid.positions.slice(0,-1),NaN]}),/Invalid/);assert.throws(()=>encodeGeometryGlb({...valid,indices:[...valid.indices,0,1,999]}),/Invalid/)});

tests/render-graph-authoring.test.js

@@ -0,0 +1,15 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { adaptFxNodeSnapshot, AuthoringGraphError } from "../static/render-graph/adapter.js";
+import { AuthoringController } from "../static/render-graph/authoring-controller.js";
+
+const sockets={surface_color:[["surface","surface:surface","output","surface"]],depth32:[["depth","depth:depth","output","depth"]],scene_forward:[["color","forward:color","input","surface"],["depth","forward:depth","input","depth"],["result","forward:result","output","surface"]],present:[["surface","present:surface","input","surface"]]};
+function fixture(){const nodes=Object.entries(sockets).map(([typeId,list],i)=>({id:["surface","depth","forward","present"][i],typeId,typeVersion:1,known:true,muted:false,parameters:typeId==="scene_forward"?{clearColor:{kind:"color",value:[.1,.2,.3,1]},clearDepth:{kind:"number",value:.5}}:{},sockets:list.map(([key,id,direction,dataType])=>({key,id,direction,dataType}))}));return {version:4,graphId:"demo_forward",catalogVersion:1,nodes,links:[{id:"l1",fromNodeId:"surface",fromSocketId:"surface:surface",toNodeId:"forward",toSocketId:"forward:color",muted:false},{id:"l2",fromNodeId:"depth",fromSocketId:"depth:depth",toNodeId:"forward",toSocketId:"forward:depth",muted:false},{id:"l3",fromNodeId:"forward",fromSocketId:"forward:result",toNodeId:"present",toSocketId:"present:surface",muted:false}],metadata:{layout:"ignored"}}}
+const rejects=(mutate,code)=>{const x=structuredClone(fixture());mutate(x);assert.throws(()=>adaptFxNodeSnapshot(x),e=>e instanceof AuthoringGraphError&&e.code===code)};
+test("adapter emits exact deterministic V1 without fxnode state",()=>{const a=adaptFxNodeSnapshot(fixture(),7),b=fixture();b.nodes.reverse();b.links.reverse();assert.deepEqual(adaptFxNodeSnapshot(b,7),a);assert.equal(a.revision,7);assert.deepEqual(a.passes[0].writes[0].access.load.value,[.1,.2,.3,1]);for(const token of ["position","socketId","known","fxnode"])assert.equal(JSON.stringify(a).includes(token),false)});
+test("adapter rejects node catalog, identity, sockets, links, topology and parameters",()=>{
+  rejects(x=>x.nodes[0].known=false,"AUTHORING_NODE_UNKNOWN");rejects(x=>delete x.nodes[0].muted,"AUTHORING_NODE_MUTED");rejects(x=>x.nodes[0].muted=true,"AUTHORING_NODE_MUTED");rejects(x=>x.nodes[0].typeVersion=2,"AUTHORING_NODE_VERSION");rejects(x=>x.nodes[0].typeId="other","AUTHORING_NODE_TYPE");rejects(x=>x.nodes[0].id="bad id","AUTHORING_ID");rejects(x=>x.nodes[1].id=x.nodes[0].id,"AUTHORING_ID_DUPLICATE");rejects(x=>x.nodes[0].sockets[0].direction="input","AUTHORING_SOCKET");rejects(x=>x.links[0].muted=true,"AUTHORING_TOPOLOGY");rejects(x=>x.links.pop(),"AUTHORING_TOPOLOGY");rejects(x=>x.nodes[2].parameters.clearDepth.value=Infinity,"AUTHORING_PARAMETER");
+});
+test("adapter carries scene mute and bounds revisions",()=>{const x=fixture();x.nodes[2].muted=true;assert.equal(adaptFxNodeSnapshot(x).passes[0].state,"disabled");assert.throws(()=>adaptFxNodeSnapshot(fixture(),0x100000000),e=>e.code==="AUTHORING_REVISION")});
+test("controller orders compile/switch, revisions and shares one in-flight apply",async()=>{let release;const gate=new Promise(r=>release=r),calls=[];const renderer={async compileGraph(ir){calls.push(`compile:${ir.revision}`);await gate;return{compiledId:[0,1]}},async switchCompiledGraph(id){calls.push(`switch:${id}`)}};const c=new AuthoringController({renderer,getState:async()=>({})});const adapt=(_,r)=>({revision:r}),a=c.apply(adapt);assert.strictEqual(c.apply(adapt),a);c.markDirty();release();await a;assert.deepEqual(calls,["compile:1","switch:0,1"]);assert.equal(c.revision,1);assert.equal(c.dirty,true)});
+test("controller reserves revisions across compile and switch failures",async()=>{let failure="compile",revisions=[];const c=new AuthoringController({getState:async()=>({}),renderer:{compileGraph:async ir=>{revisions.push(ir.revision);if(failure==="compile")throw Error("no");return{compiledId:[0,1]}},switchCompiledGraph:async()=>{if(failure==="switch")throw Error("no")}}});await assert.rejects(c.apply((_,r)=>({revision:r})));failure=null;await c.apply((_,r)=>({revision:r}));failure="switch";await assert.rejects(c.apply((_,r)=>({revision:r})));failure=null;await c.apply((_,r)=>({revision:r}));assert.deepEqual(revisions,[1,2,3,4]);assert.equal(c.revision,4)});

tests/render-graph-presets.test.js

@@ -0,0 +1,4 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { ember, midnight, renderGraphPresets } from "../static/render-graph/presets.js";
+test("Phase 8 presets are unique activatable V1 scene-forward graphs",()=>{assert.deepEqual(Object.keys(renderGraphPresets),["midnight","ember"]);assert.deepEqual([midnight.graphId,ember.graphId],["preset_midnight","preset_ember"]);assert.notDeepEqual(midnight.passes[0].writes[0].access.load.value,ember.passes[0].writes[0].access.load.value);for(const graph of [midnight,ember]){assert.equal(graph.schemaVersion,1);assert.equal(graph.revision,1);assert.equal(graph.passes.length,1);assert.equal(graph.passes[0].state,"enabled");assert.deepEqual(graph.passes[0].executor,{key:"scene_forward",version:1});assert.equal(graph.outputs[0].name,"present");}});

tests/renderer-client.test.js

@@ -0,0 +1,135 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import * as rendererModule from "../static/renderer-client.js";
+const { RendererClient, RendererError } = rendererModule;
+
+class WorkerMock extends EventTarget {
+  messages=[]; transfers=[]; terminated=false;
+  postMessage(message, transfer=[]) { this.messages.push(message); this.transfers.push(transfer); }
+  terminate(){this.terminated=true;}
+  reply(data) { this.dispatchEvent(new MessageEvent("message", { data })); }
+}
+function fixture() {
+  const memory = new WebAssembly.Memory({initial:2, maximum:4, shared:true});
+  const header = new Int32Array(memory.buffer, 0, 16);
+  header.set([0x4e574159,1,1024,24,0,0]);
+  const worker = new WorkerMock();
+  const bridge = {memory,ringPtr:0,worker,freed:false,free(){this.freed=true;}};
+  const client = new RendererClient(bridge);
+  return {memory,header,worker,bridge,client};
+}
+async function imported(f) {
+  const loading=f.client.importGlb(new ArrayBuffer(8));
+  f.worker.reply({type:"payload-ready",id:1});
+  await Promise.resolve();
+  f.worker.reply({type:"reply",request:1,ok:true,result:{meshes:[[7,3]]}});
+  return (await loading)[0];
+}
+test("replaceSceneGlb is opcode 1 and importGlb remains an alias", async()=>{
+  for(const method of ["replaceSceneGlb","importGlb"]){const f=fixture(),pending=f.client[method](new ArrayBuffer(8));f.worker.reply({type:"payload-ready",id:1});await Promise.resolve();assert.equal(new Int32Array(f.memory.buffer,64,24)[1],1);f.worker.reply({type:"reply",request:1,ok:true,result:{meshes:[]}});assert.deepEqual(await pending,[]);}
+});
+test("scene replacement carries the framing mode in opcode 1",async()=>{const f=fixture(),pending=f.client.replaceSceneGlb(new ArrayBuffer(8),{framing:"interior"});f.worker.reply({type:"payload-ready",id:1});await Promise.resolve();assert.deepEqual([...new Int32Array(f.memory.buffer,64,24).slice(1,5)],[1,1,1,1]);f.worker.reply({type:"reply",request:1,ok:true,result:{meshes:[]}});await pending;await assert.rejects(f.client.replaceSceneGlb(new ArrayBuffer(8),{framing:"bad"}),TypeError)});
+test("writes tagged fixed-slot protocol and resolves reply", async () => {
+  const f=fixture(); const mesh=await imported(f);
+  const pending=mesh.setVisible(true);
+  const {memory,header,worker}=f;
+  assert.equal(Atomics.load(header,5),2);
+  const slot=new Int32Array(memory.buffer,64+96,24);
+  assert.deepEqual([...slot.slice(0,6)],[1,2,2,7,3,1]);
+  worker.reply({type:"reply",request:2,ok:true,code:"OK"}); await pending;
+});
+test("maps stable errors and gates destroyed instances", async () => {
+  const f=fixture(), mesh=await imported(f); const {worker}=f;
+  const creating=mesh.createInstance(new Float32Array([1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]),false);
+  worker.reply({type:"reply",request:2,ok:true,result:[4,2]}); const instance=await creating;
+  const destroying=instance.destroy(); worker.reply({type:"reply",request:3,ok:true}); await destroying;
+  assert.throws(()=>instance.setVisible(true), error=>error instanceof RendererError&&error.code==="STALE_HANDLE");
+});
+test("rejects protocol mismatch", () => {
+  const {memory,worker}=fixture(); new Int32Array(memory.buffer)[1]=2;
+  assert.throws(()=>new RendererClient({memory,ringPtr:0,worker}), /PROTOCOL_MISMATCH/);
+});
+test("pending reply exists before ring publication", async () => {
+  const f=fixture(), mesh=await imported(f); const {worker}=f;
+  const pending=mesh.setVisible(true);
+  worker.reply({type:"reply",request:2,ok:true});
+  await pending;
+});
+test("worker failures and dispose reject every pending operation", async () => {
+  const f=fixture(), mesh=await imported(f); const {worker,client,bridge}=f;
+  const a=mesh.setVisible(true), b=mesh.setVisible(false);
+  worker.dispatchEvent(new Event("error"));
+  await assert.rejects(a,/WORKER_ERROR/); await assert.rejects(b,/WORKER_ERROR/);
+  client.dispose(); assert.equal(worker.terminated,true); assert.equal(bridge.freed,true);
+});
+test("import always releases staged payload when ring is full", async () => {
+  const {header,worker,client}=fixture(); Atomics.store(header,5,1024);
+  const loading=client.importGlb(new ArrayBuffer(8));
+  worker.reply({type:"payload-ready",id:1});
+  await assert.rejects(loading,/RING_FULL/);
+  assert.equal(worker.messages.at(-1).type,"payload-release");
+});
+test("does not export handle constructors or internal mutation methods", () => {
+  const {client}=fixture();
+  assert.equal(rendererModule.Mesh,undefined);
+  assert.equal(rendererModule.Instance,undefined);
+  assert.equal(client._meshFlags,undefined);
+  assert.equal(client._createInstance,undefined);
+});
+test("corrupt backlog closes and terminates the transport", async () => {
+  const f=fixture(); Atomics.store(f.header,5,1025);
+  const loading=f.client.importGlb(new ArrayBuffer(8));
+  // Payload staging must first acknowledge before enqueue sees corruption.
+  f.worker.reply({type:"payload-ready",id:1});
+  await assert.rejects(loading,/RING_CORRUPT/);
+  assert.equal(Atomics.load(f.header,6),1);
+  assert.equal(f.worker.terminated,true);
+});
+test("import rejects immediately after disposal", async () => {
+  const f=fixture();
+  f.client.dispose();
+  await assert.rejects(f.client.importGlb(new ArrayBuffer(8)),/DISPOSED/);
+  assert.equal(f.worker.messages.length,0);
+});
+test("import rejects when disposed during asynchronous source loading", async () => {
+  const f=fixture();
+  const originalFetch=globalThis.fetch;
+  let finishFetch;
+  globalThis.fetch=()=>new Promise(resolve=>{finishFetch=resolve;});
+  try {
+    const loading=f.client.importGlb("model.glb");
+    f.client.dispose();
+    finishFetch({arrayBuffer:async()=>new ArrayBuffer(8)});
+    await assert.rejects(loading,/DISPOSED/);
+    assert.equal(f.worker.messages.length,0);
+  } finally {
+    globalThis.fetch=originalFetch;
+  }
+});
+
+test("compile transfers payload and waits for ready before opcode 7", async()=>{
+  const f=fixture(), pending=f.client.compileGraph({schemaVersion:1});
+  assert.equal(f.worker.transfers[0].length,1); assert.equal(Atomics.load(f.header,5),0);
+  f.worker.reply({type:"payload-ready",id:1}); await Promise.resolve();
+  assert.equal(new Int32Array(f.memory.buffer,64,24)[1],7);
+  f.worker.reply({type:"reply",request:1,ok:true,result:{compiledId:[2,3]}});
+  assert.deepEqual(await pending,{compiledId:[2,3]});
+});
+test("flat error reply preserves structured details", async()=>{
+  const f=fixture(), pending=f.client.compileGraph({}); f.worker.reply({type:"payload-ready",id:1}); await Promise.resolve();
+  f.worker.reply({type:"reply",request:1,ok:false,code:"GRAPH_INVALID_ID",details:{message:"bad",path:"graphId"}});
+  await assert.rejects(pending,e=>e instanceof RendererError&&e.code==="GRAPH_INVALID_ID"&&e.details.path==="graphId"&&e.message==="bad");
+});
+test("compile releases payload after success", async()=>{const f=fixture(),p=f.client.compileGraph({});f.worker.reply({type:"payload-ready",id:1});await Promise.resolve();f.worker.reply({type:"reply",request:1,ok:true,result:{}});await p;assert.equal(f.worker.messages.at(-1).type,"payload-release");});
+test("compile releases payload after backend error", async()=>{const f=fixture(),p=f.client.compileGraph({});f.worker.reply({type:"payload-ready",id:1});await Promise.resolve();f.worker.reply({type:"reply",request:1,ok:false,code:"X",details:{message:"x"}});await assert.rejects(p);assert.equal(f.worker.messages.at(-1).type,"payload-release");});
+test("compile rejects circular and BigInt JSON", async()=>{const f=fixture(),x={};x.x=x;await assert.rejects(f.client.compileGraph(x),/circular/i);await assert.rejects(f.client.compileGraph({x:1n}),e=>e.code==="GRAPH_JSON_INVALID");});
+test("compile rejects oversized encoding", async()=>{const f=fixture();await assert.rejects(f.client.compileGraph({x:"x".repeat(1024*1024)}),e=>e.code==="GRAPH_PAYLOAD_TOO_LARGE");assert.equal(f.worker.messages.length,0);});
+test("drop graph emits opcode 8 and validates id", async()=>{const f=fixture(),p=f.client.dropCompiledGraph([9,4]);const slot=new Int32Array(f.memory.buffer,64,24);assert.deepEqual([...slot.slice(1,5)],[8,1,9,4]);f.worker.reply({type:"reply",request:1,ok:true});await p;assert.throws(()=>f.client.dropCompiledGraph([1]),TypeError);});
+test("ring-full graph compile releases staged payload", async()=>{const f=fixture();Atomics.store(f.header,5,1024);const p=f.client.compileGraph({});f.worker.reply({type:"payload-ready",id:1});await assert.rejects(p,e=>e.code==="RING_FULL");assert.equal(f.worker.messages.at(-1).type,"payload-release");});
+test("disposal while graph payload is pending releases and rejects", async()=>{const f=fixture(),p=f.client.compileGraph({});f.client.dispose();await assert.rejects(p,e=>e.code==="DISPOSED");assert.equal(f.worker.messages.at(-1).type,"payload-release");});
+test("payload transfer uses the exact encoded ArrayBuffer", async()=>{const f=fixture(),graph={schemaVersion:1};const expected=new TextEncoder().encode(JSON.stringify(graph));const p=f.client.compileGraph(graph);const transferred=f.worker.transfers[0][0];assert.strictEqual(f.worker.messages[0].buffer,transferred);assert.deepEqual(new Uint8Array(transferred),expected);f.client.dispose();await assert.rejects(p);});
+test("cycle error details are preserved exactly", async()=>{const f=fixture(),p=f.client.compileGraph({});f.worker.reply({type:"payload-ready",id:1});await Promise.resolve();const details={message:"cycle",kind:"cycle",edges:[{from:"a",resource:{id:"r",version:0},to:"b"}]};f.worker.reply({type:"reply",request:1,ok:false,code:"GRAPH_CYCLE",details});await assert.rejects(p,e=>e.details===details&&e.details.edges[0].from==="a");});
+test("error without details leaves details undefined", async()=>{const f=fixture(),p=f.client.dropCompiledGraph([1,1]);f.worker.reply({type:"reply",request:1,ok:false,code:"STALE_GRAPH_ID"});await assert.rejects(p,e=>e instanceof RendererError&&e.details===undefined&&e.message==="STALE_GRAPH_ID");});
+test("switch methods emit exact opcode 9 words", async()=>{const f=fixture();const a=f.client.switchCompiledGraph([9,4]);assert.deepEqual([...new Int32Array(f.memory.buffer,64,24).slice(1,7)],[9,1,1,9,4,0]);f.worker.reply({type:"reply",request:1,ok:true});await a;await new Promise(queueMicrotask);const b=f.client.switchToImmediate();assert.deepEqual([...new Int32Array(f.memory.buffer,160,24).slice(1,7)],[9,2,0,0,0,0]);f.worker.reply({type:"reply",request:2,ok:true});await b;assert.throws(()=>f.client.switchCompiledGraph([0,0]),TypeError);});
+test("graph lifecycle FIFO recovers after failure", async()=>{const f=fixture();const a=f.client.switchCompiledGraph([1,1]),b=f.client.switchToImmediate();assert.equal(Atomics.load(f.header,5),1);f.worker.reply({type:"reply",request:1,ok:false,code:"X"});await assert.rejects(a);await new Promise(queueMicrotask);assert.equal(Atomics.load(f.header,5),2);f.worker.reply({type:"reply",request:2,ok:true});await b;});
+test("dispose rejects queued graph lifecycle calls", async()=>{const f=fixture();const a=f.client.switchCompiledGraph([1,1]),b=f.client.switchToImmediate();f.client.dispose();await assert.rejects(a,/DISPOSED/);await assert.rejects(b,/DISPOSED/);});

tests/snapshot-bvh.test.js

@@ -0,0 +1,130 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SnapshotReader, SnapshotProtocolError } from "../static/render-data-snapshot.js";
+import { DerivedBvh } from "../static/bvh-core.js";
+import { RendererClient } from "../static/renderer-client.js";
+
+const align16 = value => (value + 15) & ~15;
+const componentCounts = [1, 1, 1, 3, 3, 1, 1, 1, 1, 1, 16, 3, 3, 1];
+const scalarTypes = [1, 1, 1, 2, 2, 1, 1, 1, 1, 1, 2, 2, 2, 1];
+
+function snapshotFixture({ instances = 1 } = {}) {
+  const memory = new WebAssembly.Memory({ initial: 4, maximum: 8, shared: true });
+  const words = new Uint32Array(memory.buffer);
+  const control = new Int32Array(memory.buffer, 0, 64);
+  const ptr = 256;
+  const counts = [1, 1, 1, 1, 1, ...Array(9).fill(instances)];
+  const offsets = [];
+  let cursor = 512;
+  for (let i = 0; i < 14; i++) {
+    offsets.push(cursor);
+    cursor = align16(cursor + counts[i] * componentCounts[i] * 4);
+  }
+  control.set([0x504e5359, 1, 256, 3, 64, 1, 1, 2, 1, 0, 7, 0, 4, 1, 0, 0]);
+  control.set([2, 1, 1, ptr, cursor, 7, 0, 1, instances, 1, 64, 0, 0, 0, 0, 0], 16);
+  const blob = new Uint32Array(memory.buffer, ptr, cursor / 4);
+  blob.set([0x31534452, 1, 64, cursor, 1, 7, 0, 14, 64, 32, 1, instances, 0x01020304, 3, 0, 0]);
+  for (let i = 0; i < 14; i++) {
+    blob.set([i + 1, scalarTypes[i], offsets[i], counts[i], componentCounts[i], componentCounts[i] * 4, 4, 0], 16 + i * 8);
+  }
+  const stream = i => scalarTypes[i] === 2
+    ? new Float32Array(memory.buffer, ptr + offsets[i], counts[i] * componentCounts[i])
+    : new Uint32Array(memory.buffer, ptr + offsets[i], counts[i] * componentCounts[i]);
+  stream(0)[0] = 4; stream(1)[0] = 2; stream(2)[0] = 1;
+  stream(3).set([-1, -1, -1]); stream(4).set([1, 1, 1]);
+  for (let i = 0; i < instances; i++) {
+    stream(5)[i] = 10 + i; stream(6)[i] = 3; stream(7)[i] = 4; stream(8)[i] = 2;
+    stream(9)[i] = 1; stream(13)[i] = 1;
+    stream(11).set([i * 4, -1, -1], i * 3); stream(12).set([i * 4 + 2, 1, 1], i * 3);
+  }
+  return { memory, control, ptr, cursor };
+}
+
+test("snapshot reader validates and pins an exact ABI snapshot", () => {
+  const f = snapshotFixture();
+  const reader = new SnapshotReader(f.memory, 0);
+  const result = reader.transaction(snapshot => ({
+    epoch: snapshot.epoch,
+    slot: snapshot.streams.instanceSlot[0],
+    min: [...snapshot.streams.instanceWorldMin],
+  }), 1);
+  assert.deepEqual(result, { epoch: 1, slot: 10, min: [0, -1, -1] });
+  assert.equal(Atomics.load(f.control, 16), 0);
+});
+
+test("snapshot reader rejects malformed control and WRITING slots", () => {
+  const bad = snapshotFixture();
+  bad.control[0] = 0;
+  assert.throws(() => new SnapshotReader(bad.memory, 0), SnapshotProtocolError);
+  const writing = snapshotFixture();
+  Atomics.store(writing.control, 16, 1);
+  assert.equal(new SnapshotReader(writing.memory, 0).transaction(() => true, 1), null);
+});
+
+test("snapshot reader refreshes memory after pinning", () => {
+  const f = snapshotFixture();
+  const reader = new SnapshotReader(f.memory, 0);
+  const original = Atomics.compareExchange;
+  let grew = false;
+  Atomics.compareExchange = (...args) => {
+    const result = original(...args);
+    if (!grew && args[1] === 16 && result === 2) { grew = true; f.memory.grow(1); }
+    return result;
+  };
+  try {
+    assert.equal(reader.transaction(snapshot => snapshot.instanceCount, 1), 1);
+    assert.equal(grew, true);
+  } finally {
+    Atomics.compareExchange = original;
+  }
+});
+
+function bvhSnapshot({ pickable = [1, 1], shifted = false } = {}) {
+  const count = 2;
+  return { instanceCount: count, streams: {
+    instanceSlot: Uint32Array.from([5, 6]), instanceGeneration: Uint32Array.from([1, 1]),
+    instanceMeshSlot: Uint32Array.from([2, 2]), instanceMeshGeneration: Uint32Array.from([4, 4]),
+    instancePickable: Uint32Array.from(pickable),
+    instanceWorldMin: Float32Array.from(shifted ? [10, -1, -1, 4, -1, -1] : [2, -1, -1, 4, -1, -1]),
+    instanceWorldMax: Float32Array.from(shifted ? [12, 1, 1, 6, 1, 1] : [3, 1, 1, 6, 1, 1]),
+  }};
+}
+
+test("BVH preserves topology for visibility/refit and reports world distances", () => {
+  const bvh = new DerivedBvh();
+  bvh.update(bvhSnapshot());
+  assert.equal(bvh.rebuilds, 1);
+  assert.equal(bvh.pick([0, 0, 0], [2, 0, 0], Infinity, 2)[0].distance, 2);
+  bvh.update(bvhSnapshot({ pickable: [0, 1], shifted: true }));
+  assert.equal(bvh.rebuilds, 1);
+  assert.equal(bvh.refits, 1);
+  assert.deepEqual(bvh.pick([0, 0, 0], [1, 0, 0], Infinity, 2).map(hit => hit.slot), [6]);
+});
+
+class WorkerMock extends EventTarget {
+  messages = []; terminated = false;
+  postMessage(message) { this.messages.push(message); }
+  terminate() { this.terminated = true; }
+  reply(data) { this.dispatchEvent(new MessageEvent("message", { data })); }
+}
+
+test("renderer pick returns gated instances and exact epoch", async () => {
+  const scene = snapshotFixture();
+  const ring = 8192;
+  const ringHeader = new Int32Array(scene.memory.buffer, ring, 16);
+  ringHeader.set([0x4e574159, 1, 1024, 24]);
+  const rendererWorker = new WorkerMock(), bvhWorker = new WorkerMock();
+  const bridge = { memory: scene.memory, ringPtr: ring, worker: rendererWorker, workerFactory: () => bvhWorker, free() {} };
+  const client = new RendererClient(bridge);
+  rendererWorker.reply({ type: "snapshot-init", controlPtr: 0, controlVersion: 1, schemaVersion: 1 });
+  rendererWorker.reply({ type: "snapshot-published", epoch: 1 });
+  const picking = client.pickRay([0, 0, 0], [1, 0, 0]);
+  const request = bvhWorker.messages.find(message => message.type === "pick");
+  bvhWorker.reply({ type: "pick", request: request.request, epoch: 1, stale: false, hits: [{ slot: 10, generation: 3, distance: 2 }] });
+  const result = await picking;
+  assert.equal(result.epoch, 1);
+  assert.equal(result.hits[0].distance, 2);
+  assert.equal(typeof result.hits[0].instance.setVisible, "function");
+  client.dispose();
+  assert.equal(bvhWorker.terminated, true);
+});