@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/asset-registry-scene.test-d.ts

@@ -0,0 +1,49 @@
+// asset-registry-scene.test-d - type-level assertion that the 5-element
+// AssetUnion exhaustive switch narrows correctly without a default arm
+// (feat-20260514-scene-as-world-blueprint w6 / AC-01 / AC-03; merged with
+// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w15 which
+// retired the `'instanced-buffer-asset'` variant -> Asset closed-union
+// 5 -> 4, then widened to 5 again with the new `'scene'` member).
+//
+// w3 widens `Asset` to include `SceneAsset` and the runtime exhaustiveness
+// guard narrows correctly. The exhaustive switch below doubles as a
+// negative regression: deleting any case produces a `never` flow (TS reports
+// `Type 'SceneAsset' is not assignable to type 'never'` at the affected
+// arm), so this file fails fast if the union ever drifts.
+//
+// feat-20260623 M2 / w8: AssetBrand retired (PR #496 eliminated brand concept);
+// the brand(asset) function and local AssetBrand type are removed. The Asset
+// union exhaustive switch is the remaining type-level guard.
+//
+// Charter mapping: proposition 3 (machine-readable union > prose) +
+// proposition 4 (explicit failure: closed-union exhaustive switch needs no
+// default fallback; tsc strict mode guards completeness).
+
+import type { Asset } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('AssetUnion exhaustive switch covers all 15 members (feat-20260608 M0 baseline rebuild + feat-20260623-world-space-video-asset M1)', () => {
+  it('Asset union is the closed type-level discriminator for engine-known assets', () => {
+    // Asset is the SSOT for engine-known asset types; exhaustiveness is
+    // enforced by TypeScript's closed-union narrowing. A missing member
+    // triggers `Type 'XxxAsset' is not assignable to type 'never'`.
+    expectTypeOf<Asset['kind']>().toEqualTypeOf<
+      | 'mesh'
+      | 'texture'
+      | 'sampler'
+      | 'material'
+      | 'scene'
+      | 'equirect'
+      | 'skeleton'
+      | 'skin'
+      | 'animation-clip'
+      | 'animation-graph'
+      | 'audio'
+      | 'font'
+      | 'render-pipeline'
+      | 'tileset'
+      | 'video'
+      | 'particle-effect'
+    >();
+  });
+});

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();
+  });
+});