@forgeax/engine-runtime 0.1.3 → 0.1.6

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

@@ -0,0 +1,362 @@
+// template-game-default-api-contract.test - the surface APIs that the
+// `templates/game-default/main.ts` `instantiateScenePack` helper 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
+// `world.sceneInstances.setSceneAssetResolver(...)` call survived a refactor
+// that moved the resolver onto World itself + made `assets.instantiate`
+// return the synthetic root Entity directly.
+//
+// Coverage (red-then-green tickets bundled into one file):
+//   (a) `assets.instantiate(handle, world)` exists and returns a
+//       Result<Entity>; when the scene is catalogued and a column handle is
+//       minted via `world.allocSharedRef('SceneAsset', payload)`, the call
+//       resolves handle-typed component fields automatically (no caller-side
+//       `setSceneAssetResolver` wiring required).
+//   (b) the synthetic root carries the `SceneInstance` component, whose
+//       `mapping` Uint32Array is indexed by `localId` and yields the live
+//       Entity for each authored node — the lookup the template's
+//       `attachScenePhysics` / `setupPlayerRoot` walks per node.
+//   (c) `world.sceneInstances` is NOT a thing on the current API
+//       surface (placeholder anti-regression: the runtime exposes the
+//       resolver via `world._setSceneAssetResolver` — already auto-wired
+//       inside `assets.instantiate` for in-registry handles — and the
+//       returned `instRes.value` is the synthetic root Entity, not an id
+//       to look up via a non-existent `byRef`).
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+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 { MeshRenderer, SceneInstance } from '@forgeax/engine-render';
+// Importing the runtime components barrel populates the global component
+// table consulted by `World._buildSceneEntityComponentDatas` — without
+// these named bindings, Transform / MeshRenderer / ChildOf resolve to
+// undefined during instantiate. ChildOf + SceneInstance are used directly
+// below as values; Transform / MeshRenderer pin the side-effect import.
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import type { LocalEntityId, MaterialAsset, SceneAsset, SceneEntity } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { registerRuntimeComponents } from './helpers/register-runtime-components';
+
+function lid(n: number): LocalEntityId {
+  return n as LocalEntityId;
+}
+
+// Shape this fixture mirrors the `templates/game-default/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
+// resolves through the registry's two-phase parse.
+const MAT_GUID = '00000000-0000-5000-8000-000000000001';
+const SCENE_GUID = '00000000-0000-5000-8000-0000000000aa';
+
+function buildSceneAssetWithGuidRef(): SceneAsset {
+  // Touch the bindings so noUnusedLocals doesn't strip the import (which
+  // would also strip its component-table side effect).
+  void Transform;
+  void MeshRenderer;
+
+  const nodes: SceneEntity[] = [
+    {
+      localId: lid(0),
+      components: {
+        Transform: { pos: [0, 0, 0] },
+        // GUID string (post template ref-int → GUID rewrite). The registry's
+        // `_resolveSceneGuids` lifts this to a `Handle<MaterialAsset>` at
+        // instantiate time.
+        MeshRenderer: { materials: [MAT_GUID] },
+      },
+    },
+    {
+      localId: lid(1),
+      components: {
+        Transform: { pos: [1, 0, 0] },
+        ChildOf: { parent: 0 as unknown as EntityHandle },
+      },
+    },
+  ];
+  return { kind: 'scene', entities: nodes };
+}
+
+describe('templates/game-default 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();
+    registerRuntimeComponents(world);
+
+    const matGuid = AssetGuid.parse(MAT_GUID);
+    expect(matGuid.ok).toBe(true);
+    if (!matGuid.ok) return;
+    const mat: MaterialAsset = {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-unlit' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: { baseColor: [1, 1, 1, 1] as [number, number, number, number] },
+    };
+    reg.catalog<MaterialAsset>(matGuid.value, mat);
+
+    const sceneGuid = AssetGuid.parse(SCENE_GUID);
+    expect(sceneGuid.ok).toBe(true);
+    if (!sceneGuid.ok) return;
+    reg.catalog<SceneAsset>(sceneGuid.value, buildSceneAssetWithGuidRef());
+
+    const payloadRes = await reg.loadByGuid<SceneAsset>(sceneGuid.value);
+    expect(payloadRes.ok).toBe(true);
+    if (!payloadRes.ok) return;
+
+    // loadByGuid returns the PAYLOAD; mint a user-tier column handle to feed
+    // instantiate (the template does exactly this at its call site).
+    const handle = world.allocSharedRef('SceneAsset', payloadRes.value);
+
+    // The template uses precisely this 2-line shape; both must compile +
+    // succeed without touching a `world.sceneInstances` surface.
+    const instRes = reg.instantiate<SceneAsset>(handle, world);
+    expect(instRes.ok).toBe(true);
+    if (!instRes.ok) return;
+    // `instRes.value` is an Entity (the synthetic SceneInstance root), not
+    // an id needing a separate lookup.
+    const root: EntityHandle = instRes.value;
+    expect(typeof root).toBe('number');
+  });
+
+  it('(b) the synthetic root carries SceneInstance.mapping[localId] = Entity (per-node lookup the template walks)', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const world = new World();
+    registerRuntimeComponents(world);
+
+    const matGuid = AssetGuid.parse(MAT_GUID);
+    if (!matGuid.ok) throw new Error('parse');
+    const mat: MaterialAsset = {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-unlit' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: { baseColor: [1, 1, 1, 1] as [number, number, number, number] },
+    };
+    reg.catalog<MaterialAsset>(matGuid.value, mat);
+
+    const sceneGuid = AssetGuid.parse(SCENE_GUID);
+    if (!sceneGuid.ok) throw new Error('parse');
+    reg.catalog<SceneAsset>(sceneGuid.value, buildSceneAssetWithGuidRef());
+
+    const payloadRes = await reg.loadByGuid<SceneAsset>(sceneGuid.value);
+    if (!payloadRes.ok) throw new Error('load');
+    const handle = world.allocSharedRef('SceneAsset', payloadRes.value);
+    const instRes = reg.instantiate<SceneAsset>(handle, world);
+    if (!instRes.ok) throw new Error('inst');
+    const root = instRes.value;
+
+    const inst = world.get(root, SceneInstance);
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+
+    // mapping is positional: mapping[localId] = packed Entity u32
+    const mapping = inst.value.mapping as unknown as ArrayLike<number>;
+    expect(mapping.length).toBeGreaterThanOrEqual(2);
+    const node0 = mapping[0];
+    const node1 = mapping[1];
+    expect(node0).toBeDefined();
+    expect(node1).toBeDefined();
+    if (node0 === undefined || node1 === undefined) return;
+    expect(node0).not.toBe(node1);
+
+    // The two member entities both ChildOf the synthetic root (template
+    // walks Children to find PlayerTorso/Head/etc).
+    const child0 = world.get(node0 as EntityHandle, ChildOf);
+    const child1 = world.get(node1 as EntityHandle, ChildOf);
+    // node 1 explicitly authored ChildOf{parent:0}; that resolves to node 0.
+    expect(child1.ok).toBe(true);
+    if (child1.ok) {
+      expect(child1.value.parent as unknown as number).toBe(node0);
+    }
+    // node 0 has no authored ChildOf but the synthetic root attaches one
+    // pointing at root for tree-walking.
+    expect(child0.ok).toBe(true);
+    if (child0.ok) {
+      expect(child0.value.parent as unknown as number).toBe(root as unknown as number);
+    }
+  });
+
+  it('(c) world has no removed scene-instance container or resolver mutator', () => {
+    const world = new World();
+    expect((world as unknown as { sceneInstances?: unknown }).sceneInstances).toBeUndefined();
+    // Resolver wiring is owned by the AssetRegistry/scene-instantiation path;
+    // the former private World mutator is not part of the ECS surface.
+    expect(
+      typeof (world as unknown as { _setSceneAssetResolver?: unknown })._setSceneAssetResolver,
+    ).toBe('undefined');
+  });
+
+  // The template main.ts source file must consume the current API. Catches
+  // the literal regression we hit at runtime: `world.sceneInstances.
+  // setSceneAssetResolver(...)` survived a refactor that removed
+  // `world.sceneInstances`. Lint the file statically so a TS compile
+  // 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`', () => {
+    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');
+    // Strip line comments so prose explaining the rename does not trip the
+    // grep gate; the gate targets actual member access only.
+    const noComments = main
+      .split('\n')
+      .map((line) => line.replace(/\/\/.*$/, ''))
+      .join('\n');
+    // No member access on the removed container surface (e.g.
+    // `world.sceneInstances.setSceneAssetResolver(...)` /
+    // `world.sceneInstances.byRef(id)`).
+    expect(noComments).not.toMatch(/\.sceneInstances\b/);
+    // And no `byRef`, the indirection that came with it.
+    expect(noComments).not.toMatch(/\.byRef\(/);
+  });
+
+  // bug-20260619: the real `scene.pack.json` shipped a DirectionalLightShadow
+  // node carrying `orthoHalfExtent` — a field deleted when shadows moved to CSM
+  // (cascadeCount / splitLambda / ...). Strict instantiate (bug-20260615
+  // fail-fast) rejected the WHOLE scene on the unknown key, so every freshly
+  // created game booted empty (only the ground+sky fallback survived). The
+  // prior contract tests used a hand-built fixture, so the live-schema-vs-
+  // template drift had no gate. This reads the SHIPPED pack and asserts every
+  // authored component field — AFTER the template loader's documented projection
+  // — exists in the live component schema, i.e. the exact key check
+  // `_buildSceneEntityComponentDatas` runs at instantiate time.
+  //
+  // scene-as-asset (2026-06-29): the shipped pack now lives at
+  // `assets/scene.pack.json` and is authored DIRECTLY in the current engine
+  // schema — `payload.entities` (not `nodes`), `MeshRenderer.materials` (not
+  // the legacy ref-int `material`), no Studio-only `Collider`, dense localIds.
+  // main.ts loads it through the pure-GUID path (loadByGuid<SceneAsset> ->
+  // instantiate) with NO preprocessing projection, so every authored field must
+  // satisfy the live schema VERBATIM — that's what _buildSceneEntityComponentDatas
+  // enforces at instantiate time. STRIP/FIELD_RENAME below are retained as
+  // defensive no-ops in case an Edit round-trip ever re-writes a legacy shape.
+  it('(e) [regression] every shipped scene.pack.json component field exists in its live schema', () => {
+    // Touch the barrel bindings so the component-table side-effect import is
+    // not tree-shaken (World.components.resolve reads that per-World table).
+    void Transform;
+    void MeshRenderer;
+    void ChildOf;
+    void SceneInstance;
+    const world = new World();
+    registerRuntimeComponents(world);
+
+    // Defensive back-compat projection (the shipped pack is already clean):
+    // an editor ✎ Edit save would write `Collider` (Studio metadata) and could
+    // emit the legacy singular `material`; tolerate both so the gate is stable.
+    const STRIP_COMPONENTS = new Set(['Collider']);
+    const FIELD_RENAME: Record<string, Record<string, string>> = {
+      MeshRenderer: { material: 'materials' },
+    };
+
+    const here = fileURLToPath(import.meta.url);
+    const repoRoot = resolve(here, '..', '..', '..', '..', '..');
+    const packPath = resolve(repoRoot, 'templates', 'game-default', 'assets', 'scene.pack.json');
+    const pack = JSON.parse(readFileSync(packPath, 'utf-8')) as {
+      assets: {
+        kind: string;
+        payload?: { entities?: SceneEntity[]; nodes?: SceneEntity[] };
+      }[];
+    };
+
+    const offenders: string[] = [];
+    let scanned = 0;
+    for (const asset of pack.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).
+      if (asset.kind !== 'scene') continue;
+      for (const node of asset.payload?.entities ?? asset.payload?.nodes ?? []) {
+        for (const [compName, data] of Object.entries(node.components)) {
+          if (STRIP_COMPONENTS.has(compName)) continue;
+          scanned++;
+          const token = world.components.resolve(compName);
+          if (token === undefined) {
+            offenders.push(`${compName} (component not defined)`);
+            continue;
+          }
+          const schema = componentDefinition(token).fields;
+          const rename = FIELD_RENAME[compName] ?? {};
+          for (const rawField of Object.keys(data ?? {})) {
+            const field = rename[rawField] ?? rawField;
+            if (!(field in schema)) {
+              offenders.push(
+                `${compName}.${rawField} (localId ${node.localId as unknown as number})`,
+              );
+            }
+          }
+        }
+      }
+    }
+
+    expect(offenders).toEqual([]);
+    // Guard against a vacuous pass (e.g. component table not populated / pack
+    // shape drift silently yielding zero scanned components).
+    expect(scanned).toBeGreaterThan(0);
+  });
+
+  // The editor serializes inline materials only when they are reachable from a
+  // live MeshRenderer. An orphaned inline material therefore turns its
+  // load-time count floor into a false save rejection for every new game.
+  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 pack = JSON.parse(readFileSync(packPath, 'utf-8')) as {
+      assets: {
+        guid: string;
+        kind: string;
+        payload?: { entities?: { components: { MeshRenderer?: { materials?: number[] } } }[] };
+        refs?: string[];
+      }[];
+    };
+    const scene = pack.assets.find((asset) => asset.kind === 'scene');
+    expect(scene).toBeDefined();
+    if (scene === undefined) return;
+
+    const referencedMaterialGuids = new Set(
+      (scene.payload?.entities ?? []).flatMap((entity) =>
+        (entity.components.MeshRenderer?.materials ?? []).map((index) => scene.refs?.[index]),
+      ),
+    );
+    const orphanedMaterialGuids = pack.assets
+      .filter((asset) => asset.kind === 'material')
+      .map((asset) => asset.guid)
+      .filter((guid) => !referencedMaterialGuids.has(guid));
+
+    expect(orphanedMaterialGuids).toEqual([]);
+  });
+
+  it('(d) loadByGuid returns the catalogued SceneAsset payload (identity)', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const sceneGuid = AssetGuid.parse(SCENE_GUID);
+    if (!sceneGuid.ok) throw new Error('parse');
+    const payload: SceneAsset = { kind: 'scene', entities: [] };
+    const cataloged = reg.catalog<SceneAsset>(sceneGuid.value, payload);
+    expect(cataloged.ok).toBe(true);
+    if (!cataloged.ok) return;
+    const loaded = await reg.loadByGuid<SceneAsset>(sceneGuid.value);
+    expect(loaded.ok).toBe(true);
+    if (!loaded.ok) return;
+    // loadByGuid returns the PAYLOAD (no handle); it is the same object the
+    // registry catalogued.
+    expect(loaded.value).toBe(cataloged.value);
+    expect(loaded.value.kind).toBe('scene');
+  });
+});

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

