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

package/dist/image-importer.mjs

@@ -0,0 +1,1085 @@
+import { err, ok, ImportError, IMPORT_ERROR_HINTS, IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+import { parseKtx2, ktx2ColorSpace } from '@forgeax/engine-codec';
+import { basisEncode } from '@forgeax/engine-codec/encode';
+import * as jpeg from 'jpeg-js';
+import * as UPNG from 'upng-js';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+function imageError(detail) {
+  return new ImageErrorImpl(detail);
+}
+var IMAGE_ERROR_EXPECTED, ImageErrorImpl;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    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"
+    };
+    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;
+      }
+    };
+  }
+});
+var init_result = __esm({
+  "src/result.ts"() {
+  }
+});
+
+// src/hdr-decoder.ts
+var hdr_decoder_exports = {};
+__export(hdr_decoder_exports, {
+  decodeHdr: () => decodeHdr
+});
+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
+  });
+}
+var LF;
+var init_hdr_decoder = __esm({
+  "src/hdr-decoder.ts"() {
+    init_errors();
+    init_result();
+    LF = 10;
+  }
+});
+function resolveEncodeMode(mode, source) {
+  switch (mode) {
+    case "none":
+      return "none";
+    case "etc1s":
+      return "etc1s";
+    case "uastc":
+      return source.isHdr ? "uastc-hdr" : "uastc";
+    case "auto":
+      if (source.isHdr) return "uastc-hdr";
+      return source.colorSpace === "srgb" ? "etc1s" : "uastc";
+  }
+}
+function basisEncodeParamsFor(mode, source) {
+  const resolved = resolveEncodeMode(mode, source);
+  const srgbColor = source.colorSpace === "srgb";
+  switch (resolved) {
+    case "none":
+      return null;
+    case "etc1s":
+      return {
+        mode: "etc1s",
+        srgb: srgbColor,
+        perceptual: srgbColor,
+        uastcSupercompression: false,
+        mipGen: false
+      };
+    case "uastc":
+      return {
+        mode: "uastc-ldr",
+        srgb: srgbColor,
+        perceptual: srgbColor,
+        uastcSupercompression: true,
+        mipGen: false
+      };
+    case "uastc-hdr":
+      return {
+        mode: "uastc-hdr",
+        srgb: false,
+        perceptual: false,
+        uastcSupercompression: false,
+        mipGen: false
+      };
+  }
+}
+var MAX_ENCODE_SOURCE_PIXELS = 4096 * 4096;
+async function encodeTextureToKtx2(pixels, width, height, mode, source) {
+  const params = basisEncodeParamsFor(mode, source);
+  if (params === null) {
+    return {
+      ok: false,
+      error: {
+        code: "ktx2-encode-failed",
+        mode: "none",
+        reason: "compressionMode resolved to none"
+      }
+    };
+  }
+  const resolved = resolveEncodeMode(mode, source);
+  if (width * height > MAX_ENCODE_SOURCE_PIXELS) {
+    return {
+      ok: false,
+      error: {
+        code: "ktx2-encode-source-too-large",
+        mode: resolved,
+        reason: `source ${width}x${height} (${width * height} px) exceeds the ${MAX_ENCODE_SOURCE_PIXELS} px (4096x4096) Basis encode ceiling; reduce the texture resolution to <=4096x4096 or set compressionMode:'none' in the sidecar to keep it uncompressed`
+      }
+    };
+  }
+  const result = await basisEncode(pixels, {
+    mode: params.mode,
+    width,
+    height,
+    srgb: params.srgb,
+    perceptual: params.perceptual,
+    uastcSupercompression: params.uastcSupercompression,
+    mipGen: params.mipGen
+  });
+  if (!result.ok) {
+    const reason = result.error.detail !== void 0 && "reason" in result.error.detail ? String(result.error.detail.reason) : result.error.code;
+    return {
+      ok: false,
+      error: {
+        code: result.error.code === "codec-init-failed" ? "codec-init-failed" : "ktx2-encode-failed",
+        mode: resolved,
+        reason
+      }
+    };
+  }
+  return { ok: true, value: { ktx2: result.value, mode: resolved } };
+}
+
+// src/parse-image.ts
+init_errors();
+
+// 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
+init_result();
+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/image-importer.ts
+function mimeFromSource(source) {
+  const lower = source.toLowerCase();
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  return void 0;
+}
+function requiredImageOutputKind(source) {
+  const lower = source.toLowerCase();
+  if (lower.endsWith(".hdr")) return "equirect";
+  if (mimeFromSource(source) !== void 0 || lower.endsWith(".basis") || lower.endsWith(".ktx2")) {
+    return "texture";
+  }
+  return void 0;
+}
+function imageOutputTopologyActual(ctx) {
+  if (ctx.subAssets.length === 0) return "subAssets[] is empty";
+  return ctx.subAssets.map(
+    (sub, index) => `subAssets[${index}]=${sub.kind}:${sub.guid}:sourceIndex=${sub.sourceIndex}`
+  ).join(", ");
+}
+function imageConversionFailure(ctx, stage, ownerCode, sourcePath, expected, actual, hint) {
+  const diagnosticSourcePath = sourcePath.length === 0 ? ctx.source : sourcePath;
+  return new ImportError({
+    code: "source-validation-failed",
+    expected,
+    actual,
+    hint: IMPORT_ERROR_HINTS["source-validation-failed"],
+    detail: {
+      diagnostics: [
+        {
+          code: `image-conversion-${stage}-${ownerCode}`,
+          severity: "error",
+          sourcePath: diagnosticSourcePath,
+          sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+          rule: `image-conversion-${stage}`,
+          expected,
+          actual,
+          hint
+        }
+      ]
+    }
+  });
+}
+function validateImageOutputTopology(ctx, requiredKind) {
+  if (ctx.subAssets.length === 1 && ctx.subAssets[0]?.kind === requiredKind && ctx.subAssets[0]?.sourceIndex === 0) {
+    return void 0;
+  }
+  const expected = `exactly one subAssets[] entry with kind "${requiredKind}" and sourceIndex 0`;
+  const actual = imageOutputTopologyActual(ctx);
+  return new ImportError({
+    code: "source-validation-failed",
+    expected,
+    actual,
+    hint: IMPORT_ERROR_HINTS["source-validation-failed"],
+    detail: {
+      diagnostics: [
+        {
+          code: "image-subasset-topology",
+          severity: "error",
+          sourcePath: `${ctx.source}#subAssets`,
+          sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+          rule: "image-required-single-output",
+          expected,
+          actual,
+          hint: `declare exactly one ${requiredKind} sub-asset with sourceIndex 0 and remove foreign, duplicate, or misplaced entries`
+        }
+      ]
+    }
+  });
+}
+function mipmapTokenToBoolean(token) {
+  return token === "auto" || token === true;
+}
+function colorSpaceToFormat(colorSpace) {
+  return colorSpace === "srgb" ? "rgba8unorm-srgb" : "rgba8unorm";
+}
+async function inspectKtx2Source(ctx, bytes, metaColorSpace) {
+  const parsed = await parseKtx2(bytes);
+  if (!parsed.ok) {
+    return imageConversionFailure(
+      ctx,
+      "inspect",
+      "ktx2-parse",
+      ctx.source,
+      "a valid KTX2 container with a supported Basis profile",
+      `codec:${parsed.error.code}`,
+      "repair the KTX2 container and retry the image import"
+    );
+  }
+  const dfdColorSpace = ktx2ColorSpace(parsed.value);
+  if (dfdColorSpace === void 0) {
+    return imageConversionFailure(
+      ctx,
+      "inspect",
+      "ktx2-color-space-missing",
+      `${ctx.source}#DFD.transferFunction`,
+      "DFD transfer function to identify sRGB or linear color space",
+      "missing-or-unsupported-transfer-function",
+      "repair the KTX2 DFD color-space declaration before importing"
+    );
+  }
+  if (metaColorSpace !== void 0 && metaColorSpace !== dfdColorSpace) {
+    return imageConversionFailure(
+      ctx,
+      "inspect",
+      "ktx2-color-space-conflict",
+      `${ctx.source}#importSettings.colorSpace`,
+      "Meta.colorSpace to match the KTX2 DFD transfer function",
+      `meta=${metaColorSpace},dfd=${dfdColorSpace}`,
+      "repair Meta.colorSpace or re-encode the KTX2 source with matching color provenance"
+    );
+  }
+  const { pixelDepth, layerCount, faceCount } = parsed.value.header;
+  if (pixelDepth !== 0 || layerCount > 1 || faceCount !== 1) {
+    return imageConversionFailure(
+      ctx,
+      "inspect",
+      "ktx2-shape-unsupported",
+      `${ctx.source}#header`,
+      "a 2D, single-layer, single-face KTX2 texture",
+      `pixelDepth=${pixelDepth},layerCount=${layerCount},faceCount=${faceCount}`,
+      "re-encode the source as one 2D Basis texture"
+    );
+  }
+  const { initBasisTranscoder } = await import('@forgeax/engine-codec');
+  const module = await initBasisTranscoder();
+  let file;
+  try {
+    file = new module.KTX2File(bytes);
+  } catch {
+    return imageConversionFailure(
+      ctx,
+      "inspect",
+      "ktx2-invalid",
+      ctx.source,
+      "Basis KTX2File bytes to pass transcoder validation",
+      "basis-file-constructor-failed",
+      "repair or re-encode the KTX2 source before importing"
+    );
+  }
+  try {
+    try {
+      if (!file.isValid()) {
+        return imageConversionFailure(
+          ctx,
+          "inspect",
+          "ktx2-invalid",
+          ctx.source,
+          "Basis KTX2File bytes to pass transcoder validation",
+          "basis-file-invalid",
+          "repair or re-encode the KTX2 source before importing"
+        );
+      }
+      const profile = file.isETC1S() ? "etc1s" : file.isHDR() || file.isHDR4x4() ? "uastc-hdr" : file.isUASTC_LDR_4x4() ? "uastc-ldr" : void 0;
+      if (profile === void 0) {
+        return imageConversionFailure(
+          ctx,
+          "inspect",
+          "ktx2-profile-unsupported",
+          `${ctx.source}#Basis.profile`,
+          "ETC1S, UASTC-LDR, or UASTC-HDR Basis profile",
+          "unsupported-basis-profile",
+          "re-encode the source with ETC1S, UASTC-LDR, or UASTC-HDR"
+        );
+      }
+      if (profile === "uastc-hdr" && dfdColorSpace !== "linear") {
+        return imageConversionFailure(
+          ctx,
+          "inspect",
+          "ktx2-hdr-color-space-invalid",
+          `${ctx.source}#DFD.transferFunction`,
+          "UASTC-HDR source to use linear color space",
+          `profile=${profile},dfd=${dfdColorSpace}`,
+          "re-encode HDR data with a linear KTX2 DFD transfer function"
+        );
+      }
+      return {
+        colorSpace: dfdColorSpace,
+        profile,
+        width: file.getWidth(),
+        height: file.getHeight(),
+        levelCount: file.getLevels()
+      };
+    } catch {
+      return imageConversionFailure(
+        ctx,
+        "inspect",
+        "ktx2-invalid",
+        ctx.source,
+        "Basis KTX2File bytes to pass transcoder inspection",
+        "basis-inspection-threw",
+        "repair or re-encode the KTX2 source before importing"
+      );
+    }
+  } finally {
+    file.close();
+  }
+}
+async function importKtx2Source(ctx, bytes) {
+  const sourceKey = ctx.subAssets[0]?.sourceKey;
+  const metaColorSpace = sourceKey === void 0 ? ctx.importSettings.colorSpace : ctx.sourceOverrides?.[sourceKey]?.colorSpace;
+  const inspection = await inspectKtx2Source(
+    ctx,
+    bytes,
+    metaColorSpace === "srgb" || metaColorSpace === "linear" ? metaColorSpace : void 0
+  );
+  if (inspection instanceof ImportError) return { ok: false, error: inspection };
+  const out = [];
+  for (const sub of ctx.subAssets) {
+    if (sub.kind !== "texture" || sub.sourceIndex !== 0) continue;
+    out.push({
+      guid: sub.guid,
+      kind: "texture",
+      payload: {
+        kind: "texture",
+        width: inspection.width,
+        height: inspection.height,
+        format: colorSpaceToFormat(inspection.colorSpace),
+        data: bytes,
+        colorSpace: inspection.colorSpace,
+        mipmap: inspection.levelCount > 1,
+        mipLevelCount: inspection.levelCount
+      },
+      refs: [],
+      artifacts: {
+        body: {
+          mediaType: "image/ktx2",
+          assetCodec: {
+            name: "basis",
+            container: "ktx2",
+            profile: inspection.profile,
+            version: "1"
+          },
+          bytes
+        }
+      }
+    });
+  }
+  return { ok: true, value: { assets: out, sourceDependencies: [] } };
+}
+function basisMetaColorSpace(ctx) {
+  const sourceKey = ctx.subAssets[0]?.sourceKey;
+  const override = sourceKey === void 0 ? void 0 : ctx.sourceOverrides?.[sourceKey];
+  const value = override?.colorSpace ?? ctx.importSettings.colorSpace;
+  if (value !== "srgb" && value !== "linear") {
+    return imageConversionFailure(
+      ctx,
+      "inspect",
+      "basis-color-space-invalid",
+      `${ctx.source}#Meta.colorSpace`,
+      "Meta.colorSpace to be srgb or linear for raw Basis",
+      value === void 0 ? "missing" : `invalid:${String(value)}`,
+      "set Meta.colorSpace to srgb or linear before importing raw Basis bytes"
+    );
+  }
+  return value;
+}
+async function importBasisSource(ctx, bytes) {
+  const colorSpace = basisMetaColorSpace(ctx);
+  if (colorSpace instanceof ImportError) return { ok: false, error: colorSpace };
+  const { initBasisTranscoder, inspectBasisSource } = await import('@forgeax/engine-codec');
+  const module = await initBasisTranscoder();
+  if (module.BasisFile === void 0) {
+    throw new Error("basis-source-inspection-unavailable: transcoder lacks BasisFile");
+  }
+  let file;
+  try {
+    file = new module.BasisFile(bytes);
+  } catch {
+    return {
+      ok: false,
+      error: imageConversionFailure(
+        ctx,
+        "inspect",
+        "basis-source-invalid",
+        ctx.source,
+        "raw Basis bytes to pass transcoder validation",
+        "basis-file-invalid",
+        "repair or re-encode the raw Basis source before importing"
+      )
+    };
+  }
+  let inspection;
+  try {
+    try {
+      const format = file.getBasisTexFormat();
+      const profile = format === module.basis_tex_format.cETC1S.value ? "etc1s" : format === module.basis_tex_format.cUASTC_LDR_4x4.value ? "uastc-ldr" : void 0;
+      if (profile === void 0) {
+        return {
+          ok: false,
+          error: imageConversionFailure(
+            ctx,
+            "inspect",
+            "basis-profile-unsupported",
+            `${ctx.source}#Basis.profile`,
+            "ETC1S or UASTC-LDR raw Basis profile",
+            "unsupported-basis-profile",
+            "re-encode the source with ETC1S or UASTC-LDR"
+          )
+        };
+      }
+      const result = inspectBasisSource(file, { colorSpace }, profile);
+      if (!result.ok) {
+        return {
+          ok: false,
+          error: imageConversionFailure(
+            ctx,
+            "inspect",
+            "basis-inspection-failed",
+            ctx.source,
+            "raw Basis source metadata to pass codec inspection",
+            `codec:${result.error.code}`,
+            "repair the raw Basis source metadata and retry the import"
+          )
+        };
+      }
+      inspection = result.value;
+    } catch {
+      return {
+        ok: false,
+        error: imageConversionFailure(
+          ctx,
+          "inspect",
+          "basis-source-invalid",
+          ctx.source,
+          "raw Basis bytes to pass transcoder inspection",
+          "basis-inspection-threw",
+          "repair or re-encode the raw Basis source before importing"
+        )
+      };
+    }
+  } finally {
+    file.close();
+  }
+  if (inspection === void 0) {
+    return {
+      ok: false,
+      error: imageConversionFailure(
+        ctx,
+        "inspect",
+        "basis-inspection-failed",
+        ctx.source,
+        "raw Basis source metadata to be available after codec inspection",
+        "missing-inspection-result",
+        "repair the raw Basis source and retry the import"
+      )
+    };
+  }
+  const out = [];
+  for (const sub of ctx.subAssets) {
+    if (sub.kind !== "texture") continue;
+    if (sub.sourceIndex !== 0 || inspection.imageCount !== 1) {
+      return {
+        ok: false,
+        error: imageConversionFailure(
+          ctx,
+          "inspect",
+          "basis-image-shape-unsupported",
+          `${ctx.source}#Basis.images`,
+          "one raw Basis image at sourceIndex 0",
+          `imageCount=${inspection.imageCount},sourceIndex=${sub.sourceIndex}`,
+          "re-encode the source as one raw Basis image"
+        )
+      };
+    }
+    out.push({
+      guid: sub.guid,
+      kind: "texture",
+      payload: {
+        kind: "texture",
+        width: inspection.width,
+        height: inspection.height,
+        format: colorSpaceToFormat(colorSpace),
+        data: bytes,
+        colorSpace,
+        mipmap: inspection.levelCount > 1,
+        mipLevelCount: inspection.levelCount
+      },
+      refs: [],
+      artifacts: {
+        body: {
+          mediaType: "application/x-forgeax-basis",
+          assetCodec: {
+            name: "basis",
+            container: "basis",
+            profile: inspection.profile,
+            version: "1"
+          },
+          bytes
+        }
+      }
+    });
+  }
+  return { ok: true, value: { assets: out, sourceDependencies: [] } };
+}
+function compressionModeToken(token) {
+  if (token === "auto" || token === "etc1s" || token === "uastc" || token === "none") {
+    return token;
+  }
+  return "none";
+}
+async function maybeEncodeTextureBytes(ctx, pixels, width, height, compressionMode, colorSpace, isHdr) {
+  if (resolveEncodeMode(compressionMode, { colorSpace, isHdr }) === "none") {
+    return { ok: true, value: null };
+  }
+  const result = await encodeTextureToKtx2(pixels, width, height, compressionMode, {
+    colorSpace,
+    isHdr
+  });
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: imageConversionFailure(
+        ctx,
+        "encode",
+        result.error.code === "ktx2-encode-source-too-large" ? "ktx2-source-too-large" : "ktx2-encode-refused",
+        `${ctx.source}#compressionMode`,
+        "the requested compression mode to accept the decoded image",
+        `codec:${result.error.code},mode:${result.error.mode}`,
+        result.error.code === "ktx2-encode-source-too-large" ? "reduce source dimensions or set compressionMode to none" : "repair the source image or compression settings and retry the import"
+      )
+    };
+  }
+  return { ok: true, value: result.value.ktx2 };
+}
+async function importImage(ctx) {
+  const requiredKind = requiredImageOutputKind(ctx.source);
+  if (requiredKind !== void 0) {
+    const topologyError = validateImageOutputTopology(ctx, requiredKind);
+    if (topologyError !== void 0) return { ok: false, error: topologyError };
+  }
+  const read = await ctx.readSource();
+  if (!read.ok) {
+    return {
+      ok: false,
+      error: new ImportError({
+        code: "source-read-failed",
+        expected: `readable source file at "${ctx.source}"`,
+        hint: IMPORT_ERROR_HINTS["source-read-failed"],
+        detail: {
+          source: ctx.source,
+          reason: read.error instanceof Error ? read.error.message : String(read.error)
+        }
+      })
+    };
+  }
+  const mime = mimeFromSource(ctx.source);
+  if (ctx.source.toLowerCase().endsWith(".basis")) {
+    return importBasisSource(ctx, read.value);
+  }
+  if (ctx.source.toLowerCase().endsWith(".ktx2")) {
+    return importKtx2Source(ctx, read.value);
+  }
+  if (mime === void 0 && ctx.source.toLowerCase().endsWith(".hdr")) {
+    const { decodeHdr: decodeHdr2 } = await Promise.resolve().then(() => (init_hdr_decoder(), hdr_decoder_exports));
+    const decoded2 = decodeHdr2(read.value);
+    if (!decoded2.ok) {
+      return {
+        ok: false,
+        error: imageConversionFailure(
+          ctx,
+          "decode",
+          "hdr",
+          ctx.source,
+          "valid Radiance RGBE bytes to decode into an equirect asset",
+          `image:${decoded2.error.code}`,
+          "repair the HDR header or pixel payload and retry the import"
+        )
+      };
+    }
+    const dec2 = decoded2.value;
+    const { halfFloat } = await import('@forgeax/engine-math');
+    const f16Bytes = halfFloat.f32ToF16Bytes(
+      new Uint8Array(dec2.data.buffer, dec2.data.byteOffset, dec2.data.byteLength)
+    );
+    const out2 = [];
+    for (const sub of ctx.subAssets) {
+      if (sub.kind !== "equirect") continue;
+      const payload = {
+        kind: "equirect",
+        width: dec2.width,
+        height: dec2.height,
+        format: "rgba16float",
+        data: f16Bytes,
+        colorSpace: "linear"
+      };
+      out2.push({
+        guid: sub.guid,
+        kind: "equirect",
+        payload,
+        refs: [],
+        artifacts: {
+          body: {
+            mediaType: "application/x-forgeax-rgba16f",
+            assetCodec: { name: "rgba16float" },
+            bytes: f16Bytes
+          }
+        }
+      });
+    }
+    return { ok: true, value: { assets: out2, sourceDependencies: [] } };
+  }
+  if (mime === void 0) {
+    throw new Error(
+      `imageImporter: unsupported source extension for "${ctx.source}" (expected .png / .jpg / .jpeg / .hdr / .ktx2 / .basis)`
+    );
+  }
+  const colorSpace = ctx.importSettings.colorSpace === "srgb" ? "srgb" : "linear";
+  const mipmap = mipmapTokenToBoolean(ctx.importSettings.mipmap);
+  const compressionMode = compressionModeToken(ctx.importSettings.compressionMode);
+  const downscaleMaxDimension = typeof ctx.importSettings.downscaleMaxDimension === "number" && Number.isInteger(ctx.importSettings.downscaleMaxDimension) && ctx.importSettings.downscaleMaxDimension > 0 ? ctx.importSettings.downscaleMaxDimension : void 0;
+  const decoded = parseImage(read.value, mime, {
+    colorSpace,
+    mipmap,
+    ...downscaleMaxDimension !== void 0 ? { downscaleMaxDimension } : {}
+  });
+  if (!decoded.ok) {
+    return {
+      ok: false,
+      error: imageConversionFailure(
+        ctx,
+        "decode",
+        "ldr",
+        ctx.source,
+        "valid PNG or JPEG bytes to decode into RGBA pixels",
+        `image:${decoded.error.code}`,
+        "repair the source image bytes and retry the import"
+      )
+    };
+  }
+  const dec = decoded.value;
+  const encoded = await maybeEncodeTextureBytes(
+    ctx,
+    dec.bytes,
+    dec.width,
+    dec.height,
+    compressionMode,
+    colorSpace,
+    false
+  );
+  if (!encoded.ok) return encoded;
+  const encodedBytes = encoded.value;
+  const out = [];
+  for (const sub of ctx.subAssets) {
+    if (sub.kind !== "texture") continue;
+    const payload = {
+      kind: "texture",
+      width: dec.width,
+      height: dec.height,
+      format: colorSpaceToFormat(colorSpace),
+      data: encodedBytes ?? dec.bytes,
+      colorSpace,
+      mipmap
+    };
+    out.push({
+      guid: sub.guid,
+      kind: "texture",
+      payload,
+      refs: [],
+      artifacts: {
+        body: {
+          mediaType: encodedBytes === null ? "application/x-forgeax-rgba8" : "image/ktx2",
+          assetCodec: encodedBytes === null ? { name: "rgba8", version: "1" } : {
+            name: "basis",
+            container: "ktx2",
+            profile: resolveEncodeMode(compressionMode, { colorSpace, isHdr: false })
+          },
+          bytes: encodedBytes ?? dec.bytes
+        }
+      }
+    });
+  }
+  return { ok: true, value: { assets: out, sourceDependencies: [] } };
+}
+var decodeImageForImport = async (bytes, mimeType, importSettings) => {
+  const colorSpace = importSettings.colorSpace === "srgb" || importSettings.colorSpace === "linear" ? importSettings.colorSpace : "linear";
+  const mipmap = importSettings.mipmap === true;
+  const downscaleMaxDimension = typeof importSettings.downscaleMaxDimension === "number" && Number.isInteger(importSettings.downscaleMaxDimension) && importSettings.downscaleMaxDimension > 0 ? importSettings.downscaleMaxDimension : void 0;
+  const decoded = parseImage(bytes, mimeType, {
+    colorSpace,
+    mipmap,
+    ...downscaleMaxDimension === void 0 ? {} : { downscaleMaxDimension }
+  });
+  if (!decoded.ok) return decoded;
+  const tex = decoded.value;
+  const requestedCompression = importSettings.compressionMode === "auto" || importSettings.compressionMode === "etc1s" || importSettings.compressionMode === "uastc" || importSettings.compressionMode === "none" ? importSettings.compressionMode : "none";
+  const resolvedCompression = resolveEncodeMode(requestedCompression, {
+    colorSpace,
+    isHdr: false
+  });
+  let cookedBytes = tex.bytes;
+  let mediaType = mimeType;
+  let assetCodec = {
+    name: "rgba8",
+    version: "1"
+  };
+  if (resolvedCompression !== "none") {
+    const encoded = await encodeTextureToKtx2(
+      tex.bytes,
+      tex.width,
+      tex.height,
+      requestedCompression,
+      { colorSpace, isHdr: false }
+    );
+    if (!encoded.ok) {
+      throw new Error(
+        `embedded texture compression failed (${encoded.error.code} / ${encoded.error.mode}): ${encoded.error.reason}`
+      );
+    }
+    cookedBytes = encoded.value.ktx2;
+    mediaType = "image/ktx2";
+    assetCodec = { name: "basis", profile: encoded.value.mode };
+  }
+  return {
+    ok: true,
+    value: {
+      texture: {
+        kind: "texture",
+        data: cookedBytes,
+        width: tex.width,
+        height: tex.height,
+        format: colorSpaceToFormat(colorSpace),
+        colorSpace,
+        mipmap
+      },
+      bytes: cookedBytes,
+      mediaType,
+      assetCodec
+    }
+  };
+};
+var imageImporter = {
+  key: "image",
+  import: importImage,
+  capabilities: { decodeImage: decodeImageForImport }
+};
+
+export { decodeImageForImport, imageImporter };
+//# sourceMappingURL=image-importer.mjs.map
+//# sourceMappingURL=image-importer.mjs.map