@forgeax/engine-render 0.1.27 → 0.1.29

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

@@ -62,9 +62,7 @@ describe('GPU-driven scaling contract', () => {
 
     const moved = mat4.identity(mat4.create());
     moved[12] = 3;
-    delta = projection.apply([
-      { kind: 'update-transform', worldId: 0, entityKey: 50_000, world: moved },
-    ]);
+    delta = projection.apply([{ kind: 'update', worldId: 0, entityKey: 50_000, world: moved }]);
     topologyChanged = topology.apply(delta);
   });
 

package/src/__tests__/gpu-driven-shadow-views.browser.test.ts

@@ -0,0 +1,63 @@
+import type { GraphBuffer } from '@forgeax/engine-render-graph';
+import { describe, expect, it } from 'vitest';
+import { shadowViewLabelPrefix, shadowViewRasterAccesses } from '../gpu-driven/shadow-views';
+import type { GpuDrivenViewGraphResources } from '../gpu-driven/view-gpu';
+
+describe('GPU-driven shadow views Browser ownership contract', () => {
+  it('keeps Browser coverage independent from adapter acquisition', () => {
+    expect([
+      shadowViewLabelPrefix({ kind: 'directional', index: 1 }),
+      shadowViewLabelPrefix({ kind: 'point', index: 2, face: 5 }),
+      shadowViewLabelPrefix({ kind: 'spot', index: 3 }),
+    ]).toEqual([
+      'gpu-driven.shadow.directional-cascade-1',
+      'gpu-driven.shadow.point-cube-face-2-5',
+      'gpu-driven.shadow.spot-atlas-3',
+    ]);
+  });
+
+  it('publishes one graph access contract for each shared shadow view output', () => {
+    const resources = {
+      primitive: {} as GraphBuffer,
+      instance: {} as GraphBuffer,
+      transform: {} as GraphBuffer,
+      material: {} as GraphBuffer,
+      visible: {} as GraphBuffer,
+      indirect: {} as GraphBuffer,
+      overflow: {} as GraphBuffer,
+    } satisfies GpuDrivenViewGraphResources;
+    expect(shadowViewRasterAccesses(resources)).toEqual([
+      { resource: resources.primitive, usage: 'storage-read' },
+      { resource: resources.instance, usage: 'storage-read' },
+      { resource: resources.transform, usage: 'storage-read' },
+      { resource: resources.material, usage: 'storage-read' },
+      { resource: resources.visible, usage: 'storage-read' },
+      { resource: resources.indirect, usage: 'indirect-read' },
+    ]);
+  });
+
+  it('keeps the view-local ABI limited to storage and indirect reads', () => {
+    const resources = {
+      primitive: {} as GraphBuffer,
+      instance: {} as GraphBuffer,
+      transform: {} as GraphBuffer,
+      material: {} as GraphBuffer,
+      visible: {} as GraphBuffer,
+      indirect: {} as GraphBuffer,
+      overflow: {} as GraphBuffer,
+    } satisfies GpuDrivenViewGraphResources;
+    const accesses = shadowViewRasterAccesses(resources);
+    expect(
+      accesses.every(
+        (access) => access.usage === 'storage-read' || access.usage === 'indirect-read',
+      ),
+    ).toBe(true);
+    expect(
+      accesses.every((access) =>
+        (Object.values(resources) as readonly GraphBuffer[]).includes(
+          access.resource as GraphBuffer,
+        ),
+      ),
+    ).toBe(true);
+  });
+});

package/src/__tests__/gpu-driven-shadow-views.dawn.test.ts

