@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/asset-registry.browser.test.ts

@@ -0,0 +1,81 @@
+// w12 - AssetRegistry browser path (loadByGuid + GUID-keyed catalog API)
+//
+// Migration from load(url) to loadByGuid (feat-20260513-guid-asset-package-system w13).
+// feat-20260614 M8 (D-17): the registry catalogues GUID -> payload and
+// `loadByGuid` returns the PAYLOAD (no handle). Column minting moved to
+// `world.allocSharedRef`. Covers catalog + loadByGuid ok path + payload
+// idempotency + AC-11 inspect() shape for a GUID-catalogued asset.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const GUID_BROWSER_A = '00000000-0000-7000-8000-000000000021';
+
+function makeMesh(): TypesMeshAsset {
+  return {
+    kind: 'mesh',
+    // 1 vertex * 12F canonical layout (position vec3 + normal vec3 + uv vec2 + tangent vec4)
+    vertices: new Float32Array([0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1]),
+    indices: new Uint16Array([0]),
+    attributes: {},
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 1,
+        vertexCount: 12,
+        topology: 'triangle-list',
+        materialSlot: 0,
+      },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  };
+}
+
+describe('w12 - AssetRegistry browser loadByGuid happy path', () => {
+  it('loadByGuid() returns Ok(payload) for a catalogued GUID', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const parseResult = AssetGuid.parse(GUID_BROWSER_A);
+    if (!parseResult.ok) throw new Error('expected ok');
+    const guid = parseResult.value;
+    const mesh = makeMesh();
+    reg.catalog<TypesMeshAsset>(guid, mesh);
+    const res = await reg.loadByGuid<TypesMeshAsset>(guid);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.kind).toBe('mesh');
+  });
+
+  it('two loadByGuid(sameGuid) calls return the same payload', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const parseResult = AssetGuid.parse(GUID_BROWSER_A);
+    if (!parseResult.ok) throw new Error('expected ok');
+    const guid = parseResult.value;
+    reg.catalog<TypesMeshAsset>(guid, makeMesh());
+    const a = await reg.loadByGuid<TypesMeshAsset>(guid);
+    const b = await reg.loadByGuid<TypesMeshAsset>(guid);
+    expect(a.ok).toBe(true);
+    expect(b.ok).toBe(true);
+    if (a.ok && b.ok) {
+      expect(a.value).toBe(b.value);
+    }
+  });
+
+  it('AC-11: inspect() reports MeshAsset brand after catalog()', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const before = reg.inspect().assets.length;
+    const parseResult = AssetGuid.parse(GUID_BROWSER_A);
+    if (!parseResult.ok) throw new Error('expected ok');
+    const guid = parseResult.value;
+    reg.catalog<TypesMeshAsset>(guid, makeMesh());
+    const snap = reg.inspect();
+    expect(snap.assets.length).toBe(before + 1);
+    const last = snap.assets[snap.assets.length - 1];
+    expect(last).toBeDefined();
+    if (last === undefined) return;
+    expect(last.kind).toBe('mesh');
+  });
+});

package/src/__tests__/asset-registry.dawn.test.ts

