@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/gpu-driven-view.browser.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import {
+  runGpuDrivenViewGpuEvidence,
+  runGpuDrivenViewLifecycleEvidence,
+} from './gpu-driven-view-gpu-evidence';
+
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe.skipIf(!browserReady)('GPU-driven View Browser WebGPU', () => {
+  it('produces compact visible IDs and portable indirect args on the real browser device', async () => {
+    await expect(runGpuDrivenViewGpuEvidence()).resolves.toEqual({
+      visibleInstance: 0,
+      indexCount: 36,
+      instanceCount: 1,
+      firstIndex: 3,
+      baseVertex: -2,
+      firstInstance: 0,
+      overflow: 0,
+      persistentTranslationX: 0,
+    });
+  });
+
+  it('survives 300 frames of spawn/despawn capacity crossings without stale buffers', async () => {
+    await expect(runGpuDrivenViewLifecycleEvidence()).resolves.toEqual({
+      frames: 300,
+      bufferRebuilds: 4,
+      candidateCapacity: 8,
+    });
+  }, 30_000);
+});

package/src/__tests__/gpu-driven-view.dawn.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import {
+  runGpuDrivenViewGpuEvidence,
+  runGpuDrivenViewLifecycleEvidence,
+} from './gpu-driven-view-gpu-evidence';
+
+describe('GPU-driven View Dawn', () => {
+  it('produces compact visible IDs and portable indirect args on the real GPU API', async () => {
+    await expect(runGpuDrivenViewGpuEvidence()).resolves.toEqual({
+      visibleInstance: 0,
+      indexCount: 36,
+      instanceCount: 1,
+      firstIndex: 3,
+      baseVertex: -2,
+      firstInstance: 0,
+      overflow: 0,
+      persistentTranslationX: 0,
+    });
+  });
+
+  it('survives 300 frames of spawn/despawn capacity crossings without stale buffers', async () => {
+    await expect(runGpuDrivenViewLifecycleEvidence()).resolves.toEqual({
+      frames: 300,
+      bufferRebuilds: 4,
+      candidateCapacity: 8,
+    });
+  }, 30_000);
+});

package/src/__tests__/gpu-driven-view.unit.test.ts

