@forgeax/engine-runtime 0.1.3 → 0.1.6

package/src/__tests__/msaa-sprite-pixel-diff.dawn.test.ts

@@ -9,7 +9,7 @@
 // No existing green test reached it - the MSAA demo scene is pure mesh
 // (triangle/cube/quad/sphere) and the hello-sprite smoke runs antialias=none.
 //
-// This test renders a sprite entity (a World-owned unit quad + forgeax::sprite material)
+// This test renders a sprite entity (HANDLE_QUAD + forgeax::sprite material)
 // behind a default perspective Camera with tonemap=none, once at
 // antialias=none and once at antialias=msaa, and asserts:
 //   (1) the MSAA pass emits 0 RhiError - if the sprite sub-pass paired a
@@ -34,9 +34,8 @@
 // covered by the hello-sprite smoke FPS gate (smoke green = no
 // regression beyond the SMOKE_PIXEL_THRESHOLD eps).
 
+import { HANDLE_QUAD } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '@forgeax/engine-render/authoring';
 import {
   ANTIALIAS_MSAA,
   ANTIALIAS_NONE,
@@ -44,11 +43,11 @@ import {
   MeshFilter,
   MeshRenderer,
   TONEMAP_NONE,
-} from '@forgeax/engine-render/internal';
+} from '@forgeax/engine-render';
+import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '@forgeax/engine-render/authoring';
 import { Transform } from '@forgeax/engine-scene';
