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

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__/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__/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/decode-image-from-file.ts

@@ -0,0 +1,233 @@
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+
+import type { DecodedImage, ImageError, ImageMeta } from '@forgeax/engine-types';
+import { imageError } from './errors.js';
+import { decodeHdr, type HdrDecoded } from './hdr-decoder.js';
+import { parseImage } from './parse-image.js';
+import type { Result } from './result.js';
+import { err, ok } from './result.js';
+
+/**
+ * Sidecar JSON shape consumed by decodeImageFromFile. The schema is the
+ * external-asset-package $defs from `packages/pack/schema/meta.schema.json`
+ * (research F-9). Only the fields required by the Node-side decoder are
+ * enumerated here; importSettings remains free-form per plan-strategy R5.
+ */
+interface SidecarMeta {
+  readonly schemaVersion: string;
+  readonly kind: 'external-asset-package';
+  readonly importer: 'image';
+  readonly source: string;
+  readonly importSettings: Partial<{
+    colorSpace: ImageMeta['colorSpace'];
+    mipmap: ImageMeta['mipmap'];
+    addressMode: ImageMeta['addressMode'];
+    filterMode: ImageMeta['filterMode'];
+  }>;
+  readonly subAssets: ReadonlyArray<{
+    readonly guid: string;
+    readonly sourceIndex: number;
+    readonly kind: string;
+  }>;
+}
+
+/**
+ * Result envelope returned by decodeImageFromFile for PNG/JPG sources.
+ * Carries both the raw DecodedImage POD (for direct uploadTexture consumption)
+ * and the parsed ImageMeta POD.
+ */
+export interface DecodedImageWithMeta {
+  readonly decoded: DecodedImage;
+  readonly meta: ImageMeta;
+}
+
+/**
+ * Result envelope returned by decodeImageFromFile for .hdr sources.
+ * Carries the HDR-decoded float data ready for cubemap upload.
+ */
+export interface DecodedHdrWithMeta {
+  readonly hdr: HdrDecoded;
+  readonly meta: ImageMeta;
+}
+
+const EXT_TO_MIME: Readonly<Record<string, 'image/png' | 'image/jpeg' | 'image/vnd.radiance'>> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.hdr': 'image/vnd.radiance',
+};
+
+function deriveSidecarPath(sourcePath: string): string {
+  const dir = dirname(sourcePath);
+  // sidecar lives next to source as <source-with-ext>.meta.json
+  // (feat-20260521 unify-sidecar-meta-dispatch-by-content; the importer field
+  //  in the JSON drives importer dispatch instead of filename suffix).
+  const base = sourcePath.slice(dir.length + 1);
+  return join(dir, `${base}.meta.json`);
+}
+
+/**
+ * Async file-system entry to the image importer (plan-strategy section 3.2
+ * sequence A; AC-17 path (a) sidecar three-way fallback).
+ *
+ * Behaviour (left-to-right, fail-fast on first surfaced ImageError):
+ *  1. Sniff extension -- not in `.png / .jpg / .jpeg` -> image-format-unsupported
+ *  2. Stat source -- absent -> image-decode-failed with the source path
+ *  3. Stat sibling `<source>.meta.json` (importer: 'image') -- absent -> image-meta-missing
+ *  4. Read source bytes + parse sidecar JSON
+ *  5. Hand off to `parseImage(bytes, mime, opts)` -- surfaces image-decode-failed
+ *     / image-format-unsupported / image-dimension-out-of-bounds
+ *  6. Compose DecodedImage POD + ImageMeta POD return envelope.
+ *
+ * AC-17 path (a) lock: when the sidecar is absent, the returned error
+ * carries `detail.sourcePath` + `detail.expectedSidecarPath` so AI users
+ * read .hint and run `forgeax-engine-remote-asset import <path>` to
+ * self-recover (charter P3 explicit failure + IDE jump-to-source).
+ */
+export async function decodeImageFromFile(
+  sourcePath: string,
+): Promise<Result<DecodedImageWithMeta, ImageError>> {
+  const ext = extname(sourcePath).toLowerCase();
+  const mime = EXT_TO_MIME[ext];
+  if (mime === undefined) {
+    return err(
+      imageError({
+        code: 'image-format-unsupported',
+        actualMime: `extension '${ext || '<none>'}'`,
+        path: sourcePath,
+      }),
+    );
+  }
+
+  const sidecarPath = deriveSidecarPath(sourcePath);
+
+  try {
+    await stat(sourcePath);
+  } catch (e) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: `failed to read source: ${e instanceof Error ? e.message : String(e)}`,
+        path: sourcePath,
+      }),
+    );
+  }
+
+  try {
+    await stat(sidecarPath);
+  } catch {
+    return err(
+      imageError({
+        code: 'image-meta-missing',
+        sourcePath,
+        expectedSidecarPath: sidecarPath,
+      }),
+    );
+  }
+
+  let sidecarText: string;
+  try {
+    sidecarText = (await readFile(sidecarPath)).toString('utf8');
+  } catch (e) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: `failed to read sidecar: ${e instanceof Error ? e.message : String(e)}`,
+        path: sidecarPath,
+      }),
+    );
+  }
+
+  let sidecar: SidecarMeta;
+  try {
+    sidecar = JSON.parse(sidecarText) as SidecarMeta;
+  } catch (e) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: `sidecar JSON parse failed: ${e instanceof Error ? e.message : String(e)}`,
+        path: sidecarPath,
+      }),
+    );
+  }
+
+  const settings = sidecar.importSettings ?? {};
+  const colorSpace: ImageMeta['colorSpace'] = settings.colorSpace ?? 'srgb';
+  const mipmap: ImageMeta['mipmap'] = settings.mipmap ?? 'auto';
+  const addressMode: ImageMeta['addressMode'] = settings.addressMode ?? 'repeat';
+  const filterMode: ImageMeta['filterMode'] = settings.filterMode ?? 'linear';
+  const guid = sidecar.subAssets[0]?.guid ?? '';
+
+  const meta: ImageMeta = {
+    guid,
+    colorSpace,
+    mipmap,
+    addressMode,
+    filterMode,
+  };
+
+  let bytes: Uint8Array;
+  try {
+    const buf = await readFile(sourcePath);
+    bytes = new Uint8Array(buf);
+  } catch (e) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: `failed to read source: ${e instanceof Error ? e.message : String(e)}`,
+        path: sourcePath,
+      }),
+    );
+  }
+
+  // .hdr path: delegate to HDR decoder, enforce linear color space
+  if (mime === 'image/vnd.radiance') {
+    if (colorSpace !== 'linear') {
+      return err(
+        imageError({
+          code: 'image-format-unsupported',
+          actualMime: `colorSpace conflict: HDR requires linear, got ${colorSpace}`,
+          path: sourcePath,
+        }),
+      );
+    }
+    const hdrRes = decodeHdr(bytes);
+    if (!hdrRes.ok) return err(hdrRes.error);
+    // DecodedImageWithMeta expects DecodedImage; for HDR we return the HDR
+    // variant through a separate export path. Downstream consumers
+    // distinguish by file extension.
+    // For the DecodedImageWithMeta return type compatibility, we synthesise
+    // a minimal DecodedImage POD carrying the byte representation.
+    // This keeps the return type stable for existing PNG/JPG callers.
+    // The HDR data is available through the separate decodeHdr export.
+    const rgba8 = new Uint8Array(hdrRes.value.width * hdrRes.value.height * 4);
+    // convert float to quantised 8-bit for the POD shape (lossy; consumers
+    // should use decodeHdr directly for float precision)
+    for (let i = 0; i < hdrRes.value.data.length; i++) {
+      const v = hdrRes.value.data[i];
+      const clamped = v !== undefined ? Math.max(0, Math.min(1, v as number)) : 0;
+      rgba8[i] = Math.round(clamped * 255);
+    }
+    const decoded: DecodedImage = {
+      bytes: rgba8,
+      width: hdrRes.value.width,
+      height: hdrRes.value.height,
+      mime: 'image/jpeg',
+      colorSpace: 'linear',
+      mipmap: false,
+    };
+    return ok({ decoded, meta });
+  }
+
+  const r = parseImage(bytes, mime, {
+    colorSpace,
+    mipmap: mipmap === 'auto',
+    path: sourcePath,
+  });
+  if (!r.ok) {
+    return err(r.error);
+  }
+
+  return ok({ decoded: r.value, meta });
+}

