@forgeax/engine-assets-runtime 0.1.4 → 0.1.7

package/src/__tests__/inline-pack-loaders.unit.test.ts

@@ -0,0 +1,548 @@
+// @forgeax/engine-assets-runtime -- inline pack-payload loader coverage
+// (fix issue #709). Each loader is a pure (payload, refs, ctx) -> Asset|undefined
+// function; exercise the accept + reject arms of all eight, plus the
+// wireDefaultLoaders / createDefaultLoaderRegistry seed-table helpers.
+
+import type { LoadContext, MaterialAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { LoaderRegistry } from '../loader-registry';
+import {
+  animationClipLoader,
+  animationGraphLoader,
+  INLINE_PACK_LOADERS,
+  materialLoader,
+  meshLoader,
+  samplerLoader,
+  sceneLoader,
+  skeletonLoader,
+  skinLoader,
+} from '../loaders/inline-pack';
+import { createDefaultLoaderRegistry, wireDefaultLoaders } from '../wire-default-loaders';
+
+const emptyCtx = {} as LoadContext;
+
+describe('meshLoader', () => {
+  it('rejects legacy mesh binaries without a white/default fallback', () => {
+    const output = meshLoader.loadPack?.(
+      {
+        guid: 'mesh-legacy',
+        payload: {},
+        artifacts: { body: { bytes: new Uint8Array([2, 0, 0]) } },
+      } as never,
+      emptyCtx,
+    );
+    expect(output).toMatchObject({ ok: false, error: { sourceKey: 'mesh-legacy' } });
+  });
+
+  it('normalises Array vertices/indices into typed arrays with a default submesh', () => {
+    const out = meshLoader.load(
+      { vertices: new Array(12).fill(0), indices: [0, 0, 0] },
+      undefined,
+      emptyCtx,
+    );
+    expect(out).toBeDefined();
+    const mesh = out as {
+      kind: string;
+      vertices: Float32Array;
+      indices?: Uint16Array;
+      submeshes: unknown[];
+    };
+    expect(mesh.kind).toBe('mesh');
+    expect(mesh.vertices).toBeInstanceOf(Float32Array);
+    expect(mesh.indices).toBeInstanceOf(Uint16Array);
+    expect(mesh.submeshes).toHaveLength(1);
+  });
+
+  it('drops an empty index array (vertex-only path)', () => {
+    const out = meshLoader.load(
+      { vertices: new Float32Array(12), indices: [] },
+      undefined,
+      emptyCtx,
+    ) as {
+      indices?: unknown;
+    };
+    expect(out.indices).toBeUndefined();
+  });
+
+  it('accepts skinIndex/skinWeight as arrays', () => {
+    const out = meshLoader.load(
+      {
+        vertices: new Float32Array(18),
+        attributes: { skinIndex: [0, 1, 2, 3], skinWeight: [1, 0, 0, 0] },
+      },
+      undefined,
+      emptyCtx,
+    ) as { attributes: { skinIndex: unknown; skinWeight: unknown } };
+    expect(out.attributes.skinIndex).toBeInstanceOf(Uint16Array);
+    expect(out.attributes.skinWeight).toBeInstanceOf(Float32Array);
+  });
+
+  it('rejects a non-array/non-typed vertices payload', () => {
+    expect(meshLoader.load({ vertices: 'bad' }, undefined, emptyCtx)).toBeUndefined();
+  });
+
+  it('rejects a malformed skinIndex', () => {
+    expect(
+      meshLoader.load(
+        { vertices: new Float32Array(12), attributes: { skinIndex: 'bad' } },
+        undefined,
+        emptyCtx,
+      ),
+    ).toBeUndefined();
+  });
+});
+
+describe('meshLoader strict v4 inline artifact', () => {
+  it('routes a malformed inline mesh artifact as a structured error and publishes no asset', () => {
+    const output = meshLoader.loadPack?.(
+      {
+        guid: 'mesh-guid',
+        kind: 'mesh',
+        payload: {},
+        refs: [],
+        artifacts: {
+          body: {
+            descriptor: {
+              path: 'mesh.bin',
+              mediaType: 'application/x-forgeax-mesh',
+              assetCodec: { name: 'mesh-binary', version: '4' },
+            },
+            bytes: new Uint8Array([3, 0, 0]),
+          },
+        },
+      } as never,
+      emptyCtx,
+    );
+    expect(output).toMatchObject({
+      ok: false,
+      error: { sourceKey: 'mesh-guid', recovery: expect.stringContaining('re-cook') },
+    });
+  });
+});
+
+describe('sceneLoader', () => {
+  it('parses a scene payload into a SceneAsset', () => {
+    const out = sceneLoader.load(
+      { entities: [{ localId: 0, components: {} }] },
+      undefined,
+      emptyCtx,
+    );
+    expect((out as { kind?: string }).kind).toBe('scene');
+  });
+
+  it('returns undefined for a malformed scene payload', () => {
+    expect(sceneLoader.load({ entities: 'bad' }, undefined, emptyCtx)).toBeUndefined();
+  });
+
+  it('routes an out-of-bounds ref error inline as { ok:false, error }', () => {
+    const out = sceneLoader.load(
+      { entities: [{ localId: 0, components: { MeshFilter: { assetHandle: 9 } } }] },
+      ['only-one-guid'],
+      emptyCtx,
+    );
+    expect(out).toMatchObject({ ok: false });
+  });
+});
+
+describe('materialLoader', () => {
+  it('builds a material from passes + values', () => {
+    const out = materialLoader.load(
+      {
+        passes: [{ name: 'main', program: { module: 'forgeax::standard' } }],
+        values: { roughness: 0.5 },
+      },
+      undefined,
+      emptyCtx,
+    );
+    expect((out as { kind?: string }).kind).toBe('material');
+  });
+
+  it('preserves the authored parameter schema and color space', () => {
+    const parameters = [
+      { name: 'tint', type: 'color', colorSpace: 'linear' },
+      { name: 'flowTexture', type: 'texture' },
+    ] as const;
+    const out = materialLoader.load(
+      {
+        passes: [{ name: 'particle-billboard', program: { module: 'sample::flow' } }],
+        parameters,
+        values: { tint: [0.2, 0.6, 1, 1] },
+        colorSpace: 'linear',
+      },
+      undefined,
+      emptyCtx,
+    ) as MaterialAsset;
+
+    expect(out.parameters).toEqual(parameters);
+    expect(out.colorSpace).toBe('linear');
+  });
+
+  it('resolves a numeric parent ref-index to a parentGuid string', () => {
+    const out = materialLoader.load(
+      { passes: [{ name: 'main', program: { module: 'x' } }], parent: 1 },
+      ['g0', 'g1'],
+      emptyCtx,
+    ) as { parentGuid?: string };
+    expect(out.parentGuid).toBe('g1');
+  });
+
+  it('preserves an authored parent GUID without requiring a refs index', () => {
+    const out = materialLoader.load(
+      { values: { baseColor: [1, 0, 0, 1] }, parent: '01935b00-0000-7000-8000-000000000001' },
+      undefined,
+      emptyCtx,
+    ) as { parentGuid?: string };
+    expect(out.parentGuid).toBe('01935b00-0000-7000-8000-000000000001');
+  });
+
+  it('returns undefined when a parent ref-index is out of bounds', () => {
+    expect(
+      materialLoader.load(
+        { passes: [{ name: 'm', program: { module: 'x' } }], parent: 9 },
+        ['g0'],
+        emptyCtx,
+      ),
+    ).toBeUndefined();
+  });
+
+  it('resolves shader-declared texture paramValue ref-indices to GUIDs', () => {
+    const ctx = {
+      getMaterialShaderTextureFieldNames: (id: string) =>
+        id === 'forgeax::pbr' ? new Set(['baseColorTexture']) : undefined,
+    } as unknown as LoadContext;
+    const out = materialLoader.load(
+      {
+        passes: [{ name: 'm', program: { module: 'forgeax::pbr' } }],
+        values: { baseColorTexture: 0, roughness: 5 },
+      },
+      ['tex-guid'],
+      ctx,
+    ) as { values: Record<string, unknown> };
+    expect(out.values.baseColorTexture).toEqual({ texture: 'tex-guid' });
+    expect(out.values.roughness).toBe(5); // non-texture int untouched
+  });
+
+  it('uses authored parameters to distinguish texture refs from zero-valued scalars', () => {
+    const out = materialLoader.load(
+      {
+        passes: [{ name: 'main', program: { module: 'late::standard' } }],
+        parameters: [
+          { name: 'metallic', type: 'f32' },
+          { name: 'baseColorTexture', type: 'texture', optional: true },
+        ],
+        values: { metallic: 0, baseColorTexture: 0 },
+      },
+      ['texture-guid'],
+      emptyCtx,
+    ) as MaterialAsset;
+
+    expect(out.values?.metallic).toBe(0);
+    expect(out.values?.baseColorTexture).toEqual({ texture: 'texture-guid' });
+  });
+
+  it('treats an authored all-scalar parameter schema as authoritative', () => {
+    const out = materialLoader.load(
+      {
+        passes: [{ name: 'main', program: { module: 'late::standard' } }],
+        parameters: [{ name: 'metallic', type: 'f32' }],
+        values: { metallic: 0 },
+      },
+      ['texture-guid'],
+      emptyCtx,
+    ) as MaterialAsset;
+
+    expect(out.values?.metallic).toBe(0);
+  });
+
+  it('resolves nested texture and sampler ref-indices while preserving authored fields', () => {
+    const ctx = {
+      getMaterialShaderTextureFieldNames: () => new Set(['baseColorTexture']),
+    } as unknown as LoadContext;
+    const out = materialLoader.load(
+      {
+        passes: [{ name: 'm', program: { module: 'forgeax::pbr' } }],
+        values: {
+          baseColorTexture: {
+            texture: 0,
+            sampler: 1,
+            coordinates: { set: 1, transform: { scale: [2, 3] } },
+          },
+        },
+      },
+      ['tex-guid', 'sampler-guid'],
+      ctx,
+    ) as { values: Record<string, unknown> };
+    expect(out.values.baseColorTexture).toEqual({
+      texture: 'tex-guid',
+      sampler: 'sampler-guid',
+      coordinates: { set: 1, transform: { scale: [2, 3] } },
+    });
+  });
+
+  it('resolves nested texture values when the shader schema is present but empty', () => {
+    const out = materialLoader.load(
+      {
+        passes: [{ program: { module: 'forgeax::pbr-skin' } }],
+        values: { baseColor: [1, 1, 1, 1], metallic: 0, baseColorTexture: { texture: 0 } },
+      },
+      ['tex-guid'],
+      {
+        ...emptyCtx,
+        getMaterialShaderTextureFieldNames: () => new Set(),
+      },
+    ) as MaterialAsset;
+
+    expect(out.values).toBeDefined();
+    if (!out.values) throw new Error('material loader must preserve material values');
+    expect(out.values.baseColorTexture).toEqual({ texture: 'tex-guid' });
+    expect(out.values.metallic).toBe(0);
+  });
+
+  it('removes identity coordinates from structured texture references', () => {
+    const ctx = {
+      getMaterialShaderTextureFieldNames: () => new Set(['baseColorTexture']),
+    } as unknown as LoadContext;
+    const out = materialLoader.load(
+      {
+        passes: [{ program: { module: 'forgeax::pbr' } }],
+        values: {
+          baseColorTexture: {
+            texture: 0,
+            coordinates: { set: 0, transform: { offset: [0, 0], scale: [1, 1], rotation: 0 } },
+          },
+        },
+      },
+      ['tex-guid'],
+      ctx,
+    ) as MaterialAsset;
+
+    expect(out.values?.baseColorTexture).toEqual({ texture: 'tex-guid' });
+  });
+
+  it('preserves coordinate extension metadata instead of treating it as identity', () => {
+    const ctx = {
+      getMaterialShaderTextureFieldNames: () => new Set(['baseColorTexture']),
+    } as unknown as LoadContext;
+    const out = materialLoader.load(
+      {
+        passes: [{ program: { module: 'forgeax::pbr' } }],
+        values: {
+          baseColorTexture: {
+            texture: 0,
+            coordinates: { transform: { metadata: 'keep' } },
+          },
+        },
+      },
+      ['tex-guid'],
+      ctx,
+    ) as { values: Record<string, unknown> };
+
+    expect(out.values.baseColorTexture).toEqual({
+      texture: 'tex-guid',
+      coordinates: { transform: { metadata: 'keep' } },
+    });
+  });
+
+  it('returns undefined for a passes-less, parent-less material', () => {
+    expect(materialLoader.load({}, undefined, emptyCtx)).toBeUndefined();
+  });
+});
+
+describe('inline ordinary asset matrix', () => {
+  it('loads render-pipeline and tileset descriptors after a JSON roundtrip', () => {
+    const registry = createDefaultLoaderRegistry();
+    expect(registry.get('render-pipeline')).toBeDefined();
+    expect(registry.get('tileset')).toBeDefined();
+
+    const renderPipeline = registry
+      .get('render-pipeline')
+      ?.load({ kind: 'render-pipeline', pipelineId: 'forgeax::urp' }, undefined, emptyCtx);
+    const tileset = registry.get('tileset')?.load(
+      {
+        kind: 'tileset',
+        atlases: ['019d0000-0000-7000-8000-000000000001'],
+        tileWidth: 1,
+        tileHeight: 1,
+        columns: 1,
+        rows: 1,
+        regions: [{ x: 0, y: 0, width: 1, height: 1 }],
+        tiles: [{ regionIndex: 0 }],
+      },
+      undefined,
+      emptyCtx,
+    );
+    expect(renderPipeline).toMatchObject({ kind: 'render-pipeline' });
+    expect(tileset).toMatchObject({ kind: 'tileset' });
+  });
+});
+
+describe('skeletonLoader', () => {
+  it('accepts a valid inverseBindMatrices/jointCount pair', () => {
+    const out = skeletonLoader.load(
+      { inverseBindMatrices: new Array(16).fill(0), jointCount: 1 },
+      undefined,
+      emptyCtx,
+    );
+    expect((out as { kind?: string }).kind).toBe('skeleton');
+  });
+
+  it('rejects a stride mismatch (byteLength !== jointCount*64)', () => {
+    expect(
+      skeletonLoader.load(
+        { inverseBindMatrices: new Array(16).fill(0), jointCount: 2 },
+        undefined,
+        emptyCtx,
+      ),
+    ).toBeUndefined();
+  });
+
+  it('rejects a non-array inverseBindMatrices', () => {
+    expect(
+      skeletonLoader.load({ inverseBindMatrices: 'bad', jointCount: 0 }, undefined, emptyCtx),
+    ).toBeUndefined();
+  });
+});
+
+describe('skinLoader', () => {
+  it('accepts a valid skeletonGuid + jointPaths', () => {
+    const out = skinLoader.load({ skeletonGuid: 'g', jointPaths: ['a', 'b'] }, undefined, emptyCtx);
+    expect((out as { kind?: string }).kind).toBe('skin');
+  });
+
+  it('rejects a missing skeletonGuid or non-string joint path', () => {
+    expect(skinLoader.load({ jointPaths: [] }, undefined, emptyCtx)).toBeUndefined();
+    expect(
+      skinLoader.load({ skeletonGuid: 'g', jointPaths: [1] }, undefined, emptyCtx),
+    ).toBeUndefined();
+  });
+});
+
+describe('animationClipLoader', () => {
+  it('accepts a valid channel with LINEAR sampler arrays', () => {
+    const out = animationClipLoader.load(
+      {
+        duration: 1,
+        channels: [
+          {
+            targetId: 'a95da0ec669189f98273e8f86d8ad9f2',
+            property: 'translation',
+            sampler: { input: [0, 1], output: [0, 0, 0, 1, 1, 1], interpolation: 'LINEAR' },
+          },
+        ],
+      },
+      undefined,
+      emptyCtx,
+    );
+    expect((out as { kind?: string }).kind).toBe('animation-clip');
+  });
+
+  it('rejects legacy, dual, and malformed target wires', () => {
+    const sampler = { input: [0], output: [0, 0, 0], interpolation: 'LINEAR' };
+    const loadChannel = (channel: Record<string, unknown>) =>
+      animationClipLoader.load(
+        { channels: [{ ...channel, property: 'translation', sampler }] },
+        undefined,
+        emptyCtx,
+      );
+
+    expect(loadChannel({ targetPath: ['root'] })).toBeUndefined();
+    expect(
+      loadChannel({
+        targetId: 'a95da0ec669189f98273e8f86d8ad9f2',
+        targetPath: ['root'],
+      }),
+    ).toBeUndefined();
+    expect(loadChannel({ targetId: 'A95DA0EC669159F98273E8F86D8AD9F2' })).toBeUndefined();
+    expect(loadChannel({ targetId: 'a95da0ec669159f98273e8f86d8ad9f' })).toBeUndefined();
+  });
+
+  it('rejects a bad property / missing sampler / bad interpolation', () => {
+    expect(
+      animationClipLoader.load(
+        { channels: [{ targetId: 'a95da0ec669189f98273e8f86d8ad9f2', property: 'bogus' }] },
+        undefined,
+        emptyCtx,
+      ),
+    ).toBeUndefined();
+    expect(
+      animationClipLoader.load(
+        { channels: [{ targetId: 'a95da0ec669189f98273e8f86d8ad9f2', property: 'scale' }] },
+        undefined,
+        emptyCtx,
+      ),
+    ).toBeUndefined();
+    expect(
+      animationClipLoader.load(
+        {
+          channels: [
+            {
+              targetId: 'a95da0ec669189f98273e8f86d8ad9f2',
+              property: 'scale',
+              sampler: { input: [0], output: [0], interpolation: 'CUBIC' },
+            },
+          ],
+        },
+        undefined,
+        emptyCtx,
+      ),
+    ).toBeUndefined();
+  });
+
+  it('rejects a non-array channels payload', () => {
+    expect(animationClipLoader.load({ channels: 'bad' }, undefined, emptyCtx)).toBeUndefined();
+  });
+});
+
+describe('wireDefaultLoaders / createDefaultLoaderRegistry', () => {
+  it('loads a serialised sampler descriptor', () => {
+    expect(
+      samplerLoader.load(
+        { addressModeU: 'repeat', magFilter: 'linear', maxAnisotropy: 16 },
+        undefined,
+        emptyCtx,
+      ),
+    ).toEqual({
+      kind: 'sampler',
+      addressModeU: 'repeat',
+      magFilter: 'linear',
+      maxAnisotropy: 16,
+    });
+    expect(samplerLoader.load({ addressModeU: 'invalid' }, undefined, emptyCtx)).toBeUndefined();
+    expect(samplerLoader.load({ maxAnisotropy: '16' }, undefined, emptyCtx)).toBeUndefined();
+  });
+
+  it('keeps animation graph loader in assets-runtime', () => {
+    expect(animationGraphLoader.kind).toBe('animation-graph');
+  });
+  it('wires the engine default kinds and leaves shader unregistered', () => {
+    const reg = wireDefaultLoaders(new LoaderRegistry());
+    for (const kind of [
+      'mesh',
+      'scene',
+      'sampler',
+      'material',
+      'skeleton',
+      'skin',
+      'animation-clip',
+      'texture',
+      'font',
+      'equirect',
+      'video',
+    ]) {
+      expect(reg.get(kind)).toBeDefined();
+    }
+    expect(reg.get('shader')).toBeUndefined();
+  });
+
+  it('selects an explicit host owner before default seeding', () => {
+    const audio = { kind: 'audio', load: () => undefined } as never;
+    const reg = wireDefaultLoaders(new LoaderRegistry(), [audio]);
+    expect(reg.get('audio')).toBe(audio);
+  });
+
+  it('createDefaultLoaderRegistry returns a fresh pre-wired registry', () => {
+    const reg = createDefaultLoaderRegistry();
+    expect(reg.get('mesh')).toBeDefined();
+    expect(INLINE_PACK_LOADERS.length).toBe(12); // ordinary inline loader matrix
+  });
+});

package/src/__tests__/instantiate-context.unit.test.ts

@@ -0,0 +1,65 @@
+// @forgeax/engine-assets-runtime -- buildSceneChildContext coverage (fix issue
+// #709). The breadcrumb-provenance resolver walks the recursing scene's
+// envelope.refs edges (prod) or falls back to the entity component walk (dev
+// catalog()) to recover the (entityLocalId, component.field) path for a
+// sub-asset GUID. Driven through an AssetRegistry with a mock ShaderRegistry.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+import type { Asset } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry } from '../asset-registry';
+import { buildSceneChildContext } from '../registry/instantiate';
+
+const T709CtxMeshFilter = defineComponent('T709CtxMeshFilter', {
+  assetHandle: 'shared<MeshAsset>',
+});
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(
+    {
+      getMaterialShaderManifest: vi.fn().mockReturnValue(undefined),
+      findMaterialArtifact: vi.fn().mockReturnValue({ ok: false, error: new Error('mock') }),
+      getPipeline: vi.fn().mockReturnValue(undefined),
+      installMaterialArtifact: vi.fn(),
+      inspect: vi.fn().mockReturnValue({ materialShaders: [] }),
+    } as unknown as import('@forgeax/engine-shader').ShaderRegistry,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    new Map([[T709CtxMeshFilter.name, T709CtxMeshFilter]]),
+  );
+}
+
+const SUB_GUID = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+
+function sceneWithMeshRef(): Asset & { kind: 'scene' } {
+  return {
+    kind: 'scene',
+    entities: [{ localId: 7, components: { T709CtxMeshFilter: { assetHandle: SUB_GUID } } }],
+    mounts: [],
+  } as unknown as Asset & { kind: 'scene' };
+}
+
+describe('buildSceneChildContext', () => {
+  it('recovers entityLocalId + component.field via the entity walk fallback', () => {
+    const reg = makeRegistry();
+    const ctx = buildSceneChildContext(reg, sceneWithMeshRef(), SUB_GUID.toLowerCase());
+    expect(ctx?.sceneEntityId).toBe(7);
+    expect(ctx?.componentField).toBe('T709CtxMeshFilter.assetHandle');
+    expect(ctx?.sourceField).toMatchObject({
+      componentName: 'T709CtxMeshFilter',
+      fieldName: 'assetHandle',
+    });
+  });
+
+  it('returns undefined when the sub-asset GUID is not referenced by any entity', () => {
+    const reg = makeRegistry();
+    const ctx = buildSceneChildContext(
+      reg,
+      sceneWithMeshRef(),
+      'ffffffff-ffff-4fff-8fff-ffffffffffff',
+    );
+    expect(ctx).toBeUndefined();
+  });
+});