@forgeax/engine-render 0.1.21 → 0.1.24

package/src/__tests__/probe-capacity.integration.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PROBE_MAX_CONTRIBUTORS,
+  ProbeBlendSceneProjection,
+  type ProbeSceneProbeInput,
+} from '../scene/probe-blend';
+import {
+  PROBE_BLEND_RECORD_BYTE_SIZE,
+  PROBE_BLEND_RECORD_CAPACITY,
+} from '../scene/probe-blend-record';
+
+function makeProbe(index: number): ProbeSceneProbeInput {
+  return {
+    identity: `probe-${String(index).padStart(2, '0')}`,
+    position: [0, 0, 0],
+    radius: 2,
+    irradiance: new Float32Array(27).fill(index + 1),
+    admitted: true,
+  };
+}
+
+describe('probe admitted capacity', () => {
+  it('admits a stable prefix when active candidates exceed capacity', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(result.error?.code).toBe('capacity-exceeded');
+    expect(result.records[0]?.sentinel).toBeUndefined();
+    expect(result.records[0]?.accepted).toBe(true);
+    expect(result.activeContributorCount).toBe(PROBE_MAX_CONTRIBUTORS + 1);
+    expect(result.admittedProbeCount).toBe(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.activeIdentities).toHaveLength(PROBE_MAX_CONTRIBUTORS + 1);
+    expect(result.receipt.admittedIdentities).toHaveLength(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.rejectedIdentities).toHaveLength(1);
+    expect(result.receipt.overflowReason).toBe('active-count-exceeds-capacity');
+    expect(PROBE_BLEND_RECORD_CAPACITY).toBe(PROBE_MAX_CONTRIBUTORS);
+  });
+
+  it('retains the previous accepted record when a later admission overflows', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const accepted = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+    const overflow = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(overflow.error?.code).toBe('capacity-exceeded');
+    expect(overflow.records).toEqual(accepted.records);
+    expect(overflow.admittedProbeCount).toBe(PROBE_MAX_CONTRIBUTORS);
+  });
+
+  it('lets the admission prefix include every admitted active contributor', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.contributors).toHaveLength(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.admittedIdentities).toEqual(
+      Array.from(
+        { length: PROBE_MAX_CONTRIBUTORS },
+        (_, index) => `probe-${String(index).padStart(2, '0')}`,
+      ),
+    );
+    expect(result.records[0]?.byteLength).toBe(PROBE_BLEND_RECORD_BYTE_SIZE);
+  });
+
+  it('keeps stable identity order and recomputes C/S/SH after admitted clipping', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: [makeProbe(2), makeProbe(0), makeProbe(1)],
+      skyIrradiance: [0.4, 0.5, 0.6],
+    });
+
+    expect(result.contributors.map(({ identity }) => identity)).toEqual([
+      'probe-00',
+      'probe-01',
+      'probe-02',
+    ]);
+    expect(result.coverage).toBeGreaterThan(0);
+    expect(result.skyResidualFraction).toBeGreaterThanOrEqual(0);
+    expect(result.records[0]?.shPreblend).toHaveLength(27);
+  });
+});