@@ -0,0 +1,94 @@
+// w13 - AssetRegistry Node path (loadByGuid + GUID-keyed catalog API).
+//
+// Migration from load(url) to loadByGuid (feat-20260513-guid-asset-package-system w13).
+// feat-20260614 M8 (D-17): the registry catalogues GUID -> payload and
+// `loadByGuid` returns the PAYLOAD (no handle); column minting moved to
+// `world.allocSharedRef`, handle->payload resolution to `resolveAssetHandle`.
+// Covers catalog + loadByGuid ok path + payload idempotency + asset-not-found
+// error path on missing GUID + asset-not-found on an unresolvable handle.
+
+import { AssetRegistry, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { Handle, TextureAsset, MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const GUID_DAWN_A = '00000000-0000-7000-8000-000000000031';
+const GUID_DAWN_B = '00000000-0000-7000-8000-000000000032';
+
+function makeMesh(): TypesMeshAsset {
+  return {
+    kind: 'mesh',
+    // 1 vertex * 12F canonical layout (position vec3 + normal vec3 + uv vec2 + tangent vec4)
+    vertices: new Float32Array([0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1]),
+    indices: new Uint16Array([0]),
+    attributes: {},
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 1,
+        vertexCount: 12,
+        topology: 'triangle-list',
+        materialSlot: 0,
+      },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  };
+}
+
+describe('w13 - AssetRegistry Node loadByGuid happy path', () => {
+  it('loadByGuid() returns Ok(payload) for a catalogued GUID', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const parseResult = AssetGuid.parse(GUID_DAWN_A);
+    if (!parseResult.ok) throw new Error('expected ok');
+    const guid = parseResult.value;
+    const mesh = makeMesh();
+    reg.catalog<TypesMeshAsset>(guid, mesh);
+    const res = await reg.loadByGuid<TypesMeshAsset>(guid);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.value.kind).toBe('mesh');
+  });
+
+  it('two loadByGuid(sameGuid) calls return same payload (idempotent)', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const parseResult = AssetGuid.parse(GUID_DAWN_A);
+    if (!parseResult.ok) throw new Error('expected ok');
+    const guid = parseResult.value;
+    reg.catalog<TypesMeshAsset>(guid, makeMesh());
+    const a = await reg.loadByGuid<TypesMeshAsset>(guid);
+    const b = await reg.loadByGuid<TypesMeshAsset>(guid);
+    expect(a.ok).toBe(true);
+    expect(b.ok).toBe(true);
+    if (a.ok && b.ok) {
+      expect(a.value).toBe(b.value);
+    }
+  });
+});
+
+describe('w13 - AssetRegistry Node error paths (AC-03 migration)', () => {
+  it('asset-not-found: loadByGuid(unregistered guid)', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const parseResult = AssetGuid.parse(GUID_DAWN_B);
+    if (!parseResult.ok) throw new Error('expected ok');
+    const guid = parseResult.value;
+    const res = await reg.loadByGuid<TypesMeshAsset>(guid);
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.error.code).toBe('asset-not-found');
+  });
+
+  it('asset-not-found: resolveAssetHandle(unallocated gen-0 handle)', () => {
+    const world = new World();
+    // gen-0 user-tier handle for a never-allocated slot: passes the generation
+    // gate (storeGen defaults to 0) then misses the payload -> asset-not-found.
+    // (A gen>0 handle would instead surface 'shared-ref-stale' per D-3/AC-10 —
+    // see asset.unit.test.ts "unresolvable handle: stale error forwarded".)
+    const fake = toShared<'TextureAsset'>(99999);
+    const res = resolveAssetHandle<TextureAsset>(world, fake as Handle<string, 'shared'>);
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.error.code).toBe('asset-not-found');
+  });
+});

package/src/__tests__/asset-registry.listCatalog.test.ts

