@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/transcode-fallback.unit.test.ts

@@ -0,0 +1,207 @@
+// w31 -- transcode fallback dispatch unit tests (AC-04, section 8 P3).
+//
+// `loadTextureAsset` grows a Basis arm (w34): when a catalog row's
+// `compression` is a `basis-*` member, the loader parses the KTX2 container,
+// picks a transcode target from `ctx.transcodeCaps` via the codec's pure
+// `selectTranscodeTarget`, transcodes, and stamps `TextureAsset.format` with the
+// chosen target. Degradation is silent but OBSERVABLE: with no compression cap
+// the arm lands on `rgba8unorm[-srgb]` and `tex.format` reflects that reality
+// (never a black texture -- section 8 P3).
+//
+// This test keeps the REAL `selectTranscodeTarget` (its priority chain is
+// codec-w8's concern) and mocks only the container-parse + WASM-transcode seams
+// (`parseKtx2` / `transcodeKtx2`), so it validates the LOADER's dispatch:
+// caps + build-time model -> target -> `tex.format`.
+//
+// TDD-RED before w33 (LoadContext.transcodeCaps) + w34 (the Basis arm).
+//
+// Constraints (plan-tasks w31):
+//   - no real transcoder WASM execution (mocked transcode echoes the target)
+//   - no equirect fallback (w32 owns that)
+//   - degradation is not an error (only corrupt payloads raise transcode-failed)
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { TranscodeCaps } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+// Mock only the container-parse + WASM-transcode seams; keep the real
+// selectTranscodeTarget / KTX2_IDENTIFIER / block-format table.
+vi.mock('@forgeax/engine-codec', async (importActual) => {
+  const actual = await importActual<typeof import('@forgeax/engine-codec')>();
+  return {
+    ...actual,
+    // Basis colorModel echoed via header/dfd; the loader derives the model from
+    // the catalog `compression` member, so the parsed shape only needs a valid
+    // header + rawBytes.
+    parseKtx2: vi.fn(async (bytes: Uint8Array) => ({
+      ok: true as const,
+      value: {
+        header: {
+          vkFormat: 0,
+          typeSize: 1,
+          pixelWidth: 4,
+          pixelHeight: 4,
+          pixelDepth: 0,
+          layerCount: 0,
+          faceCount: 1,
+          levelCount: 1,
+          supercompressionScheme: 1,
+        },
+        index: {
+          dfdByteOffset: 0,
+          dfdByteLength: 0,
+          kvdByteOffset: 0,
+          kvdByteLength: 0,
+          sgdByteOffset: 0,
+          sgdByteLength: 0,
+        },
+        levelIndex: [{ byteOffset: 0, byteLength: bytes.length, uncompressedByteLength: 0 }],
+        dfd: null,
+        kvEntries: [],
+        sgd: null,
+        rawBytes: bytes,
+      },
+    })),
+    ktx2ColorSpace: vi.fn(() => mockedColorSpace),
+    // Echo the requested target so tex.format == the selected transcode target.
+    transcodeKtx2: vi.fn(async (_parsed: unknown, targetFormat: GPUTextureFormat) => ({
+      ok: true as const,
+      value: {
+        format: targetFormat,
+        width: 4,
+        height: 4,
+        mips: [{ level: 0, width: 4, height: 4, data: new Uint8Array(16) }],
+      },
+    })),
+  };
+});
+
+const GUID_TEX = 'c0000000-0000-4000-a000-000074657874';
+const PACK_INDEX_URL = '/test-transcode-fallback-pack-index.json';
+let mockedColorSpace: 'srgb' | 'linear' = 'srgb';
+// A minimal buffer whose first 12 bytes are the KTX2 identifier so the loader's
+// magic dispatch enters the codec arm.
+const KTX2_MAGIC = new Uint8Array([
+  0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+
+function parseGuid(g: string): AssetGuid {
+  const parsed = AssetGuid.parse(g);
+  if (!parsed.ok) throw new Error(`bad guid ${g}`);
+  return parsed.value;
+}
+
+let originalFetch: typeof globalThis.fetch;
+
+function wireFetch(
+  compression: 'basis-uastc' | 'basis-etc1s',
+  colorSpace: 'srgb' | 'linear',
+): void {
+  mockedColorSpace = colorSpace;
+  globalThis.fetch = vi.fn().mockImplementation((input: string) => {
+    const url = typeof input === 'string' ? input : String(input);
+    if (url === PACK_INDEX_URL) {
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve([
+            {
+              guid: GUID_TEX,
+              packageUrl: `/ddc/${GUID_TEX}.pack.json`,
+              kind: 'texture',
+            },
+          ]),
+      });
+    }
+    if (url === `/ddc/${GUID_TEX}.pack.json`) {
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: GUID_TEX,
+                kind: 'texture',
+                payload: { width: 4, height: 4, colorSpace },
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: `${GUID_TEX}.ktx2`,
+                    mediaType: 'image/ktx2',
+                    assetCodec: {
+                      name: 'basis',
+                      container: 'ktx2',
+                      profile: compression.slice(6),
+                    },
+                  },
+                },
+              },
+            ],
+          }),
+      });
+    }
+    return Promise.resolve({ ok: true, arrayBuffer: () => Promise.resolve(KTX2_MAGIC.buffer) });
+  }) as typeof globalThis.fetch;
+}
+
+async function loadFormat(
+  caps: TranscodeCaps,
+  compression: 'basis-uastc' | 'basis-etc1s',
+  colorSpace: 'srgb' | 'linear' = 'srgb',
+): Promise<{ ok: boolean; format?: GPUTextureFormat }> {
+  wireFetch(compression, colorSpace);
+  const reg = new AssetRegistry(makeMockShaderRegistry());
+  reg.configurePackIndex(PACK_INDEX_URL);
+  reg.setTranscodeCaps(caps);
+  const result = await reg.loadByGuid(parseGuid(GUID_TEX));
+  if (!result.ok) return { ok: false };
+  return { ok: true, format: (result.value as { format: GPUTextureFormat }).format };
+}
+
+const NO_CAPS: TranscodeCaps = { bc: false, etc2: false, astc: false };
+const BC_ONLY: TranscodeCaps = { bc: true, etc2: false, astc: false };
+
+describe('loadTextureAsset -- transcode fallback dispatch (w31, AC-04)', () => {
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    vi.clearAllMocks();
+  });
+
+  it('no cap -> rgba8unorm-srgb fallback, format field reflects reality', async () => {
+    const out = await loadFormat(NO_CAPS, 'basis-uastc', 'srgb');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('rgba8unorm-srgb');
+  });
+
+  it('no cap + linear -> rgba8unorm fallback', async () => {
+    const out = await loadFormat(NO_CAPS, 'basis-etc1s', 'linear');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('rgba8unorm');
+  });
+
+  it('bc-only -> BC7 target, format field is the block format', async () => {
+    const out = await loadFormat(BC_ONLY, 'basis-uastc', 'srgb');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('bc7-rgba-unorm-srgb');
+  });
+
+  it('bc-only linear -> bc7-rgba-unorm (no srgb suffix)', async () => {
+    const out = await loadFormat(BC_ONLY, 'basis-etc1s', 'linear');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('bc7-rgba-unorm');
+  });
+
+  it('every caps path loads without throwing (degradation is normal, not an error)', async () => {
+    for (const caps of [NO_CAPS, BC_ONLY, { bc: false, etc2: true, astc: false }] as const) {
+      const out = await loadFormat(caps, 'basis-uastc', 'srgb');
+      expect(out.ok).toBe(true);
+    }
+  });
+});

