@forgeax/engine-runtime 0.1.2

package/src/__tests__/light-gpu-byte-neutral.unit.test.ts

@@ -0,0 +1,163 @@
+// feat-20260709 M2 / w7: light GPU 4-path byte-neutral regression (AC-11).
+//
+// The vec-collapse changes the ECS column shape (per-axis scalar -> array<f32,3>)
+// and the extract read sites, but NOT the GPU pack paths: every light GPU buffer
+// packs from the extract-assembled Vec3 snapshot (direction/color are already
+// Vec3 there -- research Finding 8), never from the ECS columns. These tests
+// lock the four light GPU pack paths' byte output so the collapse is proven
+// byte-neutral end to end:
+//   1. View UBO (DirectionalLight direction/color lanes)   -> writeViewUbo
+//   2. PointLightBuffer (color lanes)                       -> packPointLight
+//   3. SpotLightBuffer (direction + color lanes)            -> packSpotLight
+//   4. Skylight uniform/ambient (color destructure)         -> SkylightSnapshot
+// (Camera clear pass is M3, not here.)
+
+import { vec3 } from '@forgeax/engine-math';
+import type {
+  CameraSnapshot,
+  DirectionalLightSnapshot,
+  ExtractedLights,
+  PointLightSnapshot,
+  SkylightSnapshot,
+  SpotLightSnapshot,
+} from '@forgeax/engine-render/internal';
+import { packPointLight, packSpotLight, writeViewUbo } from '@forgeax/engine-render/internal';
+import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+
+function identityCamera(): CameraSnapshot {
+  return {
+    worldId: 0,
+    entityKey: 0,
+    position: vec3.create(0, 0, 3),
+    world: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 3, 1]),
+    fov: Math.PI / 4,
+    aspect: 16 / 9,
+    near: 0.1,
+    far: 100,
+    projection: 'perspective',
+    orthoLeft: -1,
+    orthoRight: 1,
+    orthoBottom: -1,
+    orthoTop: 1,
+    tonemap: 'none' as CameraSnapshot['tonemap'],
+    exposure: 1,
+    whitePoint: 4,
+    antialias: 'none' as CameraSnapshot['antialias'],
+    historyVersion: 0,
+    bloom: 'off' as CameraSnapshot['bloom'],
+    bloomThreshold: 1,
+    bloomIntensity: 1,
+    bloomBlurRadius: 4,
+    clearColor: [0, 0, 0, 1],
+  };
+}
+
+const emptyLights: ExtractedLights = {
+  directional: undefined,
+  directionalCount: 0,
+  point: [],
+  spot: [],
+  lightViewProj: undefined,
+  splitPlanes: undefined,
+  cascadeCount: undefined,
+  cascadeBlend: undefined,
+  depthBias: undefined,
+  normalBias: undefined,
+  pcfKernelSize: undefined,
+} as unknown as ExtractedLights;
+
+/** Capture the single writeViewUbo payload as a Float32Array. */
+function captureViewUbo(light: DirectionalLightSnapshot): { payload: Float32Array } {
+  let captured: Float32Array | undefined;
+  const queue = {
+    writeBuffer: (_buf: Buffer, _off: number, data: ArrayBufferView | ArrayBuffer) => {
+      captured = new Float32Array((data as ArrayBufferView).buffer ?? (data as ArrayBuffer));
+      return ok(undefined);
+    },
+  } as unknown as RhiQueue;
+  const viewBuffer = {} as Buffer;
+  writeViewUbo(queue, viewBuffer, identityCamera(), light, emptyLights, []);
+  if (captured === undefined) throw new Error('writeViewUbo did not write');
+  return { payload: captured };
+}
+
+describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
+  it('View UBO packs DirectionalLight direction*intensity / color into lanes 16..18 / 20..22', () => {
+    const light: DirectionalLightSnapshot = {
+      kind: 'directional',
+      direction: vec3.create(-0.5, -1, -0.3),
+      // extract host-pre-multiplies color * intensity; snapshot color IS the
+      // pre-multiplied radiance term (Finding 8), so writeViewUbo writes it raw.
+      color: vec3.create(0.9, 0.8, 0.7),
+      intensity: 2,
+    };
+    const { payload } = captureViewUbo(light);
+    // lightDir lanes carry direction * intensity (view-ubo.ts:66-68).
+    expect(payload[16]).toBeCloseTo(-0.5 * 2, 5);
+    expect(payload[17]).toBeCloseTo(-1 * 2, 5);
+    expect(payload[18]).toBeCloseTo(-0.3 * 2, 5);
+    // lightColor lanes carry the (already pre-multiplied) color verbatim.
+    expect(payload[20]).toBeCloseTo(0.9, 5);
+    expect(payload[21]).toBeCloseTo(0.8, 5);
+    expect(payload[22]).toBeCloseTo(0.7, 5);
+  });
+
+  it('packPointLight writes color into slots 4..6 byte-for-byte (32 B)', () => {
+    const snap: PointLightSnapshot = {
+      kind: 'point',
+      position: vec3.create(1.5, -2.25, 0.125),
+      color: vec3.create(0.4, 0.5, 0.6),
+      intensity: 2,
+      invRangeSquared: 0.04,
+    };
+    const out = packPointLight(snap);
+    expect(out.byteLength).toBe(32);
+    expect(out[4]).toBeCloseTo(0.4, 6);
+    expect(out[5]).toBeCloseTo(0.5, 6);
+    expect(out[6]).toBeCloseTo(0.6, 6);
+  });
+
+  it('packSpotLight writes color slots 4..6 + direction slots 8..10 byte-for-byte (64 B)', () => {
+    const snap: SpotLightSnapshot = {
+      kind: 'spot',
+      entity: 0,
+      position: vec3.create(0, 5, 0),
+      direction: vec3.create(0.1, -0.9, 0.2),
+      color: vec3.create(0.3, 0.4, 0.5),
+      intensity: 1,
+      invRangeSquared: 0.01,
+      cosInner: 0.95,
+      cosOuter: 0.8,
+      castShadow: false,
+      lightViewProj: undefined,
+      mapSize: 2048,
+      nearPlane: 0.1,
+      farPlane: 50,
+      shadowAtlasTile: -1,
+    };
+    const out = packSpotLight(snap);
+    expect(out.byteLength).toBe(64);
+    expect(out[4]).toBeCloseTo(0.3, 6);
+    expect(out[5]).toBeCloseTo(0.4, 6);
+    expect(out[6]).toBeCloseTo(0.5, 6);
+    expect(out[8]).toBeCloseTo(0.1, 6);
+    expect(out[9]).toBeCloseTo(-0.9, 6);
+    expect(out[10]).toBeCloseTo(0.2, 6);
+  });
+
+  it('Skylight snapshot color is a 3-tuple consumed by the ambient pack (main-pass.ts:248)', () => {
+    const snap: SkylightSnapshot = {
+      equirectHandle: 0,
+      color: [0.2, 0.4, 0.6],
+      intensity: 0.3,
+      rotation: [0, 0, 0, 1],
+      entityHandle: 1,
+    };
+    const [cr, cg, cb] = snap.color;
+    expect(cr).toBeCloseTo(0.2, 6);
+    expect(cg).toBeCloseTo(0.4, 6);
+    expect(cb).toBeCloseTo(0.6, 6);
+  });
+});

