@forgeax/engine-image 0.1.2

package/src/decode-image-from-file.ts

@@ -0,0 +1,298 @@
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+
+import { validateMeta } from '@forgeax/engine-pack';
+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/x-tga' | 'image/vnd.radiance'>
+> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.tga': 'image/x-tga',
+  '.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`);
+}
+
+function sidecarSchemaFailureReason(): string {
+  const firstError = validateMeta.errors?.[0];
+  if (firstError === undefined) return 'sidecar schema validation failed';
+  const location = firstError.instancePath === '' ? '/' : firstError.instancePath;
+  return `sidecar schema validation failed: ${firstError.keyword} at ${location}`.slice(0, 256);
+}
+
+function imageSidecarFailureReason(
+  sidecar: SidecarMeta,
+  mime: (typeof EXT_TO_MIME)[keyof typeof EXT_TO_MIME],
+): string | undefined {
+  const subAsset = sidecar.subAssets[0];
+  const settings = sidecar.importSettings;
+  const expectedKind = mime === 'image/vnd.radiance' ? 'equirect' : 'texture';
+  if (sidecar.importer !== 'image') return 'image sidecar importer must be image';
+  if (sidecar.subAssets.length !== 1 || subAsset === undefined) {
+    return 'image sidecar must declare one sub-asset';
+  }
+  if (subAsset.kind !== expectedKind || subAsset.sourceIndex !== 0) {
+    return `image sidecar sub-asset must be ${expectedKind} at sourceIndex 0`;
+  }
+  if (settings.colorSpace !== undefined && !['srgb', 'linear'].includes(settings.colorSpace)) {
+    return 'image sidecar colorSpace must be srgb or linear';
+  }
+  if (settings.mipmap !== undefined && !['auto', 'none'].includes(settings.mipmap)) {
+    return 'image sidecar mipmap must be auto or none';
+  }
+  if (
+    settings.addressMode !== undefined &&
+    !['repeat', 'clamp-to-edge', 'mirror-repeat'].includes(settings.addressMode)
+  ) {
+    return 'image sidecar addressMode is unsupported';
+  }
+  if (settings.filterMode !== undefined && !['nearest', 'linear'].includes(settings.filterMode)) {
+    return 'image sidecar filterMode is unsupported';
+  }
+  return undefined;
+}
+
+/**
+ * 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 parsedSidecar: unknown;
+  try {
+    parsedSidecar = JSON.parse(sidecarText) as unknown;
+  } catch (e) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: `sidecar JSON parse failed: ${e instanceof Error ? e.message : String(e)}`,
+        path: sidecarPath,
+      }),
+    );
+  }
+
+  if (!validateMeta(parsedSidecar)) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: sidecarSchemaFailureReason(),
+        path: sidecarPath,
+      }),
+    );
+  }
+
+  const sidecar = parsedSidecar as unknown as SidecarMeta;
+  const imageSidecarFailure = imageSidecarFailureReason(sidecar, mime);
+  if (imageSidecarFailure !== undefined) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: imageSidecarFailure,
+        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', 'image/x-tga']; 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 };

package/src/hdr-decoder.ts

@@ -0,0 +1,255 @@
+import type { ImageError } from '@forgeax/engine-types';
+import { imageError } from './errors.js';
+import type { Result } from './result.js';
+import { err, ok } from './result.js';
+
+/**
+ * Decoded HDR image POD.
+ *
+ * `data` is an interleaved RGBA Float32Array (4 floats per pixel, row-major).
+ * Color space is always linear (RGBE is radiance).
+ */
+export interface HdrDecoded {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Float32Array;
+}
+
+// ASCII code points
+const LF = 0x0a;
+
+/**
+ * Decode a Radiance RGBE (.hdr) byte stream into linear RGBA float pixels.
+ *
+ * Steps per research F-6:
+ * 1. Parse ASCII header: magic (#?RADIANCE), FORMAT=32-bit_rle_rgbe,
+ *    resolution line (-Y height +X width).
+ * 2. Decode per-scanline new-RLE pixel data: 4 independent channel runs.
+ * 3. Convert RGBE to float: if E==0 -> 0; else f=2^(E-136), R=(Rm+0.5)*f.
+ * 4. Output as interleaved RGBA Float32Array (alpha=1.0).
+ *
+ * Old-RLE scanlines (prefix not matching 0x02,0x02,hi,lo with correct width)
+ * return image-hdr-decode-failed.
+ */
+export function decodeHdr(bytes: Uint8Array): Result<HdrDecoded, ImageError> {
+  let pos = 0;
+
+  // Step 1a: magic -- must start with "#?RADIANCE" or "#?RGBE"
+  if (bytes.length < 11) {
+    return err(hdrDecodeError('file too short for Radiance HDR header'));
+  }
+  const magic = String.fromCharCode(...bytes.subarray(0, 11));
+  if (magic !== '#?RADIANCE\n' && magic !== '#?RGBE\n') {
+    return err(
+      hdrDecodeError('missing or invalid Radiance HDR magic; expected #?RADIANCE or #?RGBE'),
+    );
+  }
+  pos = 11;
+
+  // Step 1b: key=value lines until empty line
+  let formatFound = false;
+  while (pos < bytes.length) {
+    const lineEnd = findByte(bytes, LF, pos);
+    if (lineEnd === -1) return err(hdrDecodeError('header truncated before empty line'));
+    const line = asciiSubstring(bytes, pos, lineEnd);
+    pos = lineEnd + 1;
+    if (line === '') break;
+    if (line.startsWith('FORMAT=')) {
+      const val = line.slice(7);
+      if (val === '32-bit_rle_rgbe') {
+        formatFound = true;
+      }
+    }
+  }
+  if (!formatFound) {
+    return err(hdrDecodeError('missing or unsupported FORMAT; expected FORMAT=32-bit_rle_rgbe'));
+  }
+
+  // Step 1c: resolution line (-Y height +X width)
+  if (pos >= bytes.length) return err(hdrDecodeError('missing resolution line'));
+  const resLineEnd = findByte(bytes, LF, pos);
+  if (resLineEnd === -1) return err(hdrDecodeError('resolution line truncated'));
+  const resLine = asciiSubstring(bytes, pos, resLineEnd);
+  pos = resLineEnd + 1;
+  const resMatch = /^-Y\s+(\d+)\s+\+X\s+(\d+)\s*$/.exec(resLine);
+  if (resMatch === null) {
+    return err(
+      hdrDecodeError(`unexpected resolution line format: "${resLine}"; expected "-Y H +X W"`),
+    );
+  }
+  const height = Number(resMatch[1]);
+  const width = Number(resMatch[2]);
+  if (height === undefined || width === undefined || height <= 0 || width <= 0) {
+    return err(hdrDecodeError(`invalid dimensions: ${width}x${height}`));
+  }
+
+  // Step 2: decode per-scanline new-RLE pixel data
+  const pixelCount = width * height;
+  const rgbe = new Uint8Array(pixelCount * 4);
+  const scanlineBytes = width * 4;
+
+  for (let y = 0; y < height; y++) {
+    if (pos + 4 > bytes.length) {
+      return err(hdrDecodeError(`truncated at scanline ${y}: expected 4-byte prefix`));
+    }
+    const p0 = bytes[pos];
+    const p1 = bytes[pos + 1];
+    const pHi = bytes[pos + 2];
+    const pLo = bytes[pos + 3];
+    if (p0 === undefined || p1 === undefined || pHi === undefined || pLo === undefined) {
+      return err(hdrDecodeError(`truncated at scanline ${y}`));
+    }
+    // biome-ignore lint/style/noNonNullAssertion: checked above
+    const prefixWidth = (pHi! << 8) | pLo!;
+
+    if (p0 === 0x02 && p1 === 0x02 && prefixWidth === width && width >= 8 && width <= 32767) {
+      // New-RLE: 4 channels independently RLE-encoded, then interleaved
+      const decoded = decodeNewRleScanline(bytes, pos + 4, width);
+      if (decoded === null) {
+        return err(hdrDecodeError(`RLE decode failed at scanline ${y}`));
+      }
+      // Copy into rgbe interleaved buffer
+      const base = y * scanlineBytes;
+      const channels = [decoded[0], decoded[1], decoded[2], decoded[3]];
+      for (let x = 0; x < width; x++) {
+        for (let ch = 0; ch < 4; ch++) {
+          // biome-ignore lint/style/noNonNullAssertion: checked at allocation
+          rgbe[base + x * 4 + ch] = channels[ch]![x]!;
+        }
+      }
+      // Advance pos past the 4-byte prefix + the total RLE bytes consumed
+      pos += 4 + decoded.totalBytes;
+    } else {
+      // Old-RLE: not supported
+      return err(
+        hdrDecodeError(
+          'old-RLE format is not supported; only new-RLE (32-bit_rle_rgbe) is accepted',
+        ),
+      );
+    }
+  }
+
+  // Step 3: RGBE to float
+  const out = new Float32Array(pixelCount * 4);
+  for (let i = 0; i < pixelCount; i++) {
+    const base = i * 4;
+    // biome-ignore lint/style/noNonNullAssertion: checked at allocation
+    const r = rgbe[base]!;
+    // biome-ignore lint/style/noNonNullAssertion: checked at allocation
+    const g = rgbe[base + 1]!;
+    // biome-ignore lint/style/noNonNullAssertion: checked at allocation
+    const b = rgbe[base + 2]!;
+    // biome-ignore lint/style/noNonNullAssertion: checked at allocation
+    const e = rgbe[base + 3]!;
+    out[base + 3] = 1.0;
+
+    if (e === 0) {
+      out[base] = 0;
+      out[base + 1] = 0;
+      out[base + 2] = 0;
+    } else {
+      // f = 2^(E - 136) = ldexp(1.0, E - 128 - 8)
+      // Equivalent: ldexp(1.0 / 256.0, E - 128)
+      // But simpler: const f = (1.0 / 256.0) * Math.pow(2, e - 128);
+      // Using ldexp: Math.pow(2, e - 136)
+      const f = 2 ** (e - 136);
+      out[base] = (r + 0.5) * f;
+      out[base + 1] = (g + 0.5) * f;
+      out[base + 2] = (b + 0.5) * f;
+    }
+  }
+
+  return ok({ width, height, data: out });
+}
+
+interface DecodedScanline {
+  /** 4 channels, each width bytes */
+  readonly 0: Uint8Array;
+  readonly 1: Uint8Array;
+  readonly 2: Uint8Array;
+  readonly 3: Uint8Array;
+  readonly totalBytes: number;
+}
+
+/**
+ * Decode one scanline of new-RLE data into 4 channel arrays.
+ * Returns null on failure (data underrun).
+ */
+function decodeNewRleScanline(
+  bytes: Uint8Array,
+  start: number,
+  width: number,
+): DecodedScanline | null {
+  const channels: Uint8Array[] = [];
+  let cursor = start;
+
+  for (let ch = 0; ch < 4; ch++) {
+    const data = new Uint8Array(width);
+    let x = 0;
+    while (x < width) {
+      if (cursor >= bytes.length) return null;
+      // biome-ignore lint/style/noNonNullAssertion: checked above
+      const code = bytes[cursor]!;
+      cursor++;
+      if (code > 128) {
+        // RLE run: next byte repeated (code - 128) times
+        const count = code - 128;
+        if (cursor >= bytes.length || x + count > width) return null;
+        // biome-ignore lint/style/noNonNullAssertion: checked above
+        const val = bytes[cursor]!;
+        cursor++;
+        data.fill(val, x, x + count);
+        x += count;
+      } else {
+        // Literal run: next `code` bytes copied verbatim
+        if (code === 0) continue;
+        if (cursor + code > bytes.length || x + code > width) return null;
+        for (let k = 0; k < code; k++) {
+          // biome-ignore lint/style/noNonNullAssertion: checked above
+          data[x + k] = bytes[cursor + k]!;
+        }
+        cursor += code;
+        x += code;
+      }
+    }
+    channels.push(data);
+  }
+
+  const ch0 = channels[0];
+  const ch1 = channels[1];
+  const ch2 = channels[2];
+  const ch3 = channels[3];
+  if (ch0 === undefined || ch1 === undefined || ch2 === undefined || ch3 === undefined) {
+    return null; // channels should always have 4 entries
+  }
+  return {
+    0: ch0,
+    1: ch1,
+    2: ch2,
+    3: ch3,
+    totalBytes: cursor - start,
+  };
+}
+
+function findByte(bytes: Uint8Array, target: number, start: number): number {
+  for (let i = start; i < bytes.length; i++) {
+    if (bytes[i] === target) return i;
+  }
+  return -1;
+}
+
+function asciiSubstring(bytes: Uint8Array, start: number, end: number): string {
+  let s = '';
+  for (let i = start; i < end; i++) {
+    // biome-ignore lint/style/noNonNullAssertion: in bounds
+    s += String.fromCharCode(bytes[i]!);
+  }
+  return s;
+}
+
+function hdrDecodeError(reason: string): ImageError {
+  return imageError({
+    code: 'image-hdr-decode-failed',
+    reason,
+  });
+}

