@forgeax/engine-runtime 0.1.4 → 0.1.7

package/src/__tests__/audio-load-by-guid.unit.test.ts

@@ -0,0 +1,126 @@
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { audioLoader } from '@forgeax/engine-audio-webaudio';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { AudioClipAsset } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const AUDIO_GUID = 'db30f00d-0000-4000-8000-000000000001';
+const PACK_INDEX_URL = '/pack-index.json';
+const PACKAGE_URL = '/assets/audio.pack.json';
+const ARTIFACT_URL = '/assets/audio/source.bin';
+
+function audioPack(byteLength = 16) {
+  return {
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    assets: [
+      {
+        guid: AUDIO_GUID,
+        kind: 'audio',
+        payload: { kind: 'audio', mediaType: 'audio/wav' },
+        refs: [],
+        artifacts: {
+          source: {
+            path: 'audio/source.bin',
+            mediaType: 'audio/wav',
+            assetCodec: { name: 'browser-audio' },
+            contentEncoding: 'identity',
+            byteLength,
+          },
+        },
+      },
+    ],
+  };
+}
+
+describe('audio loadByGuid', () => {
+  const originalFetch = globalThis.fetch;
+  const originalAudioContext = globalThis.AudioContext;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    globalThis.AudioContext = originalAudioContext;
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('loads and catalogues an audio GUID through its Pack v2 artifact', async () => {
+    const audioData = new ArrayBuffer(16);
+    const audioContext = vi.fn();
+    const fetchMock = vi.fn().mockImplementation((url: string) => {
+      if (url === PACK_INDEX_URL) {
+        return Promise.resolve({
+          ok: true,
+          json: async () => [{ guid: AUDIO_GUID, packageUrl: PACKAGE_URL, kind: 'audio' }],
+        });
+      }
+      if (url === PACKAGE_URL) {
+        return Promise.resolve({ ok: true, json: async () => audioPack() });
+      }
+      if (url === ARTIFACT_URL) {
+        return Promise.resolve({ ok: true, arrayBuffer: async () => audioData });
+      }
+      return Promise.resolve({ ok: false, status: 404, statusText: 'Not Found' });
+    });
+    globalThis.fetch = fetchMock as typeof globalThis.fetch;
+    globalThis.AudioContext = audioContext as unknown as typeof AudioContext;
+
+    const registry = new AssetRegistry(makeMockShaderRegistry(), undefined, [audioLoader]);
+    registry.configurePackIndex(PACK_INDEX_URL);
+    const parsed = AssetGuid.parse(AUDIO_GUID);
+    if (!parsed.ok) throw new Error('test GUID must be valid');
+
+    const first = await registry.loadByGuid<AudioClipAsset>(parsed.value);
+    const second = await registry.loadByGuid<AudioClipAsset>(parsed.value);
+
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(true);
+    if (!first.ok) throw first.error;
+    if (!second.ok) throw second.error;
+    expect(first.value).toEqual({
+      kind: 'audio',
+      sourceKey: AUDIO_GUID,
+      mediaType: 'audio/wav',
+      bytes: new Uint8Array(audioData),
+    });
+    expect(second.value).toBe(first.value);
+    expect(registry.lookup(parsed.value)).toBe(first.value);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(audioContext).not.toHaveBeenCalled();
+  });
+
+  it('defers malformed-byte rejection to the Host audio consumer', async () => {
+    const fetchMock = vi.fn().mockImplementation((url: string) => {
+      if (url === PACK_INDEX_URL) {
+        return Promise.resolve({
+          ok: true,
+          json: async () => [{ guid: AUDIO_GUID, packageUrl: PACKAGE_URL, kind: 'audio' }],
+        });
+      }
+      if (url === PACKAGE_URL) {
+        return Promise.resolve({ ok: true, json: async () => audioPack(8) });
+      }
+      return Promise.resolve({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
+    });
+    globalThis.fetch = fetchMock as typeof globalThis.fetch;
+    globalThis.AudioContext = vi.fn().mockImplementation(function AudioContextMock() {
+      return {
+        decodeAudioData: vi.fn().mockRejectedValue(new Error('bad audio')),
+        close: vi.fn(),
+      } as unknown as AudioContext;
+    }) as unknown as typeof AudioContext;
+
+    const registry = new AssetRegistry(makeMockShaderRegistry(), undefined, [audioLoader]);
+    registry.configurePackIndex(PACK_INDEX_URL);
+    const parsed = AssetGuid.parse(AUDIO_GUID);
+    if (!parsed.ok) throw new Error('test GUID must be valid');
+
+    const result = await registry.loadByGuid<AudioClipAsset>(parsed.value);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw result.error;
+    expect(result.value.sourceKey).toBe(AUDIO_GUID);
+    expect(result.value.bytes).toEqual(new Uint8Array(8));
+  });
+});

package/src/__tests__/backend-selection.integration.test.ts

@@ -0,0 +1,11 @@
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { loadBackendPack } from '../backend-selection';
+
+describe('backend selection', () => {
+  it('uses an explicitly injected backend without probing global state', async () => {
+    const result = await loadBackendPack({ rhi });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value.rhi).toBe(rhi);
+  });
+});

package/src/__tests__/basis-catalog-dispatch.integration.test.ts

@@ -0,0 +1,320 @@
+// basis-catalog-dispatch.integration.test.ts -- feat-20260707 M6 fix regression.
+//
+// End-to-end witness for the catalog round-trip bug: the pack-index ROW must
+// carry the resolved `compression: 'basis-*'` discriminant so the runtime
+// `loadTextureAsset` dispatches its transcode arm. Before the fix, the build /
+// dev texture arms stamped the row with the STRATEGY_TABLE 'none' default (the
+// resolved basis-* lived only in `metadata.compression`), so loadTextureAsset
+// missed the transcode arm and the scheme=1 (BasisLZ / ETC1S) KTX2 fell through
+// to `ktx2LevelsToRGBA`, which rejects it with `ktx2-unsupported-scheme`.
+//
+// This test uses the REAL encoder + REAL transcoder WASM (no mocks) so it
+// exercises the exact scheme=1 payload the pipeline ships:
+//   (bug witness) row compression='none'         -> scheme=1 reject (load fails)
+//   (fix)         row compression='basis-etc1s'  -> transcode arm succeeds
+//
+// pkg/ (encoder + transcoder glue) is a gitignored emcc artefact (AC-12); CI's
+// build-artifacts job builds it. Skip when absent (contributor without emsdk).
+
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+// NOTE: @forgeax/engine-codec/encode is the build-time encoder subpath. The
+// image-pipeline isolation gate (path d) forbids a STATIC import of it from
+// packages/runtime/src (encode is build-time only). This test needs the real
+// encoder to mint a Basis KTX2 fixture, so it uses a DYNAMIC import inside the
+// pkg-gated beforeAll — build-time-only, never reached in shipped runtime code.
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { TranscodeCaps } from '@forgeax/engine-types';
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import type { BasisEncoderModule, BasisModuleFactory } from '../../../codec/src/wasm/basis-types';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const ENCODER_GLUE = new URL('../../../codec/pkg/encode/basis_encoder.mjs', import.meta.url);
+const TRANSCODER_GLUE = new URL('../../../codec/pkg/basis_transcoder.mjs', import.meta.url);
+const pkgBuilt =
+  existsSync(fileURLToPath(ENCODER_GLUE)) && existsSync(fileURLToPath(TRANSCODER_GLUE));
+
+const GUID_TEX = 'c0000000-0000-4000-a000-0000626173a1';
+const PACK_INDEX_URL = '/basis-catalog-dispatch-pack-index.json';
+const PACK_URL = `/ddc/${GUID_TEX}.pack.json`;
+const W = 16;
+const H = 16;
+const CAPABILITY_CELLS = [
+  [{ bc: false, etc2: false, astc: false }, 'rgba'],
+  [{ bc: false, etc2: false, astc: true }, 'astc'],
+  [{ bc: true, etc2: false, astc: false }, 'bc'],
+  [{ bc: false, etc2: true, astc: false }, 'etc'],
+  [{ bc: true, etc2: true, astc: true }, 'all'],
+] as const;
+const NO_CAPS = CAPABILITY_CELLS[0][0];
+
+let basisKtx2: Uint8Array;
+let uastcLdrKtx2: Uint8Array;
+let uastcHdrKtx2: Uint8Array;
+let rawBasis: Uint8Array;
+let originalFetch: typeof globalThis.fetch;
+
+type TextureFixture = {
+  readonly bytes: Uint8Array;
+  readonly extension: 'ktx2' | 'basis';
+  readonly mediaType: 'image/ktx2' | 'image/basis';
+  readonly container: 'ktx2' | 'basis';
+  readonly profile: 'etc1s' | 'uastc-ldr' | 'uastc-hdr';
+  readonly colorSpace: 'srgb' | 'linear';
+};
+
+function parseGuid(g: string): AssetGuid {
+  const parsed = AssetGuid.parse(g);
+  if (!parsed.ok) throw new Error(`bad guid ${g}`);
+  return parsed.value;
+}
+
+// Build a deterministic RGBA gradient and encode it to a real ETC1S Basis KTX2
+// (scheme=1). The exact payload the vite-plugin-pack image arm ships for a
+// compressionMode:'auto' sRGB texture.
+beforeAll(async () => {
+  if (!pkgBuilt) return;
+  const { basisEncode } = await import('@forgeax/engine-codec/encode');
+  const pixels = new Uint8Array(W * H * 4);
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const i = (y * W + x) * 4;
+      pixels[i] = (x * 16) & 0xff;
+      pixels[i + 1] = (y * 16) & 0xff;
+      pixels[i + 2] = 128;
+      pixels[i + 3] = 255;
+    }
+  }
+  async function encode(mode: 'etc1s' | 'uastc-ldr' | 'uastc-hdr', source: Uint8Array) {
+    const enc = await basisEncode(source, {
+      mode,
+      width: W,
+      height: H,
+      srgb: mode !== 'uastc-hdr',
+      perceptual: mode !== 'uastc-hdr',
+      uastcSupercompression: mode === 'uastc-ldr',
+      mipGen: false,
+    });
+    if (!enc.ok) throw new Error(`basisEncode failed: ${enc.error.code}`);
+    return enc.value;
+  }
+  basisKtx2 = await encode('etc1s', pixels);
+  uastcLdrKtx2 = await encode('uastc-ldr', pixels);
+  uastcHdrKtx2 = await encode('uastc-hdr', new Uint8Array(W * H * 8));
+
+  const factory = (
+    (await import(/* @vite-ignore */ ENCODER_GLUE.href)) as {
+      default: BasisModuleFactory<BasisEncoderModule>;
+    }
+  ).default;
+  const mod = await factory({
+    locateFile: () => new URL('../../../codec/pkg/encode/basis_encoder.wasm', import.meta.url).href,
+  });
+  mod.initializeBasis();
+  const encoder = new mod.BasisEncoder();
+  try {
+    encoder.setSliceSourceImage(0, pixels, W, H, 0);
+    encoder.setCreateKTX2File(false);
+    encoder.setFormatMode(mod.basis_tex_format.cUASTC_LDR_4x4.value);
+    encoder.setPerceptual(false);
+    encoder.setMipGen(false);
+    const bytes = new Uint8Array(1 << 20);
+    const length = encoder.encode(bytes);
+    if (length <= 0) throw new Error('raw Basis encode failed');
+    rawBasis = bytes.slice(0, length);
+  } finally {
+    encoder.delete();
+  }
+});
+
+function wireFetch(
+  includeCodec: boolean,
+  fixture: TextureFixture = {
+    bytes: basisKtx2,
+    extension: 'ktx2',
+    mediaType: 'image/ktx2',
+    container: 'ktx2',
+    profile: 'etc1s',
+    colorSpace: 'srgb',
+  },
+): void {
+  globalThis.fetch = ((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: PACK_URL,
+              kind: 'texture',
+            },
+          ]),
+      });
+    }
+    if (url === PACK_URL) {
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: GUID_TEX,
+                kind: 'texture',
+                payload: {
+                  width: W,
+                  height: H,
+                  format: fixture.colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba16float',
+                  colorSpace: fixture.colorSpace,
+                },
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: `${GUID_TEX}.${fixture.extension}`,
+                    mediaType: fixture.mediaType,
+                    ...(includeCodec
+                      ? {
+                          assetCodec: {
+                            name: 'basis',
+                            container: fixture.container,
+                            profile: fixture.profile,
+                          },
+                        }
+                      : {}),
+                  },
+                },
+              },
+            ],
+          }),
+      });
+    }
+    // Serve the real Basis KTX2 bytes for the artifact URL.
+    return Promise.resolve({
+      ok: true,
+      arrayBuffer: () =>
+        Promise.resolve(
+          fixture.bytes.buffer.slice(
+            fixture.bytes.byteOffset,
+            fixture.bytes.byteOffset + fixture.bytes.byteLength,
+          ),
+        ),
+    });
+  }) as unknown as typeof globalThis.fetch;
+}
+
+async function loadWith(
+  includeCodec: boolean,
+  fixture?: TextureFixture,
+  caps: TranscodeCaps = NO_CAPS,
+) {
+  wireFetch(includeCodec, fixture);
+  const reg = new AssetRegistry(makeMockShaderRegistry());
+  reg.configurePackIndex(PACK_INDEX_URL);
+  reg.setTranscodeCaps(caps);
+  return reg.loadByGuid(parseGuid(GUID_TEX));
+}
+
+describe.skipIf(!pkgBuilt)('Basis catalog dispatch round-trip (M6 fix)', () => {
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('loads a Basis texture when the artifact has no optional codec hint', async () => {
+    // Catalog v2 carries package navigation only. The optional codec hint is
+    // owned by the artifact descriptor, so a valid KTX2 artifact remains
+    // loadable when that hint is absent from the package row.
+    const result = await loadWith(false);
+    expect(result.ok).toBe(true);
+  });
+
+  it('artifact codec=basis-etc1s takes the transcode arm and loads', async () => {
+    const result = await loadWith(true);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error(`load failed: ${result.error.code}`);
+    const tex = result.value as { kind: string; width: number; height: number; format: string };
+    expect(tex.kind).toBe('texture');
+    expect(tex.width).toBe(W);
+    expect(tex.height).toBe(H);
+    // NO_CAPS -> the transcode arm degrades to the uncompressed sRGB fallback
+    // (section 8 P3), never a scheme=1 reject.
+    expect(tex.format).toBe('rgba8unorm-srgb');
+  });
+
+  it('loads every real KTX2/Basis profile through Catalog and loadByGuid', async () => {
+    const fixtures: readonly TextureFixture[] = [
+      {
+        bytes: basisKtx2,
+        extension: 'ktx2',
+        mediaType: 'image/ktx2',
+        container: 'ktx2',
+        profile: 'etc1s',
+        colorSpace: 'srgb',
+      },
+      {
+        bytes: uastcLdrKtx2,
+        extension: 'ktx2',
+        mediaType: 'image/ktx2',
+        container: 'ktx2',
+        profile: 'uastc-ldr',
+        colorSpace: 'srgb',
+      },
+      {
+        bytes: uastcHdrKtx2,
+        extension: 'ktx2',
+        mediaType: 'image/ktx2',
+        container: 'ktx2',
+        profile: 'uastc-hdr',
+        colorSpace: 'linear',
+      },
+      {
+        bytes: rawBasis,
+        extension: 'basis',
+        mediaType: 'image/basis',
+        container: 'basis',
+        profile: 'uastc-ldr',
+        colorSpace: 'srgb',
+      },
+    ];
+
+    for (const fixture of fixtures) {
+      for (const [caps, arm] of CAPABILITY_CELLS) {
+        const result = await loadWith(true, fixture, caps);
+        expect(result.ok, `${fixture.container}:${fixture.profile}:${arm}`).toBe(true);
+        if (!result.ok) continue;
+        const texture = result.value as {
+          kind: string;
+          width: number;
+          height: number;
+          format: string;
+          data: Uint8Array;
+          colorSpace: string;
+        };
+        expect(texture.kind).toBe('texture');
+        expect(texture.width).toBe(W);
+        expect(texture.height).toBe(H);
+        expect(texture.data.byteLength).toBeGreaterThan(0);
+        expect(texture.colorSpace).toBe(fixture.colorSpace);
+        const expected =
+          fixture.profile === 'uastc-hdr'
+            ? caps.bc
+              ? 'bc6h-rgb-ufloat'
+              : 'rgba16float'
+            : caps.bc
+              ? `bc7-rgba-unorm${fixture.colorSpace === 'srgb' ? '-srgb' : ''}`
+              : caps.astc
+                ? `astc-4x4-unorm${fixture.colorSpace === 'srgb' ? '-srgb' : ''}`
+                : caps.etc2
+                  ? `etc2-rgba8unorm${fixture.colorSpace === 'srgb' ? '-srgb' : ''}`
+                  : `rgba8unorm${fixture.colorSpace === 'srgb' ? '-srgb' : ''}`;
+        expect(texture.format, `${fixture.container}:${fixture.profile}:${arm}`).toBe(expected);
+      }
+    }
+  });
+});

