@forgeax/engine-render 0.1.2

package/src/__tests__/render-scene-projection.unit.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from 'vitest';
+import { RenderSceneProjection } from '../render-scene-projection';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+
+const material = {} 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: 1,
+    transform: { world },
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+  };
+}
+
+function factSnapshot(
+  entityKey: number,
+  translationX: number,
+  options: Partial<RenderableSnapshot> = {},
+): RenderableSnapshot {
+  return {
+    ...snapshot(entityKey, translationX),
+    localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    ...options,
+  };
+}
+
+describe('RenderSceneProjection', () => {
+  it('does not manufacture a material revision from equivalent shared object graphs', () => {
+    const projection = new RenderSceneProjection();
+    const initialShared = { value: 1 };
+    const initialMaterial = {
+      first: initialShared,
+      second: initialShared,
+    } as unknown as MaterialSnapshot;
+    const initial = {
+      ...snapshot(1, 0),
+      material: initialMaterial,
+      materials: [initialMaterial],
+    };
+    projection.reset([initial]);
+    projection.commitSubmission(projection.captureSubmission([initial]));
+
+    const rebuiltShared = { value: 1 };
+    const rebuiltMaterial = {
+      first: rebuiltShared,
+      second: rebuiltShared,
+    } as unknown as MaterialSnapshot;
+    projection.replaceCurrent([
+      {
+        ...snapshot(1, 0),
+        material: rebuiltMaterial,
+        materials: [rebuiltMaterial],
+      },
+    ]);
+
+    expect(
+      projection.withTemporal(projection.materialize()[0] as RenderableSnapshot).temporal,
+    ).toMatchObject({
+      previousSource: 'last-submitted',
+      reactive: false,
+      reactiveReasons: [],
+    });
+  });
+
+  it('coalesces create and transform updates into one stable slot', () => {
+    const projection = new RenderSceneProjection();
+    const initial = snapshot(7, 1);
+    const updatedWorld = new Float32Array(initial.transform.world);
+    updatedWorld[12] = 9;
+
+    const result = projection.apply([
+      { kind: 'create', snapshot: initial },
+      { kind: 'update-transform', worldId: 0, entityKey: 7, world: updatedWorld },
+    ]);
+
+    expect(result).toMatchObject({ created: 1, updated: 0, removed: 0, recreated: 0 });
+    expect(projection.inspect().current).toEqual([
+      expect.objectContaining({ slot: 0, generation: 0, worldId: 0, entityKey: 7 }),
+    ]);
+    expect(projection.materialize()[0]?.transform.world[12]).toBe(9);
+  });
+
+  it('cancels a transient create/remove pair without allocating a slot', () => {
+    const projection = new RenderSceneProjection();
+
+    const result = projection.apply([
+      { kind: 'create', snapshot: snapshot(3, 1) },
+      { kind: 'remove', worldId: 0, entityKey: 3 },
+    ]);
+
+    expect(result).toMatchObject({ created: 0, updated: 0, removed: 0, recreated: 0 });
+    expect(projection.inspect().current).toEqual([]);
+  });
+
+  it('bumps generation when remove and recreate reuse a slot', () => {
+    const projection = new RenderSceneProjection();
+    projection.apply([{ kind: 'create', snapshot: snapshot(5, 1) }]);
+    const before = projection.inspect().current[0];
+
+    const result = projection.apply([
+      { kind: 'remove', worldId: 0, entityKey: 5 },
+      { kind: 'create', snapshot: snapshot(5, 2) },
+      { kind: 'update-transform', worldId: 0, entityKey: 5, world: snapshot(5, 7).transform.world },
+    ]);
+
+    const after = projection.inspect().current[0];
+    expect(result).toMatchObject({ created: 0, updated: 0, removed: 0, recreated: 1 });
+    expect(after?.slot).toBe(before?.slot);
+    expect(after?.generation).toBe((before?.generation ?? -1) + 1);
+    expect(projection.materialize()[0]?.transform.world[12]).toBe(7);
+  });
+
+  it('ignores an update that arrives after removal', () => {
+    const projection = new RenderSceneProjection();
+    projection.apply([{ kind: 'create', snapshot: snapshot(9, 1) }]);
+
+    const result = projection.apply([
+      { kind: 'remove', worldId: 0, entityKey: 9 },
+      { kind: 'update-transform', worldId: 0, entityKey: 9, world: snapshot(9, 4).transform.world },
+    ]);
+
+    expect(result).toMatchObject({ removed: 1, ignoredLateUpdates: 1 });
+    expect(projection.inspect().current).toEqual([]);
+  });
+
+  it('keeps identical entity handles isolated by World identity', () => {
+    const projection = new RenderSceneProjection();
+    projection.apply([
+      { kind: 'create', snapshot: snapshot(1, 3) },
+      { kind: 'create', snapshot: { ...snapshot(1, 8), worldId: 1 } },
+    ]);
+
+    expect(projection.materialize().map((record) => record.transform.world[12])).toEqual([3, 8]);
+  });
+
+  it('keeps static BVH and dynamic loose-tree ownership conservative and revisioned', () => {
+    const projection = new RenderSceneProjection();
+    projection.apply([
+      {
+        kind: 'create',
+        snapshot: factSnapshot(1, 0, { sceneFact: { mobility: 'static' } }),
+      },
+      {
+        kind: 'create',
+        snapshot: factSnapshot(2, 10, { sceneFact: { mobility: 'dynamic' } }),
+      },
+      { kind: 'create', snapshot: factSnapshot(3, 20) },
+      { kind: 'create', snapshot: snapshot(4, 30) },
+    ]);
+
+    const initial = projection.inspect().spatialIndex;
+    expect(initial.static.entries).toBe(1);
+    expect(initial.dynamic).toMatchObject({
+      entries: 3,
+      dynamicEntries: 1,
+      unknownEntries: 2,
+      unboundedEntries: 1,
+    });
+    const query = projection.querySpatialIndex(new Float32Array([-2, -2, -2, 12, 2, 2]), {
+      verifyAgainstBruteForce: true,
+    });
+    expect(query.hits.map((hit) => [hit.entityKey, hit.owner, hit.mobility])).toEqual([
+      [1, 'static-bvh', 'static'],
+      [2, 'dynamic-loose-tree', 'dynamic'],
+      [4, 'dynamic-loose-tree', 'unknown'],
+    ]);
+    expect(query.falseNegativeSlots).toEqual([]);
+    for (let center = -4; center <= 34; center += 0.5) {
+      const referenceChecked = projection.querySpatialIndex(
+        new Float32Array([center - 0.25, -2, -2, center + 0.25, 2, 2]),
+        { verifyAgainstBruteForce: true },
+      );
+      expect(referenceChecked.falseNegativeSlots).toEqual([]);
+    }
+
+    const moved = factSnapshot(2, 11).transform.world;
+    projection.apply([{ kind: 'update-transform', worldId: 0, entityKey: 2, world: moved }]);
+    const afterDynamicMove = projection.inspect().spatialIndex;
+    expect(afterDynamicMove.static.revision).toBe(initial.static.revision);
+    expect(afterDynamicMove.dynamic.revision).toBeGreaterThan(initial.dynamic.revision);
+
+    projection.apply([
+      {
+        kind: 'create',
+        snapshot: factSnapshot(1, 0, { sceneFact: { mobility: 'dynamic' } }),
+      },
+    ]);
+    const afterMobilityChange = projection.inspect().spatialIndex;
+    expect(afterMobilityChange.static.entries).toBe(0);
+    expect(afterMobilityChange.dynamic.dynamicEntries).toBe(2);
+    expect(afterMobilityChange).toMatchObject({
+      bruteForceComparisons: 78,
+      falseNegatives: 0,
+    });
+  });
+});

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -0,0 +1,125 @@
+import type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import {
+  resolveMaterialShaderBindingContract,
+  resolveMaterialShaderVertexInputContract,
+  selectHdrpPbrPrewarmVariants,
+} from '../renderer/renderer-factory';
+
+describe('material shader binding contract', () => {
+  it('recognizes a world-space shader that reads only the canonical view uniform', () => {
+    const source = `
+      struct View { worldViewProj: mat4x4<f32> }
+      @group(0) @binding(0) var<uniform> view: View;
+      @vertex fn vs_main() -> @builtin(position) vec4<f32> { return view.worldViewProj[0]; }
+    `;
+
+    expect(resolveMaterialShaderBindingContract(source)).toBe('view-only');
+  });
+
+  it('recognizes the canonical view name after naga-oil import mangling', () => {
+    const source = `
+      @group(0) @binding(0)
+      var<uniform> viewX_naga_oil_mod_XMZXXEZ3FMF4F65TJMV3TUOTDN5WW233OX: View;
+    `;
+
+    expect(resolveMaterialShaderBindingContract(source)).toBe('view-only');
+  });
+
+  it('keeps shaders with material groups on the full render-material layout', () => {
+    const source = `
+      @group(0) @binding(0) var<uniform> view: mat4x4<f32>;
+      @group(1) @binding(0) var<uniform> material: vec4<f32>;
+    `;
+
+    expect(resolveMaterialShaderBindingContract(source)).toBe('render-material');
+  });
+
+  it('recognizes a group-zero sampled depth resource without inventing a view uniform', () => {
+    const source = `
+      @group(0) @binding(0) var sceneDepth: texture_depth_2d;
+      @fragment fn fs_main(@builtin(position) position: vec4<f32>) -> @location(0) vec4<f32> {
+        return vec4<f32>(textureLoad(sceneDepth, vec2<i32>(position.xy), 0));
+      }
+    `;
+
+    expect(resolveMaterialShaderBindingContract(source)).toBe('group-0-resource');
+  });
+
+  it('keeps the canonical view uniform and scene depth in one group-zero layout', () => {
+    const source = `
+      struct View { inverseViewProj: mat4x4<f32> }
+      @group(0) @binding(0) var<uniform> view: View;
+      @group(0) @binding(1) var sceneDepth: texture_depth_2d;
+    `;
+
+    expect(resolveMaterialShaderBindingContract(source)).toBe('view-with-resource');
+  });
+});
+
+describe('material shader vertex input contract', () => {
+  it('recognizes VsIn-style vertex input structs', () => {
+    const source = `
+      struct VsIn { @location(0) position: vec3<f32> }
+      struct VsOut { @builtin(position) position: vec4<f32> }
+      @vertex fn vs_main(input: VsIn) -> VsOut { var out: VsOut; return out }
+    `;
+
+    expect(resolveMaterialShaderVertexInputContract(source)).toBe('render-material');
+  });
+
+  it('does not treat fullscreen output locations as vertex inputs', () => {
+    const source = `
+      struct FullscreenOutput {
+        @builtin(position) position: vec4<f32>,
+        @location(0) uv: vec2<f32>,
+      }
+      @vertex fn vs_main(@builtin(vertex_index) vertexIndex: u32) -> FullscreenOutput {
+        var out: FullscreenOutput;
+        return out;
+      }
+    `;
+
+    expect(resolveMaterialShaderVertexInputContract(source)).toBe('none');
+  });
+});
+
+describe('PBR variant boot prewarm contract', () => {
+  it('prewarms every device HDRP variant, including the no-color variant', () => {
+    const manifest = {
+      identifier: 'forgeax::default-standard-pbr',
+      sourcePath: 'standard-pbr.wgsl',
+      composedWgsl: 'default',
+      paramSchema: '[]',
+      variants: [
+        {
+          definesKey: '',
+          defines: { CLUSTER_FORWARD_AVAILABLE: true, STORAGE_BUFFER_AVAILABLE: true },
+          composedWgsl: 'colored',
+        },
+        {
+          definesKey:
+            'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+          defines: {
+            CLUSTER_FORWARD_AVAILABLE: true,
+            STORAGE_BUFFER_AVAILABLE: true,
+            VERTEX_COLOR_AVAILABLE: false,
+          },
+          composedWgsl: 'plain',
+        },
+        {
+          definesKey: 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+          defines: { CLUSTER_FORWARD_AVAILABLE: false, STORAGE_BUFFER_AVAILABLE: true },
+          composedWgsl: 'urp',
+        },
+      ],
+    } satisfies MaterialShaderManifestEntry;
+
+    expect(
+      selectHdrpPbrPrewarmVariants(manifest, true).map((variant) => variant.composedWgsl),
+    ).toEqual(['colored', 'plain']);
+    expect(
+      selectHdrpPbrPrewarmVariants(manifest, false).map((variant) => variant.composedWgsl),
+    ).toEqual([]);
+  });
+});

