@forgeax/engine-runtime 0.1.20 → 0.1.23

package/src/__tests__/template-game-default-api-contract.test.ts

@@ -1,5 +1,5 @@
 // template-game-default-api-contract.test - the surface APIs that the
-// `templates/game-default/main.ts` `instantiateScenePack` helper relies on
+// `apps/game-capability-lab/main.ts` scene instantiation relies on
 // must continue to exist and compose. Catches the API drift that produced
 // `TypeError: Cannot read properties of undefined (reading
 // 'setSceneAssetResolver')` at runtime when an earlier
@@ -30,7 +30,7 @@ import { fileURLToPath } from 'node:url';
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
 import { componentDefinition } from '@forgeax/engine-ecs/internal';
-import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { AssetGuid, PackageId } from '@forgeax/engine-pack/guid';
 import { MeshRenderer, SceneInstance } from '@forgeax/engine-render';
 // Importing the runtime components barrel populates the global component
 // table consulted by `World._buildSceneEntityComponentDatas` — without
@@ -47,7 +47,7 @@ function lid(n: number): LocalEntityId {
   return n as LocalEntityId;
 }
 
-// Shape this fixture mirrors the `templates/game-default/scene.pack.json`
+// Shape this fixture mirrors the `apps/game-capability-lab/assets/scene.pack.json`
 // SceneAsset payload after the template's `instantiateScenePack` helper has
 // rewritten ref-int → GUID strings + lifted MeshRenderer.material → materials[].
 // We register one MaterialAsset so the SceneAsset's MeshRenderer GUID slot
@@ -83,7 +83,7 @@ function buildSceneAssetWithGuidRef(): SceneAsset {
   return { kind: 'scene', entities: nodes };
 }
 
