@forgeax/engine-assets-runtime 0.1.4 → 0.1.7

package/src/__tests__/loader-input-contract.unit.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it, vi } from 'vitest';
+import { LoaderRegistry, type PackLoaderInput } from '../loader-registry';
+import { renderPipelineLoader, tilesetLoader } from '../loaders/pack-artifact';
+
+const input: PackLoaderInput = {
+  guid: '11111111-1111-4111-8111-111111111111',
+  kind: 'host-blob',
+  payload: { value: 1 },
+  refs: [],
+  artifacts: {
+    source: {
+      descriptor: { path: 'source.bin', mediaType: 'application/octet-stream' },
+      bytes: Uint8Array.of(1, 2),
+    },
+  },
+};
+
+describe('uniform Pack v2 loader input', () => {
+  it('contains asset-local artifacts and no catalog transport facts', () => {
+    expect(input.artifacts.source?.bytes).toEqual(Uint8Array.of(1, 2));
+    expect(input).not.toHaveProperty('packageUrl');
+    expect(input).not.toHaveProperty('packageUrl');
+  });
+
+  it('dispatches one uniform input to the registered kind loader', async () => {
+    const load = vi.fn().mockResolvedValue({ ok: true, value: { kind: 'host-blob' } });
+    const registry = new LoaderRegistry();
+    registry.registerPackLoader({ kind: 'host-blob', load });
+    const result = await registry.loadPack(input, {} as never);
+    expect(result.ok).toBe(true);
+    expect(load).toHaveBeenCalledWith(input, {});
+  });
+
+  it('rejects a malformed render-pipeline artifact descriptor', async () => {
+    const result = await renderPipelineLoader.loadPack?.(
+      {
+        guid: input.guid,
+        kind: 'render-pipeline',
+        payload: { kind: 'render-pipeline', pipelineId: 'forgeax::urp' },
+        refs: [],
+        artifacts: {
+          body: {
+            descriptor: { path: 'pipeline.json', mediaType: 'application/json' },
+            bytes: new TextEncoder().encode(
+              JSON.stringify({
+                kind: 'render-pipeline',
+                pipelineId: 'forgeax::urp',
+                config: { passCount: 0 },
+              }),
+            ),
+          },
+        },
+      },
+      {} as never,
+    );
+    expect(result).toMatchObject({ ok: false });
+  });
+
+  it('rejects a tileset artifact whose atlas list differs from envelope refs', async () => {
+    const refs = ['atlas-a', 'atlas-b'];
+    const result = await tilesetLoader.loadPack?.(
+      {
+        guid: input.guid,
+        kind: 'tileset',
+        payload: { kind: 'tileset' },
+        refs,
+        artifacts: {
+          body: {
+            descriptor: { path: 'tileset.json', mediaType: 'application/json' },
+            bytes: new TextEncoder().encode(
+              JSON.stringify({
+                kind: 'tileset',
+                atlases: ['atlas-a', 'atlas-other'],
+                tileWidth: 1,
+                tileHeight: 1,
+                columns: 1,
+                rows: 1,
+                regions: [{ x: 0, y: 0, width: 1, height: 1 }],
+                tiles: [{ regionIndex: 0 }],
+              }),
+            ),
+          },
+        },
+      },
+      {} as never,
+    );
+    expect(result).toMatchObject({ ok: false });
+  });
+});

package/src/__tests__/loader-registry.unit.test.ts