package/src/image-decoder-browser.ts

@@ -0,0 +1,88 @@
+import type { DecodedImage, ImageColorSpace, ImageError } from '@forgeax/engine-types';
+import { imageError } from './errors.js';
+import type { Result } from './result.js';
+import { err, ok } from './result.js';
+
+/**
+ * Browser image decoder (plan-strategy section 3.3 + section 2.4 D Open Q-3).
+ *
+ * Uses `createImageBitmap(blob, { colorSpaceConversion: 'none' })` to keep
+ * the bytes in their authored color space (sRGB / linear); the runtime
+ * uploadTexture entry asserts `format <-> colorSpace` consistency at GPU
+ * upload time (plan-strategy section 2.5 D Open Q-4 (c)).
+ *
+ * Pixel readback uses an offscreen 2D canvas + `getImageData`; AI users
+ * never call this directly -- it is the browser-mode counterpart of
+ * `parseImage` (Node-mode upng / jpeg-js path) consumed by future M2b
+ * vite-plugin overlay paths and direct browser-mode loaders. The Node
+ * decoder remains the SSOT for parseImage; this file is the browser
+ * fallback when running inside vitest browser mode or the Vite dev server.
+ */
+export async function decodeImageInBrowser(
+  bytes: Uint8Array,
+  mime: 'image/png' | 'image/jpeg',
+  opts: { colorSpace?: ImageColorSpace; mipmap?: boolean } = {},
+): Promise<Result<DecodedImage, ImageError>> {
+  if (typeof createImageBitmap !== 'function') {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: 'createImageBitmap is not available in this environment',
+      }),
+    );
+  }
+
+  let bitmap: ImageBitmap;
+  try {
+    const blob = new Blob([bytes as BlobPart], { type: mime });
+    bitmap = await createImageBitmap(blob, {
+      colorSpaceConversion: 'none',
+      premultiplyAlpha: 'none',
+    });
+  } catch (e) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: e instanceof Error ? e.message : String(e),
+      }),
+    );
+  }
+
+  // Read pixels back via OffscreenCanvas (browser context) -- 2D context is
+  // ubiquitous and avoids the WebGPU readback round-trip during disk-side
+  // decode (charter P5 producer / consumer split: GPU upload happens inside
+  // the Render DeviceScope, not in this byte decoder).
+  const canvas =
+    typeof OffscreenCanvas !== 'undefined'
+      ? new OffscreenCanvas(bitmap.width, bitmap.height)
+      : (() => {
+          const c = document.createElement('canvas');
+          c.width = bitmap.width;
+          c.height = bitmap.height;
+          return c;
+        })();
+  const ctx = canvas.getContext('2d') as
+    | OffscreenCanvasRenderingContext2D
+    | CanvasRenderingContext2D
+    | null;
+  if (ctx === null) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: 'failed to acquire 2d canvas context for pixel readback',
+      }),
+    );
+  }
+  ctx.drawImage(bitmap, 0, 0);
+  const data = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
+  bitmap.close();
+
+  return ok({
+    bytes: new Uint8Array(data.data.buffer.slice(0)),
+    width: data.width,
+    height: data.height,
+    mime,
+    colorSpace: opts.colorSpace ?? 'srgb',
+    mipmap: opts.mipmap ?? true,
+  });
+}