@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/inspect-name.test.ts

@@ -0,0 +1,139 @@
+// AC-12 inspector snapshot name (feat-20260618 w25).
+//
+// Verify that inspect().assets carries resolved names for single-package,
+// multi-package, and null-package assets. Each entry.name must match
+// resolveName(guid), confirming the inspect() wiring from M1/w3 placeholder
+// to resolveName (D-9).
+//
+// Plan-targeted console unit test, but inspect() runs inside AssetRegistry
+// (runtime). A real AssetRegistry is needed to exercise the inspect() ->
+// resolveName wiring.
+//
+// The AssetRegistry constructor pre-registers 5 builtin meshes with null
+// packages (D-5). Builtins have resolveName === ''.
+//
+// catalog() puts the asset into the assetCatalog; _registerPackage sets up
+// the Package mapping for name resolution. Both are needed before inspect()
+// can surface resolved names.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeReg() {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const stubSampler = { kind: 'sampler' as const };
+
+function register(reg: AssetRegistry, guid: string, path: string | null, name?: string) {
+  reg.catalog(guid, stubSampler);
+  reg._registerPackage(path, [guid], name ? new Map([[guid, name]]) : undefined);
+}
+
+describe('inspect InspectEntry.name (AC-12)', () => {
+  const BUILTIN_COUNT = 5;
+
+  it('single-asset package -> inspect entry carries basename derived name', () => {
+    const reg = makeReg();
+    register(reg, '01890000-0000-7000-8000-000000000001', '/tmp/hero.pack.json');
+    const snap = reg.inspect();
+    expect(snap.assets.length).toBeGreaterThanOrEqual(BUILTIN_COUNT + 1);
+    const entry = snap.assets.find((e) => e.guid === '01890000-0000-7000-8000-000000000001');
+    expect(entry).toBeDefined();
+    if (!entry) return;
+    expect(entry.name).toBe(reg.resolveName('01890000-0000-7000-8000-000000000001'));
+    expect(entry.name).toBe('hero.pack.json');
+  });
+
+  it('multi-asset package with stored names -> each entry carries distinct name', () => {
+    const reg = makeReg();
+    const g1 = '01890000-0000-7000-8000-000000000002';
+    const g2 = '01890000-0000-7000-8000-000000000003';
+    reg.catalog(g1, stubSampler);
+    reg.catalog(g2, stubSampler);
+    reg._registerPackage(
+      '/tmp/multi.pack.json',
+      [g1, g2],
+      new Map([
+        [g1, 'Body'],
+        [g2, 'Head'],
+      ]),
+    );
+    const snap = reg.inspect();
+    const e1 = snap.assets.find((e) => e.guid === g1);
+    const e2 = snap.assets.find((e) => e.guid === g2);
+    expect(e1).toBeDefined();
+    expect(e2).toBeDefined();
+    if (!e1 || !e2) return;
+    expect(e1.name).toBe('Body');
+    expect(e2.name).toBe('Head');
+    expect(e1.name).toBe(reg.resolveName(g1));
+    expect(e2.name).toBe(reg.resolveName(g2));
+  });
+
+  it('null-package asset with stored name -> entry carries stored name', () => {
+    const reg = makeReg();
+    register(reg, '01890000-0000-7000-8000-000000000004', null, 'myProcMesh');
+    const snap = reg.inspect();
+    const entry = snap.assets.find((e) => e.guid === '01890000-0000-7000-8000-000000000004');
+    expect(entry).toBeDefined();
+    if (!entry) return;
+    expect(entry.name).toBe(reg.resolveName('01890000-0000-7000-8000-000000000004'));
+    expect(entry.name).toBe('myProcMesh');
+  });
+
+  it('null-package asset without name -> entry.name is empty string', () => {
+    const reg = makeReg();
+    register(reg, '01890000-0000-7000-8000-000000000005', null);
+    const snap = reg.inspect();
+    const entry = snap.assets.find((e) => e.guid === '01890000-0000-7000-8000-000000000005');
+    expect(entry).toBeDefined();
+    if (!entry) return;
+    expect(entry.name).toBe(reg.resolveName('01890000-0000-7000-8000-000000000005'));
+    expect(entry.name).toBe('');
+  });
+
+  it('mixed multi/single/null packages -> all entries carry resolveName value', () => {
+    const reg = makeReg();
+    const ga = '01890000-0000-7000-8000-000000000006';
+    const gb = '01890000-0000-7000-8000-000000000007';
+    const gc = '01890000-0000-7000-8000-000000000008';
+    const gd = '01890000-0000-7000-8000-000000000009';
+
+    register(reg, ga, '/tmp/hero.pack.json');
+    reg.catalog(gb, stubSampler);
+    reg.catalog(gc, stubSampler);
+    reg._registerPackage(
+      '/tmp/multi.pack.json',
+      [gb, gc],
+      new Map([
+        [gb, 'Body'],
+        [gc, 'Head'],
+      ]),
+    );
+    register(reg, gd, null);
+
+    const snap = reg.inspect();
+    const ours = snap.assets.filter((e) => [ga, gb, gc, gd].includes(e.guid));
+    expect(ours).toHaveLength(4);
+
+    for (const entry of ours) {
+      expect(typeof entry.name).toBe('string');
+      expect(entry.name).toBe(reg.resolveName(entry.guid));
+    }
+  });
+
+  it('builtin assets have empty string names (D-5 null package)', () => {
+    const reg = makeReg();
+    const snap = reg.inspect();
+    // First entries are the 5 builtin meshes.
+    expect(snap.assets.length).toBeGreaterThanOrEqual(BUILTIN_COUNT);
+    for (const entry of snap.assets) {
+      expect(typeof entry.name).toBe('string');
+    }
+    // Builtins resolve to empty string.
+    const builtinNames = snap.assets.slice(0, BUILTIN_COUNT).map((e) => e.name);
+    expect(builtinNames).toEqual(['', '', '', '', '']);
+  });
+});

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

