@forgeax/engine-image 0.1.2

package/src/__tests__/ktx2-basis-importer.unit.test.ts

@@ -0,0 +1,126 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { basisEncode } from '@forgeax/engine-codec/encode';
+import { ImportError } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type {
+  BasisEncoderModule,
+  BasisModuleFactory,
+} from '../../../codec/src/wasm/basis-types.js';
+import { imageImporter } from '../image-importer.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));
+
+const GUID = '019f0000-0000-7000-8000-000000000301';
+
+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;
+}
+
+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();
+  }
+}
+
+function context(source: string, bytes: Uint8Array) {
+  return {
+    source,
+    readSource: async () => ({ ok: true as const, value: bytes }),
+    readSibling: async () => ({
+      ok: false as const,
+      error: new ImportError({
+        code: 'source-read-failed',
+        expected: 'no sibling source',
+        hint: 'test source has no sibling',
+        detail: { source, reason: 'no sibling' },
+      }),
+    }),
+    decodeImage: async () => {
+      throw new Error('precompressed source must not call decodeImage');
+    },
+    subAssets: [{ guid: GUID, sourceIndex: 0, sourceKey: 'main', kind: 'texture' as const }],
+    importSettings: { colorSpace: 'linear' as const },
+    sourceOverrides: { main: { colorSpace: 'linear' as const } },
+  };
+}
+
+describe.skipIf(!pkgBuilt)('KTX2/Basis source importer', () => {
+  it('rejects an unsupported precompressed extension before image decoding', async () => {
+    await expect(imageImporter.import(context('fixture.dds', new Uint8Array()))).rejects.toThrow(
+      'unsupported source extension',
+    );
+  });
+
+  it('imports a KTX2 source without decoding it as PNG/JPEG and preserves codec facts', async () => {
+    const bytes = await makeKtx2();
+    const result = await imageImporter.import(context('fixture.ktx2', bytes));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.assets[0]?.payload).toMatchObject({
+      kind: 'texture',
+      width: 4,
+      height: 4,
+      format: 'rgba8unorm',
+      colorSpace: 'linear',
+      mipmap: false,
+    });
+    expect(result.value.assets[0]?.artifacts.body?.assetCodec).toMatchObject({
+      name: 'basis',
+      container: 'ktx2',
+      profile: 'uastc-ldr',
+    });
+    expect(result.value.assets[0]?.artifacts.body?.bytes).toEqual(bytes);
+  });
+
+  it('imports raw Basis with authored Meta color-space provenance', async () => {
+    const bytes = await makeBasis();
+    const result = await imageImporter.import(context('fixture.basis', bytes));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.assets[0]?.payload.colorSpace).toBe('linear');
+    expect(result.value.assets[0]?.artifacts.body?.assetCodec).toMatchObject({
+      name: 'basis',
+      container: 'basis',
+      profile: 'uastc-ldr',
+    });
+  });
+});

package/src/__tests__/ktx2-encode-mode-owner.test-d.ts

