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

package/src/__tests__/image-importer-conversion-failure.unit.test.ts

@@ -0,0 +1,297 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { basisEncode } from '@forgeax/engine-codec/encode';
+import { ImporterRegistry, type RunImportMeta, runImport } from '@forgeax/engine-import';
+import type { ImportContext } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  BasisEncoderModule,
+  BasisModuleFactory,
+} from '../../../codec/src/wasm/basis-types.js';
+import { imageImporter } from '../image-importer.js';
+import { makeCorruptPng, makeJpg, makePng } from './make-fixture.js';
+
+const GUID = '019f0000-0000-7000-8000-000000000301';
+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));
+
+function registry(): ImporterRegistry {
+  const result = new ImporterRegistry();
+  result.register(imageImporter);
+  return result;
+}
+
+function meta(
+  source = 'retry.png',
+  importSettings: Readonly<Record<string, unknown>> = {
+    colorSpace: 'srgb',
+    mipmap: 'none',
+  },
+  sourceOverrides: RunImportMeta['sourceOverrides'] = undefined,
+  kind: 'texture' | 'equirect' = 'texture',
+): RunImportMeta {
+  return {
+    importer: 'image',
+    source,
+    importSettings,
+    subAssets: [{ guid: GUID, sourceIndex: 0, sourceKey: 'image:texture', kind }],
+    ...(sourceOverrides === undefined ? {} : { sourceOverrides }),
+  };
+}
+
+function source(state: { bytes: Uint8Array; reads: number }): ImportContext['readSource'] {
+  return vi.fn(async () => {
+    state.reads += 1;
+    return { ok: true as const, value: state.bytes };
+  });
+}
+
+function expectConversionFailure(
+  result: Awaited<ReturnType<typeof runImport>>,
+  diagnosticCode: string,
+): void {
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  expect(result.error.code).toBe('source-validation-failed');
+  expect(result.error.detail).toMatchObject({
+    diagnostics: [
+      expect.objectContaining({
+        code: diagnosticCode,
+        rule: expect.stringMatching(/^image-conversion-/),
+        severity: 'error',
+      }),
+    ],
+  });
+  expect(result).not.toHaveProperty('value');
+}
+
+async function loadEncoder(): Promise<BasisEncoderModule> {
+  const factory = (
+    (await import(/* @vite-ignore */ ENCODER_GLUE.href)) as {
+      default: BasisModuleFactory<BasisEncoderModule>;
+    }
+  ).default;
+  const module = await factory({
+    locateFile: () => new URL('../../../codec/pkg/encode/basis_encoder.wasm', import.meta.url).href,
+  });
+  module.initializeBasis();
+  return module;
+}
+
+async function makeRawBasis(hdr = false): Promise<Uint8Array> {
+  const module = await loadEncoder();
+  const encoder = new module.BasisEncoder();
+  try {
+    const width = 4;
+    const height = 4;
+    if (hdr) {
+      encoder.setSliceSourceImageHDR(
+        0,
+        new Uint8Array(width * height * 8),
+        width,
+        height,
+        0,
+        false,
+        1,
+      );
+      encoder.setFormatMode(module.basis_tex_format.cUASTC_HDR_4x4.value);
+    } else {
+      encoder.setSliceSourceImage(
+        0,
+        new Uint8Array(width * height * 4).fill(127),
+        width,
+        height,
+        0,
+      );
+      encoder.setFormatMode(module.basis_tex_format.cUASTC_LDR_4x4.value);
+    }
+    encoder.setCreateKTX2File(false);
+    encoder.setMipGen(false);
+    const output = new Uint8Array(1 << 20);
+    const length = encoder.encode(output);
+    if (length <= 0) throw new Error('raw Basis encode failed');
+    return output.slice(0, length);
+  } finally {
+    encoder.delete();
+  }
+}
+
+async function makeKtx2(): Promise<Uint8Array> {
+  const result = await basisEncode(new Uint8Array(4 * 4 * 4).fill(127), {
+    mode: 'uastc-ldr',
+    width: 4,
+    height: 4,
+    srgb: false,
+    perceptual: false,
+    uastcSupercompression: true,
+    mipGen: false,
+  });
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+describe('image importer conversion failure through the public runner', () => {
+  it.each([
+    { source: 'corrupt.png', bytes: makeCorruptPng(), code: 'image-conversion-decode-ldr' },
+    {
+      source: 'corrupt.jpeg',
+      bytes: makeJpg(2, 2, [10, 20, 30, 255]).slice(0, 8),
+      code: 'image-conversion-decode-ldr',
+    },
+    {
+      source: 'corrupt.hdr',
+      bytes: new Uint8Array([0, 0, 0, 0]),
+      code: 'image-conversion-decode-hdr',
+    },
+    {
+      source: 'corrupt.ktx2',
+      bytes: new Uint8Array([0, 0, 0, 0]),
+      code: 'image-conversion-inspect-ktx2-parse',
+    },
+  ])('returns stable source-validation-failed diagnostics for corrupt $source', async (input) => {
+    const state = { bytes: input.bytes, reads: 0 };
+    const result = await runImport(
+      meta(
+        input.source,
+        input.source.endsWith('.hdr') ? { colorSpace: 'linear' } : undefined,
+        undefined,
+        input.source.endsWith('.hdr') ? 'equirect' : 'texture',
+      ),
+      registry(),
+      {
+        readSource: source(state),
+      },
+    );
+
+    expectConversionFailure(result, input.code);
+    expect(state.reads).toBe(2);
+  });
+
+  it.skipIf(!pkgBuilt)('returns a stable diagnostic for corrupt raw Basis bytes', async () => {
+    const state = { bytes: new Uint8Array([0, 0, 0, 0]), reads: 0 };
+    const result = await runImport(meta('corrupt.basis', { colorSpace: 'linear' }), registry(), {
+      readSource: source(state),
+    });
+
+    expectConversionFailure(result, 'image-conversion-inspect-basis-inspection-failed');
+    expect(state.reads).toBe(2);
+  });
+
+  it('retries corrected bytes through the same registry and preserves the GUID artifact', async () => {
+    const state = { bytes: makeCorruptPng(), reads: 0 };
+    const importerRegistry = registry();
+    const input = meta();
+
+    const readSource = source(state);
+    const rejected = await runImport(input, importerRegistry, { readSource });
+    expectConversionFailure(rejected, 'image-conversion-decode-ldr');
+
+    state.bytes = makePng(1, 1, [1, 2, 3, 255]);
+    const repaired = await runImport(input, importerRegistry, { readSource });
+
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok || 'skipped' in repaired.value) return;
+    expect(repaired.value.pack.assets).toHaveLength(1);
+    expect(repaired.value.pack.assets[0]).toMatchObject({
+      guid: GUID,
+      artifacts: { body: { mediaType: 'application/x-forgeax-rgba8' } },
+    });
+    expect(repaired.value.pack).not.toHaveProperty('diagnostics');
+    expect(state.reads).toBe(4);
+
+    const repeated = await runImport(input, importerRegistry, { readSource });
+    expect(repeated).toEqual(repaired);
+    expect(state.reads).toBe(6);
+  });
+
+  it.skipIf(!pkgBuilt)('repairs raw Basis color-space settings in the same registry', async () => {
+    const state = { bytes: await makeRawBasis(), reads: 0 };
+    const importerRegistry = registry();
+    let settings: Readonly<Record<string, unknown>> = {};
+    const readSource = source(state);
+
+    const rejected = await runImport(meta('texture.basis', settings), importerRegistry, {
+      readSource,
+    });
+    expectConversionFailure(rejected, 'image-conversion-inspect-basis-color-space-invalid');
+
+    settings = { colorSpace: 'linear' };
+    const repaired = await runImport(meta('texture.basis', settings), importerRegistry, {
+      readSource,
+    });
+
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok || 'skipped' in repaired.value) return;
+    expect(repaired.value.pack.assets[0]).toMatchObject({
+      guid: GUID,
+      payload: { colorSpace: 'linear', width: 4, height: 4 },
+      artifacts: {
+        body: {
+          mediaType: 'application/x-forgeax-basis',
+          assetCodec: { name: 'basis', container: 'basis', profile: 'uastc-ldr' },
+        },
+      },
+    });
+  });
+
+  it.skipIf(!pkgBuilt)('rejects an unsupported raw Basis profile before publication', async () => {
+    const state = { bytes: await makeRawBasis(true), reads: 0 };
+    const result = await runImport(
+      meta('hdr-profile.basis', { colorSpace: 'linear' }),
+      registry(),
+      {
+        readSource: source(state),
+      },
+    );
+
+    expectConversionFailure(result, 'image-conversion-inspect-basis-profile-unsupported');
+  });
+
+  it.skipIf(!pkgBuilt)('repairs KTX2 color-space provenance in the same registry', async () => {
+    const state = { bytes: await makeKtx2(), reads: 0 };
+    const importerRegistry = registry();
+    const readSource = source(state);
+    const rejected = await runImport(
+      meta('texture.ktx2', { colorSpace: 'srgb' }, { 'image:texture': { colorSpace: 'srgb' } }),
+      importerRegistry,
+      { readSource },
+    );
+
+    expectConversionFailure(rejected, 'image-conversion-inspect-ktx2-color-space-conflict');
+
+    const repaired = await runImport(
+      meta('texture.ktx2', { colorSpace: 'linear' }, { 'image:texture': { colorSpace: 'linear' } }),
+      importerRegistry,
+      { readSource },
+    );
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok || 'skipped' in repaired.value) return;
+    expect(repaired.value.pack.assets[0]).toMatchObject({
+      guid: GUID,
+      payload: { colorSpace: 'linear', width: 4, height: 4, mipmap: false },
+      artifacts: {
+        body: {
+          mediaType: 'image/ktx2',
+          assetCodec: { name: 'basis', container: 'ktx2', profile: 'uastc-ldr' },
+        },
+      },
+    });
+  });
+
+  it.skipIf(!pkgBuilt)(
+    'returns a structured encode refusal before Pack publication',
+    async () => {
+      const oversized = makePng(4097, 4096, [1, 2, 3, 255]);
+      const result = await runImport(
+        meta('oversized.png', { colorSpace: 'linear', compressionMode: 'uastc' }),
+        registry(),
+        { readSource: source({ bytes: oversized, reads: 0 }) },
+      );
+
+      expectConversionFailure(result, 'image-conversion-encode-ktx2-source-too-large');
+    },
+    15_000,
+  );
+});

