@forgeax/engine-runtime 0.1.3 → 0.1.6

package/src/__tests__/render-system-owner-split-contract.test.ts

@@ -30,35 +30,11 @@
 //   plan-strategy §2 D-3 (explicit `{ cameraOwner, resourceOwner }` required
 //     indices) + §5.3 key test point + §3.3 interface example
 
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { World } from '@forgeax/engine-ecs';
-import { Camera, extractFrames, Skylight } from '@forgeax/engine-render/internal';
+import { Camera, Skylight } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
-
-const TEST_DIR = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = resolve(TEST_DIR, '../../../..');
-const LEGACY_EXTRACT_PATH = resolve(REPO_ROOT, 'packages/render/src/extract/render-system.ts');
-const CANONICAL_EXTRACT_PATH = resolve(REPO_ROOT, 'packages/render/src/render-system-extract.ts');
-const EXTRACT_GATE_PATH = resolve(
-  REPO_ROOT,
-  'scripts/forgeax/check-render-extract-single-query.mjs',
-);
-
-describe('render extract M1-R0 cohesion gate', () => {
-  it('requires the extract owner to live below src/extract', () => {
-    expect(existsSync(CANONICAL_EXTRACT_PATH)).toBe(true);
-    expect(existsSync(LEGACY_EXTRACT_PATH)).toBe(false);
-  });
-
-  it('points the single-query gate at the canonical extract owner', () => {
-    const gate = readFileSync(EXTRACT_GATE_PATH, 'utf8');
-    expect(gate).toContain('packages/render/src/render-system-extract.ts');
-    expect(gate).not.toContain('packages/render/src/extract/render-system.ts');
-  });
-});
+import { extractFrames } from '../../../render/src/render-system-extract';
 
 // The two-index owner shape w4-w6 will introduce. Declared locally so this
 // test states the contract independent of the (not-yet-updated) source type.
@@ -131,8 +107,9 @@ describe('extractFrames camera-owner / resource-owner split contract (w1, AC-08)
     // Skylight is surfaced from B (resourceOwner=1) — recognisable by intensity.
     // If skylight were (wrongly) read from cameraOwner world A, it would be
     // undefined (A has no skylight), so this assertion has discriminating power.
-    expect(frame.environment.kind).toBe('none');
-    expect(frame.environment.skylightCount).toBe(1);
+    expect(frame.skylight).toBeDefined();
+    expect(frame.skylight?.intensity).toBeCloseTo(SKYLIGHT_B_INTENSITY);
+    expect(frame.skylightCount).toBe(1);
   });
 
   // ── Combination 2: same world is both owners (degenerate — old owner semantics) ──
@@ -173,10 +150,10 @@ describe('extractFrames camera-owner / resource-owner split contract (w1, AC-08)
     // Both camera and singleton resource resolve from world 0 only.
     expect(frame.cameras.length).toBe(1);
     expect(frame.cameras[0]?.far).toBe(CAMERA_A_FAR);
-    expect(frame.environment.kind).toBe('none');
+    expect(frame.skylight?.intensity).toBeCloseTo(SKYLIGHT_B_INTENSITY);
     // skylightCount reports the OWNER (resource) world's live skylight count,
     // not the other world's — proves no cross-world leak in the degenerate case.
-    expect(frame.environment.skylightCount).toBe(1);
+    expect(frame.skylightCount).toBe(1);
   });
 
   // ── Combination 3: owners swapped — camera from B, resource from A ──
@@ -194,7 +171,8 @@ describe('extractFrames camera-owner / resource-owner split contract (w1, AC-08)
     // Skylight surfaced from world0 (resourceOwner=0). If the code read skylight
     // from cameraOwner (world1, no skylight) this would be undefined — so the
     // swap direction is genuinely exercised.
-    expect(frame.environment.kind).toBe('none');
-    expect(frame.environment.skylightCount).toBe(1);
+    expect(frame.skylight).toBeDefined();
+    expect(frame.skylight?.intensity).toBeCloseTo(SKYLIGHT_B_INTENSITY);
+    expect(frame.skylightCount).toBe(1);
   });
 });

package/src/__tests__/render-system-record-multi-material-textureview.test.ts

