@forgeax/engine-runtime 0.1.2

package/src/__tests__/skin-parented-double-transform.test.ts

@@ -0,0 +1,268 @@
+// @ts-nocheck -- node:fs / node:path / node:url imports outside @types/node
+// bug-20260615-skin-mesh-node-double-transform M0 / m0-1 (AC-01).
+//
+// AC-01 red-then-green unit test: construct a minimal scene with
+//   parent: Transform { posZ = 5 }
+//   skinEntity: ChildOf { parent }, Skin { joints: [jointEntity] }
+//   jointEntity: Transform { identity } (also child of parent)
+//   IBM = identity (joint at origin in bind pose)
+//   vertex position = (0,0,0), skinIndex = 0, skinWeight = 1
+//
+// After propagateTransforms, the joint's world mat4 = parent (z=5),
+// the skin entity's world mat4 = parent (z=5). The palette is
+// palette = jointWorld * IBM = parent * I = parent.
+//
+// Current shader math (line 182):
+//   world = meshes[0].worldFromLocal * instanceLocal * (palette * pos)
+//         = parent * I * (parent * (0,0,0,1)^T)
+//       -> world.z = 10  (double transform, BUG).
+//
+// Spec-correct shader math (line 60 comment / glTF 2.0 sec.Skins):
+//   world = palette * pos
+//         = parent * (0,0,0,1)^T
+//       -> world.z = 5  (rigid-follow).
+//
+// This test simulates both paths in pure TypeScript (no GPU).
+// The BUG repro assertion PASSES today (current math -> z=10).
+// The AC-01 contract assertion FAILS today (current math -> expects
+// z=5 per spec, but produces z=10). M1's shader patch will update the
+// AC-01 test to use correct math -> z=5 -> green.
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { World } from '@forgeax/engine-ecs';
+import type { Mat4, Vec3 } from '@forgeax/engine-math';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+import { describe, expect, it } from 'vitest';
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Build mat4 from a Float32Array (16 floats column-major).
+ * Copies into a new mat4 by writing internal number[] directly.
+ */
+function mat4FromFloat32Array(arr: Float32Array): Mat4 {
+  const nums = Array.from(arr) as number[];
+  const m = mat4.create();
+  // Column-major indexing:
+  // col0: 0,1,2,3  col1: 4,5,6,7  col2: 8,9,10,11  col3: 12,13,14,15
+  const mn = m as unknown as number[];
+  for (let i = 0; i < 16; i++) {
+    mn[i] = nums[i] ?? 0;
+  }
+  return m;
+}
+
+/**
+ * Simulate the CURRENT shader vertex math (buggy, line 182).
+ *
+ *   world = meshes[0].worldFromLocal * instanceLocal * (palette * pos4)
+ *   instanceLocal = identity
+ */
+function shaderCurrentWorld(
+  meshWorldFromLocal: Mat4,
+  palette: Mat4,
+  localPos: readonly number[],
+): Vec3 {
+  const skinnedLocal = vec3.create(0, 0, 0);
+  const pos4 = vec3.create(localPos[0] ?? 0, localPos[1] ?? 0, localPos[2] ?? 0);
+  mat4.transformVec3(skinnedLocal, palette, pos4);
+  const world = vec3.create(0, 0, 0);
+  mat4.transformVec3(world, meshWorldFromLocal, skinnedLocal);
+  return world;
+}
+
+/**
+ * Simulate the SPEC-CORRECT shader vertex math (glTF 2.0 sec.Skins).
+ *
+ *   world = palette * pos4
+ *
+ * The palette already encodes full world-space joint transforms
+ * (jointWorld_i * IBM_i, pre-computed host-side with propagateTransforms).
+ * No additional meshes[0].worldFromLocal left-multiply is needed.
+ *
+ * @internal exported for AC-01 contract test (M1 green flip)
+ */
+export function shaderSpecCorrectWorld(palette: Mat4, localPos: readonly number[]): Vec3 {
+  const pos4 = vec3.create(localPos[0] ?? 0, localPos[1] ?? 0, localPos[2] ?? 0);
+  const world = vec3.create(0, 0, 0);
+  mat4.transformVec3(world, palette, pos4);
+  return world;
+}
+
+// ── tests ────────────────────────────────────────────────────────────────
+
+describe('skin parented double transform (AC-01)', () => {
+  it('current shader math double-transforms ancestor (BUG repro)', () => {
+    const world = new World();
+
+    // Parent at z=5.
+    const parent = world.spawn({ component: Transform, data: { pos: [0, 0, 5] } }).unwrap();
+
+    // Joint entity: identity local, also child of parent.
+    const jointEntity = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+      .unwrap();
+
+    // Skin entity: identity local, child of parent, Skin with one joint.
+    const skinEntity = world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: ChildOf, data: { parent } },
+        {
+          component: Skin,
+          data: {
+            skeleton: 123 as unknown as never, // unused in math-only test
+            joints: new Uint32Array([jointEntity as unknown as number]),
+          },
+        },
+      )
+      .unwrap();
+
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+
+    // Read Transform.world for skin entity and joint entity.
+    const st = world.get(skinEntity, Transform);
+    expect(st.ok).toBe(true);
+    if (!st.ok) return;
+    const meshWorldMat = mat4FromFloat32Array(st.value.world as unknown as Float32Array);
+
+    const jt = world.get(jointEntity, Transform);
+    expect(jt.ok).toBe(true);
+    if (!jt.ok) return;
+    const jointWorldMat = mat4FromFloat32Array(jt.value.world as unknown as Float32Array);
+
+    // Verify propagate produced correct worlds: both should be z=5.
+    const mn = meshWorldMat as unknown as number[];
+    const jn = jointWorldMat as unknown as number[];
+    expect(mn[14]).toBeCloseTo(5, 5);
+    expect(jn[14]).toBeCloseTo(5, 5);
+
+    // IBM = identity (joint at origin in bind pose).
+    const ibm = mat4.create();
+    mat4.identity(ibm);
+
+    // palette = jointWorld * IBM = parent.
+    const palette = mat4.create();
+    mat4.multiply(palette, jointWorldMat, ibm);
+
+    // Vertex at origin.
+    const vertexPos = [0, 0, 0] as const;
+
+    // Current shader: world = meshWorld * instanceLocal * (palette * pos).
+    const bugWorld = shaderCurrentWorld(meshWorldMat, palette, vertexPos);
+
+    // With parent T(0,0,5): parent * parent * origin = (0,0,10).
+    // BUG: world.z should be 10, not 5.
+    expect(bugWorld[0]).toBeCloseTo(0, 5);
+    expect(bugWorld[1]).toBeCloseTo(0, 5);
+    expect(bugWorld[2]).toBeCloseTo(10, 5);
+  });
+
+  it('spec-correct shader math (post-M1) rigid-follows parent (AC-01)', () => {
+    // This assertion codifies the AC-01 contract.
+    //
+    // AFTER M1's shader fix (line 182: world = skinnedLocal), the shader
+    // no longer left-multiplies by meshes[0].worldFromLocal. We simulate
+    // the CORRECTED math (shaderSpecCorrectWorld), which matches glTF 2.0
+    // sec.Skins: world = palette * pos -- the palette already encodes
+    // full world-space joint transforms, so a vertex at origin with parent
+    // at z=5 lands at world.z=5 (rigid-follow via palette alone).
+
+    const world = new World();
+
+    // Parent at z=5.
+    const parent = world.spawn({ component: Transform, data: { pos: [0, 0, 5] } }).unwrap();
+
+    // Joint entity: identity local, child of parent.
+    const jointEntity = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+      .unwrap();
+
+    // Skin entity: identity local, child of parent, Skin with one joint.
+    // (unused in corrected-math path -- mesh node world not needed).
+    void world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: ChildOf, data: { parent } },
+        {
+          component: Skin,
+          data: {
+            skeleton: 123 as unknown as never,
+            joints: new Uint32Array([jointEntity as unknown as number]),
+          },
+        },
+      )
+      .unwrap();
+
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+
+    const jt = world.get(jointEntity, Transform);
+    expect(jt.ok).toBe(true);
+    if (!jt.ok) return;
+    const jointWorldMat = mat4FromFloat32Array(jt.value.world as unknown as Float32Array);
+
+    // Verify propagate correctness.
+    const jn = jointWorldMat as unknown as number[];
+    expect(jn[14]).toBeCloseTo(5, 5);
+
+    // IBM = identity.
+    const ibm = mat4.create();
+    mat4.identity(ibm);
+
+    // palette = jointWorld * IBM = parent.
+    const palette = mat4.create();
+    mat4.multiply(palette, jointWorldMat, ibm);
+
+    // Vertex at origin.
+    const vertexPos = [0, 0, 0] as const;
+
+    // Simulate the CORRECTED (M1) shader math: world = palette * pos.
+    const worldPos = shaderSpecCorrectWorld(palette, vertexPos);
+
+    // AC-01 contract: vertex at origin with parent at z=5 lands at z=5
+    // (rigid-follows parent via palette alone).
+    expect(worldPos[0]).toBeCloseTo(0, 5);
+    expect(worldPos[1]).toBeCloseTo(0, 5);
+    expect(worldPos[2]).toBeCloseTo(5, 5);
+  });
+
+  // F-1 (round 1 minor-edit): WGSL source-grep gate. The CPU simulation tests
+  // above assert the math contract, but they are decoupled from the actual
+  // WGSL shader. To catch a future revert of M1's shader patch, assert the
+  // shader source contains the spec-correct form and does NOT contain the
+  // pre-M1 buggy left-multiply chain. Same pattern as
+  // skin-extract-getarrayview-count.unit.test.ts (M2's grep gate for AC-03).
+  it('default-standard-pbr-skin.wgsl encodes spec-correct skin math (AC-01 source gate)', () => {
+    const shaderPath = resolve(
+      dirname(fileURLToPath(import.meta.url)),
+      '../../../shader/src/default-standard-pbr-skin.wgsl',
+    );
+    const src = readFileSync(shaderPath, 'utf8');
+
+    // Pre-M1 buggy form: world = meshes[0].worldFromLocal * instanceLocal * skinnedLocal.
+    // If this regex matches anywhere in the file (outside comments), the shader
+    // is double-transforming again.
+    const buggyChain = /meshes\[0\]\.worldFromLocal\s*\*\s*instanceLocal\s*\*\s*skinnedLocal/;
+    expect(src).not.toMatch(buggyChain);
+
+    // Pre-M1 buggy normal form: mat3(instanceLocal) * meshes[0].normalMatrix * skinNormal3x3.
+    const buggyNormal = /meshes\[0\]\.normalMatrix\s*\*\s*skinNormal3x3/;
+    expect(src).not.toMatch(buggyNormal);
+
+    // Post-M1 spec-correct form: world position is skinnedLocal directly.
+    // Match `out.worldPos = skinnedLocal.xyz` (line 198 post-M1).
+    const specCorrectWorldPos = /out\.worldPos\s*=\s*skinnedLocal\.xyz/;
+    expect(src).toMatch(specCorrectWorldPos);
+
+    // Post-M1 spec-correct normal: only skinNormal3x3 * in.normal (no instanceLocal /
+    // normalMatrix factor).
+    const specCorrectNormal = /out\.worldNormal\s*=\s*normalize\(skinNormal3x3\s*\*\s*in\.normal\)/;
+    expect(src).toMatch(specCorrectNormal);
+  });
+});