@@ -0,0 +1,70 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import type { BasisEncodeMode } from '@forgeax/engine-codec/encode';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+  BasisEncodeParams,
+  CompressionMode,
+  EncodeTextureResult,
+  ResolvedEncodeMode,
+} from '../ktx2-encode.js';
+
+type ExpectedCompressionMode = 'auto' | 'etc1s' | 'uastc' | 'none';
+type ExpectedResolvedEncodeMode = 'etc1s' | 'uastc' | 'uastc-hdr' | 'none';
+type EncodedMode = Extract<EncodeTextureResult, { readonly ok: true }>['value']['mode'];
+type FailedMode = Extract<EncodeTextureResult, { readonly ok: false }>['error']['mode'];
+
+const encodeSource = readFileSync(new URL('../ktx2-encode.ts', import.meta.url), 'utf8');
+
+describe('image KTX2 encode mode owner', () => {
+  it('keeps both exact image-side vocabularies and their public projections', () => {
+    expectTypeOf<CompressionMode>().toEqualTypeOf<ExpectedCompressionMode>();
+    expectTypeOf<ExpectedCompressionMode>().toEqualTypeOf<CompressionMode>();
+    expectTypeOf<ResolvedEncodeMode>().toEqualTypeOf<ExpectedResolvedEncodeMode>();
+    expectTypeOf<ExpectedResolvedEncodeMode>().toEqualTypeOf<ResolvedEncodeMode>();
+
+    const acceptsCompressionMode = (mode: CompressionMode): CompressionMode => mode;
+    acceptsCompressionMode('auto');
+    acceptsCompressionMode('etc1s');
+    acceptsCompressionMode('uastc');
+    acceptsCompressionMode('none');
+    // @ts-expect-error Delivery modes are not sidecar control-plane values.
+    acceptsCompressionMode('uastc-hdr');
+
+    const acceptsResolvedMode = (mode: ResolvedEncodeMode): ResolvedEncodeMode => mode;
+    acceptsResolvedMode('etc1s');
+    acceptsResolvedMode('uastc');
+    acceptsResolvedMode('uastc-hdr');
+    acceptsResolvedMode('none');
+    // @ts-expect-error The control-plane-only auto mode is not a resolved encoding.
+    acceptsResolvedMode('auto');
+
+    expectTypeOf<EncodedMode>().toEqualTypeOf<ResolvedEncodeMode>();
+    expectTypeOf<FailedMode>().toEqualTypeOf<ResolvedEncodeMode>();
+    expectTypeOf<BasisEncodeParams['mode']>().toEqualTypeOf<BasisEncodeMode>();
+  });
+
+  it('keeps the runtime tuples as the single image-side mode owners', () => {
+    expect(encodeSource).toContain(
+      "const COMPRESSION_MODES = ['auto', 'etc1s', 'uastc', 'none'] as const;",
+    );
+    expect(encodeSource).toContain(
+      'export type CompressionMode = (typeof COMPRESSION_MODES)[number];',
+    );
+    expect(encodeSource).toContain(
+      "const RESOLVED_ENCODE_MODES = ['etc1s', 'uastc', 'uastc-hdr', 'none'] as const;",
+    );
+    expect(encodeSource).toContain(
+      'export type ResolvedEncodeMode = (typeof RESOLVED_ENCODE_MODES)[number];',
+    );
+    expect(encodeSource).toContain('case COMPRESSION_MODES[3]:');
+    expect(encodeSource).toContain('case RESOLVED_ENCODE_MODES[2]:');
+    expect(encodeSource).not.toContain(
+      "export type CompressionMode = 'auto' | 'etc1s' | 'uastc' | 'none';",
+    );
+    expect(encodeSource).not.toContain(
+      "export type ResolvedEncodeMode = 'etc1s' | 'uastc' | 'uastc-hdr' | 'none';",
+    );
+  });
+});

package/src/__tests__/make-fixture.ts