package/src/__tests__/probe-recovery.integration.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { PROBE_MAX_CONTRIBUTORS, ProbeBlendSceneProjection } from '../scene/probe-blend';
+
+function probe(identity: string) {
+  return {
+    identity,
+    position: [0, 0, 0] as const,
+    radius: 2,
+    irradiance: new Float32Array(27).fill(1),
+    admitted: true,
+  };
+}
+
+describe('probe recovery carrier', () => {
+  it('recovers from capacity-exceeded with a deterministic stable prefix', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const object = { objectKey: 4, generation: 0, position: [0, 0, 0] as const };
+    const overflow = projection.apply({
+      objects: [object],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => probe(`p-${index}`)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+    const recovered = projection.apply({
+      objects: [{ ...object, generation: 1 }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => probe(`p-${index}`)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(overflow.error?.code).toBe('capacity-exceeded');
+    expect(overflow.records).toHaveLength(1);
+    expect(overflow.records[0]).toMatchObject({
+      objectKey: object.objectKey,
+      generation: object.generation,
+      accepted: true,
+    });
+    expect(overflow.records[0]?.sentinel).toBeUndefined();
+    expect(overflow.records[0]?.shPreblend).not.toEqual(new Array(27).fill(0));
+    expect(recovered.error).toBeUndefined();
+    expect(recovered.records).toHaveLength(1);
+    expect(recovered.records[0]?.generation).toBe(1);
+    expect(recovered.receipt.rejectedIdentities).toEqual([]);
+  });
+
+  it('rebuilds all object lanes after a scene resize boundary', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const probes = [probe('p-0')];
+    projection.apply({
+      objects: [{ objectKey: 4, generation: 0, position: [0, 0, 0] }],
+      probes,
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+    const resized = projection.apply({
+      objects: [
+        { objectKey: 4, generation: 0, position: [0, 0, 0] },
+        { objectKey: 5, generation: 0, position: [0, 0, 0] },
+      ],
+      probes,
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(resized.dirtyReasons).toContain('object-boundary');
+    expect(resized.records.map((record) => record.objectKey)).toEqual([4, 5]);
+    expect(resized.records.every((record) => record.byteLength === 160)).toBe(true);
+  });
+
+  it('drops stale local records and visits every object when Sky changes', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const object = { objectKey: 4, generation: 0, position: [0, 0, 0] as const };
+    const sky = {
+      available: true,
+      identity: 'skylight:1',
+      sourceKey: 'equirect:2',
+      irradiance: [0.1, 0.2, 0.3] as const,
+    };
+    projection.apply({ objects: [object], probes: [probe('p-0')], sky });
+
+    const changedSky = projection.apply({
+      objects: [object],
+      probes: [probe('p-0')],
+      sky: { ...sky, irradiance: [0.4, 0.5, 0.6] },
+    });
+    expect(changedSky.dirtyReasons).toContain('sky');
+    expect(changedSky.affectedObjectKeys).toEqual([object.objectKey]);
+    expect(projection.inspect().sky.irradiance).toEqual([0.4, 0.5, 0.6]);
+
+    const noLocalProbes = projection.apply({
+      objects: [object],
+      probes: [],
+      sky: changedSkyInputSky(),
+    });
+    expect(noLocalProbes.records).toEqual([]);
+    expect(projection.getRecord(object.objectKey)).toBeUndefined();
+    expect(projection.inspect().records).toEqual([]);
+  });
+});
+
+function changedSkyInputSky() {
+  return {
+    available: true,
+    identity: 'skylight:1',
+    sourceKey: 'equirect:2',
+    irradiance: [0.4, 0.5, 0.6] as const,
+  };
+}

package/src/__tests__/probe-scene-dirty.integration.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ProbeBlendSceneProjection,
+  type ProbeSceneObjectInput,
+  type ProbeSceneProbeInput,
+} from '../scene/probe-blend';
+
+const identityWorld = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+function object(objectKey: number, generation = 0, x = 0): ProbeSceneObjectInput {
+  return { objectKey, generation, position: [x, 0, 0] };
+}
+
+function probe(identity: string, x = 0, irradiance = 1): ProbeSceneProbeInput {
+  return {
+    identity,
+    position: [x, 0, 0],
+    radius: 2,
+    irradiance: new Float32Array(27).fill(irradiance),
+    admitted: true,
+  };
+}
+
+describe('PersistentRenderScene probe projection', () => {
+  it('creates one 160-byte record per object and reports candidate/accepted/LKG state', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const first = projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [0.25, 0.5, 0.75],
+    });
+
+    expect(first.records).toHaveLength(1);
+    expect(first.records[0]?.byteLength).toBe(160);
+    expect(first.records[0]?.candidate).toBe(true);
+    expect(first.records[0]?.accepted).toBe(true);
+    expect(first.records[0]?.lastKnownGood).toBe(true);
+    expect(first.records[0]?.bytes.byteLength).toBe(160);
+    expect(identityWorld.byteLength).toBe(64);
+  });
+
+  it('does no visit, allocation, or upload for a no-change frame', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const input = {
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [0.25, 0.5, 0.75] as const,
+    };
+    projection.apply(input);
+    const second = projection.apply(input);
+
+    expect(second.dirtyReasons).toEqual([]);
+    expect(second.visits).toBe(0);
+    expect(second.allocations).toBe(0);
+    expect(second.uploads).toBe(0);
+  });
+
+  it('marks object boundary, probe fact, World, and generation changes', () => {
+    const projection = new ProbeBlendSceneProjection();
+    projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      sky: {
+        available: true,
+        identity: 'skylight:9',
+        sourceKey: 'equirect:17',
+        irradiance: [1, 1, 1],
+      },
+    });
+
+    const objectBoundary = projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [1, 1, 1],
+    });
+    expect(objectBoundary.dirtyReasons).toContain('object-boundary');
+
+    const probeFacts = projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a', 0.25, 2)],
+      skyIrradiance: [1, 1, 1],
+    });
+    expect(probeFacts.dirtyReasons).toContain('probe-fact');
+
+    const world = projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a', 0.25, 2)],
+      skyIrradiance: [2, 1, 1],
+      worldRevision: 1,
+    });
+    expect(world.dirtyReasons).toContain('world');
+
+    const generation = projection.apply({
+      objects: [object(7, 1), object(8)],
+      probes: [probe('probe-a', 0.25, 2)],
+      skyIrradiance: [2, 1, 1],
+      worldRevision: 1,
+    });
+    expect(generation.dirtyReasons).toContain('generation');
+  });
+
+  it('marks only moved objects as affected by position dirty', () => {
+    const projection = new ProbeBlendSceneProjection();
+    projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [1, 1, 1],
+    });
+    const moved = projection.apply({
+      objects: [object(7, 0, 0.25), object(8)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [1, 1, 1],
+    });
+
+    expect(moved.dirtyReasons).toContain('object-position');
+    expect(moved.affectedObjectKeys).toEqual([7]);
+  });
+
+  it('packs SH9 as nine vec4 lanes with zero padding', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const coefficients = Array.from({ length: 27 }, (_, index) => index + 1);
+    const result = projection.apply({
+      objects: [object(7)],
+      probes: [{ ...probe('probe-a'), irradiance: coefficients }],
+      skyIrradiance: [0, 0, 0],
+    });
+    const values = new Float32Array(result.records[0]?.bytes.buffer ?? new ArrayBuffer(0));
+
+    expect(Array.from(values.slice(4, 13))).toEqual([1, 2, 3, 0, 4, 5, 6, 0, 7]);
+    expect(result.records[0]?.shPreblend).toEqual(coefficients);
+  });
+
+  it('uses no-LKG and outside-radius sentinels without inventing sky contributors', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-outside', 2)],
+      skyIrradiance: [0.25, 0.5, 0.75],
+      lastKnownGood: false,
+    });
+
+    expect(result.contributors).toEqual([]);
+    expect(result.records[0]?.localBlendFraction).toBe(0);
+    expect(result.records[0]?.sentinel).toBe('no-lkg');
+    expect('skyResidualFraction' in (result.records[0] ?? {})).toBe(false);
+  });
+
+  it('exposes numeric record, admission, and fail-closed receipt facts', () => {
+    const projection = new ProbeBlendSceneProjection();
+    projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      sky: {
+        available: true,
+        identity: 'skylight:9',
+        sourceKey: 'equirect:17',
+        irradiance: [1, 1, 1],
+      },
+    });
+    const inspection = projection.inspect();
+
+    expect(inspection).toMatchObject({
+      activeContributorCount: 1,
+      admittedProbeCount: 1,
+      coverage: expect.any(Number),
+      skyResidualFraction: expect.any(Number),
+      finite: true,
+      errorCode: undefined,
+      receipt: {
+        activeIdentities: ['probe-a'],
+        admittedIdentities: ['probe-a'],
+        rejectedIdentities: [],
+        stableOrder: ['probe-a'],
+        capacity: 64,
+        scaleRadius: 2,
+        finite: true,
+      },
+      sky: {
+        available: true,
+        identity: 'skylight:9',
+        sourceKey: 'equirect:17',
+        irradiance: [1, 1, 1],
+      },
+      dirtyVisitCount: 1,
+      dirtyReasons: ['object-boundary'],
+    });
+    expect(inspection.records[0]).toMatchObject({
+      objectKey: 7,
+      generation: 0,
+      byteLength: 160,
+      candidate: true,
+      accepted: true,
+      lastKnownGood: true,
+      probeBlendIndex: 7,
+      qHatSum: expect.any(Number),
+      rStar: 2,
+      contributors: [
+        {
+          identity: 'probe-a',
+          distance: 0,
+          radius: 2,
+          coverage: 1,
+          q: 0.25,
+          qHat: 1,
+          alpha: 1,
+        },
+      ],
+    });
+    expect(inspection.records[0]?.shPreblend).toHaveLength(27);
+  });
+});

