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

package/src/__tests__/mesh-bin.unit.test.ts

@@ -0,0 +1,152 @@
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import {
+  MESH_BIN_HEADER_V4_BYTES,
+  type MeshBinHeaderV4,
+  writeMeshBinHeader,
+} from '@forgeax/engine-pack';
+import { describe, expect, it } from 'vitest';
+import { unpackMeshBinV4 } from '../loaders/mesh-bin';
+
+function makeArtifact(
+  options: {
+    readonly attributes?: Record<string, Float32Array | Uint16Array>;
+    readonly vertices?: Float32Array;
+    readonly indices?: Uint16Array | Uint32Array;
+    readonly json?: Record<string, unknown>;
+    readonly version?: number;
+    readonly trailingBytes?: number;
+  } = {},
+): Uint8Array {
+  const attributes = options.attributes ?? {
+    position: new Float32Array(3),
+    normal: new Float32Array(3),
+    uv: new Float32Array(2),
+    tangent: new Float32Array(4),
+  };
+  const projection = deriveVertexLayoutProjection(attributes);
+  const vertices = options.vertices ?? new Float32Array(projection.arrayStride / 4);
+  const indices = options.indices;
+  const json = new TextEncoder().encode(
+    JSON.stringify(
+      options.json ?? {
+        submeshes: [{ indexOffset: 0, indexCount: indices?.length ?? 0, materialSlot: 0 }],
+        materialSlots: [{ slotName: 'Default' }],
+      },
+    ),
+  );
+  const indexWidth = indices === undefined ? 0 : indices.BYTES_PER_ELEMENT;
+  const header: MeshBinHeaderV4 = {
+    version: 4,
+    projectionVersion: projection.schemaVersion,
+    mask: projection.mask,
+    digest: projection.digest,
+    stride: projection.arrayStride,
+    vertexCount: vertices.byteLength / projection.arrayStride,
+    vertexBytes: vertices.byteLength,
+    indexCount: indices?.length ?? 0,
+    indexWidth: indexWidth as 0 | 2 | 4,
+    indexBytes: indices?.byteLength ?? 0,
+    jsonBytes: json.byteLength,
+  };
+  const bytes = new Uint8Array(
+    MESH_BIN_HEADER_V4_BYTES + vertices.byteLength + (indices?.byteLength ?? 0) + json.byteLength,
+  );
+  writeMeshBinHeader(header, bytes);
+  if (options.version !== undefined) new DataView(bytes.buffer).setUint32(0, options.version, true);
+  let offset = MESH_BIN_HEADER_V4_BYTES;
+  bytes.set(new Uint8Array(vertices.buffer, vertices.byteOffset, vertices.byteLength), offset);
+  offset += vertices.byteLength;
+  if (indices !== undefined) {
+    bytes.set(new Uint8Array(indices.buffer, indices.byteOffset, indices.byteLength), offset);
+    offset += indices.byteLength;
+  }
+  bytes.set(json, offset);
+  if (options.trailingBytes !== undefined)
+    return new Uint8Array([...bytes, ...new Uint8Array(options.trailingBytes)]);
+  return bytes;
+}
+
+describe('unpackMeshBin v4 happy path', () => {
+  it('decodes vertices, indices, submeshes, and aabb metadata', () => {
+    const vertices = new Float32Array(12);
+    vertices[0] = 1.5;
+    const out = unpackMeshBinV4(
+      makeArtifact({
+        vertices,
+        indices: Uint16Array.of(0, 1, 0),
+        json: {
+          submeshes: [{ indexOffset: 0, indexCount: 3, materialSlot: 0 }],
+          materialSlots: [{ slotName: 'Default' }],
+          aabb: [0, 0, 0, 1, 1, 1],
+        },
+      }),
+      'mesh/happy',
+    );
+    expect(out.ok).toBe(true);
+    if (!out.ok) return;
+    expect(out.value.vertices[0]).toBeCloseTo(1.5);
+    expect(out.value.indices).toBeInstanceOf(Uint16Array);
+    expect(out.value.submeshes).toHaveLength(1);
+    expect(Array.from(out.value.aabb ?? [])).toEqual([0, 0, 0, 1, 1, 1]);
+  });
+
+  it('decodes Uint32 indices and reconstructs projection attributes', () => {
+    const out = unpackMeshBinV4(
+      makeArtifact({
+        indices: Uint32Array.of(0, 0, 0),
+        attributes: {
+          position: new Float32Array(3),
+          normal: new Float32Array(3),
+          uv: new Float32Array(2),
+          tangent: new Float32Array(4),
+          color: new Float32Array(4),
+        },
+      }),
+      'mesh/uint32',
+    );
+    expect(out.ok).toBe(true);
+    if (!out.ok) return;
+    expect(out.value.indices).toBeInstanceOf(Uint32Array);
+    expect(out.value.attributes.color).toBeInstanceOf(Float32Array);
+  });
+
+  it('decodes skin streams from the canonical interleaved projection', () => {
+    const out = unpackMeshBinV4(
+      makeArtifact({
+        attributes: {
+          position: new Float32Array(3),
+          normal: new Float32Array(3),
+          uv: new Float32Array(2),
+          tangent: new Float32Array(4),
+          skinIndex: new Uint16Array(4),
+          skinWeight: new Float32Array(4),
+        },
+      }),
+      'mesh/skin',
+    );
+    expect(out.ok).toBe(true);
+    if (!out.ok) return;
+    expect(out.value.attributes.skinIndex).toBeInstanceOf(Uint16Array);
+    expect(out.value.attributes.skinWeight).toBeInstanceOf(Float32Array);
+  });
+});
+
+describe('unpackMeshBin v4 fail-closed', () => {
+  it('rejects legacy versions and truncated headers', () => {
+    expect(unpackMeshBinV4(makeArtifact({ version: 3 }), 'mesh/legacy').ok).toBe(false);
+    expect(unpackMeshBinV4(new Uint8Array(10), 'mesh/truncated').ok).toBe(false);
+  });
+
+  it('rejects trailing bytes and malformed metadata with recovery facts', () => {
+    const trailing = unpackMeshBinV4(makeArtifact({ trailingBytes: 1 }), 'mesh/trailing');
+    expect(trailing.ok).toBe(false);
+    const malformed = unpackMeshBinV4(
+      makeArtifact({ json: { submeshes: [], materialSlots: [] } }),
+      'mesh/metadata',
+    );
+    expect(malformed.ok).toBe(false);
+    if (malformed.ok) return;
+    expect(malformed.error.sourceKey).toBe('mesh/metadata');
+    expect(malformed.error.recovery).toContain('re-cook');
+  });
+});

