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

package/dist/__tests__/encode-source-too-large.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode-source-too-large.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/encode-source-too-large.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/errors.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test-d.d.ts.map

package/dist/__tests__/errors.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/errors.test-d.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-importer-conversion-failure.unit.test.d.ts.map

package/dist/__tests__/image-importer-conversion-failure.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-importer-conversion-failure.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/image-importer-conversion-failure.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/image-importer-hdr-equirect.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-importer-hdr-equirect.test.d.ts.map

package/dist/__tests__/image-importer-hdr-equirect.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-importer-hdr-equirect.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/image-importer-hdr-equirect.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/image-importer-topology.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-importer-topology.unit.test.d.ts.map

package/dist/__tests__/image-importer-topology.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-importer-topology.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/image-importer-topology.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/image-importer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-importer.test.d.ts.map

package/dist/__tests__/image-importer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-importer.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/image-importer.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/image-local-artifacts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-local-artifacts.test.d.ts.map

package/dist/__tests__/image-local-artifacts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-local-artifacts.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/image-local-artifacts.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/image.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image.unit.test.d.ts.map

package/dist/__tests__/image.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/image.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ktx2-basis-importer.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ktx2-basis-importer.unit.test.d.ts.map

package/dist/__tests__/ktx2-basis-importer.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-basis-importer.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ktx2-basis-importer.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/make-fixture.d.ts