@@ -0,0 +1,100 @@
+// Synthetic image fixtures generated algorithmically so the engine repo
+// carries zero committed image binaries (and zero inlined asset byte blobs,
+// which would just be a relabelled asset). The PNG path hand-builds the
+// chunk structure (IHDR + IDAT + IEND) and deflates the raw scanlines with
+// node's zlib; the JPEG path uses jpeg-js, already a runtime dep of
+// @forgeax/engine-image. Both produce standard-conformant streams that the
+// production decoder (upng-js / jpeg-js in parse-image.ts) reads back.
+import { deflateSync } from 'node:zlib';
+import * as jpeg from 'jpeg-js';
+
+const jpegEncode = ((jpeg as unknown as { encode?: typeof jpeg.encode }).encode ??
+  (jpeg as unknown as { default: { encode: typeof jpeg.encode } }).default
+    .encode) as typeof jpeg.encode;
+
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+// CRC-32 (PNG polynomial) over a chunk's type+data.
+function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let k = 0; k < 8; k++) {
+      crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function u32(n: number): number[] {
+  return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+}
+
+function chunk(type: string, data: Uint8Array): number[] {
+  const typeBytes = [...type].map((c) => c.charCodeAt(0));
+  const body = new Uint8Array([...typeBytes, ...data]);
+  return [...u32(data.length), ...body, ...u32(crc32(body))];
+}
+
+/** Solid-colour 8-bit RGBA PNG, standard zlib/deflate encoding. */
+export function makePng(
+  width: number,
+  height: number,
+  rgba: [number, number, number, number],
+): Uint8Array {
+  // IHDR: width, height, bit-depth=8, colour-type=6 (RGBA), no interlace.
+  const ihdr = new Uint8Array([...u32(width), ...u32(height), 8, 6, 0, 0, 0]);
+  // Raw image: each scanline prefixed with a filter-type byte (0 = none).
+  const raw = new Uint8Array(height * (1 + width * 4));
+  let o = 0;
+  for (let y = 0; y < height; y++) {
+    raw[o++] = 0;
+    for (let x = 0; x < width; x++) {
+      raw[o++] = rgba[0];
+      raw[o++] = rgba[1];
+      raw[o++] = rgba[2];
+      raw[o++] = rgba[3];
+    }
+  }
+  const idat = new Uint8Array(deflateSync(raw));
+  return new Uint8Array([
+    ...PNG_MAGIC,
+    ...chunk('IHDR', ihdr),
+    ...chunk('IDAT', idat),
+    ...chunk('IEND', new Uint8Array(0)),
+  ]);
+}
+
+/** Solid-colour RGBA JPEG of the given dimensions. */
+export function makeJpg(
+  width: number,
+  height: number,
+  rgba: [number, number, number, number],
+): Uint8Array {
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    data[i * 4 + 0] = rgba[0];
+    data[i * 4 + 1] = rgba[1];
+    data[i * 4 + 2] = rgba[2];
+    data[i * 4 + 3] = rgba[3];
+  }
+  const encoded = jpegEncode({ data: Buffer.from(data), width, height }, 90);
+  return new Uint8Array(encoded.data);
+}
+
+/**
+ * A valid PNG header + IHDR followed by an IDAT whose deflate stream is
+ * garbage, so a real PNG decoder fails (image-decode-failed). Built from the
+ * same chunk machinery as makePng, with a corrupted IDAT body — replaces the
+ * former committed corrupt.png fixture.
+ */
+export function makeCorruptPng(): Uint8Array {
+  const ihdr = new Uint8Array([...u32(1), ...u32(1), 8, 6, 0, 0, 0]);
+  const garbageIdat = new Uint8Array([0xff, 0xff, 0xff, 0xff, 0xff, 0xff]);
+  return new Uint8Array([
+    ...PNG_MAGIC,
+    ...chunk('IHDR', ihdr),
+    ...chunk('IDAT', garbageIdat),
+    ...chunk('IEND', new Uint8Array(0)),
+  ]);
+}

package/src/__tests__/parse-image-downscale.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { parseImage } from '../parse-image.js';
+import { makeJpg } from './make-fixture.js';
+
+describe('parseImage asset-owned downscale', () => {
+  it('emits an aspect-preserving cooked payload under the declared target', async () => {
+    const result = parseImage(makeJpg(2, 2, [255, 0, 0, 255]), 'image/jpeg', {
+      downscaleMaxDimension: 1,
+      maxDimension: 1,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.width).toBe(1);
+    expect(result.value.height).toBe(1);
+    expect(result.value.bytes).toHaveLength(4);
+  });
+
+  it('keeps current hard-bound behavior when no downscale target is declared', async () => {
+    const result = parseImage(makeJpg(2, 2, [255, 0, 0, 255]), 'image/jpeg', { maxDimension: 1 });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('image-dimension-out-of-bounds');
+  });
+});

package/src/__tests__/runtime-decode.unit.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { decodeImageBytes } from '../runtime/decode-image-bytes';
+
+describe('image runtime decode owner', () => {
+  it('returns a closed failure when the host has no browser decoder', async () => {
+    const result = await decodeImageBytes(new Uint8Array([0x89, 0x50]), 'image/png');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('image-decode-failed');
+    expect(result.error.expected).toContain('decodes successfully');
+    expect(result.error.hint).toBeTruthy();
+  });
+
+  it('does not silently reinterpret a codec MIME as a different image kind', async () => {
+    const result = await decodeImageBytes(new Uint8Array([1, 2, 3]), 'image/jpeg');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.detail.code).toBe('image-decode-failed');
+  });
+});