package/src/__tests__/light-snapshot.test-d.ts

@@ -0,0 +1,84 @@
+// light-snapshot - feat-20260519-light-casters-point-spot-pbr
+// M2 / w14 (TDD red): LightSnapshot discriminated union typecheck.
+//
+// AC anchor: requirements AC-03 (LightSnapshot sum-type + exhaustive switch
+// application point); plan-strategy D-S1 (3) (LightSnapshot to GPU buffer
+// bucket 1:1 mapping; charter P4 host pre-multiplication parity);
+// plan-strategy R-10 (record-system internal consumer rewritten to three-arm
+// switch in the same commit as the snapshot evolution).
+//
+// type-level expectations:
+//   type LightSnapshot =
+//     | { kind: 'directional'; direction; color; intensity }
+//     | { kind: 'point';       position; color; intensity; invRangeSquared }
+//     | { kind: 'spot';        position; direction; color; intensity;
+//                              invRangeSquared; cosInner; cosOuter };
+//
+// Exhaustive switch on `kind` must typecheck without `default` branch; missing
+// any variant -> tsc reports `Type 'never' is not assignable` on the
+// `assertNever(s)` line. Vitest --typecheck flag picks this file up via the
+// `*.test-d.ts` suffix (root vitest config K-3 unit project's typecheck pass
+// covers any .test-d.ts file in any package).
+
+import type {
+  DirectionalLightSnapshot,
+  ExtractedLights,
+  LightSnapshot,
+  PointLightSnapshot,
+  SpotLightSnapshot,
+} from '@forgeax/engine-render/internal';
+import { expectTypeOf, test } from 'vitest';
+
+function assertNever(_x: never): never {
+  throw new Error('exhaustive');
+}
+
+// AC-03 application point: the AI user writes a switch on `kind` and TS
+// guarantees every variant is reached. assertNever in the unreachable arm
+// breaks the build if a future variant lands and the switch is not extended.
+function consumeSnapshot(s: LightSnapshot): number {
+  switch (s.kind) {
+    case 'directional':
+      return s.intensity;
+    case 'point':
+      return s.invRangeSquared;
+    case 'spot':
+      return s.cosInner + s.cosOuter;
+    default:
+      return assertNever(s);
+  }
+}
+
+test('LightSnapshot is a discriminated union on kind', () => {
+  expectTypeOf<LightSnapshot>().toEqualTypeOf<
+    DirectionalLightSnapshot | PointLightSnapshot | SpotLightSnapshot
+  >();
+  // Smoke that the consumer compiles (run-time noop; compile-time exhaustive).
+  void consumeSnapshot;
+});
+
+test('DirectionalLightSnapshot field shape', () => {
+  expectTypeOf<DirectionalLightSnapshot['kind']>().toEqualTypeOf<'directional'>();
+  expectTypeOf<DirectionalLightSnapshot['intensity']>().toEqualTypeOf<number>();
+});
+
+test('PointLightSnapshot field shape', () => {
+  expectTypeOf<PointLightSnapshot['kind']>().toEqualTypeOf<'point'>();
+  expectTypeOf<PointLightSnapshot['invRangeSquared']>().toEqualTypeOf<number>();
+});
+
+test('SpotLightSnapshot field shape', () => {
+  expectTypeOf<SpotLightSnapshot['kind']>().toEqualTypeOf<'spot'>();
+  expectTypeOf<SpotLightSnapshot['cosInner']>().toEqualTypeOf<number>();
+  expectTypeOf<SpotLightSnapshot['cosOuter']>().toEqualTypeOf<number>();
+  expectTypeOf<SpotLightSnapshot['invRangeSquared']>().toEqualTypeOf<number>();
+});
+
+test('ExtractedLights three-bucket shape', () => {
+  expectTypeOf<ExtractedLights['directional']>().toEqualTypeOf<
+    DirectionalLightSnapshot | undefined
+  >();
+  expectTypeOf<ExtractedLights['directionalCount']>().toEqualTypeOf<number>();
+  expectTypeOf<ExtractedLights['point']>().toEqualTypeOf<readonly PointLightSnapshot[]>();
+  expectTypeOf<ExtractedLights['spot']>().toEqualTypeOf<readonly SpotLightSnapshot[]>();
+});