package/src/__tests__/mipmap-generator.unit.test.ts

@@ -0,0 +1,202 @@
+// @forgeax/engine-assets-runtime -- mipmap-generator coverage (fix issue #709).
+// numMipLevels formula + per-device pipeline cache + generateMipmaps (async
+// build) + blitMipmapsSync (prewarmed) exercised against an in-memory device
+// stub (no real GPU). Mirrors the runtime-project mipmap tests, but imports the
+// relative `../mipmap-generator` so coverage attributes to src/, not dist/.
+
+import { ok as rhiOk } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  blitMipmapsSync,
+  generateMipmaps,
+  getOrCreateMipmapPipeline,
+  type MipmapBlitDevice,
+  type MipmapShaderModuleFactory,
+  mipmapCacheSize,
+  numMipLevels,
+} from '../mipmap-generator';
+
+let nextId = 0;
+// The device-surface shims are loosely typed (`any` descriptors) so a plain
+// { ok, value } POD satisfies them; the shader factory returns a real Result.
+function ok<T>(value: T) {
+  return { ok: true as const, value };
+}
+
+function makeBlitDevice(renderPasses?: unknown[]): MipmapBlitDevice {
+  const pass = {
+    setPipeline: () => {},
+    setBindGroup: () => {},
+    draw: () => {},
+    end: () => {},
+  };
+  const encoder = {
+    beginRenderPass: (desc: unknown) => {
+      renderPasses?.push(desc);
+      return pass;
+    },
+    finish: () => ok({ tag: `cmdbuf-${nextId++}` }),
+  };
+  return {
+    createSampler: () => ok({ tag: `sampler-${nextId++}` }),
+    createBindGroupLayout: () => ok({ tag: `bgl-${nextId++}` }),
+    createPipelineLayout: () => ok({ tag: `pl-${nextId++}` }),
+    createRenderPipeline: (desc: { fragment?: { targets?: ReadonlyArray<{ format?: string }> } }) =>
+      ok({ tag: `pipeline-${nextId++}`, format: desc.fragment?.targets?.[0]?.format }),
+    createTexture: () => ok({ tag: `tex-${nextId++}` }),
+    createBindGroup: () => ok({ tag: `bg-${nextId++}` }),
+    createTextureView: () => ok({ tag: `view-${nextId++}` }),
+    createCommandEncoder: () => ok(encoder),
+    queue: { submit: () => ok(undefined) },
+  } as unknown as MipmapBlitDevice;
+}
+
+const stubShaderFactory: MipmapShaderModuleFactory = async () =>
+  rhiOk({ tag: `shader-${nextId++}` } as unknown);
+
+describe('numMipLevels', () => {
+  it('256x256 -> 9', () => expect(numMipLevels({ width: 256, height: 256 })).toBe(9));
+  it('1x1 -> 1', () => expect(numMipLevels({ width: 1, height: 1 })).toBe(1));
+  it('0x0 -> 1 (max<=1 guard)', () => expect(numMipLevels({ width: 0, height: 0 })).toBe(1));
+  it('non-square 300x200 -> 9', () => expect(numMipLevels({ width: 300, height: 200 })).toBe(9));
+  it('17x5 -> 5', () => expect(numMipLevels({ width: 17, height: 5 })).toBe(5));
+});
+
+describe('getOrCreateMipmapPipeline + mipmapCacheSize', () => {
+  it('fresh device starts at cache size 0', () => {
+    expect(mipmapCacheSize(makeBlitDevice())).toBe(0);
+  });
+
+  it('same format twice -> cache hit (identical pipeline, size 1)', async () => {
+    const device = makeBlitDevice();
+    const a = await getOrCreateMipmapPipeline(device, 'rgba8unorm', stubShaderFactory);
+    const b = await getOrCreateMipmapPipeline(device, 'rgba8unorm', stubShaderFactory);
+    expect(a.ok && b.ok).toBe(true);
+    if (!a.ok || !b.ok) return;
+    expect(a.value).toBe(b.value);
+    expect(mipmapCacheSize(device)).toBe(1);
+  });
+
+  it('different formats -> separate slots (size 2)', async () => {
+    const device = makeBlitDevice();
+    await getOrCreateMipmapPipeline(device, 'rgba8unorm', stubShaderFactory);
+    await getOrCreateMipmapPipeline(device, 'rgba8unorm-srgb', stubShaderFactory);
+    expect(mipmapCacheSize(device)).toBe(2);
+  });
+
+  it('two devices keep independent caches', async () => {
+    const d1 = makeBlitDevice();
+    const d2 = makeBlitDevice();
+    const r1 = await getOrCreateMipmapPipeline(d1, 'rgba8unorm', stubShaderFactory);
+    const r2 = await getOrCreateMipmapPipeline(d2, 'rgba8unorm', stubShaderFactory);
+    if (!r1.ok || !r2.ok) throw new Error('expected ok');
+    expect(r1.value).not.toBe(r2.value);
+  });
+
+  it('propagates a shader-module factory failure', async () => {
+    const device = makeBlitDevice();
+    const failing: MipmapShaderModuleFactory = async () =>
+      ({ ok: false, error: { code: 'x' } }) as never;
+    const res = await getOrCreateMipmapPipeline(device, 'rgba8unorm', failing);
+    expect(res.ok).toBe(false);
+  });
+});
+
+describe('generateMipmaps (async build path)', () => {
+  it('returns ok immediately when levels <= 1', async () => {
+    const device = makeBlitDevice();
+    const res = await generateMipmaps(
+      device,
+      {},
+      { format: 'rgba8unorm', width: 1, height: 1 },
+      stubShaderFactory,
+    );
+    expect(res.ok).toBe(true);
+    expect(mipmapCacheSize(device)).toBe(0); // never built a pipeline
+  });
+
+  it('builds + blits the full mip chain for a 4x4 texture', async () => {
+    const device = makeBlitDevice();
+    const res = await generateMipmaps(
+      device,
+      { tag: 'tex' },
+      { format: 'rgba8unorm', width: 4, height: 4 },
+      stubShaderFactory,
+    );
+    expect(res.ok).toBe(true);
+    expect(mipmapCacheSize(device)).toBe(1);
+  });
+
+  it('uses the WebGPU GPUColor object shape for clear values', async () => {
+    const renderPasses: unknown[] = [];
+    const device = makeBlitDevice(renderPasses);
+    const res = await generateMipmaps(
+      device,
+      { tag: 'tex' },
+      { format: 'rgba8unorm', width: 4, height: 4 },
+      stubShaderFactory,
+    );
+    expect(res.ok).toBe(true);
+    expect(renderPasses).toHaveLength(2);
+    for (const pass of renderPasses) {
+      const clearValue = (pass as { colorAttachments: Array<{ clearValue: unknown }> })
+        .colorAttachments[0]?.clearValue;
+      expect(clearValue).toEqual({ r: 0, g: 0, b: 0, a: 1 });
+    }
+
+    const syncPasses: unknown[] = [];
+    const syncDevice = makeBlitDevice(syncPasses);
+    const prewarm = await getOrCreateMipmapPipeline(syncDevice, 'rgba8unorm', stubShaderFactory);
+    expect(prewarm.ok).toBe(true);
+    expect(
+      blitMipmapsSync(syncDevice, { tag: 'tex' }, { format: 'rgba8unorm', width: 4, height: 4 }).ok,
+    ).toBe(true);
+    for (const pass of syncPasses) {
+      const clearValue = (pass as { colorAttachments: Array<{ clearValue: unknown }> })
+        .colorAttachments[0]?.clearValue;
+      expect(clearValue).toEqual({ r: 0, g: 0, b: 0, a: 1 });
+    }
+  });
+});
+
+describe('blitMipmapsSync (prewarmed path)', () => {
+  it('returns ok immediately when levels <= 1', () => {
+    const res = blitMipmapsSync(
+      makeBlitDevice(),
+      {},
+      { format: 'rgba8unorm', width: 1, height: 1 },
+    );
+    expect(res.ok).toBe(true);
+  });
+
+  it('errors when the device cache was never prewarmed', () => {
+    const res = blitMipmapsSync(
+      makeBlitDevice(),
+      {},
+      { format: 'rgba8unorm', width: 4, height: 4 },
+    );
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.error.code).toBe('rhi-not-available');
+  });
+
+  it('errors when the requested format was not prewarmed', async () => {
+    const device = makeBlitDevice();
+    await getOrCreateMipmapPipeline(device, 'rgba8unorm', stubShaderFactory);
+    const res = blitMipmapsSync(device, {}, { format: 'bgra8unorm', width: 4, height: 4 });
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.error.code).toBe('rhi-not-available');
+  });
+
+  it('blits the full chain once the format is prewarmed', async () => {
+    const device = makeBlitDevice();
+    await getOrCreateMipmapPipeline(device, 'rgba8unorm', stubShaderFactory);
+    const res = blitMipmapsSync(
+      device,
+      { tag: 'tex' },
+      { format: 'rgba8unorm', width: 8, height: 8 },
+    );
+    expect(res.ok).toBe(true);
+  });
+});