@@ -0,0 +1,294 @@
+import { frustum, mat4 } from '@forgeax/engine-math';
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { BatchTopology } from '../gpu-driven/batch-topology';
+import { type ShadowViewIdentity, ShadowViewStatePool } from '../gpu-driven/shadow-views';
+import { GPU_DRIVEN_VIEW_WGSL } from '../gpu-driven/view-gpu';
+import { GpuScene } from '../gpu-scene';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+import { addTypedShadowPasses } from '../typed-shadow-passes';
+
+const GPU_MAP_MODE_READ = 0x0001;
+
+const material = {
+  baseColor: new Float32Array([1, 1, 1]),
+  metallic: 0,
+  roughness: 1,
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number, assetHandle = 3, x = 0): RenderableSnapshot {
+  const world = new Float32Array(mat4.identity(mat4.create()));
+  world[12] = x;
+  return {
+    assetHandle,
+    transform: { world },
+    localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: 0,
+        count: 36,
+        baseVertex: 0,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'opaque',
+        materialResourceClass: 'plain',
+      },
+    ],
+  };
+}
+
+function updateSnapshot(value: RenderableSnapshot) {
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    snapshot: value,
+  };
+}
+
+function topology(): RenderPipelineTopology {
+  return {
+    pipelineId: 'forgeax::standard',
+    config: undefined,
+    surface: {
+      width: 64,
+      height: 64,
+      storageFormat: 'rgba8unorm',
+      viewFormat: 'rgba8unorm',
+    },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'off' },
+    shadow: {
+      directional: { mapSize: 32, cascadeCount: 2 },
+      spotMapSize: 32,
+      pointCount: 1,
+      pointFaceSize: 16,
+      spotCount: 1,
+    },
+    lane: {
+      compute: true,
+      storageBuffer: true,
+      multisample: false,
+      maxColorAttachments: 8,
+    },
+    featureTopologySignature: 'shadow-view-dawn-test',
+    gpuDrivenTopologySignature: 'shadow-view-dawn-test',
+  };
+}
+
+const identities: readonly ShadowViewIdentity[] = [
+  { kind: 'directional', index: 0 },
+  { kind: 'point', index: 0, face: 0 },
+  { kind: 'spot', index: 0 },
+];
+
+describe('GPU-driven shadow views Dawn structural evidence', () => {
+  it('keeps all shadow attachments depth-write owned by the typed graph', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const added = addTypedShadowPasses(graph, topology());
+    expect(added.ok).toBe(true);
+    if (!added.ok) return;
+
+    const compiled = graph.compile({ device, surfaceSize: { width: 64, height: 64 } }).unwrap();
+    const shadowPasses = compiled
+      .inspect()
+      .passes.filter(
+        (pass) =>
+          pass.name.startsWith('shadowCascade') ||
+          pass.name.startsWith('point-shadow-') ||
+          pass.name.startsWith('spot-shadow-'),
+      );
+    expect(shadowPasses).toHaveLength(9);
+    expect(
+      shadowPasses.every((pass) =>
+        pass.accesses.some((access) => access.usage === 'depth-stencil-write'),
+      ),
+    ).toBe(true);
+  });
+
+  it('executes three view-local culls and reads one indirect result per view', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (
+      await rhi.createShaderModule(device, {
+        code: GPU_DRIVEN_VIEW_WGSL,
+        label: 'gpu-driven-shadow-views-dawn',
+      })
+    ).unwrap();
+    const projection = new RenderScene();
+    const delta = projection.apply([
+      updateSnapshot(snapshot(1, 3, -0.5)),
+      updateSnapshot(snapshot(2, 4, 0.5)),
+    ]);
+    const sceneAvailability = GpuScene.create(device, 2).unwrap();
+    expect(sceneAvailability.status).toBe('available');
+    if (sceneAvailability.status !== 'available') return;
+    sceneAvailability.scene.sync(delta).unwrap();
+    const topologyOwner = new BatchTopology();
+    topologyOwner.rebuild(projection.slotsSnapshot());
+    const planes = frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create()));
+    const pool = ShadowViewStatePool.create({
+      device,
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    }).unwrap();
+    const inputs = identities.map((identity) => ({
+      identity,
+      sourcePlan: topologyOwner.plan(),
+      scene: sceneAvailability.scene,
+      planes,
+      cacheToken: `${identity.kind}:dawn`,
+      candidatePrimitiveIndices: [0, 1],
+    }));
+    for (const input of inputs) {
+      const update = pool.update(input).unwrap();
+      expect(update.cache).toBe('invalidated');
+      expect(update.plan.candidateCount).toBe(2);
+      expect(update.plan.batches).toHaveLength(2);
+    }
+
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const projections = identities.map((identity) => pool.project(graph, identity).unwrap());
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    const passNames = compiled.inspect().passes.map((pass) => pass.name);
+    expect(passNames).toEqual(
+      identities.flatMap((identity) => {
+        const prefix =
+          identity.kind === 'directional'
+            ? `gpu-driven.shadow.directional-cascade-${identity.index}`
+            : identity.kind === 'point'
+              ? `gpu-driven.shadow.point-cube-face-${identity.index}-${identity.face}`
+              : `gpu-driven.shadow.spot-atlas-${identity.index}`;
+        return [
+          `${prefix}.view-reset`,
+          `${prefix}.frustum-compact`,
+          `${prefix}.finalize-indirect`,
+          `${prefix}.lod-selection-readback`,
+        ];
+      }),
+    );
+
+    const readbacks = projections.map((projection, index) => {
+      const view = projection.view;
+      const visible = view.visibleBuffer;
+      const indirect = view.indirectBuffer;
+      const overflow = view.overflowBuffer;
+      if (visible === undefined || indirect === undefined || overflow === undefined) {
+        throw new Error(`shadow view ${index} has no GPU output buffers`);
+      }
+      return {
+        view,
+        visible,
+        indirect,
+        overflow,
+        visibleReadback: device
+          .createBuffer({
+            label: `shadow-view-${index}-visible-readback`,
+            size: 520,
+            usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+          })
+          .unwrap(),
+        indirectReadback: device
+          .createBuffer({
+            label: `shadow-view-${index}-indirect-readback`,
+            size: 40,
+            usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+          })
+          .unwrap(),
+        overflowReadback: device
+          .createBuffer({
+            label: `shadow-view-${index}-overflow-readback`,
+            size: 4,
+            usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+          })
+          .unwrap(),
+      };
+    });
+    const encoder = device.createCommandEncoder({ label: 'gpu-driven-shadow-views-dawn' }).unwrap();
+    compiled.execute({ encoder }).unwrap();
+    for (const readback of readbacks) {
+      encoder.copyBufferToBuffer(readback.visible, 0, readback.visibleReadback, 0, 520);
+      encoder.copyBufferToBuffer(readback.indirect, 0, readback.indirectReadback, 0, 40);
+      encoder.copyBufferToBuffer(
+        readback.overflow,
+        readback.view.overflowByteOffset,
+        readback.overflowReadback,
+        0,
+        4,
+      );
+    }
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    await device.queue.onSubmittedWorkDone();
+    pool._commitResourceReplacement();
+
+    for (const readback of readbacks) {
+      const visibleMap = (await readback.visibleReadback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
+      const visible = new Uint32Array(visibleMap.getMappedRange().unwrap().slice(0));
+      visibleMap.unmap();
+      const indirectMap = (await readback.indirectReadback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
+      const indirect = new Uint32Array(indirectMap.getMappedRange().unwrap().slice(0));
+      indirectMap.unmap();
+      const overflowMap = (await readback.overflowReadback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
+      const overflow = new Uint32Array(overflowMap.getMappedRange().unwrap().slice(0));
+      overflowMap.unmap();
+      expect(Array.from(visible.slice(0, 2))).toEqual([0, 0]);
+      // Each indirect batch binds its own projected Mesh table, so the
+      // compact visible row is batch-local rather than a global primitive id.
+      expect(Array.from(visible.slice(128, 130))).toEqual([0, 1]);
+      expect(Array.from(indirect)).toEqual([36, 1, 0, 0, 0, 36, 1, 0, 0, 0]);
+      expect(Array.from(overflow)).toEqual([0]);
+      device.destroyBuffer(readback.visibleReadback);
+      device.destroyBuffer(readback.indirectReadback);
+      device.destroyBuffer(readback.overflowReadback);
+    }
+
+    for (const input of inputs) expect(pool.update(input).unwrap().cache).toBe('hit');
+    const hitGraph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    for (const identity of identities)
+      expect(pool.project(hitGraph, identity).unwrap().passNames).toEqual([]);
+    expect(
+      hitGraph
+        .compile({ device, surfaceSize: { width: 1, height: 1 } })
+        .unwrap()
+        .inspect().passes,
+    ).toHaveLength(0);
+
+    const pointIdentity = identities[1];
+    const pointInput = inputs[1];
+    if (pointIdentity === undefined || pointInput === undefined) {
+      throw new Error('point shadow input missing');
+    }
+    pool.invalidate(pointIdentity);
+    expect(pool.update(pointInput).unwrap().cache).toBe('invalidated');
+    const invalidatedGraph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const directionalIdentity = identities[0];
+    const spotIdentity = identities[2];
+    if (directionalIdentity === undefined || spotIdentity === undefined) {
+      throw new Error('shadow identities missing');
+    }
+    expect(pool.project(invalidatedGraph, directionalIdentity).unwrap().passNames).toEqual([]);
+    expect(pool.project(invalidatedGraph, pointIdentity).unwrap().passNames).toHaveLength(3);
+    expect(pool.project(invalidatedGraph, spotIdentity).unwrap().passNames).toEqual([]);
+    expect(
+      invalidatedGraph
+        .compile({ device, surfaceSize: { width: 1, height: 1 } })
+        .unwrap()
+        .inspect().passes,
+    ).toHaveLength(4);
+
+    pool.dispose();
+    sceneAvailability.scene.dispose();
+  });
+});