@@ -0,0 +1,101 @@
+// @forgeax/engine-assets-runtime -- LoaderRegistry coverage (fix issue #709).
+// register/get/registeredKinds with fail-fast duplicate ownership semantics.
+
+import type { Loader } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { LoaderRegistry } from '../loader-registry';
+import { createDefaultLoaderRegistry } from '../wire-default-loaders';
+
+function loader(kind: string): Loader<unknown> {
+  return { kind, load: async () => ({ ok: true, value: undefined }) } as unknown as Loader<unknown>;
+}
+
+describe('LoaderRegistry', () => {
+  it('registers and looks up a loader by kind', () => {
+    const reg = new LoaderRegistry();
+    const mesh = loader('mesh');
+    const dispose = reg.register(mesh);
+    expect(reg.get('mesh')).toBe(mesh);
+    dispose();
+    expect(reg.get('mesh')).toBeUndefined();
+    dispose();
+  });
+
+  it('get returns undefined for an unregistered kind', () => {
+    expect(new LoaderRegistry().get('nope')).toBeUndefined();
+  });
+
+  it('registeredKinds returns the kinds in insertion order', () => {
+    const reg = new LoaderRegistry();
+    reg.register(loader('mesh'));
+    reg.register(loader('material'));
+    reg.register(loader('scene'));
+    expect(reg.registeredKinds()).toEqual(['mesh', 'material', 'scene']);
+  });
+
+  it('rejects duplicate kinds instead of silently replacing the owner', () => {
+    const reg = new LoaderRegistry();
+    reg.register(loader('mesh'));
+    const second = loader('mesh');
+    expect(() => reg.register(second)).toThrow(/duplicate loader kind/);
+    expect(reg.get('mesh')).not.toBe(second);
+    expect(reg.registeredKinds()).toEqual(['mesh']);
+  });
+
+  it('throws TypeError when kind is an empty string', () => {
+    expect(() => new LoaderRegistry().register(loader(''))).toThrow(TypeError);
+  });
+
+  it('throws TypeError when load is not a function', () => {
+    const bad = { kind: 'mesh', load: 123 } as unknown as Loader<unknown>;
+    expect(() => new LoaderRegistry().register(bad)).toThrow(TypeError);
+  });
+
+  it('does not treat a catalog row as a loader input', async () => {
+    const reg = new LoaderRegistry();
+    reg.registerPackLoader({
+      kind: 'mesh',
+      load: async (input) => ({ ok: true, value: input.payload }),
+    });
+    const result = await reg.loadPack(
+      {
+        guid: 'mesh-guid',
+        kind: 'mesh',
+        payload: { vertices: [] },
+        refs: [],
+        artifacts: {},
+      },
+      {} as never,
+    );
+    expect(result.ok).toBe(true);
+  });
+
+  it('wires every ordinary Asset kind into the default loader registry', () => {
+    const expectedKinds = [
+      'mesh',
+      'material',
+      'scene',
+      'texture',
+      'equirect',
+      'sampler',
+      'font',
+      'render-pipeline',
+      'tileset',
+      'video',
+      'skeleton',
+      'skin',
+      'animation-clip',
+      'animation-graph',
+      'audio',
+      'particle-effect',
+    ];
+    const registry = createDefaultLoaderRegistry();
+    expect(
+      registry
+        .registeredKinds()
+        .filter((kind) => kind !== 'ui')
+        .sort(),
+    ).toEqual(expectedKinds.sort());
+    expect(registry.get('ui')).toBeDefined();
+  });
+});

package/src/__tests__/material-dependency-invalidation.unit.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { MaterialDependencyGraph } from '../material/dependency-graph.js';
+
+describe('material dependency invalidation', () => {
+  it('enumerates reverse edges and selectively invalidates descendants', () => {
+    const graph = new MaterialDependencyGraph();
+    graph.link('mat-child', ['mat-parent', 'texture/albedo', 'shader/module']);
+    graph.link('mat-other', ['texture/other']);
+
+    expect(graph.dependentsOf('mat-parent')).toEqual(['mat-child']);
+    expect(graph.invalidate(['mat-parent'])).toEqual(['mat-child']);
+    expect(graph.isInvalidated('mat-other')).toBe(false);
+  });
+});