package/src/__tests__/pack-artifact-transcode-model-owner.test.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import type { TranscodeModel } from '@forgeax/engine-codec';
+import type { Loader } from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { textureLoader } from '../loaders/pack-artifact.js';
+
+const packArtifactSource = readFileSync(
+  new URL('../loaders/pack-artifact.ts', import.meta.url),
+  'utf8',
+);
+
+describe('assets-runtime transcode model owner', () => {
+  it('keeps the public texture loader and model vocabulary intact', () => {
+    expectTypeOf<typeof textureLoader>().toEqualTypeOf<Loader>();
+    expectTypeOf<TranscodeModel>().toEqualTypeOf<'etc1s' | 'uastc-ldr' | 'uastc-hdr'>();
+
+    const models: readonly TranscodeModel[] = ['etc1s', 'uastc-ldr', 'uastc-hdr'];
+    expect(models).toEqual(['etc1s', 'uastc-ldr', 'uastc-hdr']);
+  });
+
+  it('derives the private model view from the codec owner', () => {
+    expect(packArtifactSource).toContain('import type { CodecError, TranscodeModel }');
+    expect(packArtifactSource).toContain(
+      'function transcodeModel(profile: string): TranscodeModel | undefined',
+    );
+    expect(packArtifactSource).not.toContain(
+      "function transcodeModel(profile: string): 'etc1s' | 'uastc-ldr' | 'uastc-hdr' | undefined",
+    );
+  });
+});