package/src/errors.ts

@@ -0,0 +1,60 @@
+import type { ImageErrorCode, ImageErrorDetailFor, ImageErrorFor } from '@forgeax/engine-types';
+import { IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+
+// Per-code .expected string literals SSOT.
+// Mirrors ASSET_ERROR_HINTS / IMAGE_ERROR_HINTS shape (charter P5 consistent
+// abstraction). AI users surface .expected when a structured error needs to
+// describe the precondition that was violated.
+const IMAGE_ERROR_EXPECTED: Readonly<Record<ImageErrorCode, string>> = {
+  'image-decode-failed': 'PNG / JPG byte stream decodes successfully',
+  'image-format-unsupported':
+    "mime is one of ['image/png', 'image/jpeg']; uploadTexture format <-> colorSpace family agrees",
+  'image-dimension-out-of-bounds':
+    'width and height fall under device caps maxTextureDimension2D (or 16384 hard cap)',
+  'image-meta-missing':
+    "<source>.meta.json sidecar (importer: 'image') exists in the same directory",
+  'image-hdr-decode-failed': 'Radiance RGBE header is valid and pixel data decodes successfully',
+  // feat-20260521-sprite-atlas-animation M1 T-03 — vite-plugin-image atlas
+  // hook .expected literals (plan-strategy section 2 D-2 + AC-10 a/b/c).
+  // ImageErrorImpl construction path is unchanged: the new atlas-* errors
+  // flow through `new ImageErrorImpl({ code: 'atlas-...', ...detail })` and
+  // pick the .expected string up from this Record at construction time
+  // (charter P3 explicit failure SSOT — AI users surface .expected next to
+  // .hint after switch (err.code) without parsing the message).
+  'atlas-empty-input': 'images.length >= 1',
+  'atlas-size-exceeded':
+    'image width x height <= maxAtlasSize^2 and each image fits in the atlas footprint',
+  'atlas-region-mismatch': 'sum(regions[i].w x regions[i].h) <= atlasWidth x atlasHeight',
+};
+
+/** Runtime implementation of the correlated `ImageErrorFor<C>` envelope. */
+export class ImageErrorImpl<C extends ImageErrorCode = ImageErrorCode>
+  extends Error
+  implements ImageErrorFor<C>
+{
+  readonly code: C;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: ImageErrorDetailFor<C>;
+
+  constructor(detail: ImageErrorDetailFor<C>) {
+    const code = detail.code;
+    const expected = IMAGE_ERROR_EXPECTED[code];
+    const hint = IMAGE_ERROR_HINTS[code];
+    super(`[ImageError ${code}] expected: ${expected}; hint: ${hint}`);
+    this.name = 'ImageError';
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+}
+
+/** Construct a structured image error while preserving its code/detail pair. */
+export function imageError<C extends ImageErrorCode>(
+  detail: ImageErrorDetailFor<C>,
+): ImageErrorFor<C> {
+  return new ImageErrorImpl<C>(detail);
+}
+
+export { IMAGE_ERROR_EXPECTED };