@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/factory-contract.integration.test.ts

@@ -1,7 +1,10 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import { createProfiler } from '@forgeax/engine-profiler';
+import { DEFAULT_STANDARD_PROFILE } from '@forgeax/engine-render';
 import { RhiError, type ShaderModule } from '@forgeax/engine-rhi';
 import {
   RhiNullAdapter,
@@ -15,6 +18,7 @@ import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
 import type { RhiBackendPack } from '../assembly/backend-contract';
 import { createRenderer as constructRenderer } from '../assembly/factory';
+import { DirectionalLight, MeshFilter, MeshRenderer, PointLight, SpotLight } from '../components';
 import {
   ANTIALIAS_NONE,
   ANTIALIAS_TAA,
@@ -26,6 +30,10 @@ import {
 import type { RenderFeature } from '../features/types';
 import { renderLifecycleManifestUrl } from './shader-manifest-fixture';
 
+const assemblyDirectory = dirname(fileURLToPath(import.meta.url));
+const factorySourcePath = resolve(assemblyDirectory, '../assembly/factory.ts');
+const renderTargetHostSourcePath = resolve(assemblyDirectory, '../assembly/render-target-host.ts');
+
 function manifestUrl(): string {
   return `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
 }
@@ -92,6 +100,17 @@ async function createBloomScenario() {
 }
 
 describe('factory contract', () => {
+  it('requires one Renderer-owned target lifecycle seam', () => {
+    expect(existsSync(renderTargetHostSourcePath)).toBe(true);
+    const factorySource = readFileSync(factorySourcePath, 'utf8');
+    expect(factorySource.match(/createRenderTargetHost\(/g)).toHaveLength(2);
+    expect(factorySource).toContain("from './render-target-host'");
+    expect(factorySource).toContain('renderTargetHost.beginFrame()');
+    expect(factorySource).toContain('renderTargetHost.onFrameSubmitted(completed)');
+    expect(factorySource).toContain('renderTargetHost.recover()');
+    expect(factorySource).toContain('renderTargetHost.dispose()');
+  });
+
   it('keeps the public output-transform identity and closes removed tone symbols', () => {
     const source = [
       'render-contract.ts',
@@ -107,6 +126,11 @@ describe('factory contract', () => {
     expect(source).not.toContain('tone-output');
   });
 
+  it('forwards the bundler build identity into RenderSystem inspections', () => {
+    const source = readFileSync(factorySourcePath, 'utf8');
+    expect(source).toContain('get build() {\n      return internals.bundler?.build;\n    },');
+  });
+
   it('releases its profiler catalog contribution on dispose', async () => {
     const profiler = createProfiler();
     const renderer = await constructRenderer(
@@ -119,6 +143,34 @@ describe('factory contract', () => {
     expect(profiler.phaseCatalog.render).toEqual([]);
   });
 
+  it('forwards timing admission to the backend device request', async () => {
+    const adapter = new RhiNullAdapter();
+    const device = (await adapter.requestDevice()).unwrap();
+    let requested: unknown;
+    const timingRhi = {
+      ...rhi,
+      requestAdapter: async () =>
+        ok({
+          features: new Set(['timestamp-query']),
+          limits: adapter.limits,
+          requestDevice: async (descriptor?: unknown) => {
+            requested = descriptor;
+            return ok(device);
+          },
+        }),
+    } as never;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      {
+        rhi: timingRhi,
+        gpuPassTiming: { maxPassesPerFrame: 4, maxFramesInFlight: 1, retentionFrames: 2 },
+      },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    expect(requested).toMatchObject({ requiredFeatures: ['timestamp-query'] });
+    renderer.dispose();
+  });
+
   it('completes the receipt-bound create, attach, draw, observe, recover chain', async () => {
     const renderer = await constructRenderer(
       { getContext: () => null },
@@ -148,6 +200,22 @@ describe('factory contract', () => {
     renderer.dispose();
   });
 
+  it('rejects the removed Standard reflection-probe profile field at the Renderer boundary', async () => {
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const staleProfile = {
+      ...DEFAULT_STANDARD_PROFILE,
+      reflectionProbes: false,
+    } as unknown as Parameters<typeof renderer.setProfile>[0];
+    const result = renderer.setProfile(staleProfile);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('frame-input-invalid');
+    renderer.dispose();
+  });
+
   it('projects stable output and observation identity without pixel payloads', async () => {
     const renderer = await constructRenderer(
       { getContext: () => null },
@@ -175,6 +243,59 @@ describe('factory contract', () => {
     renderer.dispose();
   });
 
+  it('delivers a target readback only through its matching receipt', async () => {
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const target = renderer.createRenderTarget({
+      shape: '2d',
+      width: 17,
+      height: 9,
+      format: 'rgba8unorm',
+      mipLevels: 1,
+      sampleCount: 1,
+      sampled: false,
+      readback: true,
+    });
+    expect(target.ok).toBe(true);
+    if (!target.ok) return;
+    const ticket = renderer.requestTargetReadback(target.value, { mipLevel: 0 });
+    expect(ticket.ok).toBe(true);
+    if (!ticket.ok) return;
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    const frame = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(frame.ok).toBe(true);
+    if (!frame.ok || frame.value === undefined) return;
+    const observed = await renderer.observe(frame.value, {
+      include: ['target-readbacks'],
+      targetReadbacks: [ticket.value],
+    });
+    expect(observed.ok).toBe(true);
+    if (!observed.ok) return;
+    expect(observed.value.targetReadbacks?.[0]).toMatchObject({
+      frameId: frame.value.frameId,
+      deviceGeneration: frame.value.deviceGeneration,
+      bytesPerRow: 256,
+      byteLength: 256 * 9,
+    });
+    const repeated = await renderer.observe(frame.value, {
+      include: ['target-readbacks'],
+      targetReadbacks: [ticket.value],
+    });
+    expect(repeated.ok).toBe(false);
+    if (!repeated.ok) expect(repeated.error.code).toBe('render-target-state-invalid');
+    renderer.dispose();
+  });
+
   it('does not promote a graph feature without a fullscreen effect into post-effects', async () => {
     let planCalls = 0;
     const feature = {
@@ -205,13 +326,16 @@ describe('factory contract', () => {
     renderer.dispose();
   });
 
-  it('keeps the active graph as LKG when a feature candidate cannot be projected', async () => {
+  it('keeps the active graph as LKG while a feature candidate is pending', async () => {
     let invalid = false;
+    let featurePlanCalls = 0;
     const featureErrors: string[] = [];
     const feature: RenderFeature<undefined> = {
       identity: 'synthetic.candidate-lkg',
+      shaderModuleMode: 'immediate',
       extract: () => ok(undefined),
       plan: () => {
+        featurePlanCalls += 1;
         if (!invalid) return ok({ resources: [], passes: [] });
         return ok({
           resources: [
@@ -245,7 +369,7 @@ describe('factory contract', () => {
           passes: [
             {
               kind: 'compute',
-              name: 'main',
+              name: 'forward',
               program: 'candidate.program',
               bindings: 'candidate.bindings',
               dispatches: [{ kind: 'direct', entryPoint: 'main', workgroups: [1] }],
@@ -257,7 +381,7 @@ describe('factory contract', () => {
     const renderer = await constructRenderer(
       { width: 64, height: 64, getContext: () => null },
       { rhi, features: [feature] },
-      { shaderManifestUrl: manifestUrl() },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
     );
     expect((await renderer.initialization).ok).toBe(true);
     const unsubscribe = renderer.onError((error) => featureErrors.push(error.code));
@@ -269,29 +393,43 @@ describe('factory contract', () => {
     world
       .spawn(
         { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
-        { component: LocalCamera, data: { fov: 1, aspect: 1, near: 0.1, far: 100 } },
+        {
+          component: LocalCamera,
+          data: {
+            fov: 1,
+            aspect: 1,
+            near: 0.1,
+            far: 100,
+            antialias: ANTIALIAS_NONE,
+            tonemap: TONEMAP_ACES_FILMIC,
+            bloom: BLOOM_DISABLED,
+          },
+        },
       )
       .unwrap();
     expect(world.update().ok).toBe(true);
-    expect(
-      renderer.draw({
-        leases: [attached.value],
-        camera: { lease: attached.value },
-        environment: { lease: attached.value },
-      }).ok,
-    ).toBe(true);
-    const lastKnownGoodPasses = [...renderer.perFramePassNames];
-    expect(lastKnownGoodPasses.length).toBeGreaterThan(0);
-
+    const initialDraw = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(initialDraw.ok).toBe(true);
     invalid = true;
-    expect(
-      renderer.draw({
-        leases: [attached.value],
-        camera: { lease: attached.value },
-        environment: { lease: attached.value },
-      }).ok,
-    ).toBe(true);
+    const candidateDraw = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(candidateDraw.ok).toBe(true);
     await Promise.resolve();
+    const pendingDraw = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(pendingDraw.ok).toBe(true);
+    const lastKnownGoodPasses = [...renderer.perFramePassNames];
+    expect(lastKnownGoodPasses.length).toBeGreaterThan(0);
     expect(
       renderer.draw({
         leases: [attached.value],
@@ -299,12 +437,124 @@ describe('factory contract', () => {
         environment: { lease: attached.value },
       }).ok,
     ).toBe(true);
-    expect(featureErrors).toContain('duplicate-pass-name');
+    expect(featurePlanCalls).toBeGreaterThan(1);
+    expect(featureErrors).toEqual([]);
+    expect(renderer.inspect().featureDiagnostics[0]).toMatchObject({ status: 'active' });
     expect(renderer.perFramePassNames).toEqual(lastKnownGoodPasses);
     unsubscribe();
     renderer.dispose();
   });
 
+  it('records a no-storage directional-shadow frame without Cluster resources', async () => {
+    const nullAdapter = new RhiNullAdapter();
+    const noStorageRhi = {
+      ...rhi,
+      requestAdapter: async () => {
+        const created = await nullAdapter.requestDevice();
+        if (!created.ok) return created;
+        const baseDevice = created.value;
+        const device = new Proxy(baseDevice, {
+          get(target, property, receiver) {
+            if (property === 'caps') return { ...target.caps, storageBuffer: false };
+            return Reflect.get(target, property, receiver);
+          },
+        });
+        return ok({
+          features: nullAdapter.features,
+          limits: nullAdapter.limits,
+          requestDevice: async () => ok(device),
+        });
+      },
+    };
+    const renderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi: noStorageRhi as never },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    const errors: string[] = [];
+    const unsubscribe = renderer.onError((error) => errors.push(error.code));
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    registerPropagateTransforms(world);
+    world.spawn(
+      { component: Transform, data: { pos: [0, 0, 4], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      {
+        component: LocalCamera,
+        data: {
+          fov: 1,
+          aspect: 1,
+          near: 0.1,
+          far: 100,
+          antialias: ANTIALIAS_NONE,
+          tonemap: TONEMAP_ACES_FILMIC,
+          bloom: BLOOM_DISABLED,
+        },
+      },
+    );
+    world.spawn({
+      component: DirectionalLight,
+      data: {
+        direction: [0, -1, 0],
+        color: [1, 1, 1],
+        intensity: 1,
+        cascadeCount: 1,
+        mapSize: 64,
+      },
+    });
+    world.spawn(
+      { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+    );
+    expect(world.update().ok).toBe(true);
+    const frame = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(frame.ok).toBe(true);
+    expect(renderer.inspect().standardLighting).toMatchObject({
+      producer: 'none',
+      requested: 0,
+      admitted: 0,
+    });
+    expect(renderer.perFramePassNames).not.toContain('cluster-membership-producer');
+    expect(errors).toEqual([]);
+
+    // The no-storage topology is valid only while the scene has no local
+    // lights. A Point/Spot admission must fail before graph/encoder work and
+    // retain the last successful pass list rather than silently submitting a
+    // direct-light fallback with an incompatible ABI.
+    const lastSuccessfulPasses = [...renderer.perFramePassNames];
+    const localLight = world.spawn(
+      { component: Transform, data: { pos: [0, 0, 1] } },
+      { component: PointLight, data: { intensity: 8, range: 10 } },
+    );
+    expect(localLight.ok).toBe(true);
+    const spotLight = world.spawn(
+      { component: Transform, data: { pos: [1, 0, 1] } },
+      {
+        component: SpotLight,
+        data: { direction: [0, -1, 0], intensity: 8, range: 10 },
+      },
+    );
+    expect(spotLight.ok).toBe(true);
+    expect(world.update().ok).toBe(true);
+    const rejected = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(rejected.ok).toBe(false);
+    expect(errors).toContain('standard-cluster-transport-unavailable');
+    expect(renderer.perFramePassNames).toEqual(lastSuccessfulPasses);
+    unsubscribe();
+    await renderer.dispose();
+  });
+
   it('attaches derived-state systems once without putting writes in draw', async () => {
     const renderer = await constructRenderer(
       { getContext: () => null },
@@ -412,7 +662,7 @@ describe('factory contract', () => {
       createShaderModule: (_device, desc) => {
         const label = desc.label ?? '<unlabeled>';
         moduleCalls.push(label);
-        if (label !== 'post-process-forgeax.taa-resolve-module') {
+        if (!label.startsWith('post-process-forgeax.taa-resolve-pso-')) {
           return Promise.resolve(ok({} as ShaderModule));
         }
         let resolve!: (value: ReturnType<typeof ok<ShaderModule>>) => void;
@@ -473,7 +723,7 @@ describe('factory contract', () => {
     expect(off.ok).toBe(true);
 
     expect(
-      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+      moduleCalls.filter((label) => label.startsWith('post-process-forgeax.taa-resolve-pso-')),
     ).toHaveLength(1);
 
     world.set(camera, LocalCamera, { antialias: ANTIALIAS_TAA }).unwrap();
@@ -501,7 +751,7 @@ describe('factory contract', () => {
     pending[2]?.resolve(ok({} as ShaderModule));
     await pending[2]?.promise;
     expect(
-      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+      moduleCalls.filter((label) => label.startsWith('post-process-forgeax.taa-resolve-pso-')),
     ).toHaveLength(3);
   });
 
@@ -594,7 +844,7 @@ describe('factory contract', () => {
       .slice(-4);
     expect(firstGeneration).toHaveLength(4);
     expect(
-      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+      moduleCalls.filter((label) => label.startsWith('post-process-forgeax.taa-resolve-pso-')),
     ).toHaveLength(1);
     const firstFrame = renderer.inspect().frame.frameId;
 
@@ -618,7 +868,7 @@ describe('factory contract', () => {
     expect(renderer.inspect().frame.frameId).toBe(firstFrame + 1);
     expect(renderer.inspect().state).toBe('alive');
     expect(
-      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+      moduleCalls.filter((label) => label.startsWith('post-process-forgeax.taa-resolve-pso-')),
     ).toHaveLength(1);
     world.set(camera, LocalCamera, { antialias: ANTIALIAS_NONE }).unwrap();
     expect(world.update().ok).toBe(true);
@@ -1460,10 +1710,19 @@ describe('factory contract', () => {
       const failed = await renderer.recover();
       expect(failed.ok).toBe(false);
       expect(renderer.health().reason).toBe('device-lost');
+      expect(renderer.inspect().perFramePassNames).toEqual([]);
+      expect(renderer.inspect().standardLighting).toBeUndefined();
       const recovered = await renderer.recover();
       expect(recovered.ok).toBe(true);
+      // Recovery publishes a device but not a graph. The first post-recovery
+      // draw must rebuild both the graph accessors and Standard inspection
+      // against the replacement device.
+      expect(renderer.inspect().perFramePassNames).toEqual([]);
+      expect(renderer.inspect().standardLighting).toBeUndefined();
       expect(world.update().ok).toBe(true);
       expect(renderer.draw(input()).ok).toBe(true);
+      expect(renderer.inspect().perFramePassNames.length).toBeGreaterThan(0);
+      expect(renderer.inspect().standardLighting).toBeDefined();
       expect(renderer.inspect().bloom.state).toBe('active');
       expect(renderer.inspect().bloom.generation).toBeGreaterThan(0);
       expect(renderer.inspect().temporal.deviceGeneration).toBeGreaterThan(beforeDeviceGeneration);

package/src/__tests__/fog-component.unit.test.ts

@@ -0,0 +1,67 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Fog } from '../components/fog';
+import { selectEnvironment } from '../environment/frame';
+
+describe('Fog component contract', () => {
+  it('exposes one bounded authoring component with stable defaults', () => {
+    expect(Fog.name).toBe('Fog');
+    expect(Fog.fields.color.type).toBe('array<f32, 3>');
+    expect(Fog.fields.density.default).toBe(0.01);
+    expect(Fog.fields.heightFalloff.default).toBe(0);
+    expect(Fog.fields.maxOpacity.default).toBe(1);
+
+    const world = new World();
+    const entity = world.spawn({ component: Fog, data: {} }).unwrap();
+    const value = world.get(entity, Fog).unwrap();
+    expect(Array.from(value.color)).toEqual([0.5, 0.5, 0.5]);
+    expect(value.density).toBeCloseTo(0.01);
+    expect(value.heightFalloff).toBe(0);
+    expect(value.maxOpacity).toBe(1);
+  });
+
+  it.each([
+    ['color', { color: [1.1, 0.2, 0.3] }],
+    ['density', { density: -0.1 }],
+    ['heightFalloff', { heightFalloff: Number.NaN }],
+    ['maxOpacity', { maxOpacity: 1.1 }],
+  ] as const)('rejects invalid %s at the shared selection owner', (field, override) => {
+    const result = selectEnvironment({
+      environments: [],
+      fogs: [
+        {
+          entityKey: 1,
+          color: [0.2, 0.3, 0.4],
+          density: 0.01,
+          heightFalloff: 0,
+          maxOpacity: 1,
+          ...override,
+        },
+      ],
+      suns: [],
+      lane: 'direct',
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('environment-selection-invalid');
+    expect(result.error.detail.field).toContain(field);
+    expect(result.error.expected).toContain('finite');
+    expect(result.error.hint).toContain(field);
+  });
+
+  it('rejects a second Fog owner without choosing a first-hit winner', () => {
+    const result = selectEnvironment({
+      environments: [],
+      fogs: [
+        { entityKey: 2, color: [0.2, 0.3, 0.4], density: 0.01, heightFalloff: 0, maxOpacity: 1 },
+        { entityKey: 3, color: [0.4, 0.3, 0.2], density: 0.02, heightFalloff: 0, maxOpacity: 1 },
+      ],
+      suns: [],
+      lane: 'direct',
+    });
+    expect(result).toMatchObject({
+      ok: false,
+      error: { code: 'fog-cardinality', detail: { count: 2 } },
+    });
+  });
+});

package/src/__tests__/fog.integration.test.ts

@@ -0,0 +1,86 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Atmosphere } from '../components/atmosphere';
+import { DirectionalLight } from '../components/directional-light';
+import { Fog } from '../components/fog';
+import { extractFrames } from '../render-system-extract';
+
+function worldWithFog() {
+  const world = new World();
+  world
+    .spawn({
+      component: Atmosphere,
+      data: {
+        turbidity: 2,
+        rayleigh: 1,
+        mieCoefficient: 0.005,
+        mieDirectionalG: 0.8,
+        sunAngularRadius: 0.004675,
+      },
+    })
+    .unwrap();
+  world
+    .spawn({ component: DirectionalLight, data: { direction: [0, -1, 0], intensity: 1 } })
+    .unwrap();
+  const entity = world
+    .spawn({
+      component: Fog,
+      data: { color: [0.2, 0.3, 0.4], density: 0.03, heightFalloff: 0, maxOpacity: 0.8 },
+    })
+    .unwrap();
+  return { world, entity };
+}
+
+describe('Fog frame owner integration', () => {
+  it('retains the last valid Fog frame after an invalid update and exposes failure', () => {
+    const { world, entity } = worldWithFog();
+    const initial = extractFrames([world], 0);
+    expect(initial.fog?.density).toBeCloseTo(0.03);
+    expect(initial.fog?.heightFalloff).toBe(0);
+
+    world
+      .set(entity, Fog, {
+        color: [0.2, 0.3, 0.4],
+        density: -1,
+        heightFalloff: 0,
+        maxOpacity: 0.8,
+      })
+      .unwrap();
+    const invalid = extractFrames([world], 0);
+    expect(invalid.fog).toEqual(initial.fog);
+    expect(invalid.fogFailure).toMatchObject({
+      code: 'environment-selection-invalid',
+      detail: { field: 'density', value: -1 },
+    });
+
+    world
+      .set(entity, Fog, {
+        color: [1.2, 0.3, 0.4],
+        density: 0.03,
+        heightFalloff: 0,
+        maxOpacity: 0.8,
+      })
+      .unwrap();
+    const invalidColor = extractFrames([world], 0);
+    expect(invalidColor.fog).toEqual(initial.fog);
+    expect(invalidColor.fogFailure).toMatchObject({ detail: { field: 'color[0]' } });
+  });
+
+  it('clears the retained Fog only after a valid removal, never after an invalid frame', () => {
+    const { world, entity } = worldWithFog();
+    expect(extractFrames([world], 0).fog).toBeDefined();
+    world
+      .set(entity, Fog, {
+        color: [0.2, 0.3, 0.4],
+        density: -1,
+        heightFalloff: 0,
+        maxOpacity: 0.8,
+      })
+      .unwrap();
+    expect(extractFrames([world], 0).fog).toBeDefined();
+    world.removeComponent(entity, Fog).unwrap();
+    const removed = extractFrames([world], 0);
+    expect(removed.fog).toBeUndefined();
+    expect(removed.fogFailure).toBeUndefined();
+  });
+});

package/src/__tests__/frame-observation.contract.test.ts

@@ -6,6 +6,7 @@ import {
   type FrameObservationSource,
   observeCurrentFrame,
 } from '../record/frame.js';
+import { validateGraphTargetCaptureReadback } from '../record/frame-snapshot';
 import type { FrameObservationRequest, FrameReceipt } from '../render-contract';
 
 const texture = {} as Texture;
@@ -109,4 +110,18 @@ describe('render current-frame observation producer contract', () => {
     expect(result.ok).toBe(false);
     expect(readback).not.toHaveBeenCalled();
   });
+
+  it('rejects empty fallback bytes unless the selected rows are neutral', () => {
+    const bytes = new Uint8Array(256);
+    expect(
+      validateGraphTargetCaptureReadback({ bytes, expectedByteLength: bytes.byteLength }),
+    ).toEqual({ ok: false, code: 'capture-readback-empty' });
+    expect(
+      validateGraphTargetCaptureReadback({
+        bytes,
+        expectedByteLength: bytes.byteLength,
+        allowZero: true,
+      }),
+    ).toEqual({ ok: true });
+  });
 });