-describe('templates/game-default API contract (regression for `world.sceneInstances` drift)', () => {
+describe('game-capability-lab API contract (regression for `world.sceneInstances` drift)', () => {
   it('(a) assets.instantiate returns the synthetic root Entity directly (no `byRef` indirection)', async () => {
     const reg = new AssetRegistry(makeMockShaderRegistry());
     const world = new World();
@@ -208,11 +208,11 @@ describe('templates/game-default API contract (regression for `world.sceneInstan
   // doesn't pass while runtime explodes (the template is a workspace
   // sibling that the engine packages don't import — typecheck never sees
   // it).
-  it('(c2) [regression] templates/game-default/main.ts must not call `world.sceneInstances`', () => {
+  it('(c2) [regression] apps/game-capability-lab/main.ts must not call `world.sceneInstances`', () => {
     const here = fileURLToPath(import.meta.url);
     // here = packages/runtime/src/__tests__/<file> → 4 levels up = repo root
     const repoRoot = resolve(here, '..', '..', '..', '..', '..');
-    const main = readFileSync(resolve(repoRoot, 'templates', 'game-default', 'main.ts'), 'utf-8');
+    const main = readFileSync(resolve(repoRoot, 'apps', 'game-capability-lab', 'main.ts'), 'utf-8');
     // Strip line comments so prose explaining the rename does not trip the
     // grep gate; the gate targets actual member access only.
     const noComments = main
@@ -267,17 +267,26 @@ describe('templates/game-default API contract (regression for `world.sceneInstan
 
     const here = fileURLToPath(import.meta.url);
     const repoRoot = resolve(here, '..', '..', '..', '..', '..');
-    const packPath = resolve(repoRoot, 'templates', 'game-default', 'assets', 'scene.pack.json');
+    const packPath = resolve(repoRoot, 'apps', 'game-capability-lab', 'assets', 'scene.pack.json');
     const pack = JSON.parse(readFileSync(packPath, 'utf-8')) as {
-      assets: {
-        kind: string;
-        payload?: { entities?: SceneEntity[]; nodes?: SceneEntity[] };
-      }[];
+      assets:
+        | {
+            kind: string;
+            payload?: { entities?: SceneEntity[]; nodes?: SceneEntity[] };
+          }[]
+        | Record<
+            string,
+            {
+              kind: string;
+              payload?: { entities?: SceneEntity[]; nodes?: SceneEntity[] };
+            }
+          >;
     };
+    const assets = Array.isArray(pack.assets) ? pack.assets : Object.values(pack.assets);
 
     const offenders: string[] = [];
     let scanned = 0;
-    for (const asset of pack.assets) {
+    for (const asset of assets) {
       // The envelope `kind` is the authoritative asset discriminant; the payload
       // no longer restates it (Derive, Don't Duplicate — the loader synthesises
       // Asset.kind from the envelope on load).
@@ -317,16 +326,22 @@ describe('templates/game-default API contract (regression for `world.sceneInstan
   it('(e2) [regression] every inline template material is referenced by a MeshRenderer', () => {
     const here = fileURLToPath(import.meta.url);
     const repoRoot = resolve(here, '..', '..', '..', '..', '..');
-    const packPath = resolve(repoRoot, 'templates', 'game-default', 'assets', 'scene.pack.json');
+    const packPath = resolve(repoRoot, 'apps', 'game-capability-lab', 'assets', 'scene.pack.json');
+    type TemplatePackAsset = {
+      guid?: string;
+      kind: string;
+      payload?: { entities?: { components: { MeshRenderer?: { materials?: number[] } } }[] };
+      refs?: string[];
+    };
     const pack = JSON.parse(readFileSync(packPath, 'utf-8')) as {
-      assets: {
-        guid: string;
-        kind: string;
-        payload?: { entities?: { components: { MeshRenderer?: { materials?: number[] } } }[] };
-        refs?: string[];
-      }[];
+      packageId?: string;
+      assets: TemplatePackAsset[] | Record<string, TemplatePackAsset>;
     };
-    const scene = pack.assets.find((asset) => asset.kind === 'scene');
+    const entries = Array.isArray(pack.assets)
+      ? pack.assets.map((asset) => ({ asset, sourceKey: undefined }))
+      : Object.entries(pack.assets).map(([sourceKey, asset]) => ({ asset, sourceKey }));
+    const sceneEntry = entries.find(({ asset }) => asset.kind === 'scene');
+    const scene = sceneEntry?.asset;
     expect(scene).toBeDefined();
     if (scene === undefined) return;
 
@@ -335,9 +350,16 @@ describe('templates/game-default API contract (regression for `world.sceneInstan
         (entity.components.MeshRenderer?.materials ?? []).map((index) => scene.refs?.[index]),
       ),
     );
-    const orphanedMaterialGuids = pack.assets
-      .filter((asset) => asset.kind === 'material')
-      .map((asset) => asset.guid)
+    const packageId = pack.packageId === undefined ? undefined : PackageId.parse(pack.packageId);
+    const guidFor = ({ asset, sourceKey }: (typeof entries)[number]): string | undefined => {
+      if (asset.guid !== undefined) return asset.guid;
+      if (sourceKey === undefined || packageId === undefined || !packageId.ok) return undefined;
+      return AssetGuid.format(AssetGuid.derive(packageId.value, sourceKey));
+    };
+    const orphanedMaterialGuids = entries
+      .filter(({ asset }) => asset.kind === 'material')
+      .map(guidFor)
+      .filter((guid): guid is string => guid !== undefined)
       .filter((guid) => !referencedMaterialGuids.has(guid));
 
     expect(orphanedMaterialGuids).toEqual([]);

package/src/__tests__/tilemap-chunk-extract.propagate-order.test.ts

@@ -1,7 +1,13 @@
 import { type EntityHandle, Update, World } from '@forgeax/engine-ecs';
 import { MeshFilter } from '@forgeax/engine-render';
 import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
-import { ChildOf, Children, registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  Children,
+  GlobalTransform,
+  registerPropagateTransforms,
+  Transform,
+} from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
 import { tilemapChunkExtractSystem } from '../../../render/src/tilemap-chunk-extract-system';
 import { registerRuntimeComponents } from './helpers/register-runtime-components';
@@ -65,12 +71,12 @@ describe('tilemap derivation and Transform publication order', () => {
     const children = world.get(layer, Children).unwrap();
     const derived = children.entities[0] as EntityHandle | undefined;
     expect(derived).toBeDefined();
-    const transform = derived === undefined ? undefined : world.get(derived, Transform);
+    const transform = derived === undefined ? undefined : world.get(derived, GlobalTransform);
     const matrix = transform?.ok ? transform.value.world : undefined;
     expect({
       derived: matrix?.[12],
-      layer: world.get(layer, Transform).unwrap().world[12],
-      map: world.get(map, Transform).unwrap().world[12],
+      layer: world.get(layer, GlobalTransform).unwrap().world[12],
+      map: world.get(map, GlobalTransform).unwrap().world[12],
       entityCount: world.inspect().entityCount,
     }).toEqual({ derived: 5, layer: 4, map: 4, entityCount: expect.any(Number) });
     expect(matrix?.[13]).toBeCloseTo(1);

package/src/__tests__/transform-hierarchy-pixel-diff.dawn.test.ts

@@ -7,7 +7,7 @@
 // through renderer.attach, spawns a non-identity parent + a ChildOf
 // child + a static reference sphere, then proves moving the PARENT moves the
 // CHILD's rendered world position (the child gets no Transform write of its
-// own between frames; the only change is the parent's resolved Transform.world
+// own between frames; the only change is the parent's resolved GlobalTransform.world
 // mat4 propagated down the ChildOf edge). This is the vitest-dawn-project
 // counterpart to the CI
 // smoke step so `pnpm test:dawn` exercises the visual-evidence path
@@ -154,7 +154,7 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
     if (device === undefined) throw new Error('GPUDevice not captured');
 
     // Single World wires the consume path through renderer.attach so the
-    // child's resolved Transform.world mat4 is derived each frame. feat-20260614
+    // child's resolved GlobalTransform.world mat4 is derived each frame. feat-20260614
     // M8: the material is a per-World column handle minted via allocSharedRef
     // (AssetRegistry has no handle concept).
     const world = new World();

package/src/__tests__/view-ubo-layout.browser.test.ts

@@ -1,6 +1,7 @@
 // view-ubo-layout.browser.test.ts - feat-20260518-pbr-direct-lighting-mvp
-// feat-20260531-skybox-env-background M2 / w4 (TDD red): VIEW_UBO_BYTES
-// 112 -> 176 -> 240 layout (worldViewProj 64 B + lightDir 16 B + lightColor
+// feat-20260827-directional-csm-pcss-quality M1: VIEW_UBO_BYTES remains 960
+// while the View slot remains 1024 B. The prefix layout is unchanged and the
+// directional shadow carrier reuses the existing tail pad.
 // 16 B + cameraPos 16 B + lightSpaceMatrix 64 B + inverseViewProj 64 B;
 // std140 vec3 padded to 16-byte boundaries).
 //
@@ -44,14 +45,16 @@ const VIEW_UBO_OFFSETS = {
   lightSpaceMatrix: 112,
   inverseViewProj: 176,
 } as const;
-const VIEW_UBO_BYTES = 240;
+const VIEW_UBO_BYTES = 960;
+const DIRECTIONAL_FILTER_OFFSET = 512;
+const SPOT_LIGHT_VIEW_PROJ_OFFSET = 528;
 
 describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
-  it.skipIf(!browserReady)('host write payload is exactly 240 bytes (60 floats)', () => {
-    // The host (render-system-record.ts) builds a Float32Array(60) and
+  it.skipIf(!browserReady)('host write payload is exactly 960 bytes (240 floats)', () => {
+    // The host (view-ubo.ts) builds a Float32Array(240) and
     // emits a single queue.writeBuffer. Asserting the size lock here keeps
     // the host shape and shader ABI in agreement before the GPU sees it.
-    const payload = new Float32Array(60);
+    const payload = new Float32Array(240);
     expect(payload.byteLength).toBe(VIEW_UBO_BYTES);
   });
 
@@ -63,17 +66,17 @@ describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
     expect(VIEW_UBO_OFFSETS.lightSpaceMatrix).toBe(112);
     expect(VIEW_UBO_OFFSETS.inverseViewProj).toBe(176);
     // Buffer total = inverseViewProj offset + mat4 (64 B) = 240.
-    expect(VIEW_UBO_OFFSETS.inverseViewProj + 64).toBe(VIEW_UBO_BYTES);
+    expect(VIEW_UBO_OFFSETS.inverseViewProj + 64).toBe(240);
   });
 
   it.skipIf(!browserReady)(
     'host packs lightDir / lightColor / cameraPos at canonical std140 slots',
     () => {
       // Canonical packing order documented in plan-strategy D-4: the host
-      // builds a 60-float buffer mirroring the shader-side `View` struct
+      // builds a 240-float buffer mirroring the shader-side `View` struct
       // field order. AC-06: existing field offsets unchanged -- tail append
       // only.
-      const payload = new Float32Array(60);
+      const payload = new Float32Array(240);
       // worldViewProj = identity for this assertion (mat4 in [0..16))
       payload[0] = 1; // m00
       payload[5] = 1; // m11
@@ -133,7 +136,7 @@ describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
     // calculation.
     const inverseProjF32Index = VIEW_UBO_OFFSETS.inverseViewProj / 4;
     expect(inverseProjF32Index).toBe(44);
-    const payload = new Float32Array(60);
+    const payload = new Float32Array(240);
     // Place an identity mat4 at inverseViewProj slot [44..59]
     payload[44] = 1;
     payload[49] = 1;
@@ -145,6 +148,13 @@ describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
     expect(payload[59]).toBe(1);
   });
 
+  it.skipIf(!browserReady)('shadow tail keeps the directional carrier before spot matrices', () => {
+    expect(DIRECTIONAL_FILTER_OFFSET).toBe(126 * 4 + 8);
+    expect(SPOT_LIGHT_VIEW_PROJ_OFFSET).toBe(132 * 4);
+    expect(SPOT_LIGHT_VIEW_PROJ_OFFSET - DIRECTIONAL_FILTER_OFFSET).toBe(16);
+    expect(SPOT_LIGHT_VIEW_PROJ_OFFSET + 4 * 4 * 16).toBe(VIEW_UBO_BYTES - 176);
+  });
+
   it.skipIf(!browserReady)(
     'existing field offsets unchanged by tail append (AC-06 rear-append guarantee)',
     () => {

package/src/collect-scene-asset.ts

@@ -336,7 +336,7 @@ export function rootsToSceneAsset(
   // mount.parent = P's ChildOf parent, and any ref to P resolves to the mount.
   const childOfTk0 = world.components.resolve('ChildOf');
   const childrenTk0 = world.components.resolve('Children');
-  const carrierAllowed = new Set(['Transform', 'Children', 'ChildOf', 'Entity']);
+  const carrierAllowed = new Set(['Transform', 'GlobalTransform', 'Children', 'ChildOf', 'Entity']);
   const carrierForAnchor = new Map<number, number>(); // anchorRaw -> carrierRaw
   const carrierToAnchor = new Map<number, number>(); // carrierRaw -> anchorRaw
   const isMountCarrier = (p: number, anchorRaw: number): boolean => {

package/src/components/__tests__/transform-vec-schema.test.ts

@@ -19,7 +19,7 @@
 
 import { World } from '@forgeax/engine-ecs';
 import { componentSchema } from '@forgeax/engine-ecs/internal';
-import { Transform } from '@forgeax/engine-scene';
+import { GlobalTransform, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
 
 describe('w4 -- Transform vec schema (AC-05)', () => {
@@ -46,7 +46,7 @@ describe('w4 -- Transform vec schema (AC-05)', () => {
   });
 
   it('(b) world column keeps array<f32, 16> (outside the M2 migration surface)', () => {
-    const schema = componentSchema(Transform) as Record<string, string>;
+    const schema = componentSchema(GlobalTransform) as Record<string, string>;
     expect(schema.world).toBe('array<f32, 16>');
   });
 });

package/src/createRenderer.ts

@@ -39,6 +39,8 @@ export async function createRenderer(
           ...(options.standardProfile === undefined
             ? {}
             : { standardProfile: options.standardProfile }),
+          ...(options.gpuPassTiming === undefined ? {} : { gpuPassTiming: options.gpuPassTiming }),
+          ...(options.ssrIdentity === undefined ? {} : { ssrIdentity: options.ssrIdentity }),
         };
   try {
     const constructed = await constructRuntimeRendererHost(canvas, rendererOptions, bundler);

package/src/index.ts

@@ -340,8 +340,7 @@ export {
 // never rendered). One barrel entry => one module copy => one registry shared by
 // createDebugDrawOnReady (the writer) and attachDebugOverlayPass (the reader).
 // feat-20260704-runtime-tier1-decomposition M2 / w10 (D-3): the third error
-// re-export block (HdrpCapsInsufficientError / HdrpIndexListOverflowError /
-// HdrpLightBudgetExceededError) is folded into the render-cluster class
+// re-export block (Standard Cluster error classes) is folded into the render-cluster class
 // re-export block above -- they are render-cluster members sourced from
 // ./errors/render.
 // feat-20260608-cluster-lighting M2 / w10 + verify F-1/F-2: HDRP cluster-forward

package/src/sprite-param-values.ts

@@ -31,7 +31,7 @@
  *   replaces this asset-side region.
  * - `pivotAndSize`: vec4 `[pivotX, pivotY, sizeX, sizeY]` — `.xy` is the
  *   pivot (0..1 normalised); `.zw` is the DEAD SLOT post-w11 (D-6 unit-
- *   quad: world scale flows entirely through Transform.world, no longer
+ *   quad: world scale flows entirely through GlobalTransform.world, no longer
  *   double-applied via the UBO). Default `[0.5, 0.5, 1, 1]`.
  * - `slicesAndMode`: vec4 `[left, top, right, bottom-signed]` — 9-slice
  *   border widths in UV (0..1) on the source texture region. Sum of