package/src/__tests__/gpu-driven-shadow-views.integration.test.ts

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
+import { addTypedShadowPasses } from '../typed-shadow-passes';
+
+const typedShadowSource = readFileSync(
+  new URL('../typed-shadow-passes.ts', import.meta.url),
+  'utf8',
+);
+const shadowRecordSource = readFileSync(
+  new URL('../record/shadow-pass.ts', import.meta.url),
+  'utf8',
+);
+
+function topology(): RenderPipelineTopology {
+  return {
+    pipelineId: 'forgeax::standard',
+    config: undefined,
+    surface: {
+      width: 64,
+      height: 64,
+      storageFormat: 'rgba8unorm',
+      viewFormat: 'rgba8unorm',
+    },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'off' },
+    shadow: {
+      directional: { mapSize: 32, cascadeCount: 2 },
+      spotMapSize: 32,
+      pointCount: 1,
+      pointFaceSize: 16,
+      spotCount: 1,
+    },
+    lane: {
+      compute: true,
+      storageBuffer: true,
+      multisample: false,
+      maxColorAttachments: 8,
+    },
+    featureTopologySignature: 'shadow-view-test',
+    gpuDrivenTopologySignature: 'shadow-view-test',
+  };
+}
+
+function sourceRegion(source: string, startMarker: string, endMarker: string): string {
+  const start = source.indexOf(startMarker);
+  const end = source.indexOf(endMarker, start + startMarker.length);
+  return source.slice(start, end < 0 ? source.length : end);
+}
+
+describe('GPU-driven shadow view graph integration', () => {
+  it('keeps directional, point, and spot views in one typed graph', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const input = topology();
+
+    const added = addTypedShadowPasses(graph, input);
+    expect(added.ok).toBe(true);
+    if (!added.ok) return;
+
+    const compiled = graph
+      .compile({
+        device,
+        surfaceSize: { width: input.surface.width, height: input.surface.height },
+      })
+      .unwrap();
+    expect(compiled.inspect().passes.map((pass) => pass.name)).toEqual([
+      'shadowCascade0',
+      'shadowCascade1',
+      'directional-shadow-observation',
+      'point-shadow-0-0',
+      'point-shadow-0-1',
+      'point-shadow-0-2',
+      'point-shadow-0-3',
+      'point-shadow-0-4',
+      'point-shadow-0-5',
+      'spot-shadow-0',
+    ]);
+  });
+
+  it.each([
+    ['point cube face', 'if (topology.shadow.pointCount > 0)', 'const spot ='],
+    ['spot atlas', 'const spot =', 'return ok({ directional: directional.value'],
+  ])('%s carries an explicit cache predicate', (_name, start, end) => {
+    const region = sourceRegion(typedShadowSource, start, end);
+    expect(region).toMatch(/executeIf|cache(?:Hit|Reuse)/);
+  });
+
+  it('separates the capable GPU shadow lane from the CPU caster enumerator', () => {
+    expect(shadowRecordSource).toMatch(
+      /\b(?:recordGpuDriven|recordIndirect|gpuDrivenShadow|gpuDrivenView|indirectShadow)\b/i,
+    );
+    expect(shadowRecordSource).toMatch(/recordCpuShadow|recordFallbackShadow|validatedOrdered/i);
+  });
+});