-import type { Asset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { createRenderer } from '../index';
+import { constructRuntimeRendererHost } from '../renderer-host';
 import { drawPublished } from './draw-published';
 
 const WIDTH = 256;
@@ -124,14 +123,13 @@ function buildSyntheticRgba(): { width: number; height: number; data: Uint8Array
 
 function spawnSpriteScene(world: World, spriteMaterialPayload: unknown, antialias: number): void {
   // feat-20260614 M8: MeshRenderer.materials holds a per-World column handle
-  // (numeric); mint it from the published material payload on the World the
+  // (numeric); mint it from the catalogued material payload on the World the
   // scene is spawned into. The material's texture/sampler values are GUID
   // strings the extract stage resolves to per-World handles.
   const spriteMaterial = world.allocSharedRef('MaterialAsset', spriteMaterialPayload);
   // A rotated quad gives diagonal sprite edges so MSAA has something to
   // smooth (the camera-facing axis-aligned quad would expose almost no
   // edge to antialias).
-  const meshHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('quad').unwrap());
   world.spawn(
     {
       component: Transform,
@@ -141,7 +139,7 @@ function spawnSpriteScene(world: World, spriteMaterialPayload: unknown, antialia
         scale: [1, 1, 1],
       },
     },
-    { component: MeshFilter, data: { assetHandle: meshHandle } },
+    { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
     { component: MeshRenderer, data: { materials: [spriteMaterial as never] } },
   );
   world.spawn(
@@ -224,59 +222,33 @@ describe('feat-20260604-msaa M2 w9 [F-1]: LDR sprite + MSAA split sub-pass cover
       removeEventListener() {},
     } as unknown as HTMLCanvasElement;
 
-    const payloads = new Map<string, Asset>();
-    let assetEpoch = 0;
-    const assetResolver = {
-      get epoch(): number {
-        return assetEpoch;
-      },
-      lookup<T extends Asset>(guid: string): T | undefined {
-        return payloads.get(guid) as T | undefined;
-      },
-      guidOf(asset: Asset): string | undefined {
-        for (const [guid, payload] of payloads) {
-          if (payload === asset) return guid;
-        }
-        return undefined;
-      },
-      publish(guid: string, asset: Asset): void {
-        payloads.set(guid, asset);
-        assetEpoch += 1;
-      },
-    };
-
-    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    let host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
     try {
-      renderer = await createRenderer(
+      host = await constructRuntimeRendererHost(
         mockCanvas,
         {},
         {
           shaderManifestUrl: ENGINE_MANIFEST_URL,
-          assetResolver,
         },
       );
     } finally {
       globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
     }
-    expect(renderer.backend).toBe('webgpu');
-    const ready = await renderer.ready;
-    expect(ready.ok).toBe(true);
-    if (!ready.ok) return;
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    const { renderer, assets } = host.value;
+    expect(renderer.inspect().state).toBe('alive');
     const device = sharedDevice;
     if (device === undefined) throw new Error('GPUDevice not captured');
 
-    const assets = assetResolver;
-
     // Catalogue + upload a small sprite texture, a sampler, and a
     // forgeax::sprite material. feat-20260625 M2/M3 (D-3): sprite is now
     // a regular material whose `transparent: true` first-pass flag (not
     // the legacy shadingModel='sprite' arm) drives the LDR split sub-pass
-    // in the record stage. The resolver holds GUID->
+    // in the record stage. feat-20260614 M8: AssetRegistry holds GUID->
     // payload only (no handle concept); texture/sampler are referenced
     // from the material values by GUID string and resolved to per-
-    // World column handles at extract. The explicit uploadTexture call
-    // exercises the GPU residency path via a column handle minted on an
-    // upload-only World.
+    // World column handles at extract. The record stage owns GPU residency.
     //
     // Falsification (smoke harness sensitivity claim, not committed to CI):
     // if the sprite pass's blend state is hand-rewritten to `src=one /
@@ -298,28 +270,19 @@ describe('feat-20260604-msaa M2 w9 [F-1]: LDR sprite + MSAA split sub-pass cover
     const TEX_GUID = '00000000-0000-7000-8000-0000000005a1';
     const SAMPLER_GUID = '00000000-0000-7000-8000-0000000005a2';
     const MATERIAL_GUID = '00000000-0000-7000-8000-0000000005a3';
-    assets.publish(TEX_GUID, synthPod as never);
+    const texCatalog = assets.catalog(TEX_GUID, synthPod as never);
+    expect(texCatalog.ok, 'sprite texture catalog').toBe(true);
+    if (!texCatalog.ok) return;
 
-    const uploadWorld = new World();
-    const textureHandle = uploadWorld.allocSharedRef('TextureAsset', synthPod);
-    const uploadRes = await renderer.store.uploadTexture(textureHandle, synthPod as never, {
-      bytes: synth.data,
-      width: synth.width,
-      height: synth.height,
-      mime: 'image/png',
-      colorSpace: 'srgb',
-      mipmap: false,
-    });
-    expect(uploadRes.ok, 'sprite texture upload').toBe(true);
-    if (!uploadRes.ok) return;
-
-    assets.publish(SAMPLER_GUID, {
+    const samplerCatalog = assets.catalog(SAMPLER_GUID, {
       kind: 'sampler',
       magFilter: 'linear',
       minFilter: 'linear',
       addressModeU: 'repeat',
       addressModeV: 'repeat',
     } as never);
+    expect(samplerCatalog.ok, 'sampler catalog').toBe(true);
+    if (!samplerCatalog.ok) return;
 
     const spriteMaterialPayload = {
       kind: 'material' as const,
@@ -343,20 +306,15 @@ describe('feat-20260604-msaa M2 w9 [F-1]: LDR sprite + MSAA split sub-pass cover
         // older demos keep rendering during migration; new code declares
         // the UBO-aligned forms directly.
         colorTint: [1.0, 0.4, 0.4, 1.0],
-        baseColorTexture: {
-          texture: TEX_GUID,
-          coordinates: {
-            set: 0,
-            transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-            physicalUvScale: [1, 1],
-          },
-        },
+        baseColorTexture: TEX_GUID,
         sampler: SAMPLER_GUID,
         region: [0, 0, 1, 1],
         pivotAndSize: [0.5, 0.5, 1, 1],
       },
     };
-    assets.publish(MATERIAL_GUID, spriteMaterialPayload as never);
+    const matCatalog = assets.catalog(MATERIAL_GUID, spriteMaterialPayload as never);
+    expect(matCatalog.ok, 'sprite material catalog').toBe(true);
+    if (!matCatalog.ok) return;
 
     // Pass 1: antialias=none baseline.
     const worldNone = new World();
@@ -372,7 +330,10 @@ describe('feat-20260604-msaa M2 w9 [F-1]: LDR sprite + MSAA split sub-pass cover
     // under MSAA. Capture every RhiError fired through the renderer's
     // fan-out channel during this draw.
     const msaaErrors: Array<{ code: string }> = [];
-    const unsubscribe = renderer.onError((err) => msaaErrors.push({ code: err.code }));
+    const unsubscribe = renderer.subscribe((event) => {
+      if (event.kind !== 'error') return;
+      msaaErrors.push({ code: event.error.code });
+    });
     const worldMsaa = new World();
     spawnSpriteScene(worldMsaa, spriteMaterialPayload, ANTIALIAS_MSAA);
     const drawnMsaa = drawPublished(renderer, worldMsaa);

package/src/__tests__/new-kind-refs-contract.test.ts

@@ -0,0 +1,132 @@
+// feat-20260622 M6 / w23 — AC-07 contract: a new reference does NOT require any
+// change to a graph-walk axis. The recursion source is `envelope.refs` (D-5), so
+// when the importer puts a referenced GUID into refs[], the recursive loadByGuid
+// walk pulls it -- no exhaustive `switch (asset.kind)` arm to add, no per-kind
+// runtime walker to extend. feat-20260623 M2: the ASSET_BRAND table (the only
+// kind-exhaustive mapping a new Asset kind previously touched) is now retired;
+// a new kind requires zero engine-type changes (brand concept eliminated).
+//
+// This locks the structural win of the refs-as-SSOT pivot: adding a reference
+// field to any Asset member surfaces in the load graph through refs[] alone.
+//
+// The retired graph-walk mechanisms (collect-refs.ts + the
+// asset-registry.recursive.test-d.ts exhaustive-switch guard) are deleted in
+// w19; their absence is enforced structurally -- nothing imports them and the
+// milestone grep gate asserts the retired ref-collection switch leaves zero
+// references across the tree.
+// (A filesystem existsSync check is intentionally avoided: node:fs/node:path
+// named imports are outside @types/node coverage in the runtime tsconfig.)
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const PARENT_GUID = 'c0000000-0000-4000-c000-000000000001';
+const EXTRA_REF_GUID = 'c0000000-0000-4000-c000-000000000002';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const stubMaterial: MaterialAsset = {
+  kind: 'material',
+  passes: [
+    {
+      name: 'forward',
+      program: { module: 'test::dummy' },
+      renderState: { tags: { LightMode: 'Forward' } },
+    },
+  ],
+  values: {},
+};
+
+afterEach(() => {
+  // biome-ignore lint/suspicious/noExplicitAny: test teardown
+  delete (globalThis as any).fetch;
+});
+
+describe('AC-07 — a new reference appears in the load graph via envelope.refs', () => {
+  it('an extra ref the importer adds to refs[] is recursively loaded', async () => {
+    const reg = makeRegistry();
+
+    // The "extra reference" sub-asset is pre-registered in dev mode so the
+    // recursive walk hits the fast-path. Stand-in for "importer added a brand
+    // new reference field whose GUID it dropped into refs[]".
+    reg.catalog(parseGuid(EXTRA_REF_GUID), {
+      kind: 'texture',
+      width: 1,
+      height: 1,
+      format: 'rgba8unorm',
+      data: new Uint8Array(4),
+      colorSpace: 'srgb',
+      mipmap: false,
+    });
+
+    const packIndex = [
+      { guid: PARENT_GUID, packageUrl: '/packs/parent.pack.json', kind: 'material' },
+    ];
+    // The pack body carries refs[] = [EXTRA_REF_GUID]. No new switch arm, no
+    // per-kind walker change -- the GUID in refs[] is the entire wiring.
+    const parentPack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: PARENT_GUID,
+          kind: 'material',
+          payload: {
+            passes: [
+              {
+                name: 'forward',
+                program: { module: 'test::dummy' },
+                renderState: { tags: { LightMode: 'Forward' } },
+              },
+            ],
+            values: {},
+          },
+          refs: [EXTRA_REF_GUID],
+        },
+      ],
+    };
+
+    reg.configurePackIndex('/pack-index.json');
+    const fetchMock = vi.fn().mockImplementation((url: string) => {
+      if (url === '/pack-index.json') {
+        return Promise.resolve({ ok: true, json: () => Promise.resolve(packIndex) });
+      }
+      if (url === '/packs/parent.pack.json') {
+        return Promise.resolve({ ok: true, json: () => Promise.resolve(parentPack) });
+      }
+      return Promise.resolve({ ok: false, status: 404 });
+    });
+    globalThis.fetch = fetchMock as typeof globalThis.fetch;
+
+    const result = await reg.loadByGuid<MaterialAsset>(parseGuid(PARENT_GUID));
+    expect(result.ok).toBe(true);
+    // The extra reference is in the load graph purely because it is in refs[].
+    expect(reg.lookup(parseGuid(EXTRA_REF_GUID))).not.toBe(undefined);
+  });
+
+  it('catalog() inline path: refs[] drives recursion with no walker', async () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(EXTRA_REF_GUID), {
+      kind: 'sampler',
+      magFilter: 'linear',
+      minFilter: 'linear',
+    });
+    // Direct register with an explicit refs edge; loadByGuid fast-path returns
+    // the body and the refs edge is the recursion source.
+    reg.catalog(parseGuid(PARENT_GUID), stubMaterial, [{ guid: EXTRA_REF_GUID }]);
+    const result = await reg.loadByGuid<MaterialAsset>(parseGuid(PARENT_GUID));
+    expect(result.ok).toBe(true);
+    expect(reg.lookup(parseGuid(EXTRA_REF_GUID))).not.toBe(undefined);
+  });
+});

package/src/__tests__/node-shims.d.ts

@@ -1,14 +1,12 @@
 // Ambient declarations for node:* modules used by dawn tests that read the
 // hello-triangle compiled shader manifest at runtime. The runtime package's
 // tsconfig does not enable @types/node (production target is browser); these
-// minimal shims keep tsc green for the 3 shadow dawn test files only.
+// minimal shims keep tsc green for the small set of dawn test files that read
+// compiled shader manifests at runtime.
 //
-// Used by:
-// - shadow-m2.dawn.test.ts
-// - shadow-m3.dawn.test.ts
-// - shadow-m3-calibrate-run.dawn.test.ts
+// Used by shader-manifest Dawn fixtures and the runtime benchmark fixtures.
 // - tilemap-chunk-y-sort-bench.unit.test.ts (perf_hooks + process.env)
-// - render-system-fold-scene-instances.unit.test.ts (readdirSync + dirname)
+// - record-fold-scene-instances.unit.test.ts (readdirSync + dirname)
 // - basis-catalog-dispatch.integration.test.ts (existsSync pkg-built gate)
 
 declare module 'node:fs' {

package/src/__tests__/package-promotion.test.ts

@@ -0,0 +1,88 @@
+// 1->N package promotion idempotence — AC-05 (feat-20260618 w12).
+//
+// Red-first: written before w11 adds the promotion branch to registerPackage.
+//
+// Coverage:
+//   AC-05 — when a single-asset package gains a second asset, the original
+//           asset's derived basename is frozen as its stored name so it keeps
+//           the same resolveName (now via the multi-asset branch), with no error
+//           and no caller awareness. Promotion is idempotent: re-registering the
+//           same path does not overwrite an already-frozen name.
+//
+// The promotion is observable through `package.xor-invariant-violated`: when the
+// original asset already carries a stored name at promotion time (the abnormal
+// single-asset-with-name state, D-4), the freeze must not overwrite it and the
+// soft-violation counter increments. Without w11 there is no promotion branch,
+// so the counter never fires (the falsifying assertion).
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { SamplerAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const G1 = 'c0000000-0000-4000-c000-000000000001';
+const G2 = 'c0000000-0000-4000-c000-000000000002';
+const PATH = 'assets/scene.glb';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler: SamplerAsset = { kind: 'sampler' };
+
+describe('1->N package promotion (AC-05)', () => {
+  it('single asset derives basename', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1]);
+    expect(reg.resolveName(G1)).toBe('scene.glb');
+  });
+
+  it('adding a second asset keeps the original name unchanged, no error', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1]);
+    reg.catalog(parseGuid(G2), sampler);
+    reg._registerPackage(PATH, [G2], new Map([[G2, 'SecondAsset']]));
+
+    expect(reg.resolveName(G1)).toBe('scene.glb');
+    expect(reg.resolveName(G2)).toBe('SecondAsset');
+    expect(reg.packageOf(G1)?.assetCount).toBe(2);
+  });
+
+  it('re-registering the same path is idempotent (does not overwrite frozen name)', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1]);
+    reg.catalog(parseGuid(G2), sampler);
+    reg._registerPackage(PATH, [G2], new Map([[G2, 'SecondAsset']]));
+    reg._registerPackage(PATH, [G1, G2], new Map([[G2, 'SecondAsset']]));
+
+    expect(reg.resolveName(G1)).toBe('scene.glb');
+    expect(reg.resolveName(G2)).toBe('SecondAsset');
+  });
+
+  it('abnormal single-asset-with-name state bumps the xor counter and is not overwritten', () => {
+    const reg = makeRegistry();
+    const metrics = createEngineMetrics();
+    reg.setMetrics(metrics);
+    // Abnormal: a single-asset package whose lone asset already carries a name.
+    reg.catalog(parseGuid(G1), sampler);
+    reg._registerPackage(PATH, [G1], new Map([[G1, 'PreNamed']]));
+    reg.catalog(parseGuid(G2), sampler);
+    // Promotion fires: the pre-existing name is preserved (not overwritten by
+    // basename) and the soft-violation counter records the abnormal state.
+    reg._registerPackage(PATH, [G2], new Map([[G2, 'SecondAsset']]));
+
+    expect(reg.resolveName(G1)).toBe('PreNamed');
+    expect(metrics.snapshot()['package.xor-invariant-violated']).toBe(1);
+  });
+});

