@forgeax/engine-runtime 0.1.21 → 0.1.24

package/src/__tests__/systems.cases.unit.test.ts

@@ -0,0 +1,425 @@
+// @ts-nocheck — merged file: indexed-access checks cascade across noUncheckedIndexedAccess for blocks originally outside src/ rootDir
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: block-scope isolation between merged source files (consolidation paradigm)
+//
+// Source files (N=44):
+//   - packages/runtime/__tests__/antialias-from-f32.test.ts
+//   - packages/runtime/src/__tests__/bloom-gating.test.ts
+//   - packages/runtime/src/__tests__/camera-antialias.test.ts
+//   - packages/runtime/src/__tests__/camera-bloom.test.ts
+//   - packages/runtime/src/__tests__/camera-clear-schema.test.ts
+//   - packages/runtime/src/__tests__/camera-ortho.test.ts
+//   - packages/runtime/src/__tests__/fxaa-intermediate-texture.test.ts
+//   - packages/runtime/src/__tests__/fxaa-pipeline.test.ts
+//   - packages/runtime/src/__tests__/ibl-pipeline-cache.test.ts
+//   - packages/runtime/src/__tests__/ibl-runtime-probe.test.ts
+//   - packages/runtime/src/__tests__/render-system-record-warn-once.test.ts
+//   - packages/runtime/src/__tests__/shadow-skip-non-triangle.test.ts
+//   - packages/runtime/src/__tests__/skin-errors-kebab-case.test.ts
+//   - packages/runtime/src/__tests__/skybox-error.test.ts
+//   - packages/runtime/src/__tests__/skybox-shader-compile.test.ts
+//   - packages/runtime/src/__tests__/skylight-bind-group.test.ts
+//   - packages/runtime/src/__tests__/skylight-component.test.ts
+//   - packages/runtime/src/__tests__/skylight-fallback-path.test.ts
+//   - packages/runtime/src/__tests__/skylight-pipeline-layout.test.ts
+//   - packages/runtime/src/__tests__/tonemap-hdr-target.test.ts
+//   - packages/runtime/src/__tests__/tonemap-pipeline-split.test.ts
+//   - packages/runtime/src/__tests__/zero-camera-clear-fallback.test.ts
+//   - packages/runtime/src/components/__tests__/skin.test.ts
+//   - packages/runtime/src/systems/__tests__/advance-animation-player.test.ts
+//   - packages/runtime/src/systems/__tests__/graph-skybox.test.ts
+//   - packages/runtime/src/systems/__tests__/propagate-transforms.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-cap-gate.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-instances-coexist.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-palette-extract.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-pipeline-routing.test.ts
+//   - packages/runtime/src/systems/__tests__/skybox-extract.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-boundary.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-clamp.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-frame-duration-negative.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-frame-duration-zero.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-loop.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-override-probe.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-regions-mismatch.test.ts
+//   - packages/runtime/src/systems/__tests__/tonemap.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort-config-get.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort-config-set.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort.test.ts
+//   - packages/runtime/src/__tests__/render-system-multi-material.test.ts
+//   - packages/runtime/src/__tests__/render-system-record-submesh.test.ts
+//
+// Paradigm: each block-scope wraps a source file. ancestorTitles[0] is the
+// source-preserved inner describe (NOT the source filename for these 3 files
+// — recovery path: vitest report ancestorTitles -> grep this file -> upstream
+// `// ─── from <name>.test.ts ───` block separator -> source filename).
+// Top-level imports merged + deduped.
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AnimationPlayer } from '@forgeax/engine-animation';
+import type { AssetRuntimeErrorCode } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { EntityHandle, World as WorldType } from '@forgeax/engine-ecs';
+import { ENTITY_NULL_RAW, World } from '@forgeax/engine-ecs';
+import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import type { RenderErrorCode, Renderer as RendererType } from '@forgeax/engine-render';
+import {
+  ANTIALIAS_FXAA,
+  ANTIALIAS_NONE,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  CAMERA_PROJECTION_ORTHOGRAPHIC,
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  MeshFilter,
+  MeshRenderer,
+  SkyboxBackground,
+  Skylight,
+} from '@forgeax/engine-render';
+import type { BindGroupEntry, Buffer, Sampler, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok as rhiOk } from '@forgeax/engine-rhi';
+import { ChildOf, Name, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { TONEMAP_LUMINANCE_EPSILON } from '@forgeax/engine-shader';
+import type { SkinErrorCode } from '@forgeax/engine-skinning';
+import {
+  Skin,
+  SkinInstancesCoexistForbiddenError,
+  SkinJointCountExceededError,
+  SkinJointDespawnedError,
+  SkinJointPathUnresolvedError,
+} from '@forgeax/engine-skinning';
+import type {
+  Handle,
+  MaterialAsset,
+  MeshAsset,
+  SkeletonAsset,
+  TextureFormat,
+} from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { worldInternal } from '../../../ecs/src/world-internal';
+import {
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  SpriteAnimation,
+  SpriteRegionOverride,
+} from '../../../render/src/components';
+import {
+  type CameraProjection,
+  cameraProjectionFromF32,
+} from '../../../render/src/components/camera';
+import {
+  assembleMaterialWithSkylightEntries,
+  createSkylightFallback,
+  mergeSkylightIntoMaterialBgl,
+} from '../../../render/src/ibl/skylight-bind-group';
+import { buildPbrPipelineLayouts, buildUnlitMaterialBgl } from '../../../render/src/pbr-pipeline';
+import { INSTANCE_STORAGE_STRIDE_FLOATS } from '../../../render/src/record/mesh-ssbo';
+import { selectSwapChainFormat } from '../../../render/src/render-system';
+import { createSkinPaletteAllocator } from '../../../render/src/systems/skin-palette-allocator';
+import type { TransparentEntry } from '../../../render/src/systems/transparent-sort-config';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
+import { drawWithOwners } from './renderer-test-utils';
+
+function componentFieldType(component: { fields: Record<string, { type: string }> }, name: string) {
+  return component.fields[name]?.type;
+}
+
+function componentFieldDefault(
+  component: { fields: Record<string, { default?: unknown }> },
+  name: string,
+) {
+  return component.fields[name]?.default;
+}
+
+function componentSchemaTypes(component: { fields: Record<string, { type: string }> }) {
+  return Object.fromEntries(
+    Object.entries(component.fields).map(([name, field]) => [name, field.type]),
+  );
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+type RendererErrorObservation = {
+  readonly code: string;
+  readonly detail?: unknown;
+  readonly hint?: string;
+};
+
+function unwrapRendererError(value: unknown): RendererErrorObservation {
+  let current = value as RendererErrorObservation;
+  while (
+    current.detail !== undefined &&
+    typeof current.detail === 'object' &&
+    current.detail !== null
+  ) {
+    const cause = (current.detail as { cause?: unknown }).cause;
+    if (
+      cause === undefined ||
+      typeof cause !== 'object' ||
+      cause === null ||
+      typeof (cause as { code?: unknown }).code !== 'string'
+    ) {
+      break;
+    }
+    current = cause as RendererErrorObservation;
+  }
+  return current;
+}
+
+function subscribeRendererErrors(
+  renderer: RendererType,
+  listener: (error: RendererErrorObservation) => void,
+): () => void {
+  return renderer.subscribe((event) => {
+    if (event.kind === 'error') listener(unwrapRendererError(event.error));
+  });
+}
+
+function drawPublished(renderer: RendererType, world: WorldType) {
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  world.update().unwrap();
+  return drawWithOwners(renderer, world);
+}
+
+// feat-20260704-runtime-tier1-decomposition M2 / w12: reconstitute the
+// eliminated top-level RuntimeErrorCode aggregate union (D-3) as a test-local
+// alias so the exhaustive-switch bodies below stay byte-identical (AC-09).
+type RuntimeLayerErrorCode = RenderErrorCode | AssetRuntimeErrorCode | SkinErrorCode;
+
+import {
+  AnimationTargetId,
+  bindAnimationTargets,
+  advanceAnimationPlayer as canonicalAdvanceAnimationPlayer,
+} from '@forgeax/engine-animation';
+import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
+import { DeviceScope } from '../../../render/src/device/device-scope';
+import { GpuBuffer } from '../../../render/src/gpu-resource';
+import { getOrCreateIblCache, hasIblCache } from '../../../render/src/ibl/IblPipelineCache';
+import {
+  disposeInstanceBuffers,
+  type InstanceBufferCacheEntry,
+} from '../../../render/src/instance-buffer-cache';
+import { standardPipeline as urpPipeline } from '../../../render/src/pipeline/standard-pipeline';
+import { ZERO_CAMERA_CLEAR_FALLBACK } from '../../../render/src/record/frame-snapshot';
+import {
+  warnMultiLightDirectional,
+  warnMultiLightPoint,
+  warnMultiLightSpot,
+} from '../../../render/src/record/helpers';
+import type { CameraSnapshot } from '../../../render/src/render-contract';
+import {
+  type ExtractedLights,
+  extractFrame,
+  extractFrames,
+  prepareExtractContext,
+} from '../../../render/src/render-system-extract';
+import {
+  getTransparentSortConfig,
+  setTransparentSortConfig,
+  TRANSPARENT_SORT_CONFIG_KEY,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '../../../render/src/systems/transparent-sort-config';
+import { spriteAnimationTickSystem } from '../systems/sprite-animation-tick';
+import { REC709_LUMA_WEIGHTS, tonemapReinhardLuminance } from '../systems/tonemap';
+import { transparentSortEntries } from '../systems/transparent-sort';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+void [
+  ANTIALIAS_FXAA,
+  ANTIALIAS_NONE,
+  AnimationPlayer,
+  AnimationTargetId,
+  AssetRegistry,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  CAMERA_PROJECTION_ORTHOGRAPHIC,
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  ChildOf,
+  DeviceScope,
+  ENTITY_NULL_RAW,
+  GpuBuffer,
+  INSTANCE_STORAGE_STRIDE_FLOATS,
+  MeshFilter,
+  MeshRenderer,
+  Name,
+  REC709_LUMA_WEIGHTS,
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  Skin,
+  SkinInstancesCoexistForbiddenError,
+  SkinJointCountExceededError,
+  SkinJointDespawnedError,
+  SkinJointPathUnresolvedError,
+  SkyboxBackground,
+  Skylight,
+  SpriteAnimation,
+  SpriteAnimationInvalidError,
+  SpriteRegionOverride,
+  TONEMAP_LUMINANCE_EPSILON,
+  TRANSPARENT_SORT_CONFIG_KEY,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+  Transform,
+  World,
+  ZERO_CAMERA_CLEAR_FALLBACK,
+  afterEach,
+  assembleMaterialWithSkylightEntries,
+  beforeAll,
+  beforeEach,
+  bindAnimationTargets,
+  buildPbrPipelineLayouts,
+  buildUnlitMaterialBgl,
+  cameraProjectionFromF32,
+  canonicalAdvanceAnimationPlayer,
+  componentFieldDefault,
+  componentFieldType,
+  componentSchemaTypes,
+  createSkinPaletteAllocator,
+  createSkylightFallback,
+  deriveAnimationTargetId,
+  describe,
+  disposeInstanceBuffers,
+  drawPublished,
+  drawWithOwners,
+  expect,
+  extractFrame,
+  extractFrames,
+  fileURLToPath,
+  getOrCreateIblCache,
+  getTransparentSortConfig,
+  hasIblCache,
+  it,
+  makeMockShaderRegistry,
+  mat4,
+  mergeSkylightIntoMaterialBgl,
+  prepareExtractContext,
+  propagateTransforms,
+  readFileSync,
+  resolve,
+  rhiOk,
+  selectSwapChainFormat,
+  setTransparentSortConfig,
+  spriteAnimationTickSystem,
+  standardMaterialShaderVariants,
+  subscribeRendererErrors,
+  toShared,
+  tonemapReinhardLuminance,
+  transparentSortEntries,
+  unwrapRendererError,
+  urpPipeline,
+  vec3,
+  vi,
+  warnMultiLightDirectional,
+  warnMultiLightPoint,
+  warnMultiLightSpot,
+  worldInternal,
+];
+type __MergedKeep =
+  | AssetRuntimeErrorCode
+  | BindGroupEntry
+  | Buffer
+  | CameraProjection
+  | CameraSnapshot
+  | EntityHandle
+  | ExtractedLights
+  | Handle
+  | InstanceBufferCacheEntry
+  | MaterialAsset
+  | MeshAsset
+  | RenderErrorCode
+  | RendererErrorObservation
+  | RendererType
+  | RuntimeLayerErrorCode
+  | Sampler
+  | SkeletonAsset
+  | SkinErrorCode
+  | Texture
+  | TextureFormat
+  | TextureView
+  | TransparentEntry
+  | WorldType;
+
+{
+  // --- bug-20260622-tilemap-ysort-transparent-sort-modes-followup M2 m2-1 ---
+  //
+  // AC-02 + AC-03 sanity slabs. Audit the engine-side reconcile checkpoint
+  // (4ead9e82) by asserting the two surfaces AI users reach for from the
+  // `@forgeax/engine-runtime` barrel:
+  //
+  //   AC-02 -- `encodeTilemapLayerValue(layerOrder, chunkIndex, sortScope?)`
+  //            sortScope='per-cell' folds chunkIndex into 0 (`(layerOrder << 20)`),
+  //            sortScope='layer' (default) keeps the standard
+  //            `(layerOrder << 20) | chunkIndex` encoding. Tilemap-layer entities
+  //            that opt into Y-interleave (`sortScope: 'per-cell'`) share one
+  //            Layer.value across their derived per-cell entities so they
+  //            interleave with sprite entities carrying the same Layer.value
+  //            (requirements AC-02 + plan-strategy D-2; D-V-3 round-2 renames
+  //            `ySort: boolean` -> `sortScope: 'layer' | 'per-cell'`).
+  //
+  //   AC-03 -- The 4 mode constants are reachable through the runtime
+  //            barrel (`@forgeax/engine-runtime`) under their canonical
+  //            names + numeric values 0/1/2/3, AND `setTransparentSortConfig`
+  //            accepts all 4 modes (a tight proxy for the VALID_MODES set
+  //            being size 4; the set itself is module-private SSOT).
+  //
+  // The barrel imports use the workspace alias so this slab fails if the
+  // re-export drifts (e.g. someone drops `TRANSPARENT_SORT_MODE_DISTANCE`
+  // from `packages/runtime/src/index.ts`). Same-package source tests
+  // historically use relative paths; this slab opts into the published
+  // alias path on purpose (charter F1 -- single-import barrel SSOT).
+
+  describe('AC-02 encodeTilemapLayerValue (sortScope=per-cell folds chunkIndex)', () => {
+    it("sortScope='per-cell': encodeTilemapLayerValue(2, 5, 'per-cell') === 0x200000", async () => {
+      const { encodeTilemapLayerValue } = await import(
+        '../../../render/src/tilemap-chunk-extract-system'
+      );
+      expect(encodeTilemapLayerValue(2, 5, 'per-cell')).toBe(0x200000);
+    });
+
+    it("sortScope='layer': encodeTilemapLayerValue(2, 5, 'layer') === ((2 << 20) | 5)", async () => {
+      const { encodeTilemapLayerValue } = await import(
+        '../../../render/src/tilemap-chunk-extract-system'
+      );
+      expect(encodeTilemapLayerValue(2, 5, 'layer')).toBe((2 << 20) | 5);
+    });
+
+    it("sortScope defaults to 'layer' (third arg omitted matches 'layer')", async () => {
+      const { encodeTilemapLayerValue } = await import(
+        '../../../render/src/tilemap-chunk-extract-system'
+      );
+      expect(encodeTilemapLayerValue(2, 5)).toBe(encodeTilemapLayerValue(2, 5, 'layer'));
+    });
+  });
+
+  describe('AC-03 transparent-sort 4-mode constants reachable through barrel', () => {
+    it('4 mode constants resolve to 0/1/2/3 through @forgeax/engine-runtime', async () => {
+      const runtime = await import('../../../render/src/systems/transparent-sort-config');
+      expect(runtime.TRANSPARENT_SORT_MODE_LAYER_Z).toBe(0);
+      expect(runtime.TRANSPARENT_SORT_MODE_LAYER_Y).toBe(1);
+      expect(runtime.TRANSPARENT_SORT_MODE_LAYER_YZ).toBe(2);
+      expect(runtime.TRANSPARENT_SORT_MODE_DISTANCE).toBe(3);
+    });
+
+    it('setTransparentSortConfig accepts all 4 modes (VALID_MODES proxy: size 4)', async () => {
+      const runtime = await import('../../../render/src/systems/transparent-sort-config');
+      for (const mode of [
+        runtime.TRANSPARENT_SORT_MODE_LAYER_Z,
+        runtime.TRANSPARENT_SORT_MODE_LAYER_Y,
+        runtime.TRANSPARENT_SORT_MODE_LAYER_YZ,
+        runtime.TRANSPARENT_SORT_MODE_DISTANCE,
+      ]) {
+        const world = new World();
+        const r = runtime.setTransparentSortConfig(world, { mode, yzAlpha: 1.0 });
+        expect(r.ok).toBe(true);
+      }
+    });
+  });
+}

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.overhang-bounds.test.ts

@@ -275,8 +275,8 @@ describe('tilemapChunkExtractSystem overhang bounds (D2)', () => {
       proj as Parameters<typeof mat4.orthographic>[0],
       -1000,
       1000,
-      -1000,
       1000,
+      -1000,
       0.1,
       100,
     );

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);