package/src/__tests__/image-importer-hdr-equirect.test.ts

@@ -0,0 +1,218 @@
+// image-importer-hdr-equirect.test.ts
+// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M1 / w1.
+//
+// TDD red->green: locks the .hdr arm of imageImporter producing an
+// EquirectAsset POD (kind:'equirect', rgba16float 2D) for an 'equirect'
+// sub-asset, instead of the prior TextureAsset (kind:'texture') for a
+// 'texture' sub-asset. research F-10 + plan-strategy D-9; orchestrator
+// adjudication: equirect produces a build-time .bin (2D rgba16float image).
+
+import type {
+  EquirectAsset,
+  ImportContext,
+  ImportedAsset,
+  ImportSubAsset,
+} from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { imageImporter } from '../image-importer.js';
+
+const HDR_GUID = '019e3969-1d43-7610-8810-e80dbd491d91';
+
+function unwrap(result: {
+  readonly ok: boolean;
+  readonly value?: { readonly assets: readonly ImportedAsset[] };
+}): readonly ImportedAsset[] {
+  return result.ok && result.value !== undefined ? result.value.assets : [];
+}
+
+function makeHdrFixture(width: number, height: number): Uint8Array {
+  const header = `#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y ${height} +X ${width}\n`;
+  const encoder = new TextEncoder();
+  const headerBytes = encoder.encode(header);
+
+  const hi = (width >> 8) & 0xff;
+  const lo = width & 0xff;
+  const prefix = new Uint8Array([0x02, 0x02, hi, lo]);
+
+  const chRun = new Uint8Array([128 + width, 128]);
+  const scanlineBytes = 4 + 4 * 2;
+  const pixelBytes = new Uint8Array(height * scanlineBytes);
+
+  for (let y = 0; y < height; y++) {
+    let off = y * scanlineBytes;
+    pixelBytes.set(prefix, off);
+    off += 4;
+    pixelBytes.set(chRun, off);
+    off += 2;
+    pixelBytes.set(chRun, off);
+    off += 2;
+    pixelBytes.set(chRun, off);
+    off += 2;
+    pixelBytes.set(chRun, off);
+  }
+
+  const total = new Uint8Array(headerBytes.length + pixelBytes.length);
+  total.set(headerBytes);
+  total.set(pixelBytes, headerBytes.length);
+  return total;
+}
+
+function makeHdrCtx(
+  source: string,
+  bytes: Uint8Array,
+  subAssets: readonly ImportSubAsset[],
+  importSettings: Readonly<Record<string, unknown>> = {},
+): ImportContext {
+  return {
+    source,
+    readSource: async () => ({ ok: true, value: bytes }),
+    readSibling: async () => ({ ok: true, value: new Uint8Array() }),
+    decodeImage: async () => {
+      throw new Error('decodeImage not used by imageImporter');
+    },
+    subAssets,
+    importSettings,
+  };
+}
+
+describe('imageImporter HDR arm produces EquirectAsset (w1)', () => {
+  it('(a) .hdr + equirect sub-asset -> EquirectAsset POD kind:"equirect" + rgba16float', async () => {
+    const width = 8;
+    const height = 4;
+    const ctx = makeHdrCtx('env.hdr', makeHdrFixture(width, height), [
+      { guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' },
+    ]);
+
+    const produced = unwrap(await imageImporter.import(ctx));
+    expect(produced.length).toBe(1);
+    const asset = produced[0];
+    expect(asset?.guid).toBe(HDR_GUID);
+    expect(asset?.kind).toBe('equirect');
+
+    const payload = asset?.payload as EquirectAsset;
+    expect(payload.kind).toBe('equirect');
+    expect(payload.format).toBe('rgba16float');
+    expect(payload.colorSpace).toBe('linear');
+    expect(payload.width).toBe(width);
+    expect(payload.height).toBe(height);
+  });
+
+  it('(b) byte length is width * height * 4 * 2 (rgba16f = 8 bytes/pixel)', async () => {
+    const width = 8;
+    const height = 4;
+    const ctx = makeHdrCtx('env.hdr', makeHdrFixture(width, height), [
+      { guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' },
+    ]);
+
+    const produced = unwrap(await imageImporter.import(ctx));
+    const payload = (produced[0] as { payload: EquirectAsset })?.payload;
+    expect(payload.data.length).toBe(width * height * 4 * 2);
+  });
+
+  it('(c) a texture sub-asset with .hdr source is NOT folded (only equirect is)', async () => {
+    const ctx = makeHdrCtx('env.hdr', makeHdrFixture(8, 4), [
+      { guid: HDR_GUID, sourceIndex: 0, kind: 'texture' },
+    ]);
+    const produced = unwrap(await imageImporter.import(ctx));
+    expect(produced.length).toBe(0);
+  });
+
+  it('(d) .hdr extension upper-case is still recognized via toLowerCase()', async () => {
+    const ctx = makeHdrCtx('ENV.HDR', makeHdrFixture(8, 2), [
+      { guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' },
+    ]);
+    const produced = unwrap(await imageImporter.import(ctx));
+    expect(produced.length).toBe(1);
+    expect(produced[0]?.kind).toBe('equirect');
+  });
+
+  it('(e) returns a structured validation error for a corrupt .hdr source (invalid RGBE header)', async () => {
+    const corrupt = new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x00, 0x00]);
+    const ctx = makeHdrCtx('bad.hdr', corrupt, [
+      { guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' },
+    ]);
+    const result = await imageImporter.import(ctx);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('source-validation-failed');
+    expect(result.error.detail).toMatchObject({
+      diagnostics: [expect.objectContaining({ code: 'image-conversion-decode-hdr' })],
+    });
+  });
+});
+
+// KTX2 magic identifier (first 12 bytes of every KTX 2.0 container). Used to
+// assert the HDR encode arm produced a real UASTC-HDR KTX2, not raw f16.
+const KTX2_IDENTIFIER = new Uint8Array([
+  0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+
+describe('imageImporter HDR equirect is never block-compressed (feat-20260707 fix)', () => {
+  // An equirect is ALWAYS an IBL / skybox source: it drives equirect-to-cube /
+  // irradiance / prefilter RENDER passes, and a BC6H (block-compressed) texture
+  // is sample-only, never color-renderable. So the HDR arm never encodes an
+  // equirect sub-asset -- it always ships raw rgba16float, regardless of the
+  // requested compressionMode ('auto' / 'uastc' / 'none' all yield rgba16float).
+  it("compressionMode:'auto' HDR equirect -> raw rgba16float (never a KTX2)", async () => {
+    const width = 8;
+    const height = 4;
+    const ctx = makeHdrCtx(
+      'env.hdr',
+      makeHdrFixture(width, height),
+      [{ guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' }],
+      { colorSpace: 'linear', mipmap: 'none', compressionMode: 'auto' },
+    );
+
+    const produced = unwrap(await imageImporter.import(ctx));
+    const payload = (produced[0] as { payload: EquirectAsset })?.payload;
+    // Raw rgba16float byte count (w*h*8) and NOT a KTX2 container.
+    expect(payload.data.length).toBe(width * height * 4 * 2);
+    expect(Array.from(payload.data.subarray(0, 12))).not.toEqual(Array.from(KTX2_IDENTIFIER));
+    expect(payload.format).toBe('rgba16float');
+  });
+
+  it("explicit 'uastc' HDR equirect -> raw rgba16float (never a KTX2)", async () => {
+    const width = 8;
+    const height = 4;
+    const ctx = makeHdrCtx(
+      'env.hdr',
+      makeHdrFixture(width, height),
+      [{ guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' }],
+      { colorSpace: 'linear', mipmap: 'none', compressionMode: 'uastc' },
+    );
+    const produced = unwrap(await imageImporter.import(ctx));
+    const payload = (produced[0] as { payload: EquirectAsset })?.payload;
+    expect(payload.data.length).toBe(width * height * 4 * 2);
+    expect(Array.from(payload.data.subarray(0, 12))).not.toEqual(Array.from(KTX2_IDENTIFIER));
+  });
+
+  it("compressionMode:'none' HDR equirect -> raw rgba16float .bin path", async () => {
+    const width = 8;
+    const height = 4;
+    const ctx = makeHdrCtx(
+      'env.hdr',
+      makeHdrFixture(width, height),
+      [{ guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' }],
+      { colorSpace: 'linear', mipmap: 'none', compressionMode: 'none' },
+    );
+    const produced = unwrap(await imageImporter.import(ctx));
+    const payload = (produced[0] as { payload: EquirectAsset })?.payload;
+    expect(payload.data.length).toBe(width * height * 4 * 2);
+    expect(Array.from(payload.data.subarray(0, 12))).not.toEqual(Array.from(KTX2_IDENTIFIER));
+  });
+
+  it('AC-02: HDR equirect import is deterministic (double import byte-identical)', async () => {
+    const mk = () =>
+      makeHdrCtx(
+        'env.hdr',
+        makeHdrFixture(8, 4),
+        [{ guid: HDR_GUID, sourceIndex: 0, kind: 'equirect' }],
+        { colorSpace: 'linear', mipmap: 'none', compressionMode: 'auto' },
+      );
+    const a = (unwrap(await imageImporter.import(mk()))[0] as { payload: EquirectAsset }).payload
+      .data;
+    const b = (unwrap(await imageImporter.import(mk()))[0] as { payload: EquirectAsset }).payload
+      .data;
+    expect(Array.from(a)).toEqual(Array.from(b));
+  });
+});