package/src/__tests__/package-rename.test.ts

@@ -0,0 +1,103 @@
+// rename API (in-memory) three classes + two error paths — AC-06 (feat-20260618 w14).
+//
+// Red-first: written before w13 implements rename.
+//
+// Coverage:
+//   1. null-package asset rename -> resolveName returns the new name
+//   2. multi-asset package rename -> resolveName returns the new name
+//   3. single-asset package rename -> resolveName + packagePath leaf both sync
+//   4. name collision inside the same package -> err(asset-invalid-value)
+//   5. target guid not registered -> err(asset-not-found)
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { SamplerAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const NULL_PKG = 'd0000000-0000-4000-d000-000000000001';
+const MULTI_A = 'd0000000-0000-4000-d000-000000000002';
+const MULTI_B = 'd0000000-0000-4000-d000-000000000003';
+const SINGLE = 'd0000000-0000-4000-d000-000000000004';
+const MISSING = 'd0000000-0000-4000-d000-0000000000ff';
+
+function parseGuid(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`invalid test GUID: ${s}`);
+  return r.value;
+}
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler: SamplerAsset = { kind: 'sampler' };
+
+describe('rename API (AC-06)', () => {
+  it('null-package asset rename updates the stored name', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(NULL_PKG), sampler);
+    reg._registerPackage(null, [NULL_PKG], new Map([[NULL_PKG, 'old']]));
+
+    const r = reg.rename(NULL_PKG, 'fresh');
+    expect(r.ok).toBe(true);
+    expect(reg.resolveName(NULL_PKG)).toBe('fresh');
+  });
+
+  it('multi-asset package rename updates the entry stored name', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(MULTI_A), sampler);
+    reg.catalog(parseGuid(MULTI_B), sampler);
+    reg._registerPackage(
+      'assets/char.glb',
+      [MULTI_A, MULTI_B],
+      new Map([
+        [MULTI_A, 'Body'],
+        [MULTI_B, 'Head'],
+      ]),
+    );
+
+    const r = reg.rename(MULTI_A, 'Torso');
+    expect(r.ok).toBe(true);
+    expect(reg.resolveName(MULTI_A)).toBe('Torso');
+    expect(reg.resolveName(MULTI_B)).toBe('Head');
+  });
+
+  it('single-asset package rename syncs resolveName and packagePath leaf', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(SINGLE), sampler);
+    reg._registerPackage('assets/hero.glb', [SINGLE]);
+
+    const r = reg.rename(SINGLE, 'villain');
+    expect(r.ok).toBe(true);
+    expect(reg.resolveName(SINGLE)).toBe('villain');
+    const pkg = reg.packageOf(SINGLE);
+    expect(pkg).not.toBeNull();
+    expect(pkg?.path.endsWith('villain')).toBe(true);
+  });
+
+  it('name collision inside the same package returns asset-invalid-value', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(MULTI_A), sampler);
+    reg.catalog(parseGuid(MULTI_B), sampler);
+    reg._registerPackage(
+      'assets/char.glb',
+      [MULTI_A, MULTI_B],
+      new Map([
+        [MULTI_A, 'Body'],
+        [MULTI_B, 'Head'],
+      ]),
+    );
+
+    const r = reg.rename(MULTI_A, 'Head');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.code).toBe('asset-invalid-value');
+  });
+
+  it('renaming a missing guid returns asset-not-found', () => {
+    const reg = makeRegistry();
+    const r = reg.rename(MISSING, 'whatever');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.code).toBe('asset-not-found');
+  });
+});