package/src/__tests__/renderer-lifecycle.integration.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+import { constructRenderer } from '../construct-renderer';
+
+describe('renderer lifecycle', () => {
+  it('rejects missing construction input', async () => {
+    await expect(constructRenderer(undefined, { rhi })).rejects.toBeDefined();
+  });
+});
+
+import { rhi } from '@forgeax/engine-rhi-null';

package/src/__tests__/renderer-render-scene-public.test-d.ts

@@ -0,0 +1,27 @@
+import { expectTypeOf } from 'vitest';
+import type { Renderer } from '../renderer';
+
+declare const renderer: Renderer;
+
+expectTypeOf(renderer.renderScene.fullRebuilds).toEqualTypeOf<number>();
+expectTypeOf(renderer.renderScene.worldEntitiesScanned).toEqualTypeOf<number>();
+expectTypeOf(renderer.renderScene.instanceUpdates).toEqualTypeOf<number>();
+expectTypeOf(renderer.renderScene.lastResyncReason).toEqualTypeOf<
+  | 'attach'
+  | 'asset-catalog-changed'
+  | 'shared-ref-changed'
+  | 'journal-overflow'
+  | 'unsupported-change'
+  | 'non-rigid-lane'
+  | 'explicit-invalidate'
+  | undefined
+>();
+
+if (renderer.renderScene.gpu.status === 'resident') {
+  expectTypeOf(renderer.renderScene.gpu.uploadBytes).toEqualTypeOf<number>();
+}
+
+expectTypeOf(renderer.renderScene.gpuDriven.candidateUploadBytes).toEqualTypeOf<number>();
+expectTypeOf(renderer.renderScene.gpuDriven.batchUploadBytes).toEqualTypeOf<number>();
+expectTypeOf(renderer.renderScene.gpuDriven.validatedGpuOwnedRows).toEqualTypeOf<number>();
+expectTypeOf(renderer.renderScene.gpuDriven.cpuFallbackDrawItems).toEqualTypeOf<number>();