package/src/__tests__/transform-hierarchy-pixel-diff.dawn.test.ts

@@ -4,7 +4,7 @@
 // Dawn integration test mirroring the hello-transform-hierarchy smoke
 // (apps/hello/transform-hierarchy/scripts/smoke-dawn.mjs): AC-08
 // parent-moves-child-follows. Single World wires the consume path
-// through renderer.attachWorld, spawns a non-identity parent + a ChildOf
+// through renderer.attach, spawns a non-identity parent + a ChildOf
 // child + a static reference sphere, then proves moving the PARENT moves the
 // CHILD's rendered world position (the child gets no Transform write of its
 // own between frames; the only change is the parent's resolved Transform.world
@@ -16,17 +16,12 @@
 // Follows the fxaa-pixel-diff.dawn.test.ts pattern for canvas mock,
 // device capture, and pixel readback.
 
+import { HANDLE_CUBE, HANDLE_SPHERE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  Camera,
-  DirectionalLight,
-  MeshFilter,
-  MeshRenderer,
-} from '@forgeax/engine-render/internal';
+import { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
 import { ChildOf, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
-import { createRenderer } from '../index';
+import { constructRuntimeRendererHost } from '../renderer-host';
 
 const WIDTH = 256;
 const HEIGHT = 256;
@@ -139,30 +134,31 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
       removeEventListener() {},
     } as unknown as HTMLCanvasElement;
 
-    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    let host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
     try {
-      renderer = await createRenderer(mockCanvas, {}, { shaderManifestUrl: ENGINE_MANIFEST_URL });
+      host = await constructRuntimeRendererHost(
+        mockCanvas,
+        {},
+        {
+          shaderManifestUrl: ENGINE_MANIFEST_URL,
+        },
+      );
     } 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 } = host.value;