@@ -25,7 +25,7 @@
 // `src/__tests__/` (TS rootDir = `./src`); the plan-tasks.json target
 // path matches this layout.
 
-import type { InstancesData } from '@forgeax/engine-render/internal';
+import type { InstancesData } from '@forgeax/engine-render';
 import { describe, expectTypeOf, it } from 'vitest';
 
 describe('InstancesData shape (AC-06 ECS-managed array<f32> form)', () => {

package/src/__tests__/instantiate-mount-deferred-wiring.test.ts

@@ -0,0 +1,112 @@
+// instantiate-mount-deferred-wiring.test.ts — D-8 red-first test for the
+// pre-existing structural hole that mount-collapse's serialized-Children
+// dependency was masking (feat-20260707-engine-world-clone-transient-for-
+// editor-ssot, plan-strategy D-8 / §3 static chain).
+//
+// The hole: _instantiateSceneAsset expands mounts[] FIRST (world.ts:3672-3676)
+// and spawns owned entities SECOND (world.ts:3768-3790). When a mount has
+// `mount.parent` pointing at an OWNED entity slot, that slot is still
+// ENTITY_NULL_RAW at mount-processing time, so the ChildOf wiring guard
+// (world.ts:3740-3757) silently skips — and there is NO later pass that
+// re-attempts the wire. The mount carrier is therefore left WITHOUT a ChildOf
+// edge to its owned parent.
+//
+// Before M1, the serialized `Children` array on the owned parent was written
+// back on reload and re-established the W -> carrier down-link (world.ts:
+// 3975-3987 array-of-entity remap), so collect's BFS could still reach the
+// anchor. M1 declared `Children` transient (no longer serialized), unmasking
+// the missing edge. This test asserts the edge directly, independent of
+// serialized Children — so it FAILS on main too (proving the hole is
+// PRE-EXISTING, not introduced by M1). m2t4's deferred wiring turns it green.
+
+import type { Asset } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { SceneInstance } from '@forgeax/engine-render';
+import { ChildOf, Children, Transform } from '@forgeax/engine-scene';
+import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const G_CHILD = '11111111-1111-4111-8111-111111111111';
+const G_PARENT = '22222222-2222-4222-8222-222222222222';
+
+function mkReg(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+function pg(s: string): AssetGuid {
+  const r = AssetGuid.parse(s);
+  if (!r.ok) throw new Error(`bad GUID: ${s}`);
+  return r.value;
+}
+function cat(reg: AssetRegistry, g: string, p: SceneAsset): void {
+  reg.catalog(pg(g), p as Asset);
+}
+function rs(w: World, a: SceneAsset): Handle<'SceneAsset', 'shared'> {
+  return w.allocSharedRef('SceneAsset', a);
+}
+
+function makeWorld(): World {
+  const world = new World();
+  for (const component of [ChildOf, Children, SceneInstance, Transform]) {
+    world.components.register(component).unwrap();
+  }
+  return world;
+}
+
+describe('instantiate deferred ChildOf wiring for owned-parent mounts (D-8)', () => {
+  it('mount carrier whose parent is an owned entity gets ChildOf to that owned entity', () => {
+    const reg = mkReg();
+    const w = makeWorld();
+
+    // Child scene = one owned entity.
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [7, 0, 0] } } }],
+    };
+    cat(reg, G_CHILD, child);
+
+    // Parent scene: one OWNED entity W (localId 0) + one mount whose parent
+    // points at W's slot (localId 0). This is the editor's
+    // spawnGlbSceneAsMount on-disk shape (wrapper W + nested mount).
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } }],
+      mounts: [
+        {
+          localId: 1 as never,
+          source: G_CHILD,
+          memberFirst: 2 as never,
+          memberCount: 1,
+          parent: 0 as never,
+        },
+      ],
+    };
+    cat(reg, G_PARENT, parent);
+
+    const inst = reg.instantiate(rs(w, parent), w);
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+
+    // The synthetic root carries SceneInstance; mapping[localId] -> live Entity.
+    const si = w.get(inst.value, SceneInstance);
+    expect(si.ok).toBe(true);
+    if (!si.ok) return;
+    const mapping = si.value.mapping;
+
+    const ownedW = mapping[0] as unknown as number; // owned entity W (localId 0)
+    const carrier = mapping[1] as unknown as EntityHandle; // mount carrier (localId 1)
+    expect(ownedW).toBeDefined();
+    expect(carrier).toBeDefined();
+
+    // The carrier MUST have a ChildOf whose parent is the owned entity W.
+    const co = w.get(carrier, ChildOf);
+    expect(co.ok, 'mount carrier must carry a ChildOf component').toBe(true);
+    if (!co.ok) return;
+    expect(
+      (co.value as { parent: number }).parent,
+      'carrier ChildOf.parent must equal the owned parent entity W',
+    ).toBe(ownedW);
+  });
+});