package/src/__tests__/profiler-phase-catalog.test.ts

@@ -12,11 +12,13 @@ describe('Render profiler phase catalog ownership', () => {
   it('matches the profiler receiver set and includes nested record owners', () => {
     const profiler = createProfiler();
     expect(profiler.registerPhaseCatalog('render', RENDER_PHASE_CATALOG).ok).toBe(true);
-    expect(RENDER_PHASE_CATALOG).toHaveLength(5 + RENDER_RECORD_PHASE_CATALOG.length);
+    expect(RENDER_PHASE_CATALOG).toHaveLength(6 + RENDER_RECORD_PHASE_CATALOG.length);
     expect(new Set(RENDER_PHASE_CATALOG).size).toBe(RENDER_PHASE_CATALOG.length);
     expect(new Set(RENDER_PHASE_CATALOG)).toEqual(new Set(profiler.phaseCatalog.render));
     expect(RENDER_RECORD_PHASE_CATALOG).toEqual(
       expect.arrayContaining([
+        'record/occlusion-query-submit',
+        'record/occlusion-global-advance',
         'record/graph-execute/g-buffer/material-bind-groups',
         'record/graph-execute/g-buffer/pipeline-selection',
         'record/graph-execute/g-buffer/draw-submit',
@@ -27,6 +29,7 @@ describe('Render profiler phase catalog ownership', () => {
         'record/graph-execute/forward/geometry-loop',
       ]),
     );
+    expect(RENDER_PHASE_CATALOG).toEqual(expect.arrayContaining(['occlusion-prepare']));
     expect(RENDER_SCENE_STATE_PHASE_CATALOG).toEqual(
       expect.arrayContaining([
         'record/scene-state/fold-buckets',

package/src/__tests__/profiler-phase-token.test.ts

@@ -10,6 +10,7 @@ import {
 
 const RENDER_PHASES: readonly RenderPhase[] = [
   'extract',
+  'occlusion-prepare',
   'bind-groups',
   'features',
   'sort',

package/src/__tests__/recover-error-policy-owner.unit.test.ts

@@ -14,14 +14,14 @@ const evidence = [
   {
     code: 'recover-not-needed',
     expected:
-      'renderer is healthy; call health() first to confirm degraded state before calling recover()',
-    hint: 'call health() first to confirm degraded state before calling recover()',
+      'renderer is healthy; use state() or inspect() to confirm degraded state before calling recover()',
+    hint: 'use state() or inspect().state to confirm degraded state before calling recover()',
     message: 'recover-not-needed: renderer is not in a degraded state',
   },
   {
     code: 'recover-not-implemented',
     expected: 'recovery is not yet implemented; self-heal lands in S5',
-    hint: 'self-heal recovery lands in S5; health().reason still reflects the degraded state',
+    hint: 'self-heal recovery lands in S5; inspect().state still reflects the lifecycle state',
     message: 'recover-not-implemented: self-heal recovery is not yet implemented',
   },
   {
@@ -47,6 +47,9 @@ describe('RecoverError policy ownership', () => {
 
     expect(source).toContain('export type RecoverErrorCode = keyof typeof RECOVER_ERROR_POLICY;');
     expect(source).not.toMatch(/export type RecoverErrorCode = 'recover-/);
+    expect(source).not.toContain('health()');
+    expect(source).toContain('state()');
+    expect(source).toContain('inspect()');
   });
 
   it('preserves the exact four-code vocabulary and order', () => {

package/src/__tests__/recovery-candidate-prepare.contract.test.ts

@@ -0,0 +1,140 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const renderSystemSource = readFileSync(
+  resolve(import.meta.dirname, '../render-system.ts'),
+  'utf8',
+);
+const recoveryCandidateSource = readFileSync(
+  resolve(import.meta.dirname, '../recovery/render-system-candidate.ts'),
+  'utf8',
+);
+const rendererSource = readFileSync(
+  resolve(import.meta.dirname, '../assembly/webgpu-renderer.ts'),
+  'utf8',
+);
+const rendererRecoverySource = readFileSync(
+  resolve(import.meta.dirname, '../assembly/recovery/renderer-recover.ts'),
+  'utf8',
+);
+
+describe('recovery candidate preparation contract', () => {
+  it('keeps graph preparation outside draw, record, execute, and submit', () => {
+    const start = recoveryCandidateSource.indexOf('const prepareRecoveryGraphCandidate');
+    const end = recoveryCandidateSource.indexOf('const submitCandidateSetup', start);
+    const prepare = recoveryCandidateSource.slice(start, end);
+
+    expect(prepare).toContain('prepareFrameLighting');
+    expect(prepare).toContain('ensureCompiledFrameGraph');
+    expect(prepare).toContain("kind: 'no-seed'");
+    expect(prepare).toContain("kind: 'failed'");
+    expect(prepare).toContain("kind: 'ready'");
+    expect(prepare).not.toMatch(
+      /\.draw\(|recordFrame\(|executeCompiledFrameGraph|queue\.submit|\.finish\(/,
+    );
+  });
+
+  it('keeps active generation bindings unchanged until publication', () => {
+    const start = rendererRecoverySource.indexOf('const candidateInternals =');
+    const end = rendererRecoverySource.indexOf('const preparedRecoveryRoots =', start);
+    const candidate = rendererRecoverySource.slice(start, end);
+
+    expect(candidate).toContain('prepareRecoveryGraphCandidate');
+    expect(candidate).toContain("graphPreparation.kind === 'failed'");
+    expect(candidate).toContain("graphPreparation.kind === 'ready'");
+    expect(candidate).toContain('submitCandidateSetup');
+    expect(candidate).not.toMatch(/internals\.device\s*=/);
+    expect(candidate).not.toMatch(/internals\.generationState\.current\s*=/);
+    expect(candidate).not.toContain('renderSystem.resetForRecover');
+    expect(candidate).not.toContain('featureHost?.recover');
+    expect(candidate).not.toContain('renderTargetHost.beginFrame');
+    expect(rendererRecoverySource.indexOf('submitCandidateSetup', start)).toBeLessThan(
+      rendererRecoverySource.indexOf('const preparedRecoveryRoots', start),
+    );
+    expect(rendererRecoverySource).toContain('recoveryRootBundle');
+    expect(rendererSource).toContain('publishAndRetireRendererGeneration');
+  });
+
+  it('prepares roots from candidate state and switches environment owner only at publish', () => {
+    const start = renderSystemSource.indexOf('prepareRecoveryRoots(runtime: RecoveryRootRuntime)');
+    const end = renderSystemSource.indexOf('\n    },\n  };', start);
+    const roots = renderSystemSource.slice(start, end);
+
+    expect(roots).toContain('runtime.scope');
+    expect(roots).toContain('createRecoveryCandidate');
+    expect(roots).toContain('candidateEnvironmentGeneration');
+    expect(roots).toContain('candidateEnvironmentLifecycle.publish');
+    expect(roots).toContain('candidateEnvironmentLifecycle.discard');
+    expect(roots).toContain('graphCandidate.featureHost.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.featureGpuWork.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.gpuDrivenProduction.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.gpuDrivenScene.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.pointsLines.createRecoveryRoot');
+    expect(roots).toContain('runtime.gpuStore.createRecoveryRoot');
+    expect(roots).toContain('return compiledGraph');
+    expect(roots).not.toContain('environmentLifecycle.createRecoveryRoot');
+    expect(roots).not.toContain('featureCount');
+    expect(roots).not.toContain("owner: 'gpu-driven-production'");
+    expect(rendererSource).toContain('recoveryRootBundle.publish()');
+    expect(rendererRecoverySource).toContain('rootBundle.discard()');
+    expect(roots).toContain('cleanup: releaseGraphCandidate');
+  });
+
+  it('submits only explicit mip setup work without creating frame evidence', () => {
+    const start = recoveryCandidateSource.indexOf('const submitCandidateSetup');
+    const end = recoveryCandidateSource.indexOf('\n  return {', start);
+    const setup = recoveryCandidateSource.slice(start, end);
+
+    expect(setup).toContain('work.finish()');
+    expect(setup).toContain('candidate.device.queue.submit');
+    expect(setup).toContain('candidate.device.queue.onSubmittedWorkDone');
+    expect(setup.match(/candidate\.device\.queue\.submit/g)).toHaveLength(1);
+    expect(setup).not.toContain('submittedFrameCount');
+    expect(setup).not.toContain('directFrameId');
+    expect(setup).not.toContain('frameState');
+    expect(setup).not.toContain('recordFrame');
+  });
+
+  it('arms the first published frame only after candidate pipeline preparation', () => {
+    expect(recoveryCandidateSource).toContain(
+      'candidate.recoveryReadiness.assertFirstRecoveryFrame()',
+    );
+    expect(recoveryCandidateSource).toContain('pointsLinesOwner.prepareRecoveryCandidate');
+    expect(renderSystemSource).toContain('pointsLinesOwner.abandonForDeviceLoss');
+    expect(rendererSource).toContain(
+      'candidate.producerBindings.gpuStore.setRecoveryColdWorkGuard',
+    );
+    expect(rendererSource).toContain('recoveryColdWorkGuard.arm()');
+    expect(renderSystemSource).toContain('internals.recoveryColdWorkGuard?.notePipelineColdWork()');
+    expect(recoveryCandidateSource).toContain('const previousFeatureHost = internals.featureHost');
+    expect(recoveryCandidateSource).toContain('const disposed = previousFeatureHost.dispose()');
+    expect(recoveryCandidateSource).toContain('previousFeatureHost !== candidate.featureHost');
+  });
+
+  it('keeps material pipelines scoped to the active recovery generation', () => {
+    expect(rendererSource).toContain('currentPipelineCacheState().materialShaderPipelineCache');
+    expect(rendererSource).not.toMatch(/\n\s*materialShaderPipelineCache\.(get|set|has)\(/);
+  });
+
+  it('resolves recovery variants from the candidate device capabilities', () => {
+    const start = rendererSource.indexOf('const resolveCachedMaterialShaderVariantSet');
+    const end = rendererSource.indexOf('const findMaterialShaderManifestEntry', start);
+    const resolver = rendererSource.slice(start, end);
+
+    expect(resolver).toContain('const device = currentBuildDevice()');
+    expect(resolver).not.toContain('internals.device.caps');
+    expect(resolver).not.toContain('internals.device.limits');
+  });
+
+  it('keeps render-system residency bindings live across publication', () => {
+    const start = rendererSource.indexOf('const renderSystem: RenderSystem = createRenderSystem({');
+    const end = rendererSource.indexOf('errorRegistry: internals.errorRegistry', start);
+    const assembly = rendererSource.slice(start, end);
+
+    expect(assembly).toContain('get gpuStore()');
+    expect(assembly).toContain('get dynamicTextureStore()');
+    expect(assembly).not.toMatch(/\n\s*gpuStore,\n/);
+    expect(assembly).not.toMatch(/\n\s*dynamicTextureStore,\n/);
+  });
+});

package/src/__tests__/rect-area-boundary.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { rectAreaClusterRadius, rectAreaIsInRange } from '../cluster-binner';
+import { buildRectAreaWorldFrame, closestPointOnRectArea } from '../render-system-extract';
+
+const frame = buildRectAreaWorldFrame({
+  center: [0, 0, 0],
+  axisX: [1, 0, 0],
+  axisY: [0, 1, 0],
+  width: 4,
+  height: 2,
+});
+
+describe('RectAreaLight range and cluster boundaries', () => {
+  it('clamps the nearest point to authored half extents', () => {
+    expect(Array.from(closestPointOnRectArea(frame, [3, 2, 4]))).toEqual([2, 1, 0]);
+    expect(Array.from(closestPointOnRectArea(frame, [1, 0.5, 4]))).toEqual([1, 0.5, 0]);
+  });
+
+  it('uses a conservative sphere and a strict finite range window', () => {
+    expect(rectAreaClusterRadius(frame, 5)).toBe(Math.hypot(2, 1) + 5);
+    expect(rectAreaIsInRange(frame, [0, 0, 4.99], 5)).toBe(true);
+    expect(rectAreaIsInRange(frame, [0, 0, 5], 5)).toBe(false);
+  });
+});