+    expect(renderer.inspect().state).toBe('alive');
     const device = sharedDevice;
     if (device === undefined) throw new Error('GPUDevice not captured');
 
-    const assets = renderer.assets;
-    if (assets === null) throw new Error('AssetRegistry is null');
-
-    // Single World wires the consume path through renderer.attachWorld so the
+    // Single World wires the consume path through renderer.attach so the
     // child's resolved Transform.world mat4 is derived each frame. feat-20260614
     // M8: the material is a per-World column handle minted via allocSharedRef
     // (AssetRegistry has no handle concept).
     const world = new World();
-    const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
-    const sphereHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('sphere').unwrap());
-    const attachment = renderer.attachWorld(world);
+    const attachment = renderer.attach(world);
     if (!attachment.ok) throw attachment.error;
 
     const materialHandle = world.allocSharedRef('MaterialAsset', {
@@ -187,7 +183,7 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
             scale: [0.4, 0.4, 0.4],
           },
         },
-        { component: MeshFilter, data: { assetHandle: cubeHandle } },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
         { component: MeshRenderer, data: { materials: [materialHandle] } },
       )
       .unwrap();
@@ -199,7 +195,7 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
           data: { pos: [0, 2.0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
         },
         { component: ChildOf, data: { parent } },
-        { component: MeshFilter, data: { assetHandle: cubeHandle } },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
         { component: MeshRenderer, data: { materials: [materialHandle] } },
       )
       .unwrap();
@@ -210,7 +206,7 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
           component: Transform,
           data: { pos: [1.4, 0, 0], quat: [0, 0, 0, 1], scale: [0.4, 0.4, 0.4] },
         },
-        { component: MeshFilter, data: { assetHandle: sphereHandle } },
+        { component: MeshFilter, data: { assetHandle: HANDLE_SPHERE } },
         { component: MeshRenderer, data: { materials: [materialHandle] } },
       )
       .unwrap();
@@ -241,7 +237,11 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
 
     // Frame A: parent at rest. world.update(1 / 60).unwrap() runs propagateTransforms.
     world.update(1 / 60).unwrap();
-    const drawA = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    const drawA = renderer.draw({
+      leases: [attachment.value],
+      camera: { lease: attachment.value },
+      environment: { lease: attachment.value },
+    });
     expect(drawA.ok).toBe(true);
     await device.queue.onSubmittedWorkDone();
     if (renderTarget === undefined) throw new Error('renderTarget not configured');
@@ -249,7 +249,11 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
 
     // Stability: a second render of the rest scene must be pixel-stable.
     world.update(1 / 60).unwrap();
-    const drawAA = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    const drawAA = renderer.draw({
+      leases: [attachment.value],
+      camera: { lease: attachment.value },
+      environment: { lease: attachment.value },
+    });
     expect(drawAA.ok).toBe(true);
     await device.queue.onSubmittedWorkDone();
     const pixelsAA = await doReadPixels(device, renderTarget);
@@ -259,7 +263,11 @@ describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', ()
     const setRes = world.set(parent, Transform, { pos: [PARENT_X_MOVED, 0, 0] });
     expect(setRes.ok).toBe(true);
     world.update(1 / 60).unwrap();
-    const drawB = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    const drawB = renderer.draw({
+      leases: [attachment.value],
+      camera: { lease: attachment.value },
+      environment: { lease: attachment.value },
+    });
     expect(drawB.ok).toBe(true);
     await device.queue.onSubmittedWorkDone();
     const pixelsB = await doReadPixels(device, renderTarget);

package/src/__tests__/transient-fields-collect.test.ts

@@ -1,3 +1,4 @@
+import * as SceneOwner from '@forgeax/engine-scene';
 // feat-20260709-component-vec-fields-and-field-transient-batch M1 / w1 + w2:
 //   w1: AC-07 transient exclusion tests for SpriteAnimation and VideoPlayer.
 //   w2: AC-08 round-trip + rebuild tests for SpriteAnimation and VideoPlayer.
@@ -10,15 +11,19 @@
 //   - currentFrame + accumDt ← spriteAnimationTickSystem (sprite-animation-tick.ts:255-256)
 //   - VideoPlayer.currentTime: NO ECS rebuild system (D-R2); playback head on host HTMLVideoElement
 
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
 import { VideoPlayer } from '@forgeax/engine-graphics-extras';
 import { SpriteAnimation } from '@forgeax/engine-render/authoring';
-import * as SceneOwner from '@forgeax/engine-scene';
 import type { SceneEntity } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { rootsToSceneAsset } from '../collect-scene-asset';
