@forgeax/engine-runtime 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-runtime",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,37 +26,37 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-animation": "0.1.21",
-    "@forgeax/engine-assets-runtime": "0.1.21",
-    "@forgeax/engine-audio-webaudio": "0.1.21",
-    "@forgeax/engine-codec": "0.1.21",
-    "@forgeax/engine-debug-draw": "0.1.21",
-    "@forgeax/engine-ecs": "0.1.21",
-    "@forgeax/engine-font": "0.1.21",
-    "@forgeax/engine-geometry": "0.1.21",
-    "@forgeax/engine-graphics-extras": "0.1.21",
-    "@forgeax/engine-image": "0.1.21",
-    "@forgeax/engine-input": "0.1.21",
-    "@forgeax/engine-math": "0.1.21",
-    "@forgeax/engine-pack": "0.1.21",
-    "@forgeax/engine-profiler": "0.1.21",
-    "@forgeax/engine-render": "0.1.21",
-    "@forgeax/engine-render-graph": "0.1.21",
-    "@forgeax/engine-rhi": "0.1.21",
-    "@forgeax/engine-rhi-null": "0.1.21",
-    "@forgeax/engine-rhi-webgpu": "0.1.21",
-    "@forgeax/engine-rhi-wgpu": "0.1.21",
-    "@forgeax/engine-scene": "0.1.21",
-    "@forgeax/engine-shader": "0.1.21",
-    "@forgeax/engine-skinning": "0.1.21",
-    "@forgeax/engine-types": "0.1.21",
-    "@forgeax/engine-vfx": "0.1.21"
+    "@forgeax/engine-animation": "0.1.23",
+    "@forgeax/engine-assets-runtime": "0.1.23",
+    "@forgeax/engine-audio-webaudio": "0.1.23",
+    "@forgeax/engine-codec": "0.1.23",
+    "@forgeax/engine-debug-draw": "0.1.23",
+    "@forgeax/engine-ecs": "0.1.23",
+    "@forgeax/engine-font": "0.1.23",
+    "@forgeax/engine-geometry": "0.1.23",
+    "@forgeax/engine-graphics-extras": "0.1.23",
+    "@forgeax/engine-image": "0.1.23",
+    "@forgeax/engine-input": "0.1.23",
+    "@forgeax/engine-math": "0.1.23",
+    "@forgeax/engine-pack": "0.1.23",
+    "@forgeax/engine-profiler": "0.1.23",
+    "@forgeax/engine-render": "0.1.23",
+    "@forgeax/engine-render-graph": "0.1.23",
+    "@forgeax/engine-rhi": "0.1.23",
+    "@forgeax/engine-rhi-null": "0.1.23",
+    "@forgeax/engine-rhi-webgpu": "0.1.23",
+    "@forgeax/engine-rhi-wgpu": "0.1.23",
+    "@forgeax/engine-scene": "0.1.23",
+    "@forgeax/engine-shader": "0.1.23",
+    "@forgeax/engine-skinning": "0.1.23",
+    "@forgeax/engine-types": "0.1.23",
+    "@forgeax/engine-vfx": "0.1.23"
   },
   "devDependencies": {
-    "@forgeax/engine-import": "0.1.21",
-    "@forgeax/engine-naga": "0.1.21",
-    "@forgeax/engine-state": "0.1.21",
-    "@forgeax/engine-vite-plugin-shader": "0.1.21",
+    "@forgeax/engine-import": "0.1.23",
+    "@forgeax/engine-naga": "0.1.23",
+    "@forgeax/engine-state": "0.1.23",
+    "@forgeax/engine-vite-plugin-shader": "0.1.23",
     "@types/node": "^20.14.0"
   },
   "forgeax": {

package/src/__tests__/animation-graph-asset-union.test-d.ts

@@ -68,6 +68,8 @@ describe('AnimationGraph POD in the Asset union (M2 / w12)', () => {
           return 'video';
         case 'particle-effect':
           return 'particle-effect';
+        case 'ies-profile':
+          return 'ies-profile';
         default: {
           const _exhaustive: never = a;
           return _exhaustive;

package/src/__tests__/asset-brand-and-name-retirement.test.ts

@@ -2,8 +2,9 @@
 //
 //   AC-05: storedNameOf retired; per-GUID stored name lives on the envelope and
 //          feeds resolveName's `storedName` argument. resolveName's three-arg
-//          XOR derivation (single-asset basename / multi-asset stored name /
-//          no-package '' fallback / 1->N promotion freeze) must be unchanged.
+//          display-name derivation (stored-name precedence / package basename
+//          fallback / no-package '' fallback / promotion freeze) must remain
+//          coherent.
 //   AC-06: the 14-arm assetBrand switch retired for the ASSET_BRAND Record
 //          table. The table maps every Asset.kind to its brand, and the two
 //          consumption points (instantiate -> allocSharedRef brand arg;
@@ -19,7 +20,7 @@ function makeReg(): AssetRegistry {
 
 const sampler = { kind: 'sampler' as const };
 
-// ── AC-05: resolveName XOR derivation unchanged after storedNameOf retirement ──
+// ── AC-05: resolveName remains coherent after storedNameOf retirement ──
 
 describe('AC-05 resolveName regression (storedNameOf retired, name on envelope)', () => {
   it('single-asset package -> basename(path), no stored name needed', () => {

package/src/__tests__/asset-registry-scene.test-d.ts

@@ -44,6 +44,7 @@ describe('AssetUnion exhaustive switch covers all 15 members (feat-20260608 M0 b
       | 'tileset'
       | 'video'
       | 'particle-effect'
+      | 'ies-profile'
     >();
   });
 });

package/src/__tests__/asset.unit.test.ts

@@ -784,6 +784,7 @@ function _makeStubGPU(): unknown {
     'ui',
     'audio',
     'particle-effect',
+    'ies-profile',
   ] as const;
 
   const UNREGISTERED_STUBS = ['shader'] as const;
@@ -795,13 +796,15 @@ function _makeStubGPU(): unknown {
       for (const kind of REGISTERED_KINDS) {
         expect(reg.get(kind), `expected loader for kind '${kind}'`).toBeDefined();
       }
-      expect(reg.registeredKinds()).toHaveLength(17);
+      expect(reg.registeredKinds()).toHaveLength(18);
+      expect(reg.get('ies-profile'), 'ies-profile is wired internally').toBeDefined();
     });
 
     it('default set includes audio, video, and UI', () => {
       const reg = new LoaderRegistry();
       wireDefaultLoaders(reg);
-      expect(reg.registeredKinds()).toHaveLength(17);
+      expect(reg.registeredKinds()).toHaveLength(18);
+      expect(reg.get('ies-profile'), 'ies-profile is wired internally').toBeDefined();
       expect(reg.get('video'), 'video is wired internally (graphics-extras)').toBeDefined();
       expect(reg.get('ui'), 'ui is wired internally (engine-ui)').toBeDefined();
       expect(reg.get('audio'), 'audio is an ordinary default asset kind').toBeDefined();

package/src/__tests__/collect-transient-roundtrip.test.ts

@@ -14,9 +14,15 @@ import * as SceneOwner from '@forgeax/engine-scene';
 
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle } from '@forgeax/engine-ecs';
-import { World } from '@forgeax/engine-ecs';
+import { componentDefinition, World } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
-import { ChildOf, Children, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  Children,
+  GlobalTransform,
+  propagateTransforms,
+  Transform,
+} from '@forgeax/engine-scene';
 import type { LocalEntityId, SceneAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { rootsToSceneAsset } from '../collect-scene-asset';
@@ -26,7 +32,7 @@ import { registerSceneComponents } from './helpers/register-scene-components';
 // Read the resolved world mat4 (column-major 16 floats) from the Transform
 // world column array view.
 function worldOf(world: World, entity: EntityHandle): Float32Array {
-  return world.get(entity, Transform).unwrap().world;
+  return world.get(entity, GlobalTransform).unwrap().world;
 }
 
 function makeRegistry(): AssetRegistry {
@@ -210,6 +216,7 @@ describe('w1 — AC-04 transient world roundtrip numeric equivalence', () => {
     for (const ent of collected.value.entities) {
       const t = (ent.components as Record<string, Record<string, unknown>>).Transform;
       if (t !== undefined) expect('world' in t).toBe(false);
+      expect((ent.components as Record<string, unknown>).GlobalTransform).toBeUndefined();
     }
 
     // Round-trip into a fresh world.
@@ -266,4 +273,8 @@ describe('w1 — AC-04 transient world roundtrip numeric equivalence', () => {
     expect(wDst[13] as number).toBeCloseTo(4, 5);
     expect(wDst[14] as number).toBeCloseTo(5, 5);
   });
+
+  it('declares GlobalTransform transient and reconstructs it from the authored pair', () => {
+    expect(componentDefinition(GlobalTransform).policy.transient).toBe(true);
+  });
 });

package/src/__tests__/components.test-d.ts

@@ -16,18 +16,20 @@
 
 import type { InputShapeOf, SchemaOf, ShapeOf } from '@forgeax/engine-ecs';
 import type { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
-import type { ChildOf, Transform } from '@forgeax/engine-scene';
+import type { ChildOf, GlobalTransform, Transform } from '@forgeax/engine-scene';
 import type { Handle } from '@forgeax/engine-types';
 import { describe, expectTypeOf, it } from 'vitest';
 
 describe('w7 type-level - 5 component schemas yield exact data shapes via ShapeOf', () => {
-  it('Transform data shape has 3 local inline-array fields + world array<f32,16>', () => {
+  it('Transform data shape has 3 local inline-array fields', () => {
     type Data = ShapeOf<SchemaOf<typeof Transform>>;
-    expectTypeOf<keyof Data>().toEqualTypeOf<'pos' | 'quat' | 'scale' | 'world'>();
+    expectTypeOf<keyof Data>().toEqualTypeOf<'pos' | 'quat' | 'scale'>();
     expectTypeOf<Data['pos']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<Data['quat']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<Data['scale']>().toEqualTypeOf<Float32Array>();
-    expectTypeOf<Data['world']>().toEqualTypeOf<Float32Array>();
+    type GlobalData = ShapeOf<SchemaOf<typeof GlobalTransform>>;
+    expectTypeOf<keyof GlobalData>().toEqualTypeOf<'world'>();
+    expectTypeOf<GlobalData['world']>().toEqualTypeOf<Float32Array>();
     // Write side widens `array<f32, N>` to also accept plain number[] literals
     // (InputShapeOf asymmetry): `pos: [1, 2, 3]` spawns without a
     // Float32Array wrapper at the call site.
@@ -190,12 +192,13 @@ describe('w7 type-level - component name literal types are preserved', () => {
 // ────────────────────────────────────────────────────────────────────────────
 
 describe('w15 AC-04 type constraint — ShapeOf derivation from field-payload', () => {
-  it("ShapeOf<SchemaOf<typeof Transform>> yields Float32Array views (all 'array<f32, N>' -> Float32Array)", () => {
+  it('ShapeOf<SchemaOf<typeof Transform>> yields local Float32Array views', () => {
     type T = ShapeOf<SchemaOf<typeof Transform>>;
     expectTypeOf<T['pos']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<T['quat']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<T['scale']>().toEqualTypeOf<Float32Array>();
-    expectTypeOf<T['world']>().toEqualTypeOf<Float32Array>();
+    type GlobalData = ShapeOf<SchemaOf<typeof GlobalTransform>>;
+    expectTypeOf<GlobalData['world']>().toEqualTypeOf<Float32Array>();
   });
 
   it("ShapeOf<SchemaOf<typeof Camera>> yields 21 number fields ('f32' -> number) + autoAspect boolean ('bool' -> boolean)", () => {

package/src/__tests__/components.unit.test.ts

@@ -65,7 +65,13 @@ import {
   Tilemap,
 } from '@forgeax/engine-render/authoring';
 import * as SceneOwner from '@forgeax/engine-scene';
-import { ChildOf, Children, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  Children,
+  GlobalTransform,
+  propagateTransforms,
+  Transform,
+} from '@forgeax/engine-scene';
 import type { Handle, LocalEntityId, SceneAsset, SceneEntity } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
 import { describe, expect, expectTypeOf, it } from 'vitest';
@@ -150,17 +156,17 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   // abstraction: components are flat-scalar SoA columns, not nested objects).
 
   describe('w7 - 5 component schemas register through defineComponent', () => {
-    it('Transform has pos/quat/scale inline array fields + world array<f32,16>', () => {
+    it('Transform has the three authored local array fields', () => {
       expect(Transform.name).toBe('Transform');
-      expect(Object.keys(componentSchema(Transform)).length).toBe(4);
+      expect(Object.keys(componentSchema(Transform)).length).toBe(3);
       // pos: inline [x, y, z]
       expect(componentSchema(Transform).pos).toBe('array<f32, 3>');
       // quat: inline [x, y, z, w] quaternion
       expect(componentSchema(Transform).quat).toBe('array<f32, 4>');
       // scale: inline [x, y, z]
       expect(componentSchema(Transform).scale).toBe('array<f32, 3>');
-      // world: resolved mat4 (column-major 16 floats)
-      expect(componentSchema(Transform).world).toBe('array<f32, 16>');
+      expect(GlobalTransform.name).toBe('GlobalTransform');
+      expect(componentSchema(GlobalTransform).world).toBe('array<f32, 16>');
     });
 
     it('MeshFilter has 1 shared<MeshAsset> field (assetHandle; M5 / w14)', () => {
@@ -414,9 +420,10 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   //                    file keeps an integration-shape spawn smoke for the
   //                    archetype-with-Children path.
   //
-  // feat-20260601 M4: GlobalTransform is retired. The resolved world transform
-  // is the `Transform.world` mat4 column; propagate + hierarchy compose coverage
-  // lives in render-system-extract.test.ts (Transform.world parent x child).
+  // The resolved world transform is the `GlobalTransform.world` mat4 column;
+  // Transform's generic ECS requirement materializes that carrier on normal
+  // spawn/add paths. Propagation + hierarchy compose coverage lives in
+  // render-system-extract.test.ts (GlobalTransform.world parent x child).
   //
   // charter mapping: proposition 2 (Bevy ChildOf/Children industry analog) +
   // proposition 3 (machine-readable schema > prose: grep componentSchema(ChildOf) /
@@ -435,14 +442,10 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect((componentSchema(Children) as Record<string, unknown>).entities).toBe('array<entity>');
     });
 
-    it('Transform carries the resolved world mat4 column (array<f32, 16>)', () => {
-      // feat-20260601 M4: the world transform lives on Transform.world, not a
-      // separate GlobalTransform component. The 3 local-TRS inline array
-      // columns (pos/quat/scale) plus the `world: array<f32, 16>` resolved
-      // mat4 are the full shape.
-      const tKeys = Object.keys(componentSchema(Transform));
+    it('GlobalTransform carries the resolved world mat4 column', () => {
+      const tKeys = Object.keys(componentSchema(GlobalTransform));
       expect(tKeys).toContain('world');
-      expect(componentSchema(Transform).world).toBe('array<f32, 16>');
+      expect(componentSchema(GlobalTransform).world).toBe('array<f32, 16>');
       expect(componentSchema(Transform).pos).toBe('array<f32, 3>');
       expect(componentSchema(Transform).quat).toBe('array<f32, 4>');
       expect(componentSchema(Transform).scale).toBe('array<f32, 3>');
@@ -605,7 +608,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   //
   // Two orthogonal guarantees after ChildOf gained its `relationship` block:
   //   AC-25 reader path unchanged -- propagateTransforms still walks ChildOf.parent
-  //     upward and composes child.Transform.world = parent.world x
+  //     upward and composes child.GlobalTransform.world = parent.world x
   //     compose(child local). The migration must NOT alter this output.
   //   AC-25 mirror auto-maintained -- spawning / removing / reparenting ChildOf
   //     now auto-updates the parent's Children.entities list (the OOS-10 manual-
@@ -637,9 +640,9 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       const r = propagateTransforms(world);
       expect(r.ok).toBe(true);
 
-      // feat-20260601: the resolved world transform lives on Transform.world
+      // feat-20260601: the resolved world transform lives on GlobalTransform.world
       // (a 16-float column-major mat4); the translation column is m[12,13,14].
-      const t = world.get(child, Transform);
+      const t = world.get(child, GlobalTransform);
       expect(t.ok).toBe(true);
       if (!t.ok) return;
       const w = t.value.world;
@@ -2415,6 +2418,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       const world = new World();
       const e = world.spawn({ component: Transform, data: {} }).unwrap();
       const row = world.get(e, Transform).unwrap();
+      const global = world.get(e, GlobalTransform).unwrap();
 
       // local pos/quat/scale inline array columns at identity.
       expect(Array.from(row.pos)).toEqual([0, 0, 0]);
@@ -2423,7 +2427,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
 
       // world array<f32,16> resolves to a Float32Array view of 16 contiguous
       // floats. Default fill is the identity mat4 (column-major).
-      const w = row.world as Float32Array;
+      const w = global.world as Float32Array;
       expect(w).toBeInstanceOf(Float32Array);
       expect(w.length).toBe(16);
       const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];

package/src/__tests__/errors.unit.test.ts

@@ -547,6 +547,8 @@ type RuntimeLayerError = RenderError | AssetRuntimeError | SkinError;
               return 'points lines budget exceeded';
             case 'points-lines-prepare-failed':
               return 'points lines prepare failed';
+            case 'light-resource-unavailable':
+              return 'light resource unavailable';
             case 'transmission-capability-missing':
               return 'transmission capability missing';
             case 'projector-binding-failed':
@@ -719,6 +721,7 @@ type RuntimeLayerError = RenderError | AssetRuntimeError | SkinError;
               return 'ok';
             case 'points-lines-prepare-failed':
               return 'ok';
+            case 'light-resource-unavailable':
             case 'transmission-capability-missing':
               return 'ok';
             case 'projector-binding-failed':

package/src/__tests__/extract-frames-merge.test.ts

@@ -161,11 +161,13 @@ function simulateMerge(
   // AC-04: lights — point[]/spot[] concat; directional first-hit in worlds[] order; directionalCount sum
   const point: PointLightSnapshot[] = [];
   const spot: SpotLightSnapshot[] = [];
+  const rect: ExtractedLights['rect'][number][] = [];
   let directional: DirectionalLightSnapshot | undefined;
   let directionalCount = 0;
   for (const f of frames) {
     for (const p of f.lights.point) point.push(p);
     for (const s of f.lights.spot) spot.push(s);
+    for (const r of f.lights.rect) rect.push(r);
     if (directional === undefined && f.lights.directional !== undefined) {
       directional = f.lights.directional;
     }
@@ -179,6 +181,7 @@ function simulateMerge(
     directionalCount,
     point,
     spot,
+    rect,
     lightViewProj: firstDirectionalLights?.lightViewProj,
     splitPlanes: firstDirectionalLights?.splitPlanes,
     cascadeCount: firstDirectionalLights?.cascadeCount,

package/src/__tests__/helpers/register-runtime-components.ts

@@ -24,7 +24,14 @@ import {
   TileLayer,
   Tilemap,
 } from '@forgeax/engine-render/authoring';
-import { ChildOf, Children, MorphWeights, Name, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  Children,
+  GlobalTransform,
+  MorphWeights,
+  Name,
+  Transform,
+} from '@forgeax/engine-scene';
 
 const RUNTIME_COMPONENTS: readonly Component[] = [
   Camera,
@@ -51,6 +58,7 @@ const RUNTIME_COMPONENTS: readonly Component[] = [
   TileLayer,
   Tilemap,
   Transform,
+  GlobalTransform,
   VideoPlayer,
   Visibility,
 ];

package/src/__tests__/helpers/register-scene-components.ts

@@ -1,10 +1,17 @@
 import type { Component, World } from '@forgeax/engine-ecs';
 import { SceneInstance } from '@forgeax/engine-render';
-import { ChildOf, Children, Transform } from '@forgeax/engine-scene';
+import { ChildOf, Children, GlobalTransform, Transform } from '@forgeax/engine-scene';
 
 /** Register the scene vocabulary explicitly for an isolated test World. */
 export function registerSceneComponents(world: World, extras: readonly Component[] = []): void {
-  for (const component of [SceneInstance, ChildOf, Children, Transform, ...extras]) {
+  for (const component of [
+    SceneInstance,
+    ChildOf,
+    Children,
+    Transform,
+    GlobalTransform,
+    ...extras,
+  ]) {
     world.components.register(component).unwrap();
   }
 }

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

@@ -7,8 +7,8 @@
 // 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
+//   2. PointLightBuffer (color lanes)                       -> packDirectLightSlot
+//   3. SpotLightBuffer (direction + color lanes)            -> packDirectLightSlot
 //   4. Skylight uniform/ambient (color destructure)         -> SkylightSnapshot
 // (Camera clear pass is M3, not here.)
 
@@ -16,7 +16,7 @@ import { vec3 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import { ok } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
-import { packPointLight, packSpotLight } from '../../../render/src/light-buffer-layout';
+import { packDirectLightSlot } from '../../../render/src/light-buffer-layout';
 import { writeViewUbo } from '../../../render/src/record/view-ubo';
 import type { CameraSnapshot } from '../../../render/src/render-contract';
 import type {
@@ -103,7 +103,7 @@ describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
     expect(payload[22]).toBeCloseTo(0.7, 5);
   });
 
-  it('packPointLight writes color into slots 4..6 byte-for-byte (32 B)', () => {
+  it('packDirectLightSlot writes Point color into slots 4..6 byte-for-byte (80 B)', () => {
     const snap: PointLightSnapshot = {
       kind: 'point',
       position: vec3.create(1.5, -2.25, 0.125),
@@ -111,14 +111,14 @@ describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
       intensity: 2,
       invRangeSquared: 0.04,
     };
-    const out = packPointLight(snap);
-    expect(out.byteLength).toBe(32);
+    const out = packDirectLightSlot(snap);
+    expect(out.byteLength).toBe(80);
     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 (80 B)', () => {
+  it('packDirectLightSlot writes Spot color slots 4..6 + direction slots 8..10 byte-for-byte (80 B)', () => {
     const snap: SpotLightSnapshot = {
       kind: 'spot',
       position: vec3.create(0, 5, 0),
@@ -135,9 +135,7 @@ describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
       farPlane: 50,
       shadowAtlasTile: -1,
     };
-    const out = packSpotLight(snap);
-    // SpotLight carries projector receiver controls and the shadow intensity
-    // tail in the current std430 payload.
+    const out = packDirectLightSlot(snap);
     expect(out.byteLength).toBe(80);
     expect(out[4]).toBeCloseTo(0.3, 6);
     expect(out[5]).toBeCloseTo(0.4, 6);

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

@@ -23,11 +23,16 @@
 import { expectTypeOf, test } from 'vitest';
 import type { DirectionalShadowQuality } from '../../../render/src/components/directional-shadow-filter';
 import type { LightValidationError } from '../../../render/src/components/light-helpers';
+import type {
+  DirectLightSlotKind,
+  DirectLightSnapshot,
+} from '../../../render/src/light-buffer-layout';
 import type {
   DirectionalLightSnapshot,
   ExtractedLights,
   LightSnapshot,
   PointLightSnapshot,
+  RectAreaDirectLightSnapshot,
   SpotLightSnapshot,
 } from '../../../render/src/render-system-extract';
 
@@ -46,6 +51,8 @@ function consumeSnapshot(s: LightSnapshot): number {
       return s.invRangeSquared;
     case 'spot':
       return s.cosInner + s.cosOuter;
+    case 'rect-area':
+      return s.halfWidth + s.halfHeight;
     default:
       return assertNever(s);
   }
@@ -53,7 +60,7 @@ function consumeSnapshot(s: LightSnapshot): number {
 
 test('LightSnapshot is a discriminated union on kind', () => {
   expectTypeOf<LightSnapshot>().toEqualTypeOf<
-    DirectionalLightSnapshot | PointLightSnapshot | SpotLightSnapshot
+    DirectionalLightSnapshot | PointLightSnapshot | SpotLightSnapshot | RectAreaDirectLightSnapshot
   >();
   // Smoke that the consumer compiles (run-time noop; compile-time exhaustive).
   void consumeSnapshot;
@@ -83,6 +90,25 @@ test('ExtractedLights three-bucket shape', () => {
   expectTypeOf<ExtractedLights['directionalCount']>().toEqualTypeOf<number>();
   expectTypeOf<ExtractedLights['point']>().toEqualTypeOf<readonly PointLightSnapshot[]>();
   expectTypeOf<ExtractedLights['spot']>().toEqualTypeOf<readonly SpotLightSnapshot[]>();
+  expectTypeOf<ExtractedLights['rect']>().toEqualTypeOf<readonly RectAreaDirectLightSnapshot[]>();
+});
+
+function consumeDirectLight(snapshot: DirectLightSnapshot): number {
+  switch (snapshot.kind) {
+    case 'point':
+      return snapshot.invRangeSquared;
+    case 'spot':
+      return snapshot.cosInner + snapshot.cosOuter;
+    case 'rect-area':
+      return snapshot.halfWidth + snapshot.halfHeight;
+    default:
+      return assertNever(snapshot);
+  }
+}
+
+test('DirectLightSlot kind is closed and includes only finite direct lights', () => {
+  expectTypeOf<DirectLightSlotKind>().toEqualTypeOf<'point' | 'spot' | 'rect-area'>();
+  void consumeDirectLight;
   expectTypeOf<ExtractedLights['directionalShadowQuality']>().toEqualTypeOf<
     DirectionalShadowQuality | undefined
   >();

package/src/__tests__/lights-preservation.fixup.test.ts

@@ -9,11 +9,7 @@ import {
   validatePointLightShadowData,
   validateSpotLightData,
 } from '../../../render/src/components/light-helpers';
-import {
-  packLightSlot,
-  packPointLight,
-  packSpotLight,
-} from '../../../render/src/light-buffer-layout';
+import { packDirectLightSlot } from '../../../render/src/light-buffer-layout';
 import { buildPbrViewBglEntries } from '../../../render/src/pbr-pipeline';
 import type {
   PointLightSnapshot,
@@ -87,32 +83,34 @@ describe('Point/Spot and shared-light regression guard', () => {
     expect(degToCos(60)).toBeCloseTo(0.5, 8);
   });
 
-  it('keeps Point/Spot packing and the shared LightSlot discriminant intact', () => {
+  it('keeps Point/Spot packing in the shared DirectLightSlot owner', () => {
     const point = pointSnapshot();
     const spot = spotSnapshot();
-    const pointPacked = packPointLight(point);
-    const spotPacked = packSpotLight(spot);
-    const pointSlot = packLightSlot(point, { shadowAtlasLayer: 2, near: 0.1, far: 20 });
-    const spotSlot = packLightSlot(spot);
+    const pointSlot = packDirectLightSlot({ ...point, shadowAtlasLayer: 2 });
+    const spotSlot = packDirectLightSlot(spot);
 
-    expect(pointPacked.byteLength).toBe(32);
-    expect(spotPacked.byteLength).toBe(80);
-    expect(new Uint32Array(pointSlot.buffer)[12]).toBe(0);
-    expect(new Int32Array(pointSlot.buffer)[13]).toBe(2);
-    expect(new Uint32Array(spotSlot.buffer)[12]).toBe(1);
-    expect(new Int32Array(spotSlot.buffer)[13]).toBe(-1);
+    expect(pointSlot.byteLength).toBe(80);
+    expect(spotSlot.byteLength).toBe(80);
+    expect(new Uint32Array(pointSlot.buffer)[16]).toBe(0);
+    expect(new Uint32Array(pointSlot.buffer)[17]).toBe(2);
+    expect(new Uint32Array(spotSlot.buffer)[16]).toBe(1);
+    expect(new Uint32Array(spotSlot.buffer)[17]).toBe(0xffffffff);
   });
 
-  it('keeps shared PBR view bindings for both storage and uniform light routes', () => {
+  it('keeps the PBR view layout independent from cluster light storage capability', () => {
     const storageBindings = buildPbrViewBglEntries({ storageBuffer: true });
     const uniformBindings = buildPbrViewBglEntries({ storageBuffer: false });
     expect(storageBindings.map((entry) => entry.binding)).toEqual(
       uniformBindings.map((entry) => entry.binding),
     );
-    expect(storageBindings[1]?.buffer?.type).toBe('read-only-storage');
-    expect(storageBindings[2]?.buffer?.type).toBe('read-only-storage');
-    expect(uniformBindings[1]?.buffer?.type).toBe('uniform');
-    expect(uniformBindings[2]?.buffer?.type).toBe('uniform');
+    // Local lights are consumed through the cluster payload in group(2). The
+    // shared view group therefore has no legacy direct-light storage/uniform
+    // entries at bindings 1/2, and its shape cannot drift with the capability
+    // route selected for the cluster buffers.
+    expect(storageBindings.find((entry) => entry.binding === 1)).toBeUndefined();
+    expect(storageBindings.find((entry) => entry.binding === 2)).toBeUndefined();
+    expect(uniformBindings.find((entry) => entry.binding === 1)).toBeUndefined();
+    expect(uniformBindings.find((entry) => entry.binding === 2)).toBeUndefined();
   });
 
   it('keeps Point/Spot pcfKernelSize validation independent of Directional quality', () => {