package/src/__tests__/source-key.unit.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { type ExistingExternalAssetPackage, reimportReuseMeta } from '../reimport-reuse-meta.js';
+import { deriveImageSourceKey, deriveImageSourceKeys } from '../source-key.js';
+import { subAssetKey } from '../sub-asset-key.js';
+
+const GUID = '01928000-7c00-7000-8000-000000000042';
+
+function decoded(): Parameters<typeof reimportReuseMeta>[0] {
+  return {
+    bytes: new Uint8Array(4),
+    width: 1,
+    height: 1,
+    mime: 'image/png',
+    colorSpace: 'srgb',
+    mipmap: true,
+  };
+}
+
+function existing(): ExistingExternalAssetPackage {
+  return {
+    schemaVersion: '1.0.0',
+    kind: 'external-asset-package',
+    importer: 'image',
+    source: 'renamed.png',
+    importSettings: {},
+    subAssets: [{ guid: GUID, sourceIndex: 0, kind: 'texture', sourceKey: 'image:texture' }],
+  };
+}
+
+describe('image producer sourceKey', () => {
+  it('uses a role key independent of path and sourceIndex', () => {
+    expect(deriveImageSourceKey('texture')).toBe('image:texture');
+    expect(deriveImageSourceKey('texture', { sourcePath: 'moved/wood.png', sourceIndex: 8 })).toBe(
+      'image:texture',
+    );
+  });
+
+  it('rejects an empty role instead of manufacturing an index key', () => {
+    expect(deriveImageSourceKey('')).toBeUndefined();
+  });
+
+  it('requires unique semantic roles for multi-output images', () => {
+    expect(deriveImageSourceKeys(['texture', 'equirect'])).toEqual({
+      ok: true,
+      keys: ['image:texture', 'image:equirect'],
+    });
+    expect(deriveImageSourceKeys(['texture', 'texture'])).toMatchObject({
+      ok: false,
+      code: 'duplicate-source-key',
+    });
+  });
+
+  it('keeps legacy indexFallback separate from producer sourceKey', () => {
+    expect(subAssetKey({ kind: 'texture', sourceIndex: 0 })).toEqual({
+      kind: 'texture',
+      indexFallback: 'textures/0',
+    });
+    expect(deriveImageSourceKey('texture')).not.toContain('0');
+  });
+
+  it('reuses identity after source relocation while emitting the role key', () => {
+    const result = reimportReuseMeta(decoded(), existing());
+    expect(result[0]).toMatchObject({ guid: GUID, sourceIndex: 0, sourceKey: 'image:texture' });
+  });
+});

package/src/__tests__/tga.unit.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { parseImage } from '../parse-image.js';
+
+function makeTga24(
+  width: number,
+  height: number,
+  bgrPixels: readonly number[],
+  imageDescriptor = 0,
+): Uint8Array {
+  const header = new Uint8Array(18);
+  header[2] = 2; // uncompressed true-color
+  header[12] = width & 0xff;
+  header[13] = (width >>> 8) & 0xff;
+  header[14] = height & 0xff;
+  header[15] = (height >>> 8) & 0xff;
+  header[16] = 24;
+  header[17] = imageDescriptor;
+  return new Uint8Array([...header, ...bgrPixels]);
+}
+
+describe('parseImage TGA', () => {
+  it('decodes 24-bit true-color pixels to RGBA and honours bottom-left origin', () => {
+    // File order is bottom row first: blue, green, then top row red, yellow.
+    // The descriptor has no top bit, so the decoded image must be top row
+    // first while preserving left-to-right order.
+    const tga = makeTga24(2, 2, [255, 0, 0, 0, 255, 0, 0, 0, 255, 0, 255, 255]);
+    const result = parseImage(tga, 'image/x-tga', { mipmap: false });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.mime).toBe('image/x-tga');
+    expect(Array.from(result.value.bytes)).toEqual([
+      255, 0, 0, 255, 255, 255, 0, 255, 0, 0, 255, 255, 0, 255, 0, 255,
+    ]);
+    expect(result.value.width).toBe(2);
+    expect(result.value.height).toBe(2);
+  });
+
+  it('decodes 32-bit RLE pixels and preserves alpha', () => {
+    const header = new Uint8Array(18);
+    header[2] = 10; // RLE true-color
+    header[12] = 2;
+    header[14] = 1;
+    header[16] = 32;
+    const tga = new Uint8Array([
+      ...header,
+      0x81, // run of two pixels
+      10,
+      20,
+      30,
+      40,
+    ]);
+    const result = parseImage(tga, 'image/x-tga');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(Array.from(result.value.bytes)).toEqual([30, 20, 10, 40, 30, 20, 10, 40]);
+  });
+});