package/src/__tests__/skylight-lazy-projection.test.ts

@@ -0,0 +1,359 @@
+// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w20 —
+// lazy equirect-to-cubemap projection state machine + multi-Skylight/Skybox
+// once-warn unit tests (plan-strategy §5.3 key test points (2)/(3)/(5) +
+// §3.2 sequence-diagram alt branches; requirements AC-05 / AC-06 / AC-09).
+//
+// Covers the full driveLazyEquirectProjection state machine (the single
+// per-frame trigger added in w18):
+//   - caps insufficient (rgba16floatRenderable=false) -> project through the
+//     renderable rgba8 precompute output (the WebKit path)
+//   - first sight (status undefined) + caps OK -> fire-and-forget launch; the
+//     store records status:'pending' synchronously, then 'ready' once the
+//     async projection completes
+//   - pending -> a re-entry while in flight does NOT relaunch (store dedup,
+//     idempotent per source; D-4)
+//   - failed -> EquirectProjectionFailedError fired EXACTLY ONCE per handle;
+//     the store never retries (R-2 / AC-09)
+//   - handle 0 -> solid-color ambient; trigger is never invoked (guarded by
+//     recordFrame)
+//
+// Plus the multi-Skylight / multi-SkyboxBackground once-warn (w19): the warn
+// fires once, names the winning entity handle, and does NOT flood per frame.
+
+import type { World as WorldType } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import {
+  driveLazyEquirectProjection,
+  GpuResourceStore,
+  RhiErrorListenerRegistry,
+  selectLazyEquirectHandle,
+  warnMultiSkybox,
+  warnMultiSkylight,
+} from '@forgeax/engine-render/internal';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import type { EquirectAsset, Handle } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+// ── caps probes ──────────────────────────────────────────────────────────────
+
+const capsRenderable: RhiCaps = {
+  backendKind: 'webgpu',
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  storageBuffer: true,
+  storageTexture: false,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: false,
+  float32Filterable: false,
+  maxColorAttachments: 8,
+} as unknown as RhiCaps;
+
+const capsNotRenderable: RhiCaps = {
+  ...capsRenderable,
+  rgba16floatRenderable: false,
+} as unknown as RhiCaps;
+
+// ── mock GPU device: createTexture / view / queue succeed so the upload runs to
+// a 'ready' entry; a counter tracks texture creation so the "no relaunch while
+// pending" assertion can prove a second drive does not mint a second texture. ──
+
+interface DeviceProbe {
+  textures: number;
+}
+
+const okShim = <T>(v: T) => ({ ok: true as const, value: v });
+
+// biome-ignore lint/suspicious/noExplicitAny: opaque mock GPU device surface
+function makeReadyDevice(probe: DeviceProbe): any {
+  return {
+    createShaderModule: () => okShim({ __mock: 'shader' }),
+    createSampler: () => okShim({ __mock: 'sampler' }),
+    createBindGroupLayout: () => okShim({ __mock: 'bgl' }),
+    createPipelineLayout: () => okShim({ __mock: 'layout' }),
+    createRenderPipeline: () => okShim({ __mock: 'pipeline' }),
+    createBindGroup: () => okShim({ __mock: 'bindGroup' }),
+    createCommandEncoder: () => okShim({ __mock: 'encoder', beginRenderPass: () => ({}) }),
+    createBuffer: (desc: { size?: number }) => okShim({ __mock: 'buffer', size: desc.size ?? 0 }),
+    createTexture: () => {
+      probe.textures += 1;
+      return okShim({
+        __mock: `texture-${probe.textures}`,
+        createView: () => ({ __mock: 'view' }),
+      });
+    },
+    createTextureView: () => okShim({ __mock: 'view' }),
+    queue: {
+      writeTexture: () => undefined,
+      writeBuffer: () => undefined,
+      submit: () => undefined,
+    },
+  };
+}
+
+// A device whose createTexture fails -> upload fail-fast -> status:'failed'.
+// biome-ignore lint/suspicious/noExplicitAny: opaque mock GPU device surface
+function makeFailingDevice(): any {
+  return {
+    createShaderModule: () => okShim({ __mock: 'shader' }),
+    createTexture: () => ({ ok: false as const, error: undefined }),
+    createTextureView: () => ({ ok: false as const, error: undefined }),
+    queue: { writeTexture: () => undefined, writeBuffer: () => undefined, submit: () => undefined },
+  };
+}
+
+function equirectPod(width = 4, height = 2): EquirectAsset {
+  return {
+    kind: 'equirect',
+    width,
+    height,
+    format: 'rgba16float',
+    data: new Uint8Array(width * height * 8),
+    colorSpace: 'linear',
+  };
+}
+
+// Build a store wired to a device (no shader factory -> the optional async IBL
+// precompute render-pass block is skipped). NOTE on the status timeline: the
+// cube-projection entry status (pending -> ready) and the idempotent source->cube
+// mapping are written SYNCHRONOUSLY inside _uploadCubemapFromEquirect, BEFORE the
+// first await (the async part is only the IBL prefilter precompute that populates
+// the per-device IblPipelineCache, NOT the entry status). So after one drive the
+// store entry is already 'ready'; the white-vs-real-IBL binding decision is made
+// by recordMainPass off the global cache views (out of scope for this unit test,
+// covered by the dawn IBL readback test). This unit test asserts the lazy
+// trigger's launch / dedup / caps-gate / fail-once-and-no-retry bookkeeping.
+function configuredStore(device: unknown, caps: RhiCaps): GpuResourceStore {
+  const store = new GpuResourceStore();
+  let next = 9000;
+  store.configureGpuDevice(
+    // biome-ignore lint/suspicious/noExplicitAny: mock device satisfies MipmapBlitDevice structurally
+    device as any,
+    undefined,
+    (() => okShim(toShared<'EquirectAsset'>(next++))) as never,
+    caps,
+  );
+  return store;
+}
+
+// Minimal RenderSystemInternals surface driveLazyEquirectProjection touches:
+// gpuStore, errorRegistry, device.caps. Everything else is unused by the arm.
+function makeInternals(
+  store: GpuResourceStore,
+  errorRegistry: RhiErrorListenerRegistry,
+  caps: RhiCaps,
+) {
+  return {
+    gpuStore: store,
+    errorRegistry,
+    device: { caps },
+    // biome-ignore lint/suspicious/noExplicitAny: narrow stub for the lazy-projection arm
+  } as any;
+}
+
+function makeFrameState() {
+  return { firedEquirectProjectionFailedHandles: new Set<number>() };
+}
+
+// Catalogue an equirect POD into the world's user-tier shared-ref store so
+// resolveAssetHandle<EquirectAsset>(world, handle) returns it (record path).
+function catalogEquirect(world: WorldType, pod: EquirectAsset): Handle<'EquirectAsset', 'shared'> {
+  return world.allocSharedRef('EquirectAsset', pod);
+}
+
+describe('driveLazyEquirectProjection — lazy projection state machine (M3 / w20)', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('caps insufficient (rgba16floatRenderable=false) -> projects through rgba8 output', () => {
+    const probe: DeviceProbe = { textures: 0 };
+    const store = configuredStore(makeReadyDevice(probe), capsNotRenderable);
+    const world = new World();
+    const handle = catalogEquirect(world, equirectPod());
+    const reg = new RhiErrorListenerRegistry();
+    const seen: string[] = [];
+    reg.add((e) => seen.push(e.code));
+    const frameState = makeFrameState();
+
+    driveLazyEquirectProjection(
+      makeInternals(store, reg, capsNotRenderable),
+      world,
+      frameState,
+      handle as unknown as number,
+    );
+
+    expect(probe.textures).toBeGreaterThan(0);
+    expect(store.getCubemapStatus(handle)).toBe('ready');
+    expect(seen).toEqual([]);
+  });
+
+  it('first sight + caps OK -> fire-and-forget launch projects the equirect (status ready) (AC-05)', () => {
+    const probe: DeviceProbe = { textures: 0 };
+    const store = configuredStore(makeReadyDevice(probe), capsRenderable);
+    const world = new World();
+    const handle = catalogEquirect(world, equirectPod());
+    const reg = new RhiErrorListenerRegistry();
+    const frameState = makeFrameState();
+
+    // No entry before the first drive.
+    expect(store.getCubemapStatus(handle)).toBeUndefined();
+
+    driveLazyEquirectProjection(
+      makeInternals(store, reg, capsRenderable),
+      world,
+      frameState,
+      handle as unknown as number,
+    );
+
+    // The cube projection entry status + idempotent mapping are written
+    // synchronously (before the async IBL precompute), so the entry exists +
+    // a texture was minted right after the fire-and-forget launch.
+    expect(store.getCubemapStatus(handle)).toBe('ready');
+    expect(probe.textures).toBeGreaterThan(0);
+  });
+
+  it('re-entry does NOT relaunch the projection (idempotent per source, D-4)', () => {
+    const probe: DeviceProbe = { textures: 0 };
+    const store = configuredStore(makeReadyDevice(probe), capsRenderable);
+    const world = new World();
+    const handle = catalogEquirect(world, equirectPod());
+    const reg = new RhiErrorListenerRegistry();
+    const frameState = makeFrameState();
+    const internals = makeInternals(store, reg, capsRenderable);
+
+    driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
+    const texturesAfterFirst = probe.textures;
+    expect(texturesAfterFirst).toBeGreaterThan(0);
+    expect(store.getCubemapStatus(handle)).toBe('ready');
+
+    // Subsequent frames: the existing entry (status !== undefined) short-circuits
+    // the lazy trigger, so no second projection / texture is minted.
+    driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
+    driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
+    expect(probe.textures).toBe(texturesAfterFirst);
+  });
+
+  it('failed -> EquirectProjectionFailedError fired EXACTLY ONCE per handle; no retry (R-2 / AC-09)', () => {
+    const store = configuredStore(makeFailingDevice(), capsRenderable);
+    const world = new World();
+    const handle = catalogEquirect(world, equirectPod());
+    const reg = new RhiErrorListenerRegistry();
+    const fired: Array<{ code: string; handle: number | undefined }> = [];
+    reg.add((e) => {
+      if (e.code === 'equirect-projection-failed') {
+        fired.push({ code: e.code, handle: e.detail.handle });
+      } else {
+        fired.push({ code: e.code, handle: undefined });
+      }
+    });
+    const frameState = makeFrameState();
+    const internals = makeInternals(store, reg, capsRenderable);
+
+    // Frame 1: first sight (status undefined) -> fire-and-forget launch. The
+    // failing device drives status:'failed' SYNCHRONOUSLY (the cube createTexture
+    // fails before any await), but the lazy arm checked 'undefined' this frame,
+    // so it only launched -- no error fired yet.
+    driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
+    expect(store.getCubemapStatus(handle)).toBe('failed');
+    expect(fired).toEqual([]);
+
+    // Frame 2: status:'failed' observed -> fire the structured error ONCE.
+    driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
+    expect(fired).toEqual([
+      { code: 'equirect-projection-failed', handle: handle as unknown as number },
+    ]);
+
+    // Frame 3+: the latch keeps the channel quiet -- no re-fire, no retry
+    // (the store's status:'failed' short-circuit + the frameState latch).
+    driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
+    driveLazyEquirectProjection(internals, world, frameState, handle as unknown as number);
+    expect(fired.length).toBe(1);
+    expect(store.getCubemapStatus(handle)).toBe('failed');
+  });
+
+  it('handle resolves to a non-equirect / missing POD -> no launch, no crash', () => {
+    const probe: DeviceProbe = { textures: 0 };
+    const store = configuredStore(makeReadyDevice(probe), capsRenderable);
+    const world = new World();
+    const reg = new RhiErrorListenerRegistry();
+    const seen: string[] = [];
+    reg.add((e) => seen.push(e.code));
+    const frameState = makeFrameState();
+
+    // A handle that was never catalogued (stale) -> resolveAssetHandle misses.
+    const staleHandle = 999999;
+    driveLazyEquirectProjection(
+      makeInternals(store, reg, capsRenderable),
+      world,
+      frameState,
+      staleHandle,
+    );
+
+    expect(probe.textures).toBe(0);
+    expect(store.getCubemapStatus(toShared<'EquirectAsset'>(staleHandle))).toBeUndefined();
+    expect(seen).toEqual([]);
+  });
+});
+
+describe('warnMultiSkylight / warnMultiSkybox — once-warn naming the winner (M3 / w20, w19)', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('warnMultiSkylight: warns once, names winning entity handle, includes ignored count', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const frameState = { warnedMultiSkylight: false };
+
+    warnMultiSkylight(frameState, 3, 42);
+    expect(spy).toHaveBeenCalledTimes(1);
+    const msg = String(spy.mock.calls[0]?.[0]);
+    expect(msg).toContain('Skylight');
+    // Names the winning entity handle (F-8: conflicting entity info).
+    expect(msg).toContain('42');
+    // Reports the count + how many are ignored.
+    expect(msg).toContain('3');
+    expect(msg).toContain('2'); // 3 - 1 ignored
+
+    // Second call (still >1): the latch keeps it silent -- no per-frame flood.
+    warnMultiSkylight(frameState, 3, 42);
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('warnMultiSkylight: count<=1 never warns', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const frameState = { warnedMultiSkylight: false };
+    warnMultiSkylight(frameState, 1, 7);
+    warnMultiSkylight(frameState, 0, 0);
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('warnMultiSkybox: warns once, names winning entity handle', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const frameState = { warnedMultiSkybox: false };
+
+    warnMultiSkybox(frameState, 2, 99);
+    expect(spy).toHaveBeenCalledTimes(1);
+    const msg = String(spy.mock.calls[0]?.[0]);
+    expect(msg).toContain('SkyboxBackground');
+    expect(msg).toContain('99');
+
+    warnMultiSkybox(frameState, 2, 99);
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('selectLazyEquirectHandle — shared Skylight/Skybox source selection', () => {
+  it('falls back to SkyboxBackground when Skylight is color-only (handle 0)', () => {
+    expect(selectLazyEquirectHandle({ equirectHandle: 0 }, { equirectHandle: 77 })).toBe(77);
+  });
+
+  it('prefers a non-zero Skylight equirect over the SkyboxBackground source', () => {
+    expect(selectLazyEquirectHandle({ equirectHandle: 55 }, { equirectHandle: 77 })).toBe(55);
+  });
+
+  it('returns the solid-color sentinel when neither source has an equirect', () => {
+    expect(selectLazyEquirectHandle({ equirectHandle: 0 }, undefined)).toBe(0);
+    expect(selectLazyEquirectHandle(undefined, undefined)).toBe(0);
+  });
+});

package/src/__tests__/sparse-tag-scene-roundtrip.test.ts

@@ -0,0 +1,43 @@
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import { createSceneAssetPort } from '@forgeax/engine-runtime';
+import { worldInstantiateScene } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { rootsToSceneAsset } from '../collect-scene-asset';
+import { registerSceneComponents } from './helpers/register-scene-components';
+
+const Selected = defineComponent('SparseSceneSelected', {}, { storage: 'sparse' });
+const RuntimeOnly = defineComponent(
+  'SparseSceneRuntimeOnly',
+  {},
+  {
+    storage: 'sparse',
+    transient: true,
+  },
+);
+
+describe('sparse tag scene persistence', () => {
+  it('round-trips authored sparse tags and omits transient sparse tags', () => {
+    const source = new World();
+    registerSceneComponents(source, [Selected, RuntimeOnly]);
+    const entity = source
+      .spawn({ component: Selected, data: {} }, { component: RuntimeOnly, data: {} })
+      .unwrap();
+    const assets = createSceneAssetPort(() => undefined);
+    const collected = rootsToSceneAsset(assets, source, [entity]).unwrap();
+    const components = collected.entities[0]?.components as
+      | Record<string, Record<string, unknown>>
+      | undefined;
+
+    expect(components?.SparseSceneSelected).toEqual({});
+    expect(components?.SparseSceneRuntimeOnly).toBeUndefined();
+
+    const target = new World();
+    registerSceneComponents(target, [Selected, RuntimeOnly]);
+    const handle = target.allocSharedRef('SceneAsset', collected);
+    worldInstantiateScene(target, handle).unwrap();
+    expect(
+      Array.from(target.query({ with: [Selected] }).unwrap(), (row) => row.entity),
+    ).toHaveLength(1);
+    expect(Array.from(target.query({ with: [RuntimeOnly] }).unwrap())).toEqual([]);
+  });
+});