@@ -0,0 +1,170 @@
+// w1 TDD: listCatalog unit test (plan-strategy section 2 D1)
+//
+// Test-first approach — call listCatalog() before it exists on AssetRegistry,
+// confirming the TDD "red" phase via TypeScript compile error (TS2339).
+// w2 will add the implementation and turn these tests green.
+//
+// plan-strategy section 2 D1 (engine export for AC-03 asset panel enumeration);
+// requirements AC-03 (asset panel = engine truth, no parallel discovery);
+// research Finding 5 (AssetRegistry public API is all guid point-lookup;
+// assetCatalog/packIndexCache are private — no enumeration primitive exists yet).
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeReg(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+function makeMeshFixture(): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array(36),
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: {},
+    materialSlots: [{ slotName: 'Default' }],
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 3,
+        materialSlot: 0,
+        topology: 'triangle-list' as const,
+      },
+    ],
+  } as unknown as MeshAsset;
+}
+
+describe('D-1 listCatalog() (TDD: red before w2 impl)', () => {
+  it('returns non-empty array for catalogued assets matching inspect() truth', () => {
+    const reg = makeReg();
+    const guid = AssetGuid.format(AssetGuid.random());
+    const mesh = makeMeshFixture();
+    reg.catalog(guid, mesh);
+
+    const list = reg.listCatalog();
+    expect(Array.isArray(list)).toBe(true);
+    expect(list.length).toBeGreaterThan(0);
+
+    const found = list.find(
+      (e: { guid: string; kind: string; name?: string; packageUrl: string }) =>
+        e.guid === guid.toLowerCase(),
+    );
+    expect(found).toBeDefined();
+    expect(found?.guid).toBe(guid.toLowerCase());
+    expect(found?.kind).toBe('mesh');
+    // name derived via resolveName (empty for no-package catalogued asset)
+    expect(found).toHaveProperty('name');
+    expect(found).toHaveProperty('packageUrl');
+  });
+
+  it('returns empty array for a registry with zero catalogued assets (boundary E3)', () => {
+    const reg = makeReg();
+    // Fresh registry still has builtins. Clear them via invalidateAll.
+    reg.invalidateAll();
+    const list = reg.listCatalog();
+    expect(Array.isArray(list)).toBe(true);
+    expect(list.length).toBe(0);
+  });
+
+  it('surfaces dev-path refs as flattened GUID edges (Content Browser dependency graph)', () => {
+    const reg = makeReg();
+    const guid = AssetGuid.format(AssetGuid.random());
+    const dep1 = AssetGuid.format(AssetGuid.random());
+    const dep2 = AssetGuid.format(AssetGuid.random());
+    const mesh = makeMeshFixture();
+    // catalog(guid, asset, refs) stores the rich AssetRef[] on the envelope;
+    // listCatalog must flatten it to plain GUID strings.
+    reg.catalog(guid, mesh, [{ guid: dep1, sourceField: { fieldName: 'a' } }, { guid: dep2 }]);
+
+    const found = reg.listCatalog().find((e) => e.guid === guid.toLowerCase());
+    expect(found?.refs).toEqual([dep1, dep2]);
+  });
+
+  it('omits refs when an asset has no outgoing edges (add-only, undefined not [])', () => {
+    const reg = makeReg();
+    const guid = AssetGuid.format(AssetGuid.random());
+    reg.catalog(guid, makeMeshFixture());
+
+    const found = reg.listCatalog().find((e) => e.guid === guid.toLowerCase());
+    expect(found).toBeDefined();
+    expect(found?.refs).toBeUndefined();
+  });
+
+  it('returns a snapshot — two calls return distinct array objects (no internal Map leak, charter P4)', () => {
+    const reg = makeReg();
+    const guid = AssetGuid.format(AssetGuid.random());
+    const mesh = makeMeshFixture();
+    reg.catalog(guid, mesh);
+
+    const first = reg.listCatalog();
+    const firstLen = first.length;
+
+    const second = reg.listCatalog();
+    expect(second.length).toBe(firstLen);
+    // Snapshot identity: two calls return distinct array objects
+    // (no internal Map reference leak — charter P4).
+    expect(first).not.toBe(second);
+  });
+});
+
+// Prod path: sourcePath is only present on the pack-index (fetchPackIndex ->
+// packIndexCache), never on dev-path catalog() envelopes. Editors need it to
+// locate the `.meta.json` sidecar for external-asset CRUD; `packageUrl`
+// points at the Pack v2 package and cannot
+// be reversed to the source path.
+describe('listCatalog() prod-path sourcePath (editor CRUD sidecar lookup)', () => {
+  const PACK_INDEX_URL = '/pack-index.json';
+  const MESH_GUID = 'a0000000-0000-4000-a000-000000000001';
+  const MESH_URL = '/assets/arrow_bow.fbx.a0000000.pack.json';
+  const MESH_SOURCE = 'games/marscraft/assets/arrow_bow.fbx';
+  // A row that omits sourcePath (legacy / malformed pack-index) must surface as
+  // undefined, not '', so consumers can distinguish "no source" from "empty".
+  const INLINE_GUID = 'a0000000-0000-4000-a000-000000000002';
+
+  let originalFetch: typeof globalThis.fetch | undefined;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    if (originalFetch !== undefined) {
+      globalThis.fetch = originalFetch;
+    } else {
+      // biome-ignore lint/suspicious/noExplicitAny: test teardown
+      delete (globalThis as any).fetch;
+    }
+  });
+
+  it('surfaces sourcePath from the pack-index; omits it for rows that lack one', async () => {
+    const reg = makeReg();
+    reg.configurePackIndex(PACK_INDEX_URL);
+
+    const packIndex = [
+      { guid: MESH_GUID, packageUrl: MESH_URL, kind: 'mesh', sourcePath: MESH_SOURCE },
+      { guid: INLINE_GUID, packageUrl: '/assets/other.pack.json', kind: 'mesh' },
+    ];
+    globalThis.fetch = vi.fn().mockImplementation((url: string) => {
+      if (url === PACK_INDEX_URL) {
+        return Promise.resolve({ ok: true, json: () => Promise.resolve(packIndex) });
+      }
+      return Promise.resolve({ ok: false, status: 404 });
+    }) as typeof globalThis.fetch;
+
+    // Populate packIndexCache without needing the (missing) pack bodies:
+    // refreshCatalog fetches + parses the pack-index into packIndexCache, which
+    // is the source listCatalog reads for prod rows.
+    await reg.refreshCatalog();
+
+    const withSource = reg.listCatalog().find((e) => e.guid === MESH_GUID.toLowerCase());
+    expect(withSource?.sourcePath).toBe(MESH_SOURCE);
+
+    const withoutSource = reg.listCatalog().find((e) => e.guid === INLINE_GUID.toLowerCase());
+    expect(withoutSource).toBeDefined();
+    expect(withoutSource?.sourcePath).toBeUndefined();
+  });
+});