@@ -0,0 +1,12 @@
+/** Solid-colour 8-bit RGBA PNG, standard zlib/deflate encoding. */
+export declare function makePng(width: number, height: number, rgba: [number, number, number, number]): Uint8Array;
+/** Solid-colour RGBA JPEG of the given dimensions. */
+export declare function makeJpg(width: number, height: number, rgba: [number, number, number, number]): Uint8Array;
+/**
+ * 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 declare function makeCorruptPng(): Uint8Array;
+//# sourceMappingURL=make-fixture.d.ts.map

package/dist/__tests__/make-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-fixture.d.ts","sourceRoot":"","sources":["../../src/__tests__/make-fixture.ts"],"names":[],"mappings":"AAsCA,mEAAmE;AACnE,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GACrC,UAAU,CAsBZ;AAED,sDAAsD;AACtD,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GACrC,UAAU,CAUZ;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAS3C"}

package/dist/__tests__/parse-image-downscale.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parse-image-downscale.test.d.ts.map

package/dist/__tests__/parse-image-downscale.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-image-downscale.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/parse-image-downscale.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/source-key.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-key.unit.test.d.ts.map

package/dist/__tests__/source-key.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-key.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/source-key.unit.test.ts"],"names":[],"mappings":""}

package/dist/decode-image-from-file.d.ts

@@ -0,0 +1,40 @@
+import type { DecodedImage, ImageError, ImageMeta } from '@forgeax/engine-types';
+import { type HdrDecoded } from './hdr-decoder.js';
+import type { Result } from './result.js';
+/**
+ * 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;
+}
+/**
+ * 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 declare function decodeImageFromFile(sourcePath: string): Promise<Result<DecodedImageWithMeta, ImageError>>;
+//# sourceMappingURL=decode-image-from-file.d.ts.map

package/dist/decode-image-from-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-image-from-file.d.ts","sourceRoot":"","sources":["../src/decode-image-from-file.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEjF,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA2B1C;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAkBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC,CA+InD"}

package/dist/decode-image-from-file.mjs

@@ -0,0 +1,460 @@
+import { stat, readFile } from 'fs/promises';
+import { extname, dirname, join } from 'path';
+import { err, ok, IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+import * as jpeg from 'jpeg-js';
+import * as UPNG from 'upng-js';
+
+// src/decode-image-from-file.ts
+var IMAGE_ERROR_EXPECTED = {
+  "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"
+};
+var ImageErrorImpl = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    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;
+  }
+};
+function imageError(detail) {
+  return new ImageErrorImpl(detail);
+}
+
+// src/hdr-decoder.ts
+var LF = 10;
+function decodeHdr(bytes) {
+  let pos = 0;
+  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;
+  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"));
+  }
+  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 === void 0 || width === void 0 || height <= 0 || width <= 0) {
+    return err(hdrDecodeError(`invalid dimensions: ${width}x${height}`));
+  }
+  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 === void 0 || p1 === void 0 || pHi === void 0 || pLo === void 0) {
+      return err(hdrDecodeError(`truncated at scanline ${y}`));
+    }
+    const prefixWidth = pHi << 8 | pLo;
+    if (p0 === 2 && p1 === 2 && prefixWidth === width && width >= 8 && width <= 32767) {
+      const decoded = decodeNewRleScanline(bytes, pos + 4, width);
+      if (decoded === null) {
+        return err(hdrDecodeError(`RLE decode failed at scanline ${y}`));
+      }
+      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++) {
+          rgbe[base + x * 4 + ch] = channels[ch][x];
+        }
+      }
+      pos += 4 + decoded.totalBytes;
+    } else {
+      return err(
+        hdrDecodeError(
+          "old-RLE format is not supported; only new-RLE (32-bit_rle_rgbe) is accepted"
+        )
+      );
+    }
+  }
+  const out = new Float32Array(pixelCount * 4);
+  for (let i = 0; i < pixelCount; i++) {
+    const base = i * 4;
+    const r = rgbe[base];
+    const g = rgbe[base + 1];
+    const b = rgbe[base + 2];
+    const e = rgbe[base + 3];
+    out[base + 3] = 1;
+    if (e === 0) {
+      out[base] = 0;
+      out[base + 1] = 0;
+      out[base + 2] = 0;
+    } else {
+      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 });
+}
+function decodeNewRleScanline(bytes, start, width) {
+  const channels = [];
+  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;
+      const code = bytes[cursor];
+      cursor++;
+      if (code > 128) {
+        const count = code - 128;
+        if (cursor >= bytes.length || x + count > width) return null;
+        const val = bytes[cursor];
+        cursor++;
+        data.fill(val, x, x + count);
+        x += count;
+      } else {
+        if (code === 0) continue;
+        if (cursor + code > bytes.length || x + code > width) return null;
+        for (let k = 0; k < code; k++) {
+          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 === void 0 || ch1 === void 0 || ch2 === void 0 || ch3 === void 0) {
+    return null;
+  }
+  return {
+    0: ch0,
+    1: ch1,
+    2: ch2,
+    3: ch3,
+    totalBytes: cursor - start
+  };
+}
+function findByte(bytes, target, start) {
+  for (let i = start; i < bytes.length; i++) {
+    if (bytes[i] === target) return i;
+  }
+  return -1;
+}
+function asciiSubstring(bytes, start, end) {
+  let s = "";
+  for (let i = start; i < end; i++) {
+    s += String.fromCharCode(bytes[i]);
+  }
+  return s;
+}
+function hdrDecodeError(reason) {
+  return imageError({
+    code: "image-hdr-decode-failed",
+    reason
+  });
+}
+
+// src/resize-image.ts
+function downscaleRgba(bytes, width, height, maxDimension) {
+  if (width <= maxDimension && height <= maxDimension) {
+    return { bytes, width, height };
+  }
+  const scale = maxDimension / Math.max(width, height);
+  const targetWidth = Math.max(1, Math.round(width * scale));
+  const targetHeight = Math.max(1, Math.round(height * scale));
+  const output = new Uint8Array(targetWidth * targetHeight * 4);
+  const source = (x, y, channel) => bytes[(y * width + x) * 4 + channel] ?? 0;
+  for (let y = 0; y < targetHeight; y += 1) {
+    const sourceY = (y + 0.5) * height / targetHeight - 0.5;
+    const y0 = Math.max(0, Math.floor(sourceY));
+    const y1 = Math.min(height - 1, y0 + 1);
+    const yWeight = Math.max(0, Math.min(1, sourceY - y0));
+    for (let x = 0; x < targetWidth; x += 1) {
+      const sourceX = (x + 0.5) * width / targetWidth - 0.5;
+      const x0 = Math.max(0, Math.floor(sourceX));
+      const x1 = Math.min(width - 1, x0 + 1);
+      const xWeight = Math.max(0, Math.min(1, sourceX - x0));
+      const outputOffset = (y * targetWidth + x) * 4;
+      for (let channel = 0; channel < 4; channel += 1) {
+        const top = source(x0, y0, channel) * (1 - xWeight) + source(x1, y0, channel) * xWeight;
+        const bottom = source(x0, y1, channel) * (1 - xWeight) + source(x1, y1, channel) * xWeight;
+        output[outputOffset + channel] = Math.round(top * (1 - yWeight) + bottom * yWeight);
+      }
+    }
+  }
+  return { bytes: output, width: targetWidth, height: targetHeight };
+}
+
+// src/parse-image.ts
+var DEFAULT_MAX_DIMENSION = 16384;
+var SUPPORTED_MIMES = ["image/png", "image/jpeg"];
+function parseImage(bytes, mime, opts = {}) {
+  if (!SUPPORTED_MIMES.includes(mime)) {
+    return err(
+      imageError({
+        code: "image-format-unsupported",
+        actualMime: mime,
+        ...opts.path !== void 0 ? { path: opts.path } : {}
+      })
+    );
+  }
+  let width = 0;
+  let height = 0;
+  let rgba;
+  try {
+    if (mime === "image/png") {
+      const upngMod = UPNG.default ?? UPNG;
+      const decoded = upngMod.decode(bytes);
+      width = decoded.width;
+      height = decoded.height;
+      const frames = upngMod.toRGBA8(decoded);
+      const first = frames[0];
+      if (first === void 0) {
+        return err(
+          imageError({
+            code: "image-decode-failed",
+            reason: "UPNG.toRGBA8 returned no frames",
+            ...opts.path !== void 0 ? { path: opts.path } : {}
+          })
+        );
+      }
+      rgba = new Uint8Array(first);
+    } else {
+      const jpegMod = jpeg.default ?? jpeg;
+      const decoded = jpegMod.decode(bytes, { useTArray: true, formatAsRGBA: true });
+      width = decoded.width;
+      height = decoded.height;
+      rgba = decoded.data;
+    }
+  } catch (e) {
+    return err(
+      imageError({
+        code: "image-decode-failed",
+        reason: e instanceof Error ? e.message : String(e),
+        ...opts.path !== void 0 ? { path: opts.path } : {}
+      })
+    );
+  }
+  const downscaleLimit = opts.downscaleMaxDimension;
+  if (downscaleLimit !== void 0 && Number.isInteger(downscaleLimit) && downscaleLimit > 0) {
+    const downscaled = downscaleRgba(rgba, width, height, downscaleLimit);
+    rgba = downscaled.bytes;
+    width = downscaled.width;
+    height = downscaled.height;
+  }
+  const limit = opts.maxDimension ?? DEFAULT_MAX_DIMENSION;
+  if (width > limit || height > limit) {
+    return err(
+      imageError({
+        code: "image-dimension-out-of-bounds",
+        requested: { width, height },
+        limit
+      })
+    );
+  }
+  return ok({
+    bytes: rgba,
+    width,
+    height,
+    mime,
+    colorSpace: opts.colorSpace ?? "srgb",
+    mipmap: opts.mipmap ?? true
+  });
+}
+
+// src/decode-image-from-file.ts
+var EXT_TO_MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".hdr": "image/vnd.radiance"
+};
+function deriveSidecarPath(sourcePath) {
+  const dir = dirname(sourcePath);
+  const base = sourcePath.slice(dir.length + 1);
+  return join(dir, `${base}.meta.json`);
+}
+async function decodeImageFromFile(sourcePath) {
+  const ext = extname(sourcePath).toLowerCase();
+  const mime = EXT_TO_MIME[ext];
+  if (mime === void 0) {
+    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;
+  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;
+  try {
+    sidecar = JSON.parse(sidecarText);
+  } 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 = settings.colorSpace ?? "srgb";
+  const mipmap = settings.mipmap ?? "auto";
+  const addressMode = settings.addressMode ?? "repeat";
+  const filterMode = settings.filterMode ?? "linear";
+  const guid = sidecar.subAssets[0]?.guid ?? "";
+  const meta = {
+    guid,
+    colorSpace,
+    mipmap,
+    addressMode,
+    filterMode
+  };
+  let bytes;
+  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
+      })
+    );
+  }
+  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);
+    const rgba8 = new Uint8Array(hdrRes.value.width * hdrRes.value.height * 4);
+    for (let i = 0; i < hdrRes.value.data.length; i++) {
+      const v = hdrRes.value.data[i];
+      const clamped = v !== void 0 ? Math.max(0, Math.min(1, v)) : 0;
+      rgba8[i] = Math.round(clamped * 255);
+    }
+    const decoded = {
+      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 });
+}
+
+export { decodeImageFromFile };
+//# sourceMappingURL=decode-image-from-file.mjs.map
+//# sourceMappingURL=decode-image-from-file.mjs.map