package/src/__tests__/light-casters-9-light.browser.test.ts

@@ -10,21 +10,20 @@
 // hello-room's smoke scene only carries 1 DirectionalLight; the
 // PointLight / SpotLight / cone-falloff / 9-light linear-accumulation
 // paths have no place in the smoke pipeline to be exercised. AC-09
-// requires per-pixel readback in a real createRenderer + draw +
-// readPixels chain at 3+ sample points covering AC-09 (a)(b)(c)(d)
+// requires per-pixel canvas readback in a real renderer frame contract
+// at 3+ sample points covering AC-09 (a)(b)(c)(d)
 // plus a retreat path (point=0 + spot=0 collapses to directional-only
 // and behaves indistinguishably from the prior feat baseline).
 //
 // What this round 2 file changes:
-//   - Drives the SUT through `Engine.create({ canvas })` against a real
+//   - Drives the SUT through the runtime host against a real
 //     256x256 canvas attached to the document body (mirrors the canonical
 //     pattern in apps/learn-render/1.getting-started/1.hello-window/src/
 //     __tests__/hello-window.browser.test.ts).
 //   - Spawns the full 1+4+4 scene with deliberate light placement so the
 //     four AC-09 regions land on geometrically distinct pixel locations.
-//   - Calls `renderer.draw(world)` for several frames + `renderer.readPixels()`
-//     to recover RGBA bytes from the canvas (the public engine readback
-//     entry; the same chain hello-window.browser.test.ts exercises).
+//   - Calls the renderer frame contract for several frames + test-owned
+//     canvas capture to recover RGBA bytes.
 //   - Asserts a 16 x 16 block-averaged sample at 4+ sites and uses the
 //     retreat-path readback as the directional-only baseline.
 //