@@ -9,6 +9,11 @@
 // Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
 // source as ancestorTitles[0]. Top-level imports merged + deduped.
 
+import {
+  AssetRegistry,
+  resolveAssetHandle,
+  walkMaterialPassesOverSharedRefs,
+} from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
 import { PROCEDURAL_FLOATS_PER_VERTEX } from '@forgeax/engine-geometry';
 import {
@@ -19,22 +24,18 @@ import {
   VERTEX_OFFSET,
 } from '@forgeax/engine-graphics-extras';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
-import {
-  GlyphText,
-  glyphTextLayoutSystem,
-  resetGlyphBakeCache,
-} from '@forgeax/engine-render/authoring';
-import { GpuResourceStore, MeshFilter, MeshRenderer } from '@forgeax/engine-render/internal';
+import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { GlyphText } from '@forgeax/engine-render/authoring';
 import { Transform } from '@forgeax/engine-scene';
-import type {
-  FontAsset,
-  GlyphMetric,
-  Handle,
-  MaterialAsset,
-  MeshAsset,
-} from '@forgeax/engine-types';
+import type { FontAsset, GlyphMetric, Handle, MeshAsset } from '@forgeax/engine-types';
 import { TextError } from '@forgeax/engine-types';
 import { beforeEach, describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import {
+  glyphTextLayoutSystem,
+  resetGlyphBakeCache,
+} from '../../../render/src/glyph-text-layout-system';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 
 {
   // ─── from glyph-layout-system.test.ts ───
@@ -44,7 +45,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
     // These CPU-side layout/bake/attach tests do not wire a device, so the store's
     // updateMesh dirty path no-ops -- the bake + MeshFilter/MeshRenderer attach
     // assertions are unaffected.
-    const gpuStore = new GpuResourceStore();
+    const gpuStore = new GpuResidencyCache();
 
     function metric(overrides: Partial<GlyphMetric> = {}): GlyphMetric {
       return {
@@ -84,6 +85,10 @@ import { beforeEach, describe, expect, it } from 'vitest';
       return world.allocSharedRef('FontAsset', makeFont(glyphs)) as unknown as number;
     }
 
+    function makeRegistry(): AssetRegistry {
+      return new AssetRegistry(makeMockShaderRegistry());
+    }
+
     function spawnLabel(world: World, fontId: number, text: string, fontSize = 1): EntityHandle {
       return world
         .spawn({
@@ -124,6 +129,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
         //   F-2: MeshFilter.assetHandle must read back as the registered mesh id
         //        (not the empty/dropped column that the chained-add migration bug
         //        produced when the entity already carried >=2 components).
+        const assets = makeRegistry();
         const world = new World();
         const fontId = registerFont(world, ASCII('Hi'));
         // Entity carries Transform + GlyphText (the >=2-component shape that
@@ -151,7 +157,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
         expect(mf.ok).toBe(true);
         const assetHandle = (mf.unwrap() as { assetHandle: number }).assetHandle;
         expect(Number(assetHandle)).not.toBe(0);
-        expect(world.sharedRefs.resolve<string, MeshAsset>(assetHandle as never).ok).toBe(true);
+        expect(resolveAssetHandle<MeshAsset>(world, assetHandle as never).ok).toBe(true);
 
         // F-1 guard: MeshRenderer.materials[0] is a real (non-zero) MSDF material handle.
         const mr = world.get(e, MeshRenderer);
@@ -160,10 +166,10 @@ import { beforeEach, describe, expect, it } from 'vitest';
         const material = materials[0] ?? 0;
         expect(Number(material)).not.toBe(0);
         // The bound material resolves to a forgeax::msdf-text pass (not default).
-        const resolved = world.sharedRefs
-          .resolve<string, MaterialAsset>(material as never)
-          .unwrap();
-        expect(resolved.passes?.[0]?.program.module).toBe('forgeax::msdf-text');
+        const passes = walkMaterialPassesOverSharedRefs(world, material as never, assets);
+        expect(passes.ok).toBe(true);
+        const resolved = passes.unwrap();
+        expect(resolved.passes[0]?.program.module).toBe('forgeax::msdf-text');
         expect(resolved.values?.baseColorTexture).toMatchObject({
           texture: expect.any(Uint8Array),
         });
@@ -212,7 +218,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
 
         glyphTextLayoutSystem(world, gpuStore);
         const mf = world.get(e, MeshFilter).unwrap() as { assetHandle: number };
-        const mesh = world.sharedRefs.resolve<string, MeshAsset>(mf.assetHandle as never).unwrap();
+        const mesh = resolveAssetHandle<MeshAsset>(world, mf.assetHandle as never).unwrap();
         delete (mesh as { materialSlots?: unknown }).materialSlots;
 
         glyphTextLayoutSystem(world, gpuStore);
@@ -221,16 +227,19 @@ import { beforeEach, describe, expect, it } from 'vitest';
       });
 
       it('(b2.2) bounds producer refs across slot reuse and tint changes', () => {
+        const assets = makeRegistry();
         const world = new World();
         const fontId = registerFont(world, ASCII('Hi'));
         const first = spawnLabel(world, fontId, 'Hi');
         glyphTextLayoutSystem(world, gpuStore);
         const baseline = world.sharedRefs._liveCount();
+        const catalogBaseline = assets.assetCatalog.size;
 
         for (let i = 0; i < 32; i++) {
           world.set(first, GlyphText, { color: [i / 32, 0.5, 1, 1] }).unwrap();
           glyphTextLayoutSystem(world, gpuStore);
           expect(world.sharedRefs._liveCount()).toBe(baseline);
+          expect(assets.assetCatalog.size).toBe(catalogBaseline);
         }
 
         world.despawn(first).unwrap();
@@ -255,14 +264,26 @@ import { beforeEach, describe, expect, it } from 'vitest';
 
         const filter = second.get(secondEntity, MeshFilter);
         expect(filter.ok).toBe(true);
-        const mesh = second.sharedRefs
-          .resolve<string, MeshAsset>(
-            (filter.unwrap() as { assetHandle: number }).assetHandle as never,
-          )
-          .unwrap();
+        const mesh = resolveAssetHandle<MeshAsset>(
+          second,
+          (filter.unwrap() as { assetHandle: number }).assetHandle as never,
+        ).unwrap();
         expect(mesh.materialSlots).toEqual([{ slotName: 'Default' }]);
       });
 
+      it('(b2.4) keeps runtime-derived materials out of the persistent catalog across Worlds', () => {
+        const assets = makeRegistry();
+        const catalogBaseline = assets.assetCatalog.size;
+
+        for (let i = 0; i < 16; i++) {
+          const world = new World();
+          const fontId = registerFont(world, ASCII('Hi'));
+          spawnLabel(world, fontId, 'Hi');
+          glyphTextLayoutSystem(world, gpuStore);
+          expect(assets.assetCatalog.size).toBe(catalogBaseline);
+        }
+      });
+
       it('(b3) empty first bake -> dirty text refreshes mesh payload bounds and draw range', () => {
         const world = new World();
         const fontId = registerFont(world, ASCII('Hi'));
@@ -271,7 +292,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
         glyphTextLayoutSystem(world, gpuStore);
         const mf = world.get(e, MeshFilter).unwrap() as { assetHandle: number };
         const meshHandle = mf.assetHandle as unknown as Handle<'MeshAsset', 'shared'>;
-        const initialMesh = world.sharedRefs.resolve<string, MeshAsset>(meshHandle).unwrap();
+        const initialMesh = resolveAssetHandle<MeshAsset>(world, meshHandle).unwrap();
         expect(initialMesh.vertices.length).toBe(0);
         // Simulate a pre-material-slot runtime mesh surviving into the in-place
         // rebake path. The update owns the complete procedural mesh contract and
@@ -281,7 +302,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
         world.set(e, GlyphText, { text: 'Hi' }).unwrap();
         glyphTextLayoutSystem(world, gpuStore);
 
-        const mesh = world.sharedRefs.resolve<string, MeshAsset>(meshHandle).unwrap();
+        const mesh = resolveAssetHandle<MeshAsset>(world, meshHandle).unwrap();
         expect(mesh.vertices.length).toBeGreaterThan(0);
         expect(mesh.indices?.length).toBe(12);
         expect(mesh.submeshes[0]?.indexCount).toBe(12);
@@ -297,9 +318,10 @@ import { beforeEach, describe, expect, it } from 'vitest';
         glyphTextLayoutSystem(world, gpuStore);
 
         const mf = world.get(e, MeshFilter).unwrap() as { assetHandle: number };
-        const mesh = world.sharedRefs
-          .resolve<string, MeshAsset>(mf.assetHandle as unknown as Handle<'MeshAsset', 'shared'>)
-          .unwrap();
+        const mesh = resolveAssetHandle<MeshAsset>(
+          world,
+          mf.assetHandle as unknown as Handle<'MeshAsset', 'shared'>,
+        ).unwrap();
         const aabb = mesh.aabb as Float32Array;
         // cube centered at origin: min = -R on all axes, max = +R.
         const r = aabb[3] as number;
@@ -335,9 +357,10 @@ import { beforeEach, describe, expect, it } from 'vitest';
 
         expect(world.get(e, MeshFilter).ok).toBe(true);
         const mf = world.get(e, MeshFilter).unwrap() as { assetHandle: number };
-        const mesh = world.sharedRefs
-          .resolve<string, MeshAsset>(mf.assetHandle as unknown as Handle<'MeshAsset', 'shared'>)
-          .unwrap();
+        const mesh = resolveAssetHandle<MeshAsset>(
+          world,
+          mf.assetHandle as unknown as Handle<'MeshAsset', 'shared'>,
+        ).unwrap();
         expect(mesh.vertices.length).toBe(0);
       });
     });

package/src/__tests__/tilemap-childed-despawn.test.ts

@@ -10,18 +10,7 @@
 // M2 of tweak-20260714-tilemap-layer-childed-render-entities.
 
 import { Entity, type EntityHandle, World } from '@forgeax/engine-ecs';
-import {
-  encodeSortScope,
-  markTileLayerDirty,
-  TileLayer,
-  Tilemap,
-  tilemapChunkExtractSystem,
-} from '@forgeax/engine-render/authoring';
-import {
-  _peekPerCellStreamingLayerKeys,
-  resetTilemapChunkExtractCache,
-  resetTilemapDerivedEntityTracker,
-} from '@forgeax/engine-render/internal';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
 import { ChildOf, Children, Transform } from '@forgeax/engine-scene';
 import {
   defineState,
@@ -31,7 +20,13 @@ import {
 } from '@forgeax/engine-state';
 import type { TilesetAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { registerRuntimeComponents } from './helpers/register-runtime-components';
+import { encodeSortScope, markTileLayerDirty } from '../../../render/src/components/tile-layer';
+import {
+  _peekPerCellStreamingLayerKeys,
+  resetTilemapChunkExtractCache,
+  resetTilemapDerivedEntityTracker,
+  tilemapChunkExtractSystem,
+} from '../../../render/src/tilemap-chunk-extract-system';
 import { makeTilemapAssetLookup } from './helpers/tilemap-assets';
 
 // One state token per file — defineState is module-level, redefining under
@@ -66,7 +61,6 @@ function spawnTilemap(
   rows: number,
   chunkSize = 16,
 ): { tilemap: EntityHandle; lookup: ReturnType<typeof makeTilemapAssetLookup> } {
-  registerRuntimeComponents(world);
   const tileset = makeTileset(cols, rows);
   const lookup = makeTilemapAssetLookup(tileset);
   const tilemap = world

package/src/__tests__/tilemap-chunk-extract.overhang-bounds.test.ts

@@ -51,22 +51,18 @@
 import { Entity, type EntityHandle, World } from '@forgeax/engine-ecs';
 import { encodeTileBits } from '@forgeax/engine-graphics-extras';
 import { frustum, mat4 } from '@forgeax/engine-math';
+import { CAMERA_PROJECTION_ORTHOGRAPHIC, Camera } from '@forgeax/engine-render';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { TilesetAsset, TilesetTileEntry } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { encodeSortScope } from '../../../render/src/components/tile-layer';
 import {
-  encodeSortScope,
-  TileLayer,
-  Tilemap,
-  tilemapChunkExtractSystem,
-} from '@forgeax/engine-render/authoring';
-import {
-  CAMERA_PROJECTION_ORTHOGRAPHIC,
-  Camera,
   computeChunkStreamBounds,
   resetTilemapChunkExtractCache,
   resetTilemapDerivedEntityTracker,
-} from '@forgeax/engine-render/internal';
-import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
-import type { TilesetAsset, TilesetTileEntry } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+  tilemapChunkExtractSystem,
+} from '../../../render/src/tilemap-chunk-extract-system';
 import { makeTilemapAssetLookup } from './helpers/tilemap-assets';
 
 // Camera window x in [CAMERA_POS - 5, CAMERA_POS + 5]. Landing at 55 puts

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

@@ -1,8 +1,9 @@
 import { type EntityHandle, Update, World } from '@forgeax/engine-ecs';
 import { MeshFilter } from '@forgeax/engine-render';
-import { TileLayer, Tilemap, tilemapChunkExtractSystem } from '@forgeax/engine-render/authoring';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
 import { ChildOf, Children, 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';
 import { makeTilemapAssetLookup } from './helpers/tilemap-assets';