package/src/__tests__/asset-registry.mesh-bin.test.ts

@@ -0,0 +1,316 @@
+// asset-registry.mesh-bin.test.ts -- bug-20260610-pack-mesh-binarize-fetchpackfile-cache
+// M2 / m2-1: regression test for mesh binarize round-trip via .pack.json + .bin
+// sidecar (Fix A). RED at this commit (loader cannot read .bin yet); GREEN
+// after the implementation commit.
+//
+// Cases (plan-decisions D-6):
+//   (A) binarized new path -- mesh entry payload is the empty sentinel (vertices=[],
+//       indices=[], data=Uint8Array(0)); the runtime resolves vertices/indices from
+//       a sibling <guid>.bin URL referenced by the catalog row. Asserts
+//       round-tripped vertices and indices are byte-equal to the originals.
+//   (B) inline fallback (CON-7) -- mesh entry payload carries inline number arrays
+//       (legacy pack shape). meshLoader's existing Array.isArray branch must still
+//       work. Asserts handle resolves and registered MeshAsset has the inline
+//       vertices/indices.
+//   (C) empty mesh -- vertices=[], indices=[] sentinel + 16-byte deterministic
+//       header (vlen=0, ilen=0, iwidth=0, jsonlen=0). loader returns a mesh with
+//       0 vertices and 0 indices, no panic.
+//
+// Anchors: requirements AC-04 / AC-05 / CON-1 / CON-7;
+//          plan-strategy decisions D-1 / D-2 / D-3 / D-6;
+//          plan-decisions D-6 (3-case coverage).
+//
+// The test producer delegates the v4 header and canonical projection to the
+// import owner; the runtime only consumes the resulting bytes.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { packMeshBinV4 } from '@forgeax/engine-import';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+// 12 floats per vertex (position vec3 + normal vec3 + uv vec2 + tangent vec4) --
+// matches PROCEDURAL_FLOATS_PER_VERTEX and the meshLoader stride invariant.
+const FLOATS_PER_VERTEX = 12;
+
+const MESH_BIN_GUID = '00000000-0000-7000-8000-00006d657368'; // mesh sentinel
+const MESH_INLINE_GUID = '00000000-0000-7000-8000-696e6c696e65'; // inline
+const MESH_EMPTY_GUID = '00000000-0000-7000-8000-656d70747974'; // empty
+
+function packMeshBinForTest(
+  vertices: Float32Array,
+  indices: Uint16Array | Uint32Array,
+  metaJson: string,
+): Uint8Array {
+  const parsed = JSON.parse(metaJson) as Record<string, unknown>;
+  const vertexCount = vertices.length / FLOATS_PER_VERTEX;
+  const position = new Float32Array(vertexCount * 3);
+  const normal = new Float32Array(vertexCount * 3);
+  const uv = new Float32Array(vertexCount * 2);
+  const tangent = new Float32Array(vertexCount * 4);
+  for (let vertex = 0; vertex < vertexCount; vertex++) {
+    const source = vertex * FLOATS_PER_VERTEX;
+    position.set(vertices.subarray(source, source + 3), vertex * 3);
+    normal.set(vertices.subarray(source + 3, source + 6), vertex * 3);
+    uv.set(vertices.subarray(source + 6, source + 8), vertex * 2);
+    tangent.set(vertices.subarray(source + 8, source + 12), vertex * 4);
+  }
+  const packed = packMeshBinV4(
+    {
+      vertices,
+      indices,
+      attributes: {
+        position,
+        normal,
+        uv,
+        tangent,
+      },
+      submeshes: parsed.submeshes as MeshAsset['submeshes'],
+      aabb: parsed.aabb as MeshAsset['aabb'],
+    },
+    'runtime://asset-registry',
+  );
+  if (!packed.ok) throw new Error(packed.error.actual);
+  return packed.value;
+}
+
+function makePackIndex(rows: Array<{ guid: string; packageUrl: string }>) {
+  return rows.map((r) => ({
+    guid: r.guid,
+    packageUrl: r.packageUrl,
+    kind: 'mesh' as const,
+  }));
+}
+
+interface FetchRoute {
+  json?: unknown;
+  bytes?: Uint8Array;
+  status?: number;
+}
+
+function installFetchMock(routes: Map<string, FetchRoute>): void {
+  globalThis.fetch = (async (input: string | URL | Request) => {
+    const url =
+      typeof input === 'string'
+        ? input
+        : input instanceof URL
+          ? input.href
+          : (input as Request).url;
+    const route = routes.get(url);
+    if (route === undefined) {
+      return {
+        ok: false,
+        status: 404,
+        json: async () => null,
+        arrayBuffer: async () => new ArrayBuffer(0),
+      } as unknown as Response;
+    }
+    if (route.status !== undefined && route.status >= 400) {
+      return { ok: false, status: route.status } as unknown as Response;
+    }
+    return {
+      ok: true,
+      status: 200,
+      json: async () => route.json,
+      arrayBuffer: async () =>
+        route.bytes !== undefined
+          ? route.bytes.buffer.slice(
+              route.bytes.byteOffset,
+              route.bytes.byteOffset + route.bytes.byteLength,
+            )
+          : new ArrayBuffer(0),
+    } as unknown as Response;
+  }) as unknown as typeof globalThis.fetch;
+}
+
+describe('mesh-bin loader (M2 / m2-1)', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('(A) binarized path: vertices/indices reconstructed byte-equal from sibling .bin', async () => {
+    // Two-vertex triangle stub (24 floats total = 2 verts * 12F). Vertex count <=
+    // 0xffff -> Uint16Array indices.
+    const vertices = new Float32Array(FLOATS_PER_VERTEX * 2);
+    for (let i = 0; i < vertices.length; i++) vertices[i] = i + 0.5;
+    const indices = new Uint16Array([0, 1, 0]);
+    const metaJson = JSON.stringify({
+      submeshes: [{ indexOffset: 0, indexCount: 3, vertexCount: 2, topology: 'triangle-list' }],
+      attributes: {},
+      aabb: [0, 0, 0, 1, 1, 1],
+    });
+    const binBytes = packMeshBinForTest(vertices, indices, metaJson);
+
+    const packIndexUrl = '/pack-index.json';
+    const packUrl = `/assets/${MESH_BIN_GUID.toLowerCase()}.pack.json`;
+    const binUrl = `/assets/${MESH_BIN_GUID.toLowerCase()}/body.bin`;
+    const routes = new Map<string, FetchRoute>([
+      [packIndexUrl, { json: makePackIndex([{ guid: MESH_BIN_GUID, packageUrl: packUrl }]) }],
+      [
+        packUrl,
+        {
+          json: {
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: MESH_BIN_GUID,
+                kind: 'mesh',
+                payload: {},
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: `${MESH_BIN_GUID.toLowerCase()}/body.bin`,
+                    mediaType: 'application/x-forgeax-mesh',
+                  },
+                },
+              },
+            ],
+          },
+        },
+      ],
+      [binUrl, { bytes: binBytes }],
+    ]);
+    installFetchMock(routes);
+
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(packIndexUrl);
+
+    const parsed = AssetGuid.parse(MESH_BIN_GUID);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+
+    const result = await reg.loadByGuid<MeshAsset>(parsed.value);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // D-17: loadByGuid returns the payload directly (registry holds no handles).
+    const mesh = result.value;
+    expect(mesh.kind).toBe('mesh');
+    expect(mesh.vertices.length).toBe(vertices.length);
+    for (let i = 0; i < vertices.length; i++) {
+      expect(mesh.vertices[i]).toBe(vertices[i]);
+    }
+    expect(mesh.indices).toBeInstanceOf(Uint16Array);
+    expect(mesh.indices?.length).toBe(indices.length);
+    if (mesh.indices !== undefined) {
+      for (let i = 0; i < indices.length; i++) {
+        expect(mesh.indices[i]).toBe(indices[i]);
+      }
+    }
+  });
+
+  it('(B) inline fallback (CON-7): legacy pack with Array.isArray vertices still loads', async () => {
+    // Single triangle, 12 floats per vertex, 3 vertices -> 36 floats, 3 indices.
+    const verticesArr: number[] = [];
+    for (let i = 0; i < FLOATS_PER_VERTEX * 3; i++) verticesArr.push(i + 0.25);
+    const indicesArr: number[] = [0, 1, 2];
+
+    const packIndexUrl = '/pack-index.json';
+    const packUrl = '/assets/inline.pack.json';
+    const routes = new Map<string, FetchRoute>([
+      [packIndexUrl, { json: makePackIndex([{ guid: MESH_INLINE_GUID, packageUrl: packUrl }]) }],
+      [
+        packUrl,
+        {
+          json: {
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: MESH_INLINE_GUID,
+                kind: 'mesh',
+                payload: {
+                  vertices: verticesArr,
+                  indices: indicesArr,
+                  attributes: {},
+                },
+                refs: [],
+                artifacts: {},
+              },
+            ],
+          },
+        },
+      ],
+    ]);
+    installFetchMock(routes);
+
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(packIndexUrl);
+
+    const parsed = AssetGuid.parse(MESH_INLINE_GUID);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+
+    const result = await reg.loadByGuid<MeshAsset>(parsed.value);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // D-17: loadByGuid returns the payload directly (registry holds no handles).
+    const mesh = result.value;
+    expect(mesh.kind).toBe('mesh');
+    expect(mesh.vertices.length).toBe(verticesArr.length);
+    expect(mesh.vertices[0]).toBe(0.25);
+    expect(mesh.indices?.length).toBe(indicesArr.length);
+  });
+
+  it('(C) empty mesh: v4 projection decodes to 0 verts / 0 indices', async () => {
+    const binBytes = packMeshBinForTest(
+      new Float32Array(0),
+      new Uint16Array(0),
+      JSON.stringify({
+        submeshes: [{ indexOffset: 0, indexCount: 0, vertexCount: 0, materialSlot: 0 }],
+        aabb: [0, 0, 0, 0, 0, 0],
+      }),
+    );
+
+    const packIndexUrl = '/pack-index.json';
+    const packUrl = `/assets/${MESH_EMPTY_GUID.toLowerCase()}.pack.json`;
+    const binUrl = `/assets/${MESH_EMPTY_GUID.toLowerCase()}/body.bin`;
+    const routes = new Map<string, FetchRoute>([
+      [packIndexUrl, { json: makePackIndex([{ guid: MESH_EMPTY_GUID, packageUrl: packUrl }]) }],
+      [
+        packUrl,
+        {
+          json: {
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: MESH_EMPTY_GUID,
+                kind: 'mesh',
+                payload: {},
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: `${MESH_EMPTY_GUID.toLowerCase()}/body.bin`,
+                    mediaType: 'application/x-forgeax-mesh',
+                  },
+                },
+              },
+            ],
+          },
+        },
+      ],
+      [binUrl, { bytes: binBytes }],
+    ]);
+    installFetchMock(routes);
+
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(packIndexUrl);
+
+    const parsed = AssetGuid.parse(MESH_EMPTY_GUID);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+
+    const result = await reg.loadByGuid<MeshAsset>(parsed.value);
+    expect(result.ok).toBe(false);
+  });
+});