package/src/__tests__/bind-group-cache-keying.test.ts

@@ -7,14 +7,14 @@
 // w5: cleanup eviction (cleanPerEntityCache — red until w8 rewrites it)
 //     + getOrCreatePerEntity existence (red until w8 implements it).
 
+import type { BindGroup } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import type { BindGroupCounts } from '../../../render/src/record/frame-snapshot';
 import {
-  type BindGroupCounts,
   cleanPerEntityCache,
   getOrCreateFromChain,
   getOrCreatePerEntity,
-} from '@forgeax/engine-render/internal';
-import type { BindGroup } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/record/mesh-ssbo';
 
 // ─── helpers ────────────────────────────────────────────────────────────────
 

package/src/__tests__/block-upload-math.unit.test.ts

@@ -16,12 +16,12 @@
 //   - no re-test of the block table contents (codec w9 owns that)
 //   - pure node unit, no browser / dawn dependency
 
+import { describe, expect, it } from 'vitest';
 import {
   deriveMipUploadLayout,
   deriveTextureExtent,
   type MipUploadLevel,
-} from '@forgeax/engine-render/internal';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/render-data';
 
 /** Sum of every level's byte length -- the total block-byte buffer size. */
 function totalBytes(layout: readonly MipUploadLevel[]): number {

package/src/__tests__/builtin-asset-registry.unit.test.ts

@@ -0,0 +1,112 @@
+// M6 w46 (AC-30): BuiltinAssetRegistry process-static resolution TDD.
+//
+// D-15 two-tier asset resolution: builtin payloads live in a process-static
+// const keyed by fixed slot u32 (1..6), resolved without any World. Slots
+// >= BUILTIN_BASE belong to the user tier (World.sharedRefs) and resolve to
+// null here. R-13: module init order — importing BuiltinAssetRegistry then
+// immediately resolving all 6 handles must not throw / return undefined.
+// M6 w46 (AC-30): BuiltinAssetRegistry process-static resolution TDD.
+//
+// D-15 two-tier asset resolution: builtin payloads live in a process-static
+// const keyed by fixed slot u32 (1..6), resolved without any World. Slots
+// >= BUILTIN_BASE belong to the user tier (World.sharedRefs) and resolve to
+// null here. R-13: module init order — importing BuiltinAssetRegistry then
+// immediately resolving all 6 handles must not throw / return undefined.
+import {
+  BUILTIN_BASE,
+  BUILTIN_CUBE,
+  BUILTIN_CYLINDER,
+  BUILTIN_NINESLICE_QUAD,
+  BUILTIN_QUAD,
+  BUILTIN_SPHERE,
+  BUILTIN_TRIANGLE,
+  BuiltinAssetRegistry,
+  HANDLE_CUBE,
+  HANDLE_CYLINDER,
+  HANDLE_NINESLICE_QUAD,
+  HANDLE_QUAD,
+  HANDLE_SPHERE,
+  HANDLE_TRIANGLE,
+} from '@forgeax/engine-assets-runtime';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+describe('BuiltinAssetRegistry.resolve (AC-30)', () => {
+  it('resolves each builtin slot 1..6 to its frozen payload', () => {
+    expect(BuiltinAssetRegistry.resolve(HANDLE_CUBE)).toBe(BUILTIN_CUBE);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_TRIANGLE)).toBe(BUILTIN_TRIANGLE);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_QUAD)).toBe(BUILTIN_QUAD);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_SPHERE)).toBe(BUILTIN_SPHERE);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_NINESLICE_QUAD)).toBe(BUILTIN_NINESLICE_QUAD);
+    expect(BuiltinAssetRegistry.resolve(HANDLE_CYLINDER)).toBe(BUILTIN_CYLINDER);
+  });
+
+  it('returns frozen payloads (Object.isFrozen)', () => {
+    expect(Object.isFrozen(BUILTIN_CUBE)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_TRIANGLE)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_QUAD)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_SPHERE)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_NINESLICE_QUAD)).toBe(true);
+    expect(Object.isFrozen(BUILTIN_CYLINDER)).toBe(true);
+  });
+
+  it('returns null for user-tier slots (slot >= BUILTIN_BASE)', () => {
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(BUILTIN_BASE))).toBeNull();
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(BUILTIN_BASE + 1))).toBeNull();
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(99999))).toBeNull();
+  });
+
+  it('returns null for slot 0 (no builtin reserves slot 0)', () => {
+    expect(BuiltinAssetRegistry.resolve(toShared<'MeshAsset'>(0))).toBeNull();
+  });
+
+  it('R-13: module-first-import probe resolves all 6 handles without throwing or undefined', () => {
+    // Importing BuiltinAssetRegistry then resolving must observe fully
+    // constructed frozen payloads — no init-order hazard (synchronous,
+    // module-level, no side effect).
+    for (const handle of [
+      HANDLE_CUBE,
+      HANDLE_TRIANGLE,
+      HANDLE_QUAD,
+      HANDLE_SPHERE,
+      HANDLE_NINESLICE_QUAD,
+      HANDLE_CYLINDER,
+    ]) {
+      const payload = BuiltinAssetRegistry.resolve(handle);
+      expect(payload).not.toBeUndefined();
+      expect(payload).not.toBeNull();
+    }
+  });
+});
+
+// bug-20260709-builtin-quad-withoutaabb-disables-sprite-frustum-cu M2 / AC-02.
+//
+// Flat aabb layout is `Float32Array` of length 6 [minX, minY, minZ,
+// maxX, maxY, maxZ] per `packages/types/src/index.ts:308` — the requirements
+// wording "min/max both length-3 arrays with min[i] <= max[i]" reads as
+// index [0..2] vs [3..5] within that flat array (no {min,max} object wrap).
+describe('builtin payloads carry finite local-space AABBs (AC-02)', () => {
+  it.each([
+    ['HANDLE_CUBE', HANDLE_CUBE, BUILTIN_CUBE],
+    ['HANDLE_TRIANGLE', HANDLE_TRIANGLE, BUILTIN_TRIANGLE],
+    ['HANDLE_QUAD', HANDLE_QUAD, BUILTIN_QUAD],
+    ['HANDLE_SPHERE', HANDLE_SPHERE, BUILTIN_SPHERE],
+    ['HANDLE_NINESLICE_QUAD', HANDLE_NINESLICE_QUAD, BUILTIN_NINESLICE_QUAD],
+    ['HANDLE_CYLINDER', HANDLE_CYLINDER, BUILTIN_CYLINDER],
+  ])('%s exposes the same valid local AABB through registry and export', (_name, handle, exportedConst) => {
+    const payload = BuiltinAssetRegistry.resolve(handle);
+    expect(payload).not.toBeNull();
+    expect(payload).toBe(exportedConst);
+    const aabb = payload?.aabb;
+    expect(aabb).toBeInstanceOf(Float32Array);
+    expect(aabb).toHaveLength(6);
+    if (aabb === undefined) return;
+    for (let axis = 0; axis < 3; axis++) {
+      const minV = aabb[axis];
+      const maxV = aabb[axis + 3];
+      expect(Number.isFinite(minV)).toBe(true);
+      expect(Number.isFinite(maxV)).toBe(true);
+      expect(minV as number).toBeLessThanOrEqual(maxV as number);
+    }
+  });
+});