@@ -33,7 +33,6 @@ import type { World as WorldType } from '@forgeax/engine-ecs';
 import type { Renderer as RendererType } from '@forgeax/engine-render';
 import type { Handle, MaterialAsset, MeshAsset, TextureAsset } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { registerRuntimeComponents } from './helpers/register-runtime-components';
 
 function canonicalTestMeshAttributes(vertexCount: number) {
   return {
@@ -236,22 +235,52 @@ function buildManifestDataUrl(): string {
 }
 
 interface RendererLike {
-  ready: Promise<unknown>;
+  subscribe: RendererType['subscribe'];
   draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
-  onError: (cb: (err: { code: string }) => void) => () => void;
+}
+
+function unwrapRendererError(value: unknown): { code: string; detail?: unknown } {
+  let current = value as { code: string; detail?: unknown };
+  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 { code: string; detail?: unknown };
+  }
+  return current;
 }
 
 async function importEngine(): Promise<{
-  createRenderer: (canvas: unknown, opts?: unknown, opts2?: unknown) => Promise<RendererLike>;
+  createRenderer: (...args: readonly unknown[]) => Promise<RendererLike>;
 }> {
-  return (await import('../createRenderer')) as never;
+  const engine = (await import('../createRenderer')) as {
+    createRenderer: (...args: readonly unknown[]) => Promise<unknown>;
+  };
+  return {
+    createRenderer: async (...args: readonly unknown[]) => {
+      const result = (await engine.createRenderer(...args)) as
+        | { readonly ok: true; readonly value: unknown }
+        | { readonly ok: false; readonly error: unknown };
+      if (!result.ok) throw result.error;
+      return result.value as RendererLike;
+    },
+  };
 }
 
 async function importEcs(): Promise<{
   World: new () => {
     spawn: (...componentDatas: unknown[]) => unknown;
     allocSharedRef: <Target extends string, T>(target: Target, payload: T) => number;
-    components: WorldType['components'];
   };
 }> {
   return (await import('@forgeax/engine-ecs')) as never;
@@ -265,7 +294,7 @@ async function importComponents(): Promise<{
   DirectionalLight: unknown;
 }> {
   return {
-    ...(await import('@forgeax/engine-render/internal')),
+    ...(await import('@forgeax/engine-render')),
     ...(await import('@forgeax/engine-scene')),
   } as never;
 }
@@ -354,7 +383,6 @@ async function setupRenderer(
       shaderManifestUrl: buildManifestDataUrl(),
     },
   );
-  await renderer.ready;
   return { renderer };
 }
 
@@ -362,7 +390,6 @@ async function spawnPbrMultiMaterialScene(): Promise<unknown> {
   const { World } = await importEcs();
   const C = await importComponents();
   const world = new World();
-  registerRuntimeComponents(world);
 
   // Mint the 3-submesh mesh as a user-tier column handle.
   const meshHandle = world.allocSharedRef('MeshAsset', threeSubmeshMesh()) as unknown as Handle<
@@ -383,6 +410,12 @@ async function spawnPbrMultiMaterialScene(): Promise<unknown> {
       >,
     );
   }
+  // Use numeric handles directly in values. Strings are not resolved
+  // by render-system-extract (which gates on
+  // `typeof pv.baseColorTexture === 'number'`); only the disk-pack
+  // materialLoader resolves refs[]-index. Tests targeting the in-memory
+  // extract path must pass numeric handles.
+
   // Mint 3 distinct PBR materials, each pointing at a different
   // baseColorTexture handle. shadingModel is 'standard' so the non-sprite
   // branch in record fires; this is the branch that builds the BG with
@@ -402,14 +435,7 @@ async function spawnPbrMultiMaterialScene(): Promise<unknown> {
         baseColor: [1, 1, 1],
         metallic: 0,
         roughness: 0.5,
-        baseColorTexture: {
-          texture: textureHandles[i] as unknown as string,
-          coordinates: {
-            set: 0,
-            transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-            physicalUvScale: [1, 1],
-          },
-        },
+        baseColorTexture: textureHandles[i] as unknown as number,
       },
     } as unknown as MaterialAsset) as unknown as Handle<'MaterialAsset', 'shared'>;
     materialHandles.push(matHandle);
@@ -433,7 +459,7 @@ async function spawnPbrMultiMaterialScene(): Promise<unknown> {
     { component: C.Transform, data: cameraTransform() },
   );
   world.spawn(
-    { component: C.DirectionalLight, data: { direction: [-0.5, -1, -0.3] } },
+    { component: C.DirectionalLight, data: {} },
     { component: C.Transform, data: cameraTransform() },
   );
   world.spawn(
@@ -458,16 +484,18 @@ describe('record: per-submesh PBR material BG textureView (bug-20260610 D2 regre
     const spies = makeSpies();
     const { renderer } = await setupRenderer(spies);
     const errors: string[] = [];
-    renderer.onError((e) => errors.push(e.code));
+    renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(event.error.code);
+    });
 
     const world = await spawnPbrMultiMaterialScene();
-    if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+    if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
       throw new Error('World attachment failed');
     }
     (world as WorldType).update().unwrap();
     renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
     await new Promise((resolve) => setTimeout(resolve, 0));
-    if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+    if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
       throw new Error('World attachment failed');
     }
     (world as WorldType).update().unwrap();