@@ -90,24 +89,26 @@
 // section 6.1 4-light accumulation precedent) + Finding 9 (storage
 // buffer count 0 retreat path).
 
+import { type AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
 import {
   Camera,
   DirectionalLight,
-  extractFrame,
   MeshFilter,
   MeshRenderer,
   PointLight,
-  prepareExtractContext,
   SpotLight,
-} from '@forgeax/engine-render/internal';
+} from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import type { Handle, MaterialAsset } from '@forgeax/engine-types';
 import { afterEach, describe, expect, it } from 'vitest';
-import { Engine } from '../index';
+import { constructRuntimeRendererHost } from '../renderer-host';
 
-type EngineRenderer = Awaited<ReturnType<typeof Engine.create>>;
+type EngineRenderer = import('@forgeax/engine-render').Renderer;
+interface RendererHarness {
+  readonly renderer: EngineRenderer;
+  readonly assets: AssetRegistry;
+}
 
 // Suppress WebGPU teardown race: chromium fires unhandled OperationError
 // ("Instance dropped error in getCompilationInfo") when shader compilation
@@ -193,7 +194,6 @@ function spawnCamera(world: World): void {
 }
 
 function spawnStandardCube(world: World, hStandard: Handle<'MaterialAsset', 'shared'>): void {
-  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
   world
     .spawn(
       {
@@ -204,7 +204,7 @@ function spawnStandardCube(world: World, hStandard: Handle<'MaterialAsset', 'sha
           scale: [1, 1, 1],
         },
       },
-      { component: MeshFilter, data: { assetHandle: cubeHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: { materials: [hStandard] } },
     )
     .unwrap();
@@ -339,12 +339,26 @@ function colourDistance(a: SampleColour, b: SampleColour): number {
   return Math.max(Math.abs(a.r - b.r), Math.abs(a.g - b.g), Math.abs(a.b - b.b));
 }
 
-async function buildRenderer(canvas: HTMLCanvasElement): Promise<EngineRenderer> {
-  const r = await Engine.create(canvas, {}, { shaderManifestUrl: '/shaders/manifest.json' });
-  return r;
+async function buildRenderer(canvas: HTMLCanvasElement): Promise<RendererHarness> {
+  const host = await constructRuntimeRendererHost(
+    canvas,
+    {},
+    {
+      shaderManifestUrl: '/shaders/manifest.json',
+    },
+  );
+  if (!host.ok) throw host.error;
+  if (host.value.renderer.inspect().state !== 'alive') {
+    throw new Error('runtime renderer host did not reach ready state');
+  }
+  return host.value;
 }
 
-async function readbackAfterDraw(renderer: EngineRenderer, world: World): Promise<Uint8Array> {
+async function readbackAfterDraw(
+  renderer: EngineRenderer,
+  canvas: HTMLCanvasElement,
+  world: World,
+): Promise<Uint8Array> {
   // Pump multiple draw + rAF ticks so the chromium compositor consumes
   // the WebGPU swap-chain texture into the canvas before readPixels()
   // samples it. The createImageBitmap(canvas) path documented in
@@ -357,11 +371,15 @@ async function readbackAfterDraw(renderer: EngineRenderer, world: World): Promis
   // 60 fps; in headless mode (process.env.CI set) the compositor can
   // skip frames if there is no visible output, so the readback path
   // below uses both rAF + setTimeout fences to bracket both modes.
-  const attached = renderer.attachWorld(world);
+  const attached = renderer.attach(world);
   if (!attached.ok) throw attached.error;
   for (let i = 0; i < FRAMES_PER_SCENE; i++) {
     world.update(1 / 60).unwrap();
-    const r = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    const r = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
     if (!r.ok) throw new Error(`renderer.draw frame ${i} failed`);
     await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
   }
@@ -371,18 +389,25 @@ async function readbackAfterDraw(renderer: EngineRenderer, world: World): Promis
   await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
   await new Promise<void>((resolve) => setTimeout(resolve, 50));
   await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
-  // Two-shot readback: the first call has been observed to kick the
-  // chromium compositor into consuming the WebGPU swap-chain in some
-  // headless configurations (the createImageBitmap call appears to
-  // trigger the consume); the second call then samples the consumed
-  // canvas content. Both calls are valid Renderer.readPixels chain
-  // invocations -- the second is the one whose bytes we return.
-  const warmup = await renderer.readPixels();
-  if (!warmup.ok) throw new Error(`renderer.readPixels (warmup) failed: ${warmup.error.code}`);
+  // Two-shot test-owned canvas readback: the first call can kick the
+  // chromium compositor into consuming the WebGPU swap-chain; the second
+  // samples the consumed canvas content.
+  const readCanvas = async (): Promise<Uint8Array> => {
+    const bitmap = await createImageBitmap(canvas);
+    const offscreen = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const context = offscreen.getContext('2d', { willReadFrequently: true });
+    if (context === null) {
+      bitmap.close();
+      throw new Error('OffscreenCanvas 2D context unavailable for canvas readback');
+    }
+    context.drawImage(bitmap, 0, 0);
+    const image = context.getImageData(0, 0, bitmap.width, bitmap.height);
+    bitmap.close();
+    return new Uint8Array(image.data.buffer, image.data.byteOffset, image.data.byteLength);
+  };
+  await readCanvas();
   await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
-  const r = await renderer.readPixels();
-  if (!r.ok) throw new Error(`renderer.readPixels failed: ${r.error.code}`);
-  return r.value;
+  return readCanvas();
 }
 
 // Did the chromium compositor actually consume the painted frame in
@@ -430,12 +455,8 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       canvas.style.display = 'block';
       document.body.appendChild(canvas);
 
-      renderer = await buildRenderer(canvas);
-      expect(renderer.backend).toBe('webgpu');
-      const ready = await renderer.ready;
-      expect(ready.ok).toBe(true);
-      const assets = renderer.assets;
-      if (assets === null) throw new Error('renderer.assets unavailable on the WebGPU path');
+      const harness = await buildRenderer(canvas);
+      renderer = harness.renderer;
 
       // -- Retreat-path world: 1 directional + 0 point + 0 spot. --
       const baselineWorld = new World();
@@ -447,19 +468,10 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       spawnStandardCube(baselineWorld, hStandardBaseline);
       spawnDirectional(baselineWorld);
 
-      // Sanity: extract surfaces 1 / 0 / 0 (retreat path).
-      const baselineFrame = extractFrame(
-        baselineWorld,
-        prepareExtractContext(baselineWorld, { assets }),
-      );
-      expect(baselineFrame.lights.directional).toBeDefined();
-      expect(baselineFrame.lights.point).toHaveLength(0);
-      expect(baselineFrame.lights.spot).toHaveLength(0);
-
-      const baselinePixels = await readbackAfterDraw(renderer, baselineWorld);
-      // AC-09 readPixels-chain integrity (the round-1 reviewer issue
+      const baselinePixels = await readbackAfterDraw(renderer, canvas, baselineWorld);
+      // AC-09 canvas-readback chain integrity (the round-1 reviewer issue
       // I-1): the readback returns a contract-shaped Uint8Array of the
-      // canvas size. This is the "test does call renderer.readPixels"
+      // canvas size. This is the test-owned browser readback anchor
       // anchor the round-1 review found absent.
       expect(baselinePixels.length).toBe(CANVAS_W * CANVAS_H * 4);
 
@@ -492,16 +504,7 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       spawnSpotAimingAtOrigin(ninelightWorld, -1.5, 1.5, 1.5, 1.5, 12, 12, 25);
       spawnSpotAimingAtOrigin(ninelightWorld, 0, -1.5, 1.5, 1.5, 12, 12, 25);
 
-      // Sanity: extract surfaces 1 / 4 / 4.
-      const ninelightFrame = extractFrame(
-        ninelightWorld,
-        prepareExtractContext(ninelightWorld, { assets }),
-      );
-      expect(ninelightFrame.lights.directional).toBeDefined();
-      expect(ninelightFrame.lights.point).toHaveLength(4);
-      expect(ninelightFrame.lights.spot).toHaveLength(4);
-
-      const ninelightPixels = await readbackAfterDraw(renderer, ninelightWorld);
+      const ninelightPixels = await readbackAfterDraw(renderer, canvas, ninelightWorld);
       expect(ninelightPixels.length).toBe(CANVAS_W * CANVAS_H * 4);
 
       // -- Step 3: sample 4 deliberate sites covering AC-09 (a)(b)(c)(d) --
@@ -581,7 +584,7 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       );
 
       // -- Compositor-consumed gate (file header degradation rationale).
-      //    `renderer.readPixels()` goes through createImageBitmap(canvas)
+      //    the test-owned canvas readback goes through createImageBitmap(canvas)
       //    + OffscreenCanvas 2D drawImage + getImageData; the chromium
       //    headless compositor schedules the swap-chain consumption at
       //    rAF cadence. If the compositor has not yet consumed the
@@ -685,11 +688,8 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       canvas.style.display = 'block';
       document.body.appendChild(canvas);
 
-      renderer = await buildRenderer(canvas);
-      const ready = await renderer.ready;
-      expect(ready.ok).toBe(true);
-      const assets = renderer.assets;
-      if (assets === null) throw new Error('renderer.assets unavailable on the WebGPU path');
+      const harness = await buildRenderer(canvas);
+      renderer = harness.renderer;
 
       const world = new World();
       spawnCamera(world);
@@ -700,14 +700,14 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       spawnStandardCube(world, hStandard);
       spawnDirectional(world);
 
-      // Both readbacks go through `renderer.draw + renderer.readPixels`
+      // Both readbacks go through the renderer frame contract plus test-owned canvas capture
       // (the AC-09 readback chain). Length lock is the unconditional
       // anchor; pixel-content lock applies only when the chromium
       // compositor consumed both frames (otherwise both readbacks
       // collapse to all-zero and `colourDistance` is trivially 0,
       // which still satisfies the BLOCK_EPSILON contract).
-      const firstPixels = await readbackAfterDraw(renderer, world);
-      const secondPixels = await readbackAfterDraw(renderer, world);
+      const firstPixels = await readbackAfterDraw(renderer, canvas, world);
+      const secondPixels = await readbackAfterDraw(renderer, canvas, world);
       expect(firstPixels.length).toBe(CANVAS_W * CANVAS_H * 4);
       expect(secondPixels.length).toBe(CANVAS_W * CANVAS_H * 4);
 
@@ -757,11 +757,8 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       canvas.style.display = 'block';
       document.body.appendChild(canvas);
 
-      renderer = await buildRenderer(canvas);
-      const ready = await renderer.ready;
-      expect(ready.ok).toBe(true);
-      const assets = renderer.assets;
-      if (assets === null) throw new Error('renderer.assets unavailable on the WebGPU path');
+      const harness = await buildRenderer(canvas);
+      renderer = harness.renderer;
 
       // -- Step A: directional-only baseline (1 + 0 + 0). --
       const baselineWorld = new World();
@@ -772,7 +769,7 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       );
       spawnStandardCube(baselineWorld, hStandardBaseline);
       spawnDirectional(baselineWorld);
-      const baselinePixels = await readbackAfterDraw(renderer, baselineWorld);
+      const baselinePixels = await readbackAfterDraw(renderer, canvas, baselineWorld);
       expect(baselinePixels.length).toBe(CANVAS_W * CANVAS_H * 4);
 
       // -- Step B: directional + 1 PointLight on the world `+Z` (front)
@@ -791,7 +788,7 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       // smoothstep(-1, 1, -1) = 0 (worst case! pre-fix bug actually
       // ELIMINATED the +Z PointLight). Post-fix: full omnidirectional.
       spawnPointAt(plusZWorld, 0, 0, 2, 5.0, 20);
-      const plusZPixels = await readbackAfterDraw(renderer, plusZWorld);
+      const plusZPixels = await readbackAfterDraw(renderer, canvas, plusZWorld);
       expect(plusZPixels.length).toBe(CANVAS_W * CANVAS_H * 4);
 
       // -- Step C: directional + 1 PointLight on the world `-Z` (back)
@@ -817,7 +814,7 @@ describe('w26 9-light browser-mode integration (AC-09 readPixels readback + retr
       // origin, fov=PI/4 -> the cube sides peek into view). Sample at
       // the cube right-mid pixel where the +X side face projects.
       spawnPointAt(minusZWorld, 1.5, 0, 0, 5.0, 20);
-      const minusZPixels = await readbackAfterDraw(renderer, minusZWorld);
+      const minusZPixels = await readbackAfterDraw(renderer, canvas, minusZWorld);
       expect(minusZPixels.length).toBe(CANVAS_W * CANVAS_H * 4);
 
       const cubeCx = CANVAS_W >> 1;

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

@@ -13,23 +13,22 @@
 // (Camera clear pass is M3, not here.)
 
 import { vec3 } from '@forgeax/engine-math';
+import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { packPointLight, packSpotLight } from '../../../render/src/light-buffer-layout';
+import { writeViewUbo } from '../../../render/src/record/view-ubo';
+import type { CameraSnapshot } from '../../../render/src/render-contract';
 import type {
-  CameraSnapshot,
   DirectionalLightSnapshot,
   ExtractedLights,
   PointLightSnapshot,
   SkylightSnapshot,
   SpotLightSnapshot,
-} from '@forgeax/engine-render/internal';
-import { packPointLight, packSpotLight, writeViewUbo } from '@forgeax/engine-render/internal';
-import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
-import { ok } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/render-system-extract';
 
 function identityCamera(): CameraSnapshot {
   return {
-    worldId: 0,
-    entityKey: 0,
     position: vec3.create(0, 0, 3),
     world: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 3, 1]),
     fov: Math.PI / 4,
@@ -45,7 +44,6 @@ function identityCamera(): CameraSnapshot {
     exposure: 1,
     whitePoint: 4,
     antialias: 'none' as CameraSnapshot['antialias'],
-    historyVersion: 0,
     bloom: 'off' as CameraSnapshot['bloom'],
     bloomThreshold: 1,
     bloomIntensity: 1,
@@ -122,7 +120,6 @@ describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
   it('packSpotLight writes color slots 4..6 + direction slots 8..10 byte-for-byte (64 B)', () => {
     const snap: SpotLightSnapshot = {
       kind: 'spot',
-      entity: 0,
       position: vec3.create(0, 5, 0),
       direction: vec3.create(0.1, -0.9, 0.2),
       color: vec3.create(0.3, 0.4, 0.5),

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

@@ -20,14 +20,14 @@
 // `*.test-d.ts` suffix (root vitest config K-3 unit project's typecheck pass
 // covers any .test-d.ts file in any package).
 
+import { expectTypeOf, test } from 'vitest';
 import type {
   DirectionalLightSnapshot,
   ExtractedLights,
   LightSnapshot,
   PointLightSnapshot,
   SpotLightSnapshot,
-} from '@forgeax/engine-render/internal';
-import { expectTypeOf, test } from 'vitest';
+} from '../../../render/src/render-system-extract';
 
 function assertNever(_x: never): never {
   throw new Error('exhaustive');

package/src/__tests__/lights-vec-negative.unit.test.ts

@@ -10,7 +10,7 @@
 // type assertions do NOT count), so the vitest typecheck project enforces it.
 
 import { World } from '@forgeax/engine-ecs';
-import { DirectionalLight, PointLight, Skylight, SpotLight } from '@forgeax/engine-render/internal';
+import { DirectionalLight, PointLight, Skylight, SpotLight } from '@forgeax/engine-render';
 import { describe, it } from 'vitest';
 
 describe('w5a -- residual per-axis light keys are compile errors (AC-04)', () => {