@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/builtin-shader-register-e2e.test.ts

@@ -0,0 +1,151 @@
+// 5 built-in shader register-time e2e (feat-20260613-material-paramschema-
+// driven-binding M4 / w25).
+//
+// Walks the post-w18/w19/w20 sidecar paramSchemas through derive() and
+// asserts that the BGL shape lines up with plan-strategy §3.4 + the
+// orchestrator Q3 reading (3-texture user region; emissive + occlusion
+// appended via appendInjection(bgl, 'lightmap')).
+//
+// Coverage matrix:
+//   - default-standard-pbr     : userRegionBindingEnd === 7
+//   - default-standard-pbr-skin: userRegionBindingEnd === 7
+//   - default-unlit            : userRegionBindingEnd === 3
+//   - sprite                   : userRegionBindingEnd === 3
+//   - shadow-caster (empty)    : userRegionBindingEnd === 0
+//
+// The fixtures mirror the engine sidecar files exactly — any drift between
+// this test and packages/shader/src/*.material.json surfaces immediately
+// (charter F2: structural, falsifiable).
+
+import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { appendInjection } from '../../../render/src/pbr-pipeline';
+
+// ─── post-w18 default-standard-pbr sidecar ──────────────────────────────────
+const STANDARD_PBR_SIDECAR: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+  { name: 'metallic', type: 'f32', default: 0.0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'metallicChannel', type: 'f32', default: 2.0 },
+  { name: 'roughnessChannel', type: 'f32', default: 1.0 },
+  { name: 'aoChannel', type: 'f32', default: 0.0 },
+  { name: 'extraChannel', type: 'f32', default: 0.0 },
+  { name: 'emissive', type: 'vec3', default: [0.0, 0.0, 0.0] },
+  { name: 'emissiveIntensity', type: 'f32', default: 0.0 },
+  { name: 'occlusionStrength', type: 'f32', default: 1.0 },
+  { name: 'alphaCutoff', type: 'f32', default: 0.0 },
+  { name: 'clearcoat', type: 'f32', default: 0.0 },
+  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'metallicRoughnessTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+];
+
+// ─── post-w19 default-standard-pbr-skin sidecar ────────────────────────────
+const PBR_SKIN_SIDECAR: readonly ParamSchemaEntry[] = STANDARD_PBR_SIDECAR;
+
+// ─── post-w20 default-unlit sidecar ──────────────────────────────────────────
+const UNLIT_SIDECAR: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color' },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];
+
+// ─── post-w20 sprite sidecar ─────────────────────────────────────────────────
+const SPRITE_SIDECAR: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+  { name: 'region', type: 'vec4', default: [0.0, 0.0, 1.0, 1.0] },
+  { name: 'pivot', type: 'vec2', default: [0.5, 0.5] },
+  { name: 'flipX', type: 'f32', default: 0.0 },
+  { name: 'flipY', type: 'f32', default: 0.0 },
+  { name: 'slices', type: 'vec4', default: [0.0, 0.0, 0.0, 0.0] },
+  { name: 'sliceMode', type: 'f32', default: 0.0 },
+  { name: 'texture', type: 'texture2d' },
+];
+
+// ─── shadow-caster (vertex-only depth pass; no per-material params) ──────────
+const SHADOW_CASTER_SIDECAR: readonly ParamSchemaEntry[] = [];
+
+describe('5 built-in shader register-time e2e (M4 / w25)', () => {
+  it('default-standard-pbr derives 1 UBO + 3 sampler/texture pairs', () => {
+    const out = derive(STANDARD_PBR_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(7);
+    expect(out.bglEntries.length).toBe(7);
+    expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
+    // Sampler-first (§D-4): odd bindings are samplers, even bindings
+    // (after the UBO) are textures.
+    expect(out.bglEntries[1]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[2]?.texture?.viewDimension).toBe('2d');
+    expect(out.bglEntries[3]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[4]?.texture?.viewDimension).toBe('2d');
+    expect(out.bglEntries[5]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[6]?.texture?.viewDimension).toBe('2d');
+    // Texture field names exposed for the loader's missing-handle gate.
+    expect([...out.textureFieldNames].sort()).toEqual(
+      ['baseColorTexture', 'metallicRoughnessTexture', 'normalTexture'].sort(),
+    );
+  });
+
+  it('default-standard-pbr-skin matches the standard-pbr layout (skinned vertex stream lives elsewhere)', () => {
+    const out = derive(PBR_SKIN_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(7);
+    expect(out.bglEntries.length).toBe(7);
+  });
+
+  it('default-unlit derives 1 UBO + 1 sampler/texture pair (userRegionBindingEnd=3)', () => {
+    const out = derive(UNLIT_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(3);
+    expect(out.bglEntries.map((e) => e.binding)).toEqual([0, 1, 2]);
+    expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
+    expect(out.bglEntries[1]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[2]?.texture?.sampleType).toBe('float');
+  });
+
+  it('sprite derives one merged UBO (numerics packed std140) + 1 sampler/texture pair', () => {
+    const out = derive(SPRITE_SIDECAR);
+    // Numerics: baseColor(16) + region(16) + pivot(8 align 8) + flipX(4)
+    //         + flipY(4) + slices(16) + sliceMode(4) collapse onto one UBO
+    // entry; texture+sampler pair follow.
+    expect(out.userRegionBindingEnd).toBe(3);
+    expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
+    expect(out.bglEntries[1]?.sampler?.type).toBe('filtering');
+    expect(out.bglEntries[2]?.texture?.viewDimension).toBe('2d');
+    expect(out.uboLayout.entries.find((e) => e.name === 'baseColor')?.offset).toBe(0);
+    expect(out.uboLayout.entries.find((e) => e.name === 'region')?.offset).toBe(16);
+  });
+
+  it('shadow-caster empty schema derives empty BGL (graceful per D-12)', () => {
+    const out = derive(SHADOW_CASTER_SIDECAR);
+    expect(out.userRegionBindingEnd).toBe(0);
+    expect(out.bglEntries.length).toBe(0);
+    expect(out.uboLayout.totalBytes).toBe(0);
+  });
+
+  it('appendInjection threads userRegionBindingEnd for each shader', () => {
+    // appendInjection consumes the WebGPU-native GPUBindGroupLayoutEntry
+    // shape; derive returns the structurally compatible engine-types
+    // BindGroupLayoutEntry. The cast is structural — both share the same
+    // four resource-layout members (buffer / sampler / texture / storage
+    // texture) and the only nominal divergence is exactOptionalPropertyTypes
+    // narrowing on the @webgpu/types side.
+    type LayoutEntry = readonly GPUBindGroupLayoutEntry[];
+
+    // standard-pbr: 7 + lightmap(4) -> bindings 7..10; +ibl(7) -> 11..17
+    const pbrOut = derive(STANDARD_PBR_SIDECAR);
+    const lightmap = appendInjection(pbrOut.bglEntries as unknown as LayoutEntry, 'lightmap');
+    expect(lightmap.map((e) => e.binding)).toEqual([7, 8, 9, 10]);
+    const merged = [...(pbrOut.bglEntries as unknown as LayoutEntry), ...lightmap];
+    const ibl = appendInjection(merged, 'ibl');
+    expect(ibl.map((e) => e.binding)).toEqual([11, 12, 13, 14, 15, 16, 17]);
+
+    // unlit: 3 + shadow(2) -> bindings 3..4
+    const unlitOut = derive(UNLIT_SIDECAR);
+    const unlitShadow = appendInjection(unlitOut.bglEntries as unknown as LayoutEntry, 'shadow');
+    expect(unlitShadow.map((e) => e.binding)).toEqual([3, 4]);
+
+    // shadow-caster: 0 + shadow(2) -> bindings 0..1
+    const scOut = derive(SHADOW_CASTER_SIDECAR);
+    const scShadow = appendInjection(scOut.bglEntries as unknown as LayoutEntry, 'shadow');
+    expect(scShadow.map((e) => e.binding)).toEqual([0, 1]);
+  });
+});

package/src/__tests__/cache-false-eviction.test.ts

@@ -0,0 +1,127 @@
+// m1-t3: cleanPerEntityCache false-eviction test (TDD red).
+//
+// Verify AC-13: cleanPerFrameCaches validatedEntityKeys built with
+// worldEntityKey prevents cross-world false eviction.
+//
+// Scenarios:
+//   1. worldA entity(1) survives one frame — not falsely evicted by
+//      worldB's cleanup logic (the validated set uses worldEntityKey).
+//   2. worldA entity(2) despawned — its cache is correctly cleaned up
+//      (normal eviction still works).
+//
+// Anchors:
+//   plan-tasks.json m1-t3
+//   plan-strategy D-1a #4
+//   requirements AC-13
+
+import { describe, expect, it } from 'vitest';
+import { worldEntityKey } from '../../../render/src/record/frame-snapshot';
+import { cleanPerEntityCache } from '../../../render/src/record/mesh-ssbo';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeInnerCache(): WeakMap<object, unknown> {
+  const wm = new WeakMap<object, unknown>();
+  wm.set({}, 'stub-value');
+  return wm;
+}
+
+// ─── False eviction: worldA entry survives when worldB has same entityKey ──
+
+describe('false eviction prevention', () => {
+  it('worldA entity(1) cache survives one frame (false eviction not triggered)', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    // worldA entity(1) has a cached entry
+    const keyA_e1 = worldEntityKey(0, 1);
+    cache.set(keyA_e1, makeInnerCache());
+
+    // worldB also has entity(1) — different world, same entityKey
+    const keyB_e1 = worldEntityKey(1, 1);
+    cache.set(keyB_e1, makeInnerCache());
+
+    // Build validated set from the merged renderables:
+    // Both worldA entity(1) and worldB entity(1) are present
+    const validated = new Set<number>([keyA_e1, keyB_e1]);
+    cleanPerEntityCache(cache, validated);
+
+    // Both should survive — no false eviction
+    expect(cache.has(keyA_e1)).toBe(true);
+    expect(cache.has(keyB_e1)).toBe(true);
+  });
+
+  it('worldA entity(1) survives when worldB entity(1) is the only validated one', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    // Both worlds have entity(1) entries
+    const keyA_e1 = worldEntityKey(0, 1);
+    const keyB_e1 = worldEntityKey(1, 1);
+    cache.set(keyA_e1, makeInnerCache());
+    cache.set(keyB_e1, makeInnerCache());
+
+    // Only worldB entity(1) is in the validated set (worldA entity(1) despawned)
+    const validated = new Set<number>([keyB_e1]);
+    cleanPerEntityCache(cache, validated);
+
+    // worldA entity(1) should be evicted (it despawned)
+    expect(cache.has(keyA_e1)).toBe(false);
+    // worldB entity(1) should survive
+    expect(cache.has(keyB_e1)).toBe(true);
+  });
+});
+
+// ─── Normal eviction still works ────────────────────────────────────────────
+
+describe('normal eviction still works', () => {
+  it('worldA entity(2) despawned → cache cleaned', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    // worldA has entity(1) and entity(2)
+    const keyA_e1 = worldEntityKey(0, 1);
+    const keyA_e2 = worldEntityKey(0, 2);
+    cache.set(keyA_e1, makeInnerCache());
+    cache.set(keyA_e2, makeInnerCache());
+
+    // Only entity(1) survives — entity(2) despawned
+    const validated = new Set<number>([keyA_e1]);
+    cleanPerEntityCache(cache, validated);
+
+    // entity(1) survives
+    expect(cache.has(keyA_e1)).toBe(true);
+    // entity(2) is evicted
+    expect(cache.has(keyA_e2)).toBe(false);
+  });
+
+  it('worldA entity(2) despawned while worldB entity(2) lives → only worldA cleaned', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    const keyA_e2 = worldEntityKey(0, 2);
+    const keyB_e2 = worldEntityKey(1, 2);
+    cache.set(keyA_e2, makeInnerCache());
+    cache.set(keyB_e2, makeInnerCache());
+
+    // Only worldB entity(2) is validated
+    const validated = new Set<number>([keyB_e2]);
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.has(keyA_e2)).toBe(false);
+    expect(cache.has(keyB_e2)).toBe(true);
+  });
+});
+
+// ─── Cross-world key distinctness ───────────────────────────────────────────
+
+describe('cross-world key distinctness', () => {
+  it('same entityKey, different worldId → different worldEntityKey values', () => {
+    // This is the foundation of false-eviction prevention:
+    // worldEntityKey(0, 1) !== worldEntityKey(1, 1)
+    // So the validated set correctly distinguishes them.
+    const keyA = worldEntityKey(0, 1);
+    const keyB = worldEntityKey(1, 1);
+    expect(keyA).not.toBe(keyB);
+  });
+
+  it('same worldId, same entityKey → same worldEntityKey value', () => {
+    expect(worldEntityKey(0, 1)).toBe(worldEntityKey(0, 1));
+  });
+});