package/src/__tests__/rhi-backend-package-boundary.unit.test.ts

@@ -0,0 +1,11 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+
+describe('render package backend identity boundary', () => {
+  it('externalizes stateful RHI backends from the render bundle', async () => {
+    const source = await readFile(new URL('../../tsup.config.ts', import.meta.url), 'utf8');
+
+    expect(source).toContain("'@forgeax/engine-rhi-webgpu'");
+    expect(source).toContain("'@forgeax/engine-rhi-wgpu'");
+  });
+});

package/src/__tests__/scene-temporal-coverage.unit.test.ts

@@ -0,0 +1,259 @@
+import { vec3 } from '@forgeax/engine-math';
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { Buffer } from '@forgeax/engine-rhi';
+import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue } from '@forgeax/engine-rhi-null';
+import { RenderQueue } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { RenderFeatureGraphContribution } from '../features/graph-contribution';
+import {
+  createSceneTemporalDepthTarget,
+  createSceneTemporalTarget,
+  SCENE_TEMPORAL_CLEAR_VALUE,
+  SCENE_TEMPORAL_PACKED_ABI,
+  sceneTemporalCoverage,
+} from '../features/scene-temporal';
+import { createRenderFeatureTarget } from '../features/targets';
+import type { RenderPipelineFrame } from '../render-pipeline';
+import type {
+  DispatchEntry,
+  RenderableSnapshot,
+  RenderableTemporalSnapshot,
+} from '../render-system-extract';
+
+function matrix(x = 0): Float32Array {
+  const value = new Float32Array(16);
+  value[0] = 1;
+  value[5] = 1;
+  value[10] = 1;
+  value[15] = 1;
+  value[12] = x;
+  return value;
+}
+
+function temporal(overrides: Partial<RenderableTemporalSnapshot> = {}): RenderableTemporalSnapshot {
+  return {
+    previousEpoch: 1,
+    previousSource: 'last-submitted',
+    reactive: false,
+    reactiveReasons: [],
+    previousTransform: { world: matrix() },
+    previousInstances: undefined,
+    previousSkin: undefined,
+    previousMorphWeights: undefined,
+    ...overrides,
+  };
+}
+
+function renderable(
+  entityKey: number,
+  overrides: Partial<RenderableSnapshot> = {},
+): RenderableSnapshot {
+  const material = {
+    baseColor: vec3.create(1, 1, 1),
+    metallic: 0,
+    roughness: 1,
+    materialHandle: entityKey,
+  };
+  return {
+    assetHandle: 1,
+    transform: { world: matrix() },
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    temporal: temporal(),
+    ...overrides,
+  };
+}
+
+function dispatch(renderableIndex: number, overrides: Partial<DispatchEntry> = {}): DispatchEntry {
+  return {
+    entityIndex: renderableIndex,
+    materialHandle: renderableIndex + 1,
+    renderableIndex,
+    passIndex: 0,
+    queue: RenderQueue.Geometry,
+    layer: 0,
+    tags: {},
+    renderState: undefined,
+    defines: undefined,
+    vertexEntry: undefined,
+    fragmentEntry: undefined,
+    materialShaderId: 'forgeax::standard-pbr',
+    paramSnapshot: undefined,
+    ...overrides,
+  };
+}
+
+function feature(
+  temporalCoverage: 'exact' | 'reactive' | undefined,
+  writesTemporal: boolean,
+  identity = 'forgeax::vfx',
+): RenderFeatureGraphContribution {
+  const color = createRenderFeatureTarget({
+    kind: 'scene-color',
+    format: 'rgba16float',
+    sampleCount: 1,
+  });
+  const temporalTarget = createRenderFeatureTarget({
+    kind: 'scene-temporal',
+    format: 'rgba16float',
+    sampleCount: 1,
+  });
+  return {
+    featureIdentity: identity,
+    order: 1,
+    resources: [],
+    topologySignature: 'vfx',
+    passes: [
+      {
+        featureIdentity: identity,
+        order: 1,
+        name: `${identity}::draw`,
+        descriptor: { reads: [], writes: [] },
+        dependsOn: [],
+        graphics: {
+          attachments: {
+            colors: [
+              { resource: color, format: 'rgba16float', loadOp: 'load', storeOp: 'store' },
+              ...(writesTemporal
+                ? [
+                    {
+                      resource: temporalTarget,
+                      format: 'rgba16float',
+                      loadOp: 'load' as const,
+                      storeOp: 'store' as const,
+                    },
+                  ]
+                : []),
+            ],
+          },
+          ...(temporalCoverage === undefined ? {} : { temporalCoverage }),
+          draws: [{} as never],
+        },
+      },
+    ],
+  };
+}
+
+describe('scene temporal target and coverage', () => {
+  it('allocates one single-sample rgba16float target with the packed clear ABI', () => {
+    const device = new RhiNullDevice(
+      new RhiNullQueue(),
+      (bookkeeper, owner) => new RhiNullCommandEncoder(bookkeeper, owner),
+    );
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const target = createSceneTemporalTarget(graph).unwrap();
+    const compiled = graph.compile({ device, surfaceSize: { width: 8, height: 8 } }).unwrap();
+
+    expect(target).toMatchObject({ format: 'rgba16float', sampleCount: 1 });
+    expect(SCENE_TEMPORAL_PACKED_ABI).toMatchObject({
+      x: expect.any(String),
+      w: 'reactive-0-to-1',
+    });
+    expect(SCENE_TEMPORAL_CLEAR_VALUE).toEqual({ r: 0, g: 0, b: -1, a: 1 });
+    expect(compiled.inspect()).toMatchObject({
+      passes: [expect.objectContaining({ name: 'scene-temporal-clear', kind: 'raster' })],
+      resources: [expect.objectContaining({ label: 'scene-temporal', origin: 'created' })],
+    });
+  });
+
+  it('allocates an independent depth authority for unjittered temporal replay', () => {
+    const device = new RhiNullDevice(
+      new RhiNullQueue(),
+      (bookkeeper, owner) => new RhiNullCommandEncoder(bookkeeper, owner),
+    );
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const depth = createSceneTemporalDepthTarget(graph).unwrap();
+    const compiled = graph.compile({ device, surfaceSize: { width: 8, height: 8 } }).unwrap();
+
+    expect(depth).toMatchObject({ format: 'depth24plus-stencil8', sampleCount: 1 });
+    expect(compiled.inspect().resources).toEqual([
+      expect.objectContaining({ label: 'scene-temporal-depth', origin: 'created' }),
+    ]);
+  });
+
+  it('classifies rigid, instances, skinning, morph, and alpha-cutout as exact', () => {
+    const skinMatrices = matrix();
+    const skin = {
+      jointCount: 1,
+      jointMatrices: skinMatrices,
+      byteOffset: 0,
+      buffer: {} as Buffer,
+    };
+    const renderables = [
+      renderable(1),
+      renderable(2, {
+        instances: { transforms: matrix(2), instanceCount: 1, cacheKey: 2, archVersion: 1 },
+        temporal: temporal({
+          previousInstances: {
+            transforms: matrix(1),
+            instanceCount: 1,
+            cacheKey: 2,
+            archVersion: 1,
+          },
+        }),
+      }),
+      renderable(3, { skin, temporal: temporal({ previousSkin: skin }) }),
+      renderable(4, {
+        morphWeights: new Float32Array([0.75]),
+        temporal: temporal({ previousMorphWeights: new Float32Array([0.25]) }),
+      }),
+      renderable(5),
+    ];
+    const summary = sceneTemporalCoverage({
+      renderables,
+      dispatch: renderables.map((_, index) =>
+        dispatch(
+          index,
+          index === 4 ? { queue: RenderQueue.AlphaTest, paramSnapshot: { alphaCutoff: 0.5 } } : {},
+        ),
+      ),
+      features: [],
+    });
+
+    expect(summary).toMatchObject({ complete: true, exact: 5, reactive: 0, missing: 0 });
+    expect(summary.contributors.map((contributor) => contributor.lane)).toEqual([
+      'rigid',
+      'instances',
+      'skinning',
+      'morph',
+      'alpha-cutout',
+    ]);
+  });
+
+  it('keeps conservative producers reactive and fails closed for undeclared coverage', () => {
+    const renderables = [
+      renderable(1),
+      renderable(2, {
+        material: { ...renderable(2).material, materialShaderId: 'forgeax::sprite' },
+      }),
+      renderable(3),
+    ];
+    const summary = sceneTemporalCoverage({
+      renderables,
+      dispatch: [
+        dispatch(0, { queue: RenderQueue.Transparent }),
+        dispatch(1, { materialShaderId: 'forgeax::sprite' }),
+        dispatch(2, { materialShaderId: 'custom::wind', vertexEntry: 'vs_wind' }),
+      ],
+      features: [
+        feature('reactive', false, 'forgeax::vfx'),
+        feature(undefined, false, 'forgeax::grid'),
+      ],
+    });
+
+    expect(summary).toMatchObject({ complete: false, exact: 0, reactive: 4, missing: 1 });
+    expect(summary.missingContributors).toEqual(['feature:forgeax::grid:forgeax::grid::draw']);
+  });
+
+  it('requires exact RenderFeatures to write scene-temporal', () => {
+    expect(
+      sceneTemporalCoverage({ renderables: [], dispatch: [], features: [feature('exact', false)] }),
+    ).toMatchObject({ complete: false, missing: 1 });
+    expect(
+      sceneTemporalCoverage({ renderables: [], dispatch: [], features: [feature('exact', true)] }),
+    ).toMatchObject({ complete: true, exact: 1 });
+  });
+});