-import { registerSceneComponents } from './helpers/register-scene-components';
-import { createTestSceneAssetStore } from './helpers/scene-asset-port';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { registerRuntimeComponents } from './helpers/register-runtime-components';
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
 
 function compField(entity: SceneEntity, compName: string, fieldName: string): unknown {
   const comp = (entity.components as Record<string, Record<string, unknown>>)[compName];
@@ -29,22 +34,18 @@ function hasComp(entity: SceneEntity, compName: string): boolean {
   return (entity.components as Record<string, Record<string, unknown>>)[compName] !== undefined;
 }
 
-function registerTransientWorld(world: World): void {
-  registerSceneComponents(world, [SpriteAnimation, VideoPlayer]);
-}
-
 describe('w1 — AC-07 transient exclusion (SpriteAnimation, VideoPlayer)', () => {
   it('SpriteAnimation: currentFrame and accumDt are absent from collect output', () => {
     const world = new World();
-    registerTransientWorld(world);
+    registerRuntimeComponents(world);
     const e = world.spawn({
       component: SpriteAnimation,
       data: { frameCount: 4, frameDuration: 0.1, regions: new Float32Array(16) },
     });
     if (!e.ok) return expect(e.ok).toBe(true);
 
-    const assets = createTestSceneAssetStore();
-    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    const reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, world, [e.value]);
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
 
@@ -67,15 +68,15 @@ describe('w1 — AC-07 transient exclusion (SpriteAnimation, VideoPlayer)', () =
 
   it('VideoPlayer: currentTime is absent from collect output', () => {
     const world = new World();
-    registerTransientWorld(world);
+    registerRuntimeComponents(world);
     const e = world.spawn({
       component: VideoPlayer,
       data: { playing: true, loop: false, currentTime: 5.5 },
     });
     if (!e.ok) return expect(e.ok).toBe(true);
 
-    const assets = createTestSceneAssetStore();
-    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    const reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, world, [e.value]);
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
 
@@ -98,7 +99,7 @@ describe('w1 — AC-07 transient exclusion (SpriteAnimation, VideoPlayer)', () =
 describe('w2 — AC-08 round-trip tests (SpriteAnimation, VideoPlayer)', () => {
   it('SpriteAnimation: currentFrame/accumDt excluded, round-trip defaults to 0', () => {
     const world = new World();
-    registerTransientWorld(world);
+    registerRuntimeComponents(world);
     const e = world.spawn({
       component: SpriteAnimation,
       data: {
@@ -111,8 +112,8 @@ describe('w2 — AC-08 round-trip tests (SpriteAnimation, VideoPlayer)', () => {
     });
     if (!e.ok) return expect(e.ok).toBe(true);
 
-    const assets = createTestSceneAssetStore();
-    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    const reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, world, [e.value]);
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
 
@@ -126,7 +127,10 @@ describe('w2 — AC-08 round-trip tests (SpriteAnimation, VideoPlayer)', () => {
 
     // Round-trip: instantiate the collected scene → read ECS state directly.
     const handle = world.allocSharedRef('SceneAsset', collected.value);
-    const inst = SceneOwner.worldInstantiateScene(world, handle);
+    const inst = SceneOwner.worldInstantiateScene(
+      world,
+      handle as Parameters<typeof SceneOwner.worldInstantiateScene>[1],
+    );
     expect(inst.ok).toBe(true);
     if (!inst.ok) return;
 
@@ -157,15 +161,15 @@ describe('w2 — AC-08 round-trip tests (SpriteAnimation, VideoPlayer)', () => {
     // The playback head is authoritative on the host HTMLVideoElement.
     // This test asserts exclusion + round-trip to default 0 only.
     const world = new World();
-    registerTransientWorld(world);
+    registerRuntimeComponents(world);
     const e = world.spawn({
       component: VideoPlayer,
       data: { playing: true, loop: true, currentTime: 42.0 },
     });
     if (!e.ok) return expect(e.ok).toBe(true);
 
-    const assets = createTestSceneAssetStore();
-    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    const reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, world, [e.value]);
     expect(collected.ok).toBe(true);
     if (!collected.ok) return;
 
@@ -178,7 +182,10 @@ describe('w2 — AC-08 round-trip tests (SpriteAnimation, VideoPlayer)', () => {
 
     // Round-trip: instantiate the collected scene → read ECS state directly.
     const handle = world.allocSharedRef('SceneAsset', collected.value);
-    const inst = SceneOwner.worldInstantiateScene(world, handle);
+    const inst = SceneOwner.worldInstantiateScene(
+      world,
+      handle as Parameters<typeof SceneOwner.worldInstantiateScene>[1],
+    );
     expect(inst.ok).toBe(true);
     if (!inst.ok) return;