package/src/__tests__/cache-isolation-matrix.test.ts

@@ -0,0 +1,183 @@
+// m1-t2: Dual-world entity-id cache isolation matrix test (TDD red).
+//
+// Verify that the three per-entity caches use worldId composite keys
+// (worldEntityKey) to isolate entries from different worlds that share
+// the same entityKey. The caches under test:
+//
+//   1. instanceBuffers (positive half only — D-1a #1)
+//   2. materialBgPerEntity (outer Map key — D-1a #2)
+//   3. instancesBgPerEntity (outer Map key — D-1a #3)
+//
+// Anchors:
+//   plan-tasks.json m1-t2
+//   plan-strategy D-1a #1-#3
+//   requirements AC-07
+
+import { describe, expect, it } from 'vitest';
+import { worldEntityKey } from '../../../render/src/record/frame-snapshot';
+import { cleanPerEntityCache } from '../../../render/src/record/mesh-ssbo';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeInnerCache(): WeakMap<object, unknown> {
+  const wm = new WeakMap<object, unknown>();
+  wm.set({}, 'stub-value');
+  return wm;
+}
+
+// ─── instanceBuffers (positive half) key isolation ─────────────────────────
+
+describe('instanceBuffers positive-half key isolation', () => {
+  it('worldA entity(42) write then worldB entity(42) miss', () => {
+    // Simulate the instanceBuffers Map<number, ...> with worldEntityKey
+    const cache = new Map<number, object>();
+
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = {};
+
+    // Write for worldA
+    cache.set(keyA, entryA);
+
+    // worldB entity(42) should NOT hit the worldA entry
+    expect(cache.get(keyB)).toBeUndefined();
+
+    // worldA entity(42) SHOULD hit its own entry
+    expect(cache.get(keyA)).toBe(entryA);
+  });
+
+  it('worldA entity(42) write, then worldA entity(42) read hits', () => {
+    const cache = new Map<number, object>();
+    const keyA = worldEntityKey(0, 42);
+    const entry = {};
+    cache.set(keyA, entry);
+    expect(cache.get(keyA)).toBe(entry);
+  });
+
+  it('worldA entity(1) and worldB entity(1) are independent', () => {
+    const cache = new Map<number, object>();
+    const keyA = worldEntityKey(0, 1);
+    const keyB = worldEntityKey(1, 1);
+    const entryA = { a: 1 };
+    const entryB = { b: 2 };
+
+    cache.set(keyA, entryA);
+    cache.set(keyB, entryB);
+
+    expect(cache.get(keyA)).toBe(entryA);
+    expect(cache.get(keyB)).toBe(entryB);
+    // Keys are different
+    expect(keyA).not.toBe(keyB);
+  });
+
+  it('negative half fold-bucket key is NOT worldEntityKey (stays raw)', () => {
+    // D-1a #1: negative half fold-bucket keys are NOT worldEntityKey-prefixed.
+    // They are material-handle-based fold keys and remain as-is.
+    // This test documents the invariant: a fold-bucket key is simply a
+    // negative number, not a worldEntityKey composite.
+    const foldKey = -1 - ((42 << 16) | 0); // example fold-bucket key
+    // foldKey is negative, while worldEntityKey is always >= 0
+    expect(foldKey).toBeLessThan(0);
+    expect(worldEntityKey(0, 42)).toBeGreaterThanOrEqual(0);
+  });
+});
+
+// ─── materialBgPerEntity outer Map key isolation ────────────────────────────
+
+describe('materialBgPerEntity outer Map key isolation', () => {
+  it('worldA entity(42) write then worldB entity(42) miss', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+
+    cache.set(keyA, entryA);
+
+    // worldB entity(42) should miss
+    expect(cache.get(keyB)).toBeUndefined();
+    // worldA entity(42) should hit
+    expect(cache.get(keyA)).toBe(entryA);
+  });
+
+  it('worldA entity(42) and worldB entity(42) both have independent entries', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+    const entryB = makeInnerCache();
+
+    cache.set(keyA, entryA);
+    cache.set(keyB, entryB);
+
+    expect(cache.get(keyA)).toBe(entryA);
+    expect(cache.get(keyB)).toBe(entryB);
+    expect(entryA).not.toBe(entryB);
+  });
+});
+
+// ─── instancesBgPerEntity outer Map key isolation ───────────────────────────
+
+describe('instancesBgPerEntity outer Map key isolation', () => {
+  it('worldA entity(42) write then worldB entity(42) miss', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+
+    cache.set(keyA, entryA);
+
+    expect(cache.get(keyB)).toBeUndefined();
+    expect(cache.get(keyA)).toBe(entryA);
+  });
+
+  it('worldA entity(42) and worldB entity(42) both have independent entries', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+    const entryB = makeInnerCache();
+
+    cache.set(keyA, entryA);
+    cache.set(keyB, entryB);
+
+    expect(cache.get(keyA)).toBe(entryA);
+    expect(cache.get(keyB)).toBe(entryB);
+  });
+});
+
+// ─── cleanPerEntityCache with worldEntityKey keys ───────────────────────────
+
+describe('cleanPerEntityCache with worldEntityKey keys', () => {
+  it('worldA entry survives when only worldB key is absent from validated set', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+
+    cache.set(keyA, makeInnerCache());
+    cache.set(keyB, makeInnerCache());
+
+    // Only worldA entity(42) is validated
+    const validated = new Set<number>([keyA]);
+    cleanPerEntityCache(cache, validated);
+
+    // worldA entry should survive
+    expect(cache.has(keyA)).toBe(true);
+    // worldB entry should be evicted (not in validated set)
+    expect(cache.has(keyB)).toBe(false);
+  });
+
+  it('worldA entry evicted when worldA key is absent from validated set', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+
+    cache.set(keyA, makeInnerCache());
+
+    // Empty validated set — nothing survives
+    const validated = new Set<number>();
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.has(keyA)).toBe(false);
+  });
+});