package/src/__tests__/scriptable-pack-consumer.test-d.ts

@@ -0,0 +1,14 @@
+import type { TilesetAsset } from '@forgeax/engine-types';
+import { expectTypeOf } from 'vitest';
+
+const tileset: TilesetAsset = {
+  kind: 'tileset',
+  atlases: ['019ffa97-9000-7000-8000-000000000004'],
+  tileWidth: 1,
+  tileHeight: 1,
+  columns: 1,
+  rows: 1,
+  regions: [{ x: 0, y: 0, width: 1, height: 1 }],
+  tiles: [{ regionIndex: 0 }],
+};
+expectTypeOf(tileset.atlases).toEqualTypeOf<readonly string[]>();

package/src/__tests__/shader-stage-surface.unit.test.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import {
+  GPU_SHADER_STAGE_COMPUTE,
+  GPU_SHADER_STAGE_FRAGMENT,
+  GPU_SHADER_STAGE_VERTEX,
+} from '../gpu-stage';
+
+const ownerSource = readFileSync(new URL('../gpu-stage.ts', import.meta.url), 'utf8');
+const consumerSources = [
+  readFileSync(new URL('../hdrp-buffers.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../pbr-pipeline.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../ibl/IblPipelineCache.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../pipeline-spec.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../renderer/renderer-factory.ts', import.meta.url), 'utf8'),
+];
+
+describe('shader stage owner', () => {
+  it('keeps the three shader stage bits in one owner', () => {
+    expect(GPU_SHADER_STAGE_VERTEX).toBe(0x1);
+    expect(GPU_SHADER_STAGE_FRAGMENT).toBe(0x2);
+    expect(GPU_SHADER_STAGE_COMPUTE).toBe(0x4);
+    expect(ownerSource.match(/export const GPU_SHADER_STAGE_/g)).toHaveLength(3);
+  });
+
+  it('routes render visibility consumers through the owner', () => {
+    for (const source of consumerSources) {
+      expect(source).toContain('GPU_SHADER_STAGE_FRAGMENT');
+      expect(source).not.toMatch(/const GPU_SHADER_STAGE_(VERTEX|FRAGMENT|COMPUTE)\s*=/);
+      expect(source).not.toMatch(/visibility:\s*0x[124]/);
+    }
+    expect(consumerSources[0]).toContain('GPU_SHADER_STAGE_COMPUTE');
+    expect(consumerSources[0]).toContain('GPU_SHADER_STAGE_VERTEX');
+    expect(consumerSources[1]).toContain('GPU_SHADER_STAGE_VERTEX');
+    expect(consumerSources[2]).toContain('GPU_SHADER_STAGE_VERTEX');
+  });
+});