@@ -484,14 +512,6 @@ describe('record: per-submesh PBR material BG textureView (bug-20260610 D2 regre
     // GREEN at C3: 3 calls, one per submesh's distinct material.
     expect(pbrBgCalls.length).toBeGreaterThanOrEqual(3);
 
-    // Compact authored material values still bind the full shared PBR UBO;
-    // binding a 32-byte authored slot against the 288-byte shader layout
-    // invalidates the command buffer before any pixels are produced.
-    for (const call of pbrBgCalls) {
-      const binding0 = call.entries.find((e) => e.binding === 0);
-      expect(binding0?.resource).toMatchObject({ size: 288 });
-    }
-
     // Assertion (b): the binding-2 (baseColor) textureView resources are
     // pairwise distinct across the 3 calls. RED at C2: only one call exists
     // so the set size is 1; GREEN at C3: each call's binding-2 references a
@@ -530,12 +550,11 @@ describe('record: per-submesh PBR material BG textureView (bug-20260610 D2 regre
 // to the 1x1 white view silently -- rendering flat with no warn / RhiError,
 // which is exactly what made the "GLB renders flat" symptom undiagnosable.
 // The record path now mirrors the sprite telemetry: warn-once console.warn +
-// per-frame RhiError('asset-not-registered') + affected-draw suppression.
+// per-frame RhiError('asset-not-registered') + debug-pink baseColor override.
 async function spawnPbrMissingTextureScene(): Promise<unknown> {
   const { World } = await importEcs();
   const C = await importComponents();
   const world = new World();
-  registerRuntimeComponents(world);
 
   // Single-submesh mesh so materials.length (1) matches submeshes.length (1)
   // and the entity passes the material-count-mismatch gate to reach the
@@ -562,7 +581,7 @@ async function spawnPbrMissingTextureScene(): Promise<unknown> {
   // maxTextureDimension2D of 1 while this texture is 2x2. This is the exact
   // "handle present, GPU capability refusal" condition the record-stage
   // telemetry guards -- the structured ImageError must survive alongside the
-  // affected-draw suppression.
+  // existing debug-pink fallback.
   const unresidentTexture = {
     kind: 'texture',
     width: 2,
@@ -590,14 +609,7 @@ async function spawnPbrMissingTextureScene(): Promise<unknown> {
       baseColor: [1, 1, 1],
       metallic: 0,
       roughness: 0.5,
-      baseColorTexture: {
-        texture: badTexHandleId as unknown as string,
-        coordinates: {
-          set: 0,
-          transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-          physicalUvScale: [1, 1],
-        },
-      },
+      baseColorTexture: badTexHandleId,
     },
   } as unknown as MaterialAsset) as unknown as Handle<'MaterialAsset', 'shared'>;
 
@@ -619,7 +631,7 @@ async function spawnPbrMissingTextureScene(): Promise<unknown> {
     { component: C.Transform, data: cameraTransform() },
   );
   world.spawn(
-    { component: C.DirectionalLight, data: { direction: [-0.5, -1, -0.3] } },
+    { component: C.DirectionalLight, data: {} },
     { component: C.Transform, data: cameraTransform() },
   );
   world.spawn(
@@ -644,7 +656,9 @@ describe('record: PBR missing baseColorTexture telemetry (feat-future-pbr-missin
       const spies = makeSpies();
       const { renderer } = await setupRenderer(spies, 1);
       const errors: Array<{ code: string; detail?: unknown }> = [];
-      renderer.onError((e) => errors.push(e as { code: string; detail?: unknown }));
+      renderer.subscribe((event) => {
+        if (event.kind === 'error') errors.push(unwrapRendererError(event.error));
+      });
 
       const { world, badTexHandleId } = (await spawnPbrMissingTextureScene()) as {
         world: unknown;
@@ -654,12 +668,12 @@ describe('record: PBR missing baseColorTexture telemetry (feat-future-pbr-missin
       // Two frames: the RhiError fires per-frame (machine-readable signal), but
       // the console.warn fires exactly once (warn-once across RenderSystem
       // lifetime -- signal/noise floor, charter P3).
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+      if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
         throw new Error('World attachment failed');
       }
       (world as WorldType).update().unwrap();
       renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+      if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
         throw new Error('World attachment failed');
       }
       (world as WorldType).update().unwrap();
@@ -676,7 +690,7 @@ describe('record: PBR missing baseColorTexture telemetry (feat-future-pbr-missin
         String(c[0]).includes('baseColor texture'),
       );
       expect(baseColorWarns.length).toBe(1);
-      expect(String(baseColorWarns[0]?.[0])).toContain('skipping draw');
+      expect(String(baseColorWarns[0]?.[0])).toContain('debug pink');
     } finally {
       warnSpy.mockRestore();
     }

package/src/__tests__/render-system-record-per-submesh-transparency.test.ts

@@ -26,7 +26,6 @@ import type { World as WorldType } from '@forgeax/engine-ecs';
 import type { Renderer as RendererType } from '@forgeax/engine-render';
 import type { Handle, MaterialAsset, MeshAsset, TextureAsset } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { registerRuntimeComponents } from './helpers/register-runtime-components';
 
 function canonicalTestMeshAttributes(vertexCount: number) {
   return {
@@ -200,21 +199,30 @@ function buildManifestDataUrl(): string {
 }
 
 interface RendererLike {
-  ready: Promise<unknown>;
+  subscribe: RendererType['subscribe'];
   draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
-  onError: (cb: (err: { code: string }) => void) => () => void;
 }
 
 async function importEngine(): Promise<{
-  createRenderer: (canvas: unknown, opts?: unknown, opts2?: unknown) => Promise<RendererLike>;
+  createRenderer: (...args: readonly unknown[]) => Promise<RendererLike>;
 }> {
-  return (await import('../createRenderer')) as never;
+  const engine = (await import('../createRenderer')) as {
+    createRenderer: (...args: readonly unknown[]) => Promise<unknown>;
+  };
+  return {
+    createRenderer: async (...args: readonly unknown[]) => {
+      const result = (await engine.createRenderer(...args)) as
+        | { readonly ok: true; readonly value: unknown }
+        | { readonly ok: false; readonly error: unknown };
+      if (!result.ok) throw result.error;
+      return result.value as RendererLike;
+    },
+  };
 }
 async function importEcs(): Promise<{
   World: new () => {
     spawn: (...componentDatas: unknown[]) => unknown;
     allocSharedRef: <Target extends string, T>(target: Target, payload: T) => number;
-    components: WorldType['components'];
   };
 }> {
   return (await import('@forgeax/engine-ecs')) as never;
@@ -227,7 +235,7 @@ async function importComponents(): Promise<{
   DirectionalLight: unknown;
 }> {
   return {
-    ...(await import('@forgeax/engine-render/internal')),
+    ...(await import('@forgeax/engine-render')),
     ...(await import('@forgeax/engine-scene')),
   } as never;
 }
@@ -290,7 +298,6 @@ async function setupRenderer(spies: DeviceSpies): Promise<{ renderer: RendererLi
     {},
     { shaderManifestUrl: buildManifestDataUrl() },
   );
-  await renderer.ready;
   return { renderer };
 }
 
@@ -304,7 +311,6 @@ async function spawnMixedTransparentScene(): Promise<{
   const { World } = await importEcs();
   const C = await importComponents();
   const world = new World();
-  registerRuntimeComponents(world);
 
   const meshHandle = world.allocSharedRef('MeshAsset', twoSubmeshMesh()) as unknown as Handle<
     'MeshAsset',
@@ -327,14 +333,7 @@ async function spawnMixedTransparentScene(): Promise<{
       baseColor: [1, 1, 1],
       metallic: 0,
       roughness: 0.5,
-      baseColorTexture: {
-        texture: opaqueTexHandle as unknown as string,
-        coordinates: {
-          set: 0,
-          transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-          physicalUvScale: [1, 1],
-        },
-      },
+      baseColorTexture: opaqueTexHandle,
     },
   } as unknown as MaterialAsset) as unknown as Handle<'MaterialAsset', 'shared'>;
 
@@ -363,14 +362,7 @@ async function spawnMixedTransparentScene(): Promise<{
       baseColor: [1, 1, 1],
       metallic: 0,
       roughness: 0.5,
-      baseColorTexture: {
-        texture: blendTexHandle as unknown as string,
-        coordinates: {
-          set: 0,
-          transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-          physicalUvScale: [1, 1],
-        },
-      },
+      baseColorTexture: blendTexHandle,
     },
   } as unknown as MaterialAsset) as unknown as Handle<'MaterialAsset', 'shared'>;
 
@@ -392,7 +384,7 @@ async function spawnMixedTransparentScene(): Promise<{
     { component: C.Transform, data: cameraTransform() },
   );
   world.spawn(
-    { component: C.DirectionalLight, data: { direction: [-0.5, -1, -0.3] } },
+    { component: C.DirectionalLight, data: {} },
     { component: C.Transform, data: cameraTransform() },
   );
   world.spawn(
@@ -419,16 +411,18 @@ describe('record: per-submesh transparency (feat-city-glb Bug 5)', () => {
     const spies = makeSpies();
     const { renderer } = await setupRenderer(spies);
     const errors: string[] = [];
-    renderer.onError((e) => errors.push(e.code));
+    renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(event.error.code);
+    });
 
     const { world } = await spawnMixedTransparentScene();
-    if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+    if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
       throw new Error('World attachment failed');
     }
     (world as WorldType).update().unwrap();
     renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
     await new Promise((resolve) => setTimeout(resolve, 0));
-    if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+    if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
       throw new Error('World attachment failed');
     }
     (world as WorldType).update().unwrap();