package/src/__tests__/camera-clear-snapshot-equivalence.unit.test.ts

@@ -0,0 +1,75 @@
+// feat-20260709 M3 / w13: AC-11 Camera clear path -- CameraSnapshot.clearColor
+// structural change (D-3).
+//
+// The clear-color quartet on CameraSnapshot collapses from 4 scalars
+// (clearR/G/B/A) to a single `clearColor` field, aligned with the light
+// snapshot shape. This test asserts the extract -> snapshot -> clear-consumer
+// value is byte-equal to what the authored Camera SoA column carries, AND that
+// the zero-Camera fallback snapshot paints [0,0,0,1] (frame-snapshot.ts). This
+// is the AC-11 Camera path (q5), independent of the M2 light GPU byte-neutral
+// path.
+//
+// TDD note: this test asserts the NEW `cam.clearColor` snapshot shape and stays
+// red until w14 lands the CameraSnapshot collapse (plan-strategy §5.1
+// mixed-TDD form).
+
+import { World } from '@forgeax/engine-ecs';
+import { Camera } from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import {
+  makeZeroCameraFallbackSnapshot,
+  ZERO_CAMERA_CLEAR_FALLBACK,
+} from '../../../render/src/record/frame-snapshot';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+
+function spawnCameraWithClear(world: World, clear: readonly [number, number, number, number]) {
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      {
+        component: Camera,
+        data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100, clearColor: clear },
+      },
+    )
+    .unwrap();
+}
+
+describe('w13 -- CameraSnapshot.clearColor equivalence + fallback (AC-11 / D-3)', () => {
+  it('extract surfaces clearColor byte-equal to the authored Camera SoA column', () => {
+    const authored: [number, number, number, number] = [0.25, 0.5, 0.75, 1.0];
+    const world = new World();
+    spawnCameraWithClear(world, authored);
+    propagateTransforms(world);
+    const frame = extractFrame(world, prepareExtractContext(world));
+    expect(frame.cameras.length).toBe(1);
+    const cam = frame.cameras[0];
+    expect(cam).toBeDefined();
+    if (!cam) return;
+    // f32 storage rounds each channel; compare against the same rounding the
+    // pre-collapse 4-scalar path produced (each channel was an f32 column).
+    expect(Array.from(cam.clearColor)).toEqual(authored.map((v) => Math.fround(v)));
+  });
+
+  it('Camera spawned without clearColor defaults to transparent black [0,0,0,0] on the snapshot', () => {
+    const world = new World();
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    propagateTransforms(world);
+    const frame = extractFrame(world, prepareExtractContext(world));
+    const cam = frame.cameras[0];
+    expect(cam).toBeDefined();
+    if (!cam) return;
+    expect(Array.from(cam.clearColor)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('zero-Camera fallback snapshot carries clearColor = [0,0,0,1] (frame-snapshot.ts)', () => {
+    const snap = makeZeroCameraFallbackSnapshot();
+    expect(Array.from(snap.clearColor)).toEqual([0, 0, 0, 1]);
+    expect(Array.from(snap.clearColor)).toEqual(Array.from(ZERO_CAMERA_CLEAR_FALLBACK));
+  });
+});