package/src/__tests__/lights-vec-negative.unit.test.ts

@@ -0,0 +1,52 @@
+// feat-20260709 M2 / w5a: AC-04 negative type witnesses at real spawn call-sites.
+//
+// After the vec-collapse, the per-axis scalar keys (directionX/Y/Z, colorR/G/B)
+// no longer exist on any light schema. A residual per-axis key in spawn `data`
+// is an excess-unknown-key -- a compile error. This is the compile-time half of
+// the migration-completeness guarantee (research-decisions D-R1: the "omit
+// direction" case is a runtime validate rejection, but a residual scalar KEY is
+// still typecheck-red). Each `@ts-expect-error` below is applied at a genuine
+// `world.spawn({ component, data })` call-site (AC-04: standalone *.test-d.ts
+// type assertions do NOT count), so the vitest typecheck project enforces it.
+
+import { World } from '@forgeax/engine-ecs';
+import { DirectionalLight, PointLight, Skylight, SpotLight } from '@forgeax/engine-render/internal';
+import { describe, it } from 'vitest';
+
+describe('w5a -- residual per-axis light keys are compile errors (AC-04)', () => {
+  it('DirectionalLight rejects residual directionX/colorR at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: DirectionalLight,
+      // @ts-expect-error directionX/colorR were collapsed into direction/color arrays.
+      data: { direction: [0, -1, 0], directionX: 0, colorR: 1 },
+    });
+  });
+
+  it('SpotLight rejects residual directionZ/colorG at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: SpotLight,
+      // @ts-expect-error directionZ/colorG were collapsed into direction/color arrays.
+      data: { direction: [0, -1, 0], directionZ: 0, colorG: 1 },
+    });
+  });
+
+  it('PointLight rejects residual colorB at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: PointLight,
+      // @ts-expect-error colorB was collapsed into the color array.
+      data: { color: [1, 1, 1], colorB: 1 },
+    });
+  });
+
+  it('Skylight rejects residual colorR at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: Skylight,
+      // @ts-expect-error colorR was collapsed into the color array.
+      data: { color: [1, 1, 1], colorR: 1 },
+    });
+  });
+});