package/src/__tests__/builtin-shader-register-e2e.test.ts

@@ -17,10 +17,10 @@
 // this test and packages/shader/src/*.material.json surfaces immediately
 // (charter F2: structural, falsifiable).
 
-import { appendInjection } from '@forgeax/engine-render/internal';
 import type { ParamSchemaEntry } from '@forgeax/engine-types';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { appendInjection } from '../../../render/src/pbr-pipeline';
 
 // ─── post-w18 default-standard-pbr sidecar ──────────────────────────────────
 const STANDARD_PBR_SIDECAR: readonly ParamSchemaEntry[] = [

package/src/__tests__/cache-false-eviction.test.ts

@@ -14,8 +14,9 @@
 //   plan-strategy D-1a #4
 //   requirements AC-13
 
-import { cleanPerEntityCache, worldEntityKey } from '@forgeax/engine-render/internal';
 import { describe, expect, it } from 'vitest';
+import { worldEntityKey } from '../../../render/src/record/frame-snapshot';
+import { cleanPerEntityCache } from '../../../render/src/record/mesh-ssbo';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 

package/src/__tests__/cache-isolation-matrix.test.ts

@@ -13,8 +13,9 @@
 //   plan-strategy D-1a #1-#3
 //   requirements AC-07
 
-import { cleanPerEntityCache, worldEntityKey } from '@forgeax/engine-render/internal';
 import { describe, expect, it } from 'vitest';
+import { worldEntityKey } from '../../../render/src/record/frame-snapshot';
+import { cleanPerEntityCache } from '../../../render/src/record/mesh-ssbo';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 

package/src/__tests__/camera-clear-snapshot-equivalence.unit.test.ts

@@ -14,15 +14,14 @@
 // mixed-TDD form).
 
 import { World } from '@forgeax/engine-ecs';
+import { Camera } from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
 import {
-  Camera,
-  extractFrame,
   makeZeroCameraFallbackSnapshot,
-  prepareExtractContext,
   ZERO_CAMERA_CLEAR_FALLBACK,
-} from '@forgeax/engine-render/internal';
-import { propagateTransforms, Transform } from '@forgeax/engine-scene';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/record/frame-snapshot';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
 
 function spawnCameraWithClear(world: World, clear: readonly [number, number, number, number]) {
   world