package/src/__tests__/material-generation-cache.unit.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { MaterialGenerationCache } from '../material/generation-cache.js';
+
+describe('material generation cache', () => {
+  it('reuses promises by material GUID and artifacts by specialization key', async () => {
+    const cache = new MaterialGenerationCache();
+    const first = cache.resolve('mat-a', 'key-a', async () => ({ value: 1 }));
+    const second = cache.resolve('mat-a', 'key-a', async () => ({ value: 2 }));
+
+    expect(first).toBe(second);
+    await expect(first).resolves.toEqual({ value: 1 });
+    cache.storeArtifact('key-a', Object.freeze({ bytes: new Uint8Array([1]) }));
+    expect(cache.getArtifact('key-a')).toEqual({ bytes: new Uint8Array([1]) });
+  });
+
+  it('allows distinct authored GUIDs to share one artifact', () => {
+    const cache = new MaterialGenerationCache();
+    const artifact = Object.freeze({ bytes: new Uint8Array([1]) });
+
+    cache.storeArtifact('key-a', artifact);
+    cache.linkResolved('mat-a', 'key-a');
+    cache.linkResolved('mat-b', 'key-a');
+
+    expect(cache.getResolvedKey('mat-a')).toBe('key-a');
+    expect(cache.getResolvedKey('mat-b')).toBe('key-a');
+    expect(cache.getArtifact('key-a')).toBe(artifact);
+  });
+
+  it('evicts a published specialization when a tracked dependency advances', async () => {
+    const cache = new MaterialGenerationCache();
+    let calls = 0;
+    const load = () =>
+      cache.loadWithGeneration('mat-a', ['shader/a'], async (generation) => ({
+        generation,
+        value: ++calls,
+      }));
+
+    const first = await cache.resolve('mat-a', 'key-a', load);
+    expect(first).toMatchObject({ ok: true, value: 1 });
+
+    cache.bump('shader/a');
+    const second = await cache.resolve('mat-a', 'key-a', load);
+    expect(second).toMatchObject({ ok: true, value: 2 });
+    expect(calls).toBe(2);
+  });
+});

package/src/__tests__/material-load-consumer.test-d.ts

@@ -0,0 +1,42 @@
+import type { AssetGuid, MaterialAsset } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { AssetRegistry } from '../index.js';
+import { loadMaterialReadyByGuid } from '../registry/load-by-guid.js';
+
+declare const assets: Pick<AssetRegistry, 'loadByGuid'>;
+declare const materialGuid: AssetGuid;
+
+describe('MaterialAsset loadByGuid consumer', () => {
+  it('narrows the successful load result without a cast', async () => {
+    const loaded = await assets.loadByGuid<MaterialAsset>(materialGuid);
+    if (!loaded.ok) return;
+
+    expectTypeOf(loaded.value.values).toMatchTypeOf<MaterialAsset['values']>();
+    expectTypeOf(loaded.value.passes).toMatchTypeOf<MaterialAsset['passes']>();
+  });
+
+  it('exposes the complete MaterialReady tuple and closed error union', async () => {
+    const ready = await loadMaterialReadyByGuid(assets as AssetRegistry, {
+      guid: 'material-guid',
+      specializationKey: 'specialization-key',
+    });
+    if (ready.status === 'Ready') {
+      expectTypeOf(ready.materialGuid).toBeString();
+      expectTypeOf(ready.publicationGeneration).toBeNumber();
+      expectTypeOf(ready.specializationKey).toBeString();
+      expectTypeOf(ready.artifactDigest).toBeString();
+      expectTypeOf(ready.sourceClosure).toEqualTypeOf<readonly string[]>();
+      expectTypeOf(ready.parameterContract).toHaveProperty('parameters');
+      return;
+    }
+    switch (ready.error.code) {
+      case 'material-specialization-not-cooked':
+      case 'asset-artifact-missing':
+      case 'asset-artifact-integrity-mismatch':
+      case 'material-cook-record-invalid':
+      case 'material-reference-not-ready':
+        return;
+    }
+    expectTypeOf(ready.error.code).toBeNever();
+  });
+});