package/src/__tests__/pack-basis-load.integration.test.ts

@@ -0,0 +1,168 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import type { LoadContext, TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+  BasisEncoderModule,
+  BasisModuleFactory,
+} from '../../../codec/src/wasm/basis-types.js';
+import type { CodecContextFailure } from '../loaders/pack-artifact.js';
+import { PACK_ARTIFACT_LOADERS, textureLoader } from '../loaders/pack-artifact.js';
+
+const TRANSCODER_GLUE = new URL('../../../codec/pkg/basis_transcoder.mjs', import.meta.url);
+const ENCODER_GLUE = new URL('../../../codec/pkg/encode/basis_encoder.mjs', import.meta.url);
+const pkgBuilt =
+  existsSync(fileURLToPath(TRANSCODER_GLUE)) && existsSync(fileURLToPath(ENCODER_GLUE));
+
+async function loadEncoder(): Promise<BasisEncoderModule> {
+  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();
+  return mod;
+}
+
+async function makeBasis(): Promise<Uint8Array> {
+  const mod = await loadEncoder();
+  const encoder = new mod.BasisEncoder();
+  try {
+    encoder.setSliceSourceImage(0, new Uint8Array(4 * 4 * 4).fill(127), 4, 4, 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');
+    return bytes.slice(0, length);
+  } finally {
+    encoder.delete();
+  }
+}
+
+const context: LoadContext = {
+  fetchBinary: async () => ({ ok: false as const, error: new Error('not used') }),
+  resolveRef: async () => ({ ok: false as const, error: new Error('not used') }),
+  transcodeCaps: { bc: false, etc2: false, astc: false },
+  device: undefined,
+};
+
+describe.skipIf(!pkgBuilt)('Pack runtime raw Basis loader', () => {
+  it('keeps context failure code and detail correlated as a closed union', () => {
+    type ExpectedContextFailure =
+      | {
+          readonly code: 'basis-profile-unsupported';
+          readonly detail: { readonly profile: string };
+        }
+      | {
+          readonly code: 'ktx2-color-space-mismatch';
+          readonly detail: {
+            readonly authoredColorSpace: 'srgb' | 'linear';
+            readonly dfdColorSpace: 'srgb' | 'linear' | 'unknown';
+          };
+        };
+
+    expectTypeOf<CodecContextFailure>().toEqualTypeOf<ExpectedContextFailure>();
+  });
+
+  it('transcodes a raw Basis artifact using its explicit container identity', async () => {
+    const bytes = await makeBasis();
+    const loadPack = textureLoader.loadPack;
+    if (loadPack === undefined) throw new Error('textureLoader.loadPack must be registered');
+
+    const result = (await loadPack(
+      {
+        guid: '019f0000-0000-7000-8000-000000000304',
+        kind: 'texture',
+        payload: { width: 4, height: 4, colorSpace: 'linear' },
+        refs: [],
+        artifacts: {
+          body: {
+            bytes,
+            descriptor: {
+              path: 'texture.basis',
+              mediaType: 'image/basis',
+              assetCodec: { name: 'basis', container: 'basis', profile: 'uastc-ldr' },
+            },
+          },
+        },
+      },
+      context,
+    )) as
+      | { readonly ok: true; readonly value: TextureAsset }
+      | { readonly ok: false; readonly error: unknown };
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).toMatchObject({
+      kind: 'texture',
+      width: 4,
+      height: 4,
+      format: 'rgba8unorm',
+      colorSpace: 'linear',
+      mipmap: false,
+      mipLevelCount: 1,
+    });
+    expect(result.value.data.byteLength).toBeGreaterThan(0);
+  });
+
+  it('preserves codec context for a malformed KTX2 Pack artifact', async () => {
+    const loadPack = textureLoader.loadPack;
+    if (loadPack === undefined) throw new Error('textureLoader.loadPack must be registered');
+
+    const result = (await loadPack(
+      {
+        guid: '019f0000-0000-7000-8000-000000000305',
+        kind: 'texture',
+        payload: { width: 4, height: 4, colorSpace: 'srgb' },
+        refs: [],
+        artifacts: {
+          body: {
+            bytes: new Uint8Array([0, 1, 2, 3]),
+            descriptor: {
+              path: 'texture.ktx2',
+              mediaType: 'image/ktx2',
+              assetCodec: { name: 'basis', container: 'ktx2', profile: 'uastc-ldr' },
+            },
+          },
+        },
+      },
+      context,
+    )) as
+      | { readonly ok: true; readonly value: TextureAsset }
+      | {
+          readonly ok: false;
+          readonly error: {
+            readonly code: string;
+            readonly hint: string;
+            readonly detail?: unknown;
+          };
+        };
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('asset-parse-failed');
+    expect(result.error.hint).toContain('KTX2');
+    expect(result.error.detail).toMatchObject({
+      sourcePath: '019f0000-0000-7000-8000-000000000305',
+      container: 'ktx2',
+      profile: 'uastc-ldr',
+      codecCode: 'ktx2-parse-failed',
+      capabilities: { bc: false, etc2: false, astc: false },
+    });
+    expect(result.error.detail).toHaveProperty('codecDetail.reason');
+  });
+});
+
+describe('Pack artifact loader matrix', () => {
+  it('registers every artifact-backed ordinary asset kind', () => {
+    expect(PACK_ARTIFACT_LOADERS.map((loader) => loader.kind).sort()).toEqual(
+      ['equirect', 'font', 'render-pipeline', 'texture', 'tileset'].sort(),
+    );
+  });
+});