@forgeax/engine-render 0.1.4 → 0.1.6

package/src/__tests__/render-feature-zero-work.unit.test.ts

@@ -8,8 +8,7 @@ function noWorkFeature(identity: string): RenderFeature<{ readonly empty: true }
   return {
     identity,
     extract: () => ok({ empty: true }),
-    prepare: () => ok(undefined),
-    contribute: () => ok(undefined),
+    plan: () => ok({ resources: [], passes: [] }),
   };
 }
 
@@ -17,8 +16,7 @@ function failedFeature(identity: string): RenderFeature<{ readonly empty: true }
   return {
     identity,
     extract: () => err(new RenderFeatureStageFailedError(identity, 0, 'extract', 'next-frame')),
-    prepare: () => ok(undefined),
-    contribute: () => ok(undefined),
+    plan: () => ok({ resources: [], passes: [] }),
   };
 }
 
@@ -32,12 +30,12 @@ describe('render feature zero-work boundaries', () => {
       caps: {} as never,
     });
 
-    expect(result.events).toEqual([]);
+    expect(result.stageEvents).toEqual([]);
     expect(result.errors).toEqual([]);
-    expect(result.contributions).toEqual([]);
+    expect(result.plans).toEqual([]);
   });
 
-  it('keeps empty data and zero-pass features out of the contribution list', () => {
+  it('keeps empty data and zero-pass features as an empty plan', () => {
     const host = createRenderFeatureHost([noWorkFeature('synthetic.empty')]).unwrap();
     const result = runRenderFeatureFrame(host, {
       worlds: [],
@@ -47,12 +45,11 @@ describe('render feature zero-work boundaries', () => {
     });
 
     expect(result.errors).toEqual([]);
-    expect(result.contributions).toEqual([]);
-    expect(result.events).toEqual([
-      'synthetic.empty:extract',
-      'synthetic.empty:prepare',
-      'synthetic.empty:contribute',
-    ]);
+    expect(result.plans).toHaveLength(1);
+    expect(result.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    expect(
+      result.stageEvents.map(({ featureIdentity, stage }) => `${featureIdentity}:${stage}`),
+    ).toEqual(['synthetic.empty:extract', 'synthetic.empty:plan']);
   });
 
   it('does not remove healthy work when one feature fails or is disabled', () => {
@@ -71,12 +68,9 @@ describe('render feature zero-work boundaries', () => {
     });
 
     expect(result.errors).toHaveLength(1);
-    expect(result.events).toEqual([
-      'synthetic.failed:extract',
-      'synthetic.healthy:extract',
-      'synthetic.healthy:prepare',
-      'synthetic.healthy:contribute',
-    ]);
-    expect(result.contributions).toEqual([]);
+    expect(
+      result.stageEvents.map(({ featureIdentity, stage }) => `${featureIdentity}:${stage}`),
+    ).toEqual(['synthetic.failed:extract', 'synthetic.healthy:extract', 'synthetic.healthy:plan']);
+    expect(result.plans).toHaveLength(1);
   });
 });

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { RenderSceneProjection } from '../render-scene-projection';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
 
 const material = {} as MaterialSnapshot;
 
@@ -22,58 +22,9 @@ function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
   };
 }
 
-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: [],
-    });
-  });
-
+describe('RenderScene canonical owner', () => {
   it('coalesces create and transform updates into one stable slot', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     const initial = snapshot(7, 1);
     const updatedWorld = new Float32Array(initial.transform.world);
     updatedWorld[12] = 9;
@@ -84,14 +35,14 @@ describe('RenderSceneProjection', () => {
     ]);
 
     expect(result).toMatchObject({ created: 1, updated: 0, removed: 0, recreated: 0 });
-    expect(projection.inspect().current).toEqual([
+    expect(projection.inspect().records).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 projection = new RenderScene();
 
     const result = projection.apply([
       { kind: 'create', snapshot: snapshot(3, 1) },
@@ -99,13 +50,13 @@ describe('RenderSceneProjection', () => {
     ]);
 
     expect(result).toMatchObject({ created: 0, updated: 0, removed: 0, recreated: 0 });
-    expect(projection.inspect().current).toEqual([]);
+    expect(projection.inspect().records).toEqual([]);
   });
 
   it('bumps generation when remove and recreate reuse a slot', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     projection.apply([{ kind: 'create', snapshot: snapshot(5, 1) }]);
-    const before = projection.inspect().current[0];
+    const before = projection.inspect().records[0];
 
     const result = projection.apply([
       { kind: 'remove', worldId: 0, entityKey: 5 },
@@ -113,7 +64,7 @@ describe('RenderSceneProjection', () => {
       { kind: 'update-transform', worldId: 0, entityKey: 5, world: snapshot(5, 7).transform.world },
     ]);
 
-    const after = projection.inspect().current[0];
+    const after = projection.inspect().records[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);
@@ -121,7 +72,7 @@ describe('RenderSceneProjection', () => {
   });
 
   it('ignores an update that arrives after removal', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     projection.apply([{ kind: 'create', snapshot: snapshot(9, 1) }]);
 
     const result = projection.apply([
@@ -130,11 +81,11 @@ describe('RenderSceneProjection', () => {
     ]);
 
     expect(result).toMatchObject({ removed: 1, ignoredLateUpdates: 1 });
-    expect(projection.inspect().current).toEqual([]);
+    expect(projection.inspect().records).toEqual([]);
   });
 
   it('keeps identical entity handles isolated by World identity', () => {
-    const projection = new RenderSceneProjection();
+    const projection = new RenderScene();
     projection.apply([
       { kind: 'create', snapshot: snapshot(1, 3) },
       { kind: 'create', snapshot: { ...snapshot(1, 8), worldId: 1 } },
@@ -142,65 +93,76 @@ describe('RenderSceneProjection', () => {
 
     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) },
-    ]);
+describe('RenderScene', () => {
+  it('keeps world identity slots stable across a composition reorder', () => {
+    const scene = new RenderScene();
+    const first = snapshot(1, 3);
+    const second = { ...snapshot(1, 8), worldId: 1 };
 
-    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,
+    scene.reset([first, second]);
+    const before = scene.slot(0, 1);
+    scene.reset([second, first]);
+
+    expect(scene.slotsSnapshot().map((entry) => [entry.worldId, entry.entityKey])).toEqual([
+      [1, 1],
+      [0, 1],
+    ]);
+    expect(scene.slot(0, 1)).toMatchObject({
+      slot: before?.slot,
+      generation: before?.generation,
     });
-    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'],
+  });
+
+  it('keeps one stable slot across reorder and reports no-change without scanning', () => {
+    const scene = new RenderScene();
+    scene.apply([
+      { kind: 'create', snapshot: snapshot(7, 1) },
+      { kind: 'create', snapshot: { ...snapshot(8, 2), worldId: 1 } },
     ]);
-    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([
+    const before = scene.slot(0, 7);
+    scene.apply([]);
+    const after = scene.slot(0, 7);
+
+    expect(after).toMatchObject({ slot: before?.slot, generation: before?.generation });
+    expect(scene.inspect()).toMatchObject({ noChangeFrames: 1, renderableScans: 0 });
+  });
+
+  it('indexes material and spatial facts from the same scene slots', () => {
+    const scene = new RenderScene();
+    scene.apply([
       {
         kind: 'create',
-        snapshot: factSnapshot(1, 0, { sceneFact: { mobility: 'dynamic' } }),
+        snapshot: {
+          ...snapshot(11, 4),
+          localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+          material: { ...material, materialHandle: 42 },
+          materials: [{ ...material, materialHandle: 42 }],
+        },
       },
     ]);
-    const afterMobilityChange = projection.inspect().spatialIndex;
-    expect(afterMobilityChange.static.entries).toBe(0);
-    expect(afterMobilityChange.dynamic.dynamicEntries).toBe(2);
-    expect(afterMobilityChange).toMatchObject({
-      bruteForceComparisons: 78,
-      falseNegatives: 0,
+
+    expect(scene.slotsForMaterial(42)).toHaveLength(1);
+    expect(
+      scene.querySpatial({ min: [2, -2, -2], max: [6, 2, 2] }).map((entry) => entry.entityKey),
+    ).toEqual([11]);
+  });
+
+  it('rebuilds from a resync delta after journal overflow', () => {
+    const scene = new RenderScene();
+    scene.apply([{ kind: 'create', snapshot: snapshot(1, 0) }]);
+
+    const result = scene.applyDelta({
+      operations: [],
+      overflowed: true,
+      resync: [snapshot(99, 9)],
+      reason: 'journal-overflow',
     });
+
+    expect(result.resynced).toBe(1);
+    expect(scene.has(0, 1)).toBe(false);
+    expect(scene.has(0, 99)).toBe(true);
   });
 });

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

@@ -1,13 +1,29 @@
-import type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import {
+  allowsUnlitPreparedFallback,
   resolveMaterialShaderBindingContract,
   resolveMaterialShaderVertexInputContract,
-  selectHdrpPbrPrewarmVariants,
-  selectNoColorPbrVariant,
-} from '../renderer/renderer-factory';
+  shouldDeferMissingPreparedMaterialShader,
+} from '../assembly/factory';
 
 describe('material shader binding contract', () => {
+  it('keeps record binding on the cooked projection contract', () => {
+    const recordSource = readFileSync(
+      resolve(import.meta.dirname, '../record/main-pass-material.ts'),
+      'utf8',
+    );
+    const projectionSource = readFileSync(
+      resolve(import.meta.dirname, '../assembly/material/pipeline-projection.ts'),
+      'utf8',
+    );
+    expect(projectionSource).toContain('routeMaterialPipeline');
+    expect(recordSource).not.toMatch(/internals\.assets\.get<MaterialAsset>/);
+    expect(recordSource).not.toMatch(/firstMaterial as \{/);
+    expect(recordSource).not.toContain('baseColorHandle');
+  });
+
   it('recognizes a world-space shader that reads only the canonical view uniform', () => {
     const source = `
       struct View { worldViewProj: mat4x4<f32> }
@@ -27,6 +43,19 @@ describe('material shader binding contract', () => {
     expect(resolveMaterialShaderBindingContract(source)).toBe('view-only');
   });
 
+  it('recognizes the VFX view plus sampled scene-depth contract', () => {
+    const source = `
+      struct View { worldViewProj: mat4x4<f32> }
+      @group(0) @binding(0) var<uniform> view: View;
+      @group(0) @binding(1) var scene_depth: texture_depth_2d;
+      @fragment fn fs_main() -> @location(0) vec4<f32> {
+        return vec4<f32>(textureLoad(scene_depth, vec2<i32>(0, 0), 0));
+      }
+    `;
+
+    expect(resolveMaterialShaderBindingContract(source)).toBe('view-and-scene-depth');
+  });
+
   it('keeps shaders with material groups on the full render-material layout', () => {
     const source = `
       @group(0) @binding(0) var<uniform> view: mat4x4<f32>;
@@ -46,16 +75,6 @@ describe('material shader binding contract', () => {
 
     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', () => {
@@ -83,90 +102,20 @@ describe('material shader vertex input contract', () => {
 
     expect(resolveMaterialShaderVertexInputContract(source)).toBe('none');
   });
-});
 
-describe('PBR variant boot prewarm contract', () => {
-  const manifest = {
-    identifier: 'forgeax::default-standard-pbr',
-    sourcePath: 'standard-pbr.wgsl',
-    composedWgsl: 'colored-urp',
-    paramSchema: '[]',
-    variants: [
-      {
-        definesKey: '',
-        defines: {
-          CLUSTER_FORWARD_AVAILABLE: true,
-          STORAGE_BUFFER_AVAILABLE: true,
-          VERTEX_COLOR_AVAILABLE: true,
-        },
-        composedWgsl: 'colored-hdrp',
-      },
-      {
-        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-hdrp',
-      },
-      {
-        definesKey:
-          'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
-        defines: {
-          CLUSTER_FORWARD_AVAILABLE: false,
-          STORAGE_BUFFER_AVAILABLE: true,
-          VERTEX_COLOR_AVAILABLE: false,
-        },
-        composedWgsl: 'plain-urp',
-      },
-    ],
-  } satisfies MaterialShaderManifestEntry;
-
-  it('selects the no-color PBR variant for the requested pipeline family', () => {
-    expect(selectNoColorPbrVariant(manifest, true, undefined)?.composedWgsl).toBe('plain-urp');
-    expect(selectNoColorPbrVariant(manifest, true, '')?.composedWgsl).toBe('plain-hdrp');
+  it('keeps an explicit prepared vertex layout on a missing shader', () => {
+    expect(allowsUnlitPreparedFallback(null, undefined)).toBe(true);
+    expect(allowsUnlitPreparedFallback(null, 'position-size-color-instance', 'forward')).toBe(true);
     expect(
-      selectNoColorPbrVariant(manifest, true, 'CLUSTER_FORWARD_AVAILABLE=true')?.composedWgsl,
-    ).toBe('plain-hdrp');
+      allowsUnlitPreparedFallback(null, 'position-size-color-instance', 'forgeax::missing-shader'),
+    ).toBe(false);
   });
 
-  it('prewarms every device HDRP variant, including the no-color variant', () => {
-    const prewarmManifest = {
-      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(prewarmManifest, true).map((variant) => variant.composedWgsl),
-    ).toEqual(['colored', 'plain']);
-    expect(
-      selectHdrpPbrPrewarmVariants(prewarmManifest, false).map((variant) => variant.composedWgsl),
-    ).toEqual([]);
+  it('defers every VFX prepared layout when its material shader is missing', () => {
+    expect(shouldDeferMissingPreparedMaterialShader('billboard-material-instance')).toBe(true);
+    expect(shouldDeferMissingPreparedMaterialShader('topology-segment-instance')).toBe(true);
+    expect(shouldDeferMissingPreparedMaterialShader('mesh-geometry-material-instance')).toBe(true);
+    expect(shouldDeferMissingPreparedMaterialShader('position-size-color-instance')).toBe(false);
+    expect(shouldDeferMissingPreparedMaterialShader(undefined)).toBe(false);
   });
 });

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

@@ -1,10 +1,58 @@
 import { describe, expect, it } from 'vitest';
-import { constructRenderer } from '../construct-renderer';
+import { createRenderer as constructRenderer } from '../assembly/factory';
+import { DeviceScope, LifecycleTransaction } from '../device/device-scope';
+import { RenderRecoveryError } from '../errors/recover';
+import { LifecycleConstructionError, type RenderError } from '../errors/render';
 
 describe('renderer lifecycle', () => {
   it('rejects missing construction input', async () => {
     await expect(constructRenderer(undefined, { rhi })).rejects.toBeDefined();
   });
+
+  it('keeps the lifecycle tree structural and independent from a GPU backend', async () => {
+    const scope = DeviceScope.create(60, 'renderer');
+    const transaction = new LifecycleTransaction(scope);
+    transaction.add({
+      kind: 'scene-table',
+      create: () => ({ id: 'scene-table' }),
+      cleanup: () => undefined,
+    });
+
+    const result = await transaction.commit();
+
+    expect(result.ok).toBe(true);
+    expect(scope.generation).toBe(60);
+    expect(scope.resourceDelta()).toBe(1);
+  });
+
+  it('keeps lifecycle and recovery failures structured without message parsing', () => {
+    const receipt = { owner: 'renderer', generation: 61, resourceCount: 0 } as const;
+    const lifecycleError = new LifecycleConstructionError({
+      owner: receipt.owner,
+      generation: receipt.generation,
+      operation: 'create',
+      resourceKind: 'pipeline',
+      cause: new Error('driver failure'),
+      cleanupFailures: [],
+      receipt,
+    });
+    const renderError: RenderError = lifecycleError;
+    expect(renderError.code).toBe('lifecycle-construction-failed');
+    expect(renderError.detail.owner).toBe('renderer');
+    expect(renderError.detail.receipt).toEqual(receipt);
+    expect(renderError.hint).toContain('recover');
+
+    const recoveryError = new RenderRecoveryError('recover-lifecycle-failed', {
+      owner: receipt.owner,
+      generation: receipt.generation,
+      recovery: 'recover',
+      receipt,
+      cause: lifecycleError,
+    });
+    expect(recoveryError.code).toBe('recover-lifecycle-failed');
+    expect(recoveryError.detail.receipt).toEqual(receipt);
+    expect(recoveryError.hint).toContain('rebuild');
+  });
 });
 
 import { rhi } from '@forgeax/engine-rhi-null';

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

@@ -7,13 +7,14 @@ import {
 } from '../gpu-stage';
 
 const ownerSource = readFileSync(new URL('../gpu-stage.ts', import.meta.url), 'utf8');
-const consumerSources = [
+const computeConsumerSources = [
   readFileSync(new URL('../hdrp-buffers.ts', import.meta.url), 'utf8'),
+];
+const fragmentConsumerSources = [
   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'),
+  readFileSync(new URL('../assembly/factory.ts', import.meta.url), 'utf8'),
 ];
 
 describe('shader stage owner', () => {
@@ -25,14 +26,18 @@ describe('shader stage owner', () => {
   });
 
   it('routes render visibility consumers through the owner', () => {
-    for (const source of consumerSources) {
-      expect(source).toContain('GPU_SHADER_STAGE_FRAGMENT');
+    for (const source of [...computeConsumerSources, ...fragmentConsumerSources]) {
+      expect(source).toContain('gpu-stage');
       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');
+    for (const source of fragmentConsumerSources) {
+      expect(source).toContain('GPU_SHADER_STAGE_FRAGMENT');
+    }
+    for (const source of computeConsumerSources) {
+      expect(source).toContain('GPU_SHADER_STAGE_COMPUTE');
+    }
+    expect(fragmentConsumerSources[0]).toContain('GPU_SHADER_STAGE_VERTEX');
+    expect(fragmentConsumerSources[1]).toContain('GPU_SHADER_STAGE_VERTEX');
   });
 });

package/src/__tests__/ssao-config.unit.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getSsaoParameters,
+  resolveSsaoParameters,
+  SSAO_DEFAULT_BIAS,
+  SSAO_DEFAULT_INTENSITY,
+  SSAO_DEFAULT_RADIUS,
+} from '../ssao-config';
+
+describe('SSAO parameter authority', () => {
+  it('keeps the documented defaults in one resolver', () => {
+    expect(getSsaoParameters(undefined)).toEqual({
+      radius: SSAO_DEFAULT_RADIUS,
+      bias: SSAO_DEFAULT_BIAS,
+      intensity: SSAO_DEFAULT_INTENSITY,
+    });
+  });
+
+  it('preserves configured radius, bias, and intensity', () => {
+    expect(getSsaoParameters({ radius: 0.65, bias: 0.025, intensity: 1.4 })).toEqual({
+      radius: 0.65,
+      bias: 0.025,
+      intensity: 1.4,
+    });
+  });
+
+  it('returns structured failures for invalid radius and bias', () => {
+    const invalidRadius = resolveSsaoParameters({ radius: 0 });
+    const invalidBias = resolveSsaoParameters({ bias: -0.1 });
+    expect(invalidRadius.ok).toBe(false);
+    expect(invalidBias.ok).toBe(false);
+    if (invalidRadius.ok || invalidBias.ok) throw new Error('expected structured SSAO failures');
+    expect(invalidRadius.error.code).toBe('ssao-radius-non-positive');
+    expect(invalidBias.error.code).toBe('ssao-bias-negative');
+  });
+});

package/src/__tests__/ssao-kernel-surface.unit.test.ts

@@ -1,15 +1,14 @@
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
-import { SSAO_KERNEL_SAMPLE_COUNT } from '../ssao-data';
+import { SSAO_KERNEL_SAMPLE_COUNT } from '../ssao-buffers';
 
-const ownerSource = readFileSync(new URL('../ssao-data.ts', import.meta.url), 'utf8');
-const bufferSource = readFileSync(new URL('../ssao-buffers.ts', import.meta.url), 'utf8');
+const ownerSource = readFileSync(new URL('../ssao-buffers.ts', import.meta.url), 'utf8');
 
 describe('SSAO kernel cardinality owner', () => {
   it('keeps the generated and uploaded sample count on one owner', () => {
     expect(SSAO_KERNEL_SAMPLE_COUNT).toBe(64);
     expect(ownerSource.match(/export const SSAO_KERNEL_SAMPLE_COUNT\s*=\s*64/g)).toHaveLength(1);
-    expect(bufferSource).toContain('SSAO_KERNEL_SAMPLE_COUNT');
-    expect(bufferSource).not.toMatch(/const (KERNEL_SIZE|KERNEL_SAMPLE_COUNT)\s*=\s*64/);
+    expect(ownerSource).toContain('SSAO_KERNEL_SAMPLE_COUNT');
+    expect(ownerSource).not.toMatch(/const (KERNEL_SIZE|KERNEL_SAMPLE_COUNT)\s*=\s*64/);
   });
 });