package/src/__tests__/gpu-driven-shadow-views.unit.test.ts

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { frustum, mat4 } from '@forgeax/engine-math';
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { BatchTopology } from '../gpu-driven/batch-topology';
+import { type ShadowViewIdentity, ShadowViewStatePool } from '../gpu-driven/shadow-views';
+import { GpuScene } from '../gpu-scene';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const shadowViewsPath = new URL('../gpu-driven/shadow-views.ts', import.meta.url);
+const shadowViewsSource = existsSync(shadowViewsPath) ? readFileSync(shadowViewsPath, 'utf8') : '';
+const viewSource = readFileSync(new URL('../gpu-driven/view-gpu.ts', import.meta.url), 'utf8');
+
+const shadowKinds = [
+  { name: 'directional cascade', token: 'directional' },
+  { name: 'point cube face', token: 'point' },
+  { name: 'spot atlas', token: 'spot' },
+] as const;
+
+const material = {
+  baseColor: new Float32Array([1, 1, 1]),
+  metallic: 0,
+  roughness: 1,
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number): RenderableSnapshot {
+  return {
+    assetHandle: 3,
+    transform: { world: new Float32Array(mat4.identity(mat4.create())) },
+    localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: 0,
+        count: 36,
+        baseVertex: 0,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'opaque',
+        materialResourceClass: 'plain',
+      },
+    ],
+  };
+}
+
+function updateSnapshot(value: RenderableSnapshot) {
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    snapshot: value,
+  };
+}
+
+describe('GPU-driven shadow view owner contract', () => {
+  it('publishes a single shared shadow view state pool', () => {
+    expect(existsSync(shadowViewsPath)).toBe(true);
+    expect(shadowViewsSource).toMatch(/GpuDrivenView/);
+    expect(shadowViewsSource).toMatch(/SubmissionPlan|BatchTopology/);
+    expect(shadowViewsSource).toMatch(/Map/);
+    expect(shadowViewsSource).not.toMatch(/new\s+BatchTopology/);
+  });
+
+  it.each(shadowKinds)('$name has a cache-hit and invalidation decision', ({ token }) => {
+    expect(shadowViewsSource).toContain(token);
+    expect(shadowViewsSource).toMatch(/cache|Cache|reuse|Reuse/);
+    expect(shadowViewsSource).toMatch(/invalidat|Invalidat|generation|Generation/);
+  });
+
+  it('keeps visibility, counters, and indirect arguments view-local', () => {
+    expect(viewSource).toMatch(/visible|visibility/);
+    expect(viewSource).toMatch(/counter|Counter/);
+    expect(viewSource).toMatch(/indirect|Indirect/);
+    expect(viewSource).toMatch(/labelPrefix|viewPrefix|viewId/);
+  });
+
+  it('reuses each view on a cache hit and invalidates only that view', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const projection = new RenderScene();
+    const delta = projection.apply([updateSnapshot(snapshot(1))]);
+    const sceneAvailability = GpuScene.create(device, 1).unwrap();
+    expect(sceneAvailability.status).toBe('available');
+    if (sceneAvailability.status !== 'available') return;
+    sceneAvailability.scene.sync(delta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const pool = ShadowViewStatePool.create({
+      device,
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    }).unwrap();
+    const planes = frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create()));
+    const identities: readonly ShadowViewIdentity[] = [
+      { kind: 'directional', index: 0 },
+      { kind: 'point', index: 0 },
+      { kind: 'spot', index: 0 },
+    ];
+    for (const identity of identities) {
+      const input = {
+        identity,
+        sourcePlan: topology.plan(),
+        scene: sceneAvailability.scene,
+        planes,
+        cacheToken: `${identity.kind}:stable`,
+        candidatePrimitiveIndices: [0],
+      } as const;
+      const first = pool.update(input).unwrap();
+      expect(first.cache).toBe('invalidated');
+      expect(first.plan.candidateCount).toBe(1);
+      const firstInspection = first.view.inspect();
+
+      // Cache reuse is published only after the frame's successful submit
+      // commit. The unit fixture explicitly advances that transaction before
+      // asking the pool for a hit.
+      pool._commitResourceReplacement();
+
+      const hit = pool.update(input).unwrap();
+      expect(hit.cache).toBe('hit');
+      expect(hit.generation).toBe(first.generation);
+      expect(hit.view.inspect().updateCount).toBe(firstInspection.updateCount);
+
+      const hitGraph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+      const skipped = pool.project(hitGraph, identity).unwrap();
+      expect(skipped.cache).toBe('hit');
+      expect(skipped.passNames).toEqual([]);
+      expect(
+        hitGraph
+          .compile({ device, surfaceSize: { width: 1, height: 1 } })
+          .unwrap()
+          .inspect().passes,
+      ).toHaveLength(0);
+
+      const changedMaterial = {
+        ...material,
+        baseColor: new Float32Array([0.25, 1, 1]),
+      } as MaterialSnapshot;
+      const changedDelta = projection.apply([
+        updateSnapshot({
+          ...snapshot(1),
+          material: changedMaterial,
+          materials: [changedMaterial],
+        }),
+      ]);
+      sceneAvailability.scene.sync(changedDelta).unwrap();
+      const contentInvalidated = pool.update(input).unwrap();
+      expect(contentInvalidated.cache).toBe('invalidated');
+
+      pool.invalidate(identity);
+      const invalidated = pool.update(input).unwrap();
+      expect(invalidated.cache).toBe('invalidated');
+      expect(invalidated.generation).toBe(first.generation + 2);
+      expect(invalidated.view.inspect().updateCount).toBe(firstInspection.updateCount + 2);
+    }
+
+    pool.dispose();
+    sceneAvailability.scene.dispose();
+  });
+});

package/src/__tests__/gpu-driven-skin-contract.test-d.ts

@@ -0,0 +1,11 @@
+import type { PreparedGpuDrivenDraw } from '../gpu-driven/prepared-draw';
+import type { SkinPaletteReceipt } from '../systems/skin-palette-types';
+
+declare const draw: PreparedGpuDrivenDraw;
+declare const receipt: SkinPaletteReceipt;
+
+// The skin address and palette receipt are one generation-scoped contract.
+const generation: number = receipt.generation;
+const address = draw.skinPaletteAddress;
+void generation;
+void address;