@@ -0,0 +1,199 @@
+import { frustum, mat4 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import { BatchTopology } from '../gpu-driven/batch-topology';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+import { classifyGpuDrivenView } from './gpu-driven-view-reference';
+
+const material = {
+  baseColor: new Float32Array([1, 1, 1]),
+  metallic: 0,
+  roughness: 1,
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number, x: number, resourceClass = 'plain'): RenderableSnapshot {
+  const world = mat4.identity(mat4.create());
+  world[12] = x;
+  return {
+    assetHandle: 7,
+    transform: { world: new Float32Array(world) },
+    localAabb: new Float32Array([-0.25, -0.25, -0.25, 0.25, 0.25, 0.25]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: 3,
+        count: 36,
+        baseVertex: -2,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'opaque-pbr',
+        materialResourceClass: resourceClass,
+      },
+    ],
+  };
+}
+
+describe('GPU-driven batch topology and CPU oracle', () => {
+  it('patches topology only when compatibility membership changes', () => {
+    const projection = new RenderScene();
+    projection.apply([
+      { kind: 'create', snapshot: snapshot(1, 0) },
+      { kind: 'create', snapshot: snapshot(2, 0.5) },
+      { kind: 'create', snapshot: snapshot(3, 0, 'textured') },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.inspect()).toMatchObject({ batchCount: 2, candidateCount: 3, rebuilds: 1 });
+    expect(topology.plan()).toBe(topology.plan());
+
+    const transformOnly = projection.apply([
+      {
+        kind: 'update-transform',
+        worldId: 0,
+        entityKey: 1,
+        world: snapshot(1, 0.25).transform.world,
+      },
+    ]);
+    expect(topology.apply(transformOnly)).toBe(false);
+    expect(topology.plan()).toBe(topology.plan());
+    expect(topology.inspect().patches).toBe(0);
+
+    const removed = projection.apply([{ kind: 'remove', worldId: 0, entityKey: 3 }]);
+    expect(topology.apply(removed)).toBe(true);
+    expect(topology.inspect()).toMatchObject({ batchCount: 1, candidateCount: 2, patches: 1 });
+  });
+
+  it('compacts visible primitive indices and writes portable indexed indirect args', () => {
+    const projection = new RenderScene();
+    projection.apply([
+      { kind: 'create', snapshot: snapshot(1, 0) },
+      { kind: 'create', snapshot: snapshot(2, 10) },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const planes = frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create()));
+    const result = classifyGpuDrivenView(topology.plan(), projection.slotsSnapshot(), planes);
+
+    expect(result).toMatchObject({
+      candidateCount: 2,
+      rejectedCount: 1,
+      visibleCount: 1,
+      overflowedBatches: [],
+    });
+    expect([...result.visibleInstanceIndices]).toEqual([0, 0]);
+    expect([...result.batchCounters]).toEqual([1]);
+    const args = new DataView(result.indirectArgs);
+    expect(args.getUint32(0, true)).toBe(36);
+    expect(args.getUint32(4, true)).toBe(1);
+    expect(args.getUint32(8, true)).toBe(3);
+    expect(args.getInt32(12, true)).toBe(-2);
+    expect(args.getUint32(16, true)).toBe(0);
+  });
+
+  it('keeps multi-submesh draw items independent and writes non-indexed indirect args', () => {
+    const projection = new RenderScene();
+    const source = snapshot(1, 0);
+    const first = source.gpuDrivenDraws?.[0];
+    expect(first).toBeDefined();
+    if (first === undefined) return;
+    projection.apply([
+      {
+        kind: 'create',
+        snapshot: {
+          ...source,
+          gpuDrivenDraws: [
+            { ...first, kind: 'non-indexed', first: 0, count: 3 },
+            { ...first, kind: 'non-indexed', first: 3, count: 6 },
+          ],
+        },
+      },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const plan = topology.plan();
+    expect(plan).toMatchObject({ candidateCount: 2, batches: [{}, {}] });
+    const result = classifyGpuDrivenView(
+      plan,
+      projection.slotsSnapshot(),
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+    );
+    const firstArgs = new DataView(result.indirectArgs, plan.batches[0]?.indirectOffset ?? 0, 20);
+    const secondArgs = new DataView(result.indirectArgs, plan.batches[1]?.indirectOffset ?? 0, 20);
+    expect([firstArgs.getUint32(0, true), firstArgs.getUint32(8, true)]).toEqual([3, 0]);
+    expect([secondArgs.getUint32(0, true), secondArgs.getUint32(8, true)]).toEqual([6, 3]);
+    expect(firstArgs.getUint32(12, true)).toBe(0);
+    expect(secondArgs.getUint32(12, true)).toBe(0);
+  });
+
+  it('culls ordinary instance-local transforms and emits instance identities', () => {
+    const source = snapshot(1, 0);
+    const identity = mat4.identity(mat4.create());
+    const outside = mat4.identity(mat4.create());
+    outside[12] = 10;
+    const projection = new RenderScene();
+    projection.apply([
+      {
+        kind: 'create',
+        snapshot: {
+          ...source,
+          instances: {
+            transforms: new Float32Array([...identity, ...outside]),
+            instanceCount: 2,
+            cacheKey: 1,
+            archVersion: 1,
+          },
+        },
+      },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.inspect()).toMatchObject({ candidateCount: 2, ineligible: 0 });
+    const result = classifyGpuDrivenView(
+      topology.plan(),
+      projection.slotsSnapshot(),
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+    );
+    expect(result).toMatchObject({ candidateCount: 2, visibleCount: 1, rejectedCount: 1 });
+    expect([...result.visibleInstanceIndices]).toEqual([0, 0]);
+    expect(new DataView(result.indirectArgs).getUint32(4, true)).toBe(1);
+  });
+
+  it('reports overflow instead of silently accepting a truncated batch', () => {
+    const projection = new RenderScene();
+    projection.apply([
+      { kind: 'create', snapshot: snapshot(1, 0) },
+      { kind: 'create', snapshot: snapshot(2, 0.5) },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const plan = topology.plan();
+    const batch = plan.batches[0];
+    expect(batch).toBeDefined();
+    if (batch === undefined) return;
+    const result = classifyGpuDrivenView(
+      plan,
+      projection.slotsSnapshot(),
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+      new Map([[batch.batchId, 1]]),
+    );
+    expect(result.overflowedBatches).toEqual([batch.batchId]);
+    expect(result.visibleCount).toBe(1);
+  });
+
+  it('keeps the ineligible inspection bounded to current projection membership', () => {
+    const projection = new RenderScene();
+    const { localAabb: _localAabb, ...withoutBounds } = snapshot(1, 0);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.apply([{ kind: 'create', snapshot: withoutBounds }]).createdSlots);
+    expect(topology.inspect().ineligible).toBe(1);
+
+    const removed = projection.apply([{ kind: 'remove', worldId: 0, entityKey: 1 }]);
+    topology.apply(removed);
+    expect(topology.inspect().ineligible).toBe(0);
+  });
+});

package/src/__tests__/gpu-resource-store-stride.unit.test.ts

@@ -0,0 +1,59 @@
+import { World } from '@forgeax/engine-ecs';
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { rhi } from '@forgeax/engine-rhi-null';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../device/gpu-residency';
+
+describe('GpuResidencyCache mesh stride', () => {
+  it('keeps the canonical 18F plus UV1 stride from the complete projection', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const store = new GpuResidencyCache();
+    store.configureGpuDevice(
+      device,
+      undefined,
+      () => {
+        throw new Error('cubemap registration is not part of this test');
+      },
+      device.caps,
+    );
+
+    const mesh: MeshAsset = {
+      kind: 'mesh',
+      // The producer owns a canonical 20-float interleaved buffer:
+      // 18F skinned data plus one additional UV set. Importers must publish
+      // the complete map even when source accessors are sparse.
+      vertices: new Float32Array(4 * 20),
+      attributes: {
+        position: new Float32Array(4 * 3),
+        normal: new Float32Array(4 * 3),
+        uv: new Float32Array(4 * 2),
+        tangent: new Float32Array(4 * 4),
+        skinIndex: new Uint16Array(4 * 4),
+        skinWeight: new Float32Array(4 * 4),
+        uv1: new Float32Array(4 * 2),
+      },
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 0,
+          vertexCount: 4,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+      ],
+      materialSlots: [{ slotName: 'default' }],
+    };
+    const world = new World();
+    const handle = world.allocSharedRef('MeshAsset', mesh);
+
+    const resident = store.ensureResident(handle, mesh);
+
+    expect(resident.ok).toBe(true);
+    const entry = store.getMeshGpuHandles(handle);
+    expect(entry?.layoutProjection).toEqual(deriveVertexLayoutProjection(mesh.attributes));
+    expect(entry?.layoutProjection.arrayStride).toBe(80);
+    expect(entry?.vertexCount).toBe(4);
+  });
+});

package/src/__tests__/gpu-scene-render-graph-gpu.ts

@@ -0,0 +1,308 @@
+import { type CompiledRenderGraphInfo, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { Buffer, RenderPipeline, RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import { GpuScene } from '../gpu-scene';
+import { GPU_SCENE_LAYOUTS, GPU_SCENE_WGSL } from '../gpu-scene-schema';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const BUFFER_USAGE_STORAGE = 0x0080;
+const COMPUTE_VISIBILITY = 0x4;
+const VERTEX_VISIBILITY = 0x1;
+
+const CULL_WGSL = /* wgsl */ `
+${GPU_SCENE_WGSL}
+
+@group(0) @binding(0) var<storage, read> primitives: array<GpuScenePrimitive>;
+@group(0) @binding(1) var<storage, read> transforms: array<GpuSceneTransform>;
+@group(0) @binding(2) var<storage, read_write> visibleIndices: array<u32>;
+@group(0) @binding(3) var<storage, read_write> drawArgs: array<atomic<u32>>;
+
+@compute @workgroup_size(4)
+fn cull(
+  @builtin(local_invocation_id) localId: vec3<u32>,
+  @builtin(global_invocation_id) globalId: vec3<u32>,
+) {
+  if (localId.x == 0u) {
+    atomicStore(&drawArgs[0], 3u);
+    atomicStore(&drawArgs[1], 0u);
+    atomicStore(&drawArgs[2], 0u);
+    atomicStore(&drawArgs[3], 0u);
+  }
+  storageBarrier();
+  workgroupBarrier();
+
+  let index = globalId.x;
+  let primitive = primitives[index];
+  let translationX = transforms[primitive.transformIndex].currentWorld[3].x;
+  if ((primitive.flags & 1u) != 0u && abs(translationX) <= 1.0) {
+    let compacted = atomicAdd(&drawArgs[1], 1u);
+    visibleIndices[compacted] = index;
+  }
+}
+`;
+
+const RASTER_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> visibleIndices: array<u32>;
+
+struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) color: vec4<f32>,
+};
+
+@vertex
+fn vs(
+  @builtin(vertex_index) vertex: u32,
+  @builtin(instance_index) instance: u32,
+) -> VertexOutput {
+  var positions = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>(1.0, -1.0),
+    vec2<f32>(-1.0, 3.0),
+  );
+  let halfOffset = select(-0.5, 0.5, instance == 1u);
+  let projected = vec2<f32>(positions[vertex].x * 0.5 + halfOffset, positions[vertex].y);
+  let compactedIndex = visibleIndices[instance];
+  var output: VertexOutput;
+  output.position = vec4<f32>(projected, 0.0, 1.0);
+  output.color = vec4<f32>(f32(compactedIndex + 1u) / 4.0, 1.0, 0.0, 1.0);
+  return output;
+}
+
+@fragment
+fn fs(input: VertexOutput) -> @location(0) vec4<f32> {
+  return input.color;
+}
+`;
+
+const material = { materialHandle: 1 } as MaterialSnapshot;
+
+function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = translationX;
+  return {
+    assetHandle: 100 + entityKey,
+    transform: { world },
+    localAabb: new Float32Array([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+  };
+}
+
+function bufferBinding(buffer: Buffer) {
+  return { kind: 'buffer' as const, value: { buffer } };
+}
+
+export interface GpuSceneGraphEvidence {
+  readonly graph: CompiledRenderGraphInfo;
+  readonly pixels: readonly number[];
+}
+
+export async function runGpuSceneGraph(): Promise<GpuSceneGraphEvidence> {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  if (!device.caps.compute || !device.caps.storageBuffer || !device.caps.indirectDrawing) {
+    throw new Error(`required GPU Scene capabilities unavailable: ${JSON.stringify(device.caps)}`);
+  }
+  const availability = GpuScene.create(device, 4).unwrap();
+  if (availability.status !== 'available') throw new Error(availability.reason);
+  const scene = availability.scene;
+  const projection = new RenderScene();
+  scene
+    .sync(
+      projection.apply([
+        { kind: 'create', snapshot: snapshot(10, -3) },
+        { kind: 'create', snapshot: snapshot(11, -0.5) },
+        { kind: 'create', snapshot: snapshot(12, 0.5) },
+        { kind: 'create', snapshot: snapshot(13, 3) },
+      ]),
+    )
+    .unwrap();
+
+  const cullModule = (await createShaderModule(device, { code: CULL_WGSL })).unwrap();
+  const cullLayout = device
+    .createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: COMPUTE_VISIBILITY, buffer: { type: 'read-only-storage' } },
+        { binding: 1, visibility: COMPUTE_VISIBILITY, buffer: { type: 'read-only-storage' } },
+        { binding: 2, visibility: COMPUTE_VISIBILITY, buffer: { type: 'storage' } },
+        { binding: 3, visibility: COMPUTE_VISIBILITY, buffer: { type: 'storage' } },
+      ],
+    })
+    .unwrap();
+  const cullPipelineLayout = device
+    .createPipelineLayout({ bindGroupLayouts: [cullLayout] })
+    .unwrap();
+  const cullPipeline = device
+    .createComputePipeline({
+      layout: cullPipelineLayout,
+      compute: { module: cullModule, entryPoint: 'cull' },
+    })
+    .unwrap();
+  const rasterModule = (await createShaderModule(device, { code: RASTER_WGSL })).unwrap();
+  const rasterLayout = device
+    .createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: VERTEX_VISIBILITY, buffer: { type: 'read-only-storage' } },
+      ],
+    })
+    .unwrap();
+  const rasterPipelineLayout = device
+    .createPipelineLayout({ bindGroupLayouts: [rasterLayout] })
+    .unwrap();
+  const rasterPipeline: RenderPipeline = device
+    .createRenderPipeline({
+      layout: rasterPipelineLayout as never,
+      vertex: { module: rasterModule as never, entryPoint: 'vs', buffers: [] },
+      fragment: {
+        module: rasterModule as never,
+        entryPoint: 'fs',
+        targets: [{ format: 'rgba8unorm' }],
+      },
+      primitive: { topology: 'triangle-list' },
+    })
+    .unwrap();
+  const readbackBuffer = device
+    .createBuffer({
+      label: 'gpu-scene-graph-readback',
+      size: 256,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+
+  const capacity = scene.inspect().capacity;
+  const sceneUsage = BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST | 0x0004;
+  const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+  const primitives = graph
+    .importBuffer(
+      'gpu-scene-primitives',
+      { size: capacity * GPU_SCENE_LAYOUTS.primitive.stride, usage: sceneUsage },
+      () => scene.primitiveBuffer,
+    )
+    .unwrap();
+  const transforms = graph
+    .importBuffer(
+      'gpu-scene-transforms',
+      { size: capacity * GPU_SCENE_LAYOUTS.transform.stride, usage: sceneUsage },
+      () => scene.transformBuffer,
+    )
+    .unwrap();
+  const visibleIndices = graph.createBuffer('gpu-scene-visible-indices', { size: 16 }).unwrap();
+  const drawArgs = graph.createBuffer('gpu-scene-draw-args', { size: 16 }).unwrap();
+  const output = graph
+    .createTexture('gpu-scene-output', {
+      format: 'rgba8unorm',
+      size: { width: 2, height: 1 },
+    })
+    .unwrap();
+  const outputView = graph.view(output, { label: 'gpu-scene-output.view' }).unwrap();
+  const readback = graph
+    .importBuffer(
+      'gpu-scene-readback',
+      { size: 256, usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST },
+      () => readbackBuffer,
+    )
+    .unwrap();
+
+  graph
+    .addComputePass('gpu-scene-cull-compact-args', {
+      accesses: [
+        { resource: primitives, usage: 'storage-read' },
+        { resource: transforms, usage: 'storage-read' },
+        { resource: visibleIndices, usage: 'storage-write' },
+        { resource: drawArgs, usage: 'storage-write' },
+      ],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout: cullLayout,
+            entries: [
+              { binding: 0, resource: bufferBinding(resources.buffer(primitives).unwrap()) },
+              { binding: 1, resource: bufferBinding(resources.buffer(transforms).unwrap()) },
+              { binding: 2, resource: bufferBinding(resources.buffer(visibleIndices).unwrap()) },
+              { binding: 3, resource: bufferBinding(resources.buffer(drawArgs).unwrap()) },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(cullPipeline);
+        pass.setBindGroup(0, bindings);
+        pass.dispatchWorkgroups(1);
+      },
+    })
+    .unwrap();
+  graph
+    .addRasterPass('gpu-scene-indirect-raster', {
+      accesses: [
+        { resource: visibleIndices, usage: 'storage-read' },
+        { resource: drawArgs, usage: 'indirect-read' },
+        { resource: outputView, usage: 'color-attachment' },
+      ],
+      colorAttachments: [
+        {
+          view: outputView,
+          clearValue: { r: 0, g: 0, b: 0, a: 0 },
+          loadOp: 'clear',
+          storeOp: 'store',
+        },
+      ],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout: rasterLayout,
+            entries: [
+              {
+                binding: 0,
+                resource: bufferBinding(resources.buffer(visibleIndices).unwrap()),
+              },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(rasterPipeline);
+        pass.setBindGroup(0, bindings);
+        pass.drawIndirect(resources.buffer(drawArgs).unwrap(), 0);
+      },
+    })
+    .unwrap();
+  graph
+    .addCopyPass('gpu-scene-readback', {
+      accesses: [
+        { resource: outputView, usage: 'copy-src' },
+        { resource: readback, usage: 'copy-dst' },
+      ],
+      encode: ({ encoder, resources }) => {
+        encoder.copyTextureToBuffer(
+          { texture: resources.texture(output).unwrap() as unknown as GPUTexture },
+          {
+            buffer: resources.buffer(readback).unwrap() as unknown as GPUBuffer,
+            bytesPerRow: 256,
+            rowsPerImage: 1,
+          },
+          { width: 2, height: 1, depthOrArrayLayers: 1 },
+        );
+      },
+    })
+    .unwrap();
+
+  const compiled = graph.compile({ device, surfaceSize: { width: 2, height: 1 } }).unwrap();
+  const encoder = device.createCommandEncoder({ label: 'gpu-scene-graph-frame' }).unwrap();
+  compiled.execute({ encoder }).unwrap();
+  device.queue.submit([encoder.finish().unwrap()]).unwrap();
+  await device.queue.onSubmittedWorkDone();
+  const mapped = (await readbackBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+  const range = mapped.getMappedRange().unwrap();
+  const pixels = [...new Uint8Array(range.slice(0, 8))];
+  mapped.unmap();
+  const inspected = compiled.inspect();
+  (await compiled.retire()).unwrap();
+  scene.dispose();
+  device.destroyBuffer(readbackBuffer).unwrap();
+  return { graph: inspected, pixels };
+}

package/src/__tests__/gpu-scene-render-graph.browser.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { runGpuSceneGraph } from './gpu-scene-render-graph-gpu';
+
+describe('GPU Scene render graph in Chromium WebGPU', () => {
+  it('uses compute-generated visible instances and draw args in the browser path', async () => {
+    const evidence = await runGpuSceneGraph();
+    expect(evidence.graph.resources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ label: 'gpu-scene-primitives', origin: 'imported' }),
+        expect.objectContaining({ label: 'gpu-scene-transforms', origin: 'imported' }),
+        expect.objectContaining({ label: 'gpu-scene-draw-args', derivedUsage: 0x0180 }),
+      ]),
+    );
+    const reds = [evidence.pixels[0], evidence.pixels[4]].sort(
+      (left, right) => (left ?? 0) - (right ?? 0),
+    );
+    expect(reds).toEqual([128, 191]);
+  });
+});

package/src/__tests__/gpu-scene-render-graph.dawn.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { runGpuSceneGraph } from './gpu-scene-render-graph-gpu';
+
+describe('GPU Scene render graph on Dawn', () => {
+  it('culls and compacts imported persistent tables into indirect raster work', async () => {
+    const evidence = await runGpuSceneGraph();
+    expect(evidence.graph.passes.map((pass) => [pass.name, pass.kind])).toEqual([
+      ['gpu-scene-cull-compact-args', 'compute'],
+      ['gpu-scene-indirect-raster', 'raster'],
+      ['gpu-scene-readback', 'copy'],
+    ]);
+    expect(evidence.graph.passes[1]?.dependencies).toEqual(['gpu-scene-cull-compact-args']);
+    const reds = [evidence.pixels[0], evidence.pixels[4]].sort(
+      (left, right) => (left ?? 0) - (right ?? 0),
+    );
+    expect(reds).toEqual([128, 191]);
+    expect([evidence.pixels[1], evidence.pixels[5]]).toEqual([255, 255]);
+  });
+});

package/src/__tests__/gpu-scene-schema.unit.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { GPU_SCENE_LAYOUTS, GPU_SCENE_WGSL, gpuSceneFieldOffset } from '../gpu-scene-schema';
+
+describe('GPU Scene schema derivation', () => {
+  it('derives CPU strides, offsets, and WGSL from one field roster', () => {
+    expect(GPU_SCENE_LAYOUTS.primitive.stride).toBe(64);
+    expect(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'localBoundsMin')).toBe(32);
+    expect(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'localBoundsMax')).toBe(48);
+    expect(GPU_SCENE_LAYOUTS.transform.stride).toBe(128);
+    expect(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld')).toBe(64);
+    expect(GPU_SCENE_WGSL).toContain('struct GpuScenePrimitive');
+    expect(GPU_SCENE_WGSL).toContain('currentWorld: mat4x4<f32>');
+    expect(GPU_SCENE_WGSL).toContain('struct GpuSceneMaterial');
+    expect(GPU_SCENE_WGSL).toContain('baseVertex: i32');
+  });
+});