package/src/__tests__/pass-selector.unit.test.ts

@@ -1,9 +1,9 @@
-import { matchPass, selectPasses } from '@forgeax/engine-render/internal';
 import type { MaterialPass, PassSelector } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { matchPass, selectPasses } from '../../../render/src/systems/pass-selector';
 
 /*
- * feat-20260609 M1 / T-003: AddScenePass/AddShadowPass selector required.
+ * feat-20260609 M1 / T-003: typed scene/shadow selector required.
  *
  * These tests verify the PassSelector matching semantics:
  *   - selector: {} matches every pass (AC-02)

package/src/__tests__/pbr-pipeline.unit.test.ts

@@ -10,16 +10,14 @@
 // must be replaced by buildBindGroupLayoutDescriptor calls without changing
 // what the device sees.
 
-import type { PipelineSpec } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
 import {
   appendInjection,
-  buildBindGroupLayoutDescriptor,
   buildPbrMaterialUserRegionEntries,
   buildPbrViewBglEntries,
-} from '@forgeax/engine-render/internal';
-import { DEFAULT_UNLIT_PARAM_SCHEMA } from '@forgeax/engine-shader';
-import { derive } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/pbr-pipeline';
+import type { PipelineSpec } from '../../../render/src/pipeline-spec';
+import { buildBindGroupLayoutDescriptor } from '../../../render/src/pipeline-spec';
 
 // Stable spec stub — the dispatcher uses spec.shader for reflection only when
 // a registry is supplied; without registry the BGL shape comes purely from
@@ -81,22 +79,22 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
   });
 
   describe('pbr-material-merged', () => {
-    it('20 entries: user-region 13 (derived) + ibl 7', () => {
+    it('24 entries: user-region 13 (derived) + ibl 7 + lightmap 4', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'pbr-material-merged',
       });
       // Post-M2 (D-1): user-region comes from derive(paramSchema).bglEntries
-      // (built-in standard-PBR 6-texture fallback), then IBL is appended at
-      // start = userRegion.length.
+      // (built-in standard-PBR 4-texture fallback), then IBL + lightmap are
+      // appended at start = userRegion.length.
       const userRegion = buildPbrMaterialUserRegionEntries();
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
       const expected = {
         label: 'pbr-material-skylight-bgl',
-        entries: afterIbl,
+        entries: [...afterIbl, ...appendInjection(afterIbl, 'lightmap')],
       };
       expect(out).toEqual(expected);
-      expect(out.entries.length).toBe(20);
+      expect(out.entries.length).toBe(24);
     });
   });
 
@@ -159,7 +157,7 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
   });
 
   describe('pbr-skin-mesh-array', () => {
-    it('storageBuffer=true: mesh plus current/previous palettes use dynamic offsets', () => {
+    it('storageBuffer=true: 2 entries, both dynamic offset', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'pbr-skin-mesh-array',
@@ -170,16 +168,11 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
         entries: [
           {
             binding: 0,
-            visibility: 0x3,
-            buffer: { type: 'read-only-storage', hasDynamicOffset: true },
-          },
-          {
-            binding: 1,
             visibility: 0x1,
             buffer: { type: 'read-only-storage', hasDynamicOffset: true },
           },
           {
-            binding: 2,
+            binding: 1,
             visibility: 0x1,
             buffer: { type: 'read-only-storage', hasDynamicOffset: true },
           },
@@ -189,16 +182,16 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
   });
 
   describe('unlit-material', () => {
-    it('3 entries: reflected unlit material only (no skylight injection)', () => {
+    it('13 entries: base PBR material only (no skylight injection)', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'unlit-material',
       });
       expect(out).toEqual({
         label: 'unlit-material-bgl',
-        entries: buildPbrMaterialUserRegionEntries(derive(DEFAULT_UNLIT_PARAM_SCHEMA)),
+        entries: buildPbrMaterialUserRegionEntries(),
       });
-      expect(out.entries.length).toBe(3);
+      expect(out.entries.length).toBe(13);
     });
   });
 });