@forgeax/engine-image 0.1.2

package/dist/ktx2-encode.d.ts

@@ -0,0 +1,84 @@
+import type { BasisEncodeMode } from '@forgeax/engine-codec/encode';
+declare const COMPRESSION_MODES: readonly ["auto", "etc1s", "uastc", "none"];
+/** The sidecar control-plane value (ImageMetadata.compressionMode). */
+export type CompressionMode = (typeof COMPRESSION_MODES)[number];
+declare const RESOLVED_ENCODE_MODES: readonly ["etc1s", "uastc", "uastc-hdr", "none"];
+/** The resolved delivery encoding after 'auto' derivation. `'none'` = no encode. */
+export type ResolvedEncodeMode = (typeof RESOLVED_ENCODE_MODES)[number];
+/** Source signals that drive 'auto' derivation (D-12) and encoder params. */
+export interface EncodeSourceInfo {
+    /** Color transfer of the source (from the sidecar importSettings). */
+    readonly colorSpace: 'srgb' | 'linear';
+    /** Whether the source is an HDR image (.hdr -> rgba16float). */
+    readonly isHdr: boolean;
+}
+/**
+ * Resolve the sidecar `compressionMode` into a concrete delivery encoding.
+ *
+ * D-12 'auto' derivation (zero new required inputs, derived from existing
+ * sidecar signals):
+ *   - HDR source            -> 'uastc-hdr'  (BC6H target downstream)
+ *   - colorSpace 'srgb'     -> 'etc1s'      (albedo / UI color)
+ *   - colorSpace 'linear'   -> 'uastc'      (normals / ORM / data)
+ *
+ * Explicit modes pass through, except an explicit 'uastc' on an HDR source
+ * resolves to 'uastc-hdr' (there is no LDR UASTC path for HDR pixels). 'none'
+ * and 'etc1s' pass through verbatim.
+ */
+export declare function resolveEncodeMode(mode: CompressionMode, source: EncodeSourceInfo): ResolvedEncodeMode;
+/** Encoder parameters for a resolved delivery encoding. */
+export interface BasisEncodeParams {
+    /** The codec-side delivery encoding. */
+    readonly mode: BasisEncodeMode;
+    /** Write the sRGB transfer function (LDR color only). */
+    readonly srgb: boolean;
+    /** ETC1S perceptual (sRGB) metric. */
+    readonly perceptual: boolean;
+    /** Wrap the UASTC-LDR payload in KTX2 zstd supercompression. */
+    readonly uastcSupercompression: boolean;
+    /** Encoder-side mip generation. M3 keeps this false (offline mips land in M5). */
+    readonly mipGen: boolean;
+}
+/**
+ * Map the sidecar mode + source into encoder parameters. Returns `null` for the
+ * 'none' path -- the caller keeps the uncompressed `.bin` path and never calls
+ * the encoder.
+ */
+export declare function basisEncodeParamsFor(mode: CompressionMode, source: EncodeSourceInfo): BasisEncodeParams | null;
+/** A successful encode result: KTX2 bytes + the resolved delivery encoding. */
+export interface EncodedTexture {
+    readonly ktx2: Uint8Array;
+    readonly mode: ResolvedEncodeMode;
+}
+/**
+ * Maximum source pixels the wasm32 Basis encoder accepts (4096x4096 = 16.78 Mpx
+ * = 1024*1024*16). This mirrors the raised `BASISU_ENCODER_MAX_SOURCE_IMAGE_PIXELS`
+ * ceiling patched into the encoder WASM (packages/codec/scripts/build-wasm.mjs).
+ * Sources above this are rejected fast with a structured `ktx2-encode-source-too-large`
+ * error rather than reaching the encoder and getting a silent 0-byte failure.
+ */
+export declare const MAX_ENCODE_SOURCE_PIXELS: number;
+/** Failure result carrying a short reason (encoder-side or invalid request). */
+export interface EncodeFailure {
+    readonly code: 'ktx2-encode-failed' | 'codec-init-failed' | 'ktx2-encode-source-too-large';
+    readonly mode: ResolvedEncodeMode;
+    readonly reason: string;
+}
+export type EncodeTextureResult = {
+    readonly ok: true;
+    readonly value: EncodedTexture;
+} | {
+    readonly ok: false;
+    readonly error: EncodeFailure;
+};
+/**
+ * Encode source pixels into a Basis KTX2 texture per the sidecar mode.
+ *
+ * `pixels` is tight-packed RGBA: 8-bit RGBA for LDR sources, rgba16float bytes
+ * for HDR sources. Returns `{ ok: false }` with `mode: 'none'` if the sidecar
+ * mode resolves to 'none' -- the importer treats that as "no encode, keep the
+ * .bin path" rather than an error (see importer callsite w18).
+ */
+export declare function encodeTextureToKtx2(pixels: Uint8Array, width: number, height: number, mode: CompressionMode, source: EncodeSourceInfo): Promise<EncodeTextureResult>;
+export {};
+//# sourceMappingURL=ktx2-encode.d.ts.map

package/dist/ktx2-encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-encode.d.ts","sourceRoot":"","sources":["../src/ktx2-encode.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,QAAA,MAAM,iBAAiB,6CAA8C,CAAC;AAEtE,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,QAAA,MAAM,qBAAqB,kDAAmD,CAAC;AAE/E,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAAC;IACvC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,gBAAgB,GACvB,kBAAkB,CAYpB;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,gBAAgB,GACvB,iBAAiB,GAAG,IAAI,CA+B1B;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;CACnC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,QAAc,CAAC;AAEpD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,mBAAmB,GAAG,8BAA8B,CAAC;IAC3F,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAuD9B"}

package/dist/ktx2-encode.mjs

@@ -0,0 +1,100 @@
+import { basisEncode } from '@forgeax/engine-codec/encode';
+
+// src/ktx2-encode.ts
+var COMPRESSION_MODES = ["auto", "etc1s", "uastc", "none"];
+var RESOLVED_ENCODE_MODES = ["etc1s", "uastc", "uastc-hdr", "none"];
+function resolveEncodeMode(mode, source) {
+  switch (mode) {
+    case COMPRESSION_MODES[3]:
+      return RESOLVED_ENCODE_MODES[3];
+    case COMPRESSION_MODES[1]:
+      return RESOLVED_ENCODE_MODES[0];
+    case COMPRESSION_MODES[2]:
+      return source.isHdr ? RESOLVED_ENCODE_MODES[2] : RESOLVED_ENCODE_MODES[1];
+    case COMPRESSION_MODES[0]:
+      if (source.isHdr) return RESOLVED_ENCODE_MODES[2];
+      return source.colorSpace === "srgb" ? RESOLVED_ENCODE_MODES[0] : RESOLVED_ENCODE_MODES[1];
+  }
+}
+function basisEncodeParamsFor(mode, source) {
+  const resolved = resolveEncodeMode(mode, source);
+  const srgbColor = source.colorSpace === "srgb";
+  switch (resolved) {
+    case RESOLVED_ENCODE_MODES[3]:
+      return null;
+    case RESOLVED_ENCODE_MODES[0]:
+      return {
+        mode: RESOLVED_ENCODE_MODES[0],
+        srgb: srgbColor,
+        perceptual: srgbColor,
+        uastcSupercompression: false,
+        mipGen: false
+      };
+    case RESOLVED_ENCODE_MODES[1]:
+      return {
+        mode: "uastc-ldr",
+        srgb: srgbColor,
+        perceptual: srgbColor,
+        uastcSupercompression: true,
+        mipGen: false
+      };
+    case RESOLVED_ENCODE_MODES[2]:
+      return {
+        mode: RESOLVED_ENCODE_MODES[2],
+        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 } };
+}
+
+export { MAX_ENCODE_SOURCE_PIXELS, basisEncodeParamsFor, encodeTextureToKtx2, resolveEncodeMode };
+//# sourceMappingURL=ktx2-encode.mjs.map
+//# sourceMappingURL=ktx2-encode.mjs.map

package/dist/ktx2-encode.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ktx2-encode.ts"],"names":[],"mappings":";;;AAsBA,IAAM,iBAAA,GAAoB,CAAC,MAAA,EAAQ,OAAA,EAAS,SAAS,MAAM,CAAA;AAK3D,IAAM,qBAAA,GAAwB,CAAC,OAAA,EAAS,OAAA,EAAS,aAAa,MAAM,CAAA;AA0B7D,SAAS,iBAAA,CACd,MACA,MAAA,EACoB;AACpB,EAAA,QAAQ,IAAA;AAAM,IACZ,KAAK,kBAAkB,CAAC,CAAA;AACtB,MAAA,OAAO,sBAAsB,CAAC,CAAA;AAAA,IAChC,KAAK,kBAAkB,CAAC,CAAA;AACtB,MAAA,OAAO,sBAAsB,CAAC,CAAA;AAAA,IAChC,KAAK,kBAAkB,CAAC,CAAA;AACtB,MAAA,OAAO,OAAO,KAAA,GAAQ,qBAAA,CAAsB,CAAC,CAAA,GAAI,sBAAsB,CAAC,CAAA;AAAA,IAC1E,KAAK,kBAAkB,CAAC,CAAA;AACtB,MAAA,IAAI,MAAA,CAAO,KAAA,EAAO,OAAO,qBAAA,CAAsB,CAAC,CAAA;AAChD,MAAA,OAAO,OAAO,UAAA,KAAe,MAAA,GAAS,sBAAsB,CAAC,CAAA,GAAI,sBAAsB,CAAC,CAAA;AAAA;AAE9F;AAqBO,SAAS,oBAAA,CACd,MACA,MAAA,EAC0B;AAC1B,EAAA,MAAM,QAAA,GAAW,iBAAA,CAAkB,IAAA,EAAM,MAAM,CAAA;AAC/C,EAAA,MAAM,SAAA,GAAY,OAAO,UAAA,KAAe,MAAA;AACxC,EAAA,QAAQ,QAAA;AAAU,IAChB,KAAK,sBAAsB,CAAC,CAAA;AAC1B,MAAA,OAAO,IAAA;AAAA,IACT,KAAK,sBAAsB,CAAC,CAAA;AAC1B,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,sBAAsB,CAAC,CAAA;AAAA,QAC7B,IAAA,EAAM,SAAA;AAAA,QACN,UAAA,EAAY,SAAA;AAAA,QACZ,qBAAA,EAAuB,KAAA;AAAA,QACvB,MAAA,EAAQ;AAAA,OACV;AAAA,IACF,KAAK,sBAAsB,CAAC,CAAA;AAC1B,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,WAAA;AAAA,QACN,IAAA,EAAM,SAAA;AAAA,QACN,UAAA,EAAY,SAAA;AAAA,QACZ,qBAAA,EAAuB,IAAA;AAAA,QACvB,MAAA,EAAQ;AAAA,OACV;AAAA,IACF,KAAK,sBAAsB,CAAC,CAAA;AAC1B,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,sBAAsB,CAAC,CAAA;AAAA,QAC7B,IAAA,EAAM,KAAA;AAAA,QACN,UAAA,EAAY,KAAA;AAAA,QACZ,qBAAA,EAAuB,KAAA;AAAA,QACvB,MAAA,EAAQ;AAAA,OACV;AAAA;AAEN;AAeO,IAAM,2BAA2B,IAAA,GAAO;AAqB/C,eAAsB,mBAAA,CACpB,MAAA,EACA,KAAA,EACA,MAAA,EACA,MACA,MAAA,EAC8B;AAC9B,EAAA,MAAM,MAAA,GAAS,oBAAA,CAAqB,IAAA,EAAM,MAAM,CAAA;AAChD,EAAA,IAAI,WAAW,IAAA,EAAM;AACnB,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,KAAA,EAAO;AAAA,QACL,IAAA,EAAM,oBAAA;AAAA,QACN,IAAA,EAAM,MAAA;AAAA,QACN,MAAA,EAAQ;AAAA;AACV,KACF;AAAA,EACF;AACA,EAAA,MAAM,QAAA,GAAW,iBAAA,CAAkB,IAAA,EAAM,MAAM,CAAA;AAK/C,EAAA,IAAI,KAAA,GAAQ,SAAS,wBAAA,EAA0B;AAC7C,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,KAAA,EAAO;AAAA,QACL,IAAA,EAAM,8BAAA;AAAA,QACN,IAAA,EAAM,QAAA;AAAA,QACN,MAAA,EACE,UAAU,KAAK,CAAA,CAAA,EAAI,MAAM,CAAA,EAAA,EAAK,KAAA,GAAQ,MAAM,CAAA,iBAAA,EAAoB,wBAAwB,CAAA,uJAAA;AAAA;AAG5F,KACF;AAAA,EACF;AACA,EAAA,MAAM,MAAA,GAAS,MAAM,WAAA,CAAY,MAAA,EAAQ;AAAA,IACvC,MAAM,MAAA,CAAO,IAAA;AAAA,IACb,KAAA;AAAA,IACA,MAAA;AAAA,IACA,MAAM,MAAA,CAAO,IAAA;AAAA,IACb,YAAY,MAAA,CAAO,UAAA;AAAA,IACnB,uBAAuB,MAAA,CAAO,qBAAA;AAAA,IAC9B,QAAQ,MAAA,CAAO;AAAA,GAChB,CAAA;AACD,EAAA,IAAI,CAAC,OAAO,EAAA,EAAI;AACd,IAAA,MAAM,SACJ,MAAA,CAAO,KAAA,CAAM,MAAA,KAAW,MAAA,IAAa,YAAY,MAAA,CAAO,KAAA,CAAM,MAAA,GAC1D,MAAA,CAAQ,OAAO,KAAA,CAAM,MAAA,CAA+B,MAAM,CAAA,GAC1D,OAAO,KAAA,CAAM,IAAA;AACnB,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,KAAA,EAAO;AAAA,QACL,IAAA,EACE,MAAA,CAAO,KAAA,CAAM,IAAA,KAAS,sBAAsB,mBAAA,GAAsB,oBAAA;AAAA,QACpE,IAAA,EAAM,QAAA;AAAA,QACN;AAAA;AACF,KACF;AAAA,EACF;AACA,EAAA,OAAO,EAAE,EAAA,EAAI,IAAA,EAAM,KAAA,EAAO,EAAE,MAAM,MAAA,CAAO,KAAA,EAAO,IAAA,EAAM,QAAA,EAAS,EAAE;AACnE","file":"ktx2-encode.mjs","sourcesContent":["// ktx2-encode.ts -- the image-side offline texture encode arm (M3 w18, D-5).\n//\n// This module is the image-semantic layer of the Basis encode path: it maps the\n// sidecar `compressionMode` control-plane value + the source's colorSpace / HDR\n// signal into a delivery encoding (D-12 'auto' derivation), maps that to the\n// encoder parameters, and drives the low-level `basisEncode` binding that lives\n// in `@forgeax/engine-codec/encode` (the WASM + enum plumbing stays in codec;\n// the image semantics stay here -- D-5 \"arm in image, binary in codec/encode\").\n//\n// It is a NODE-ONLY build-time module (consumed by imageImporter, itself a\n// node-only sub-export). It never touches GPU (isolation path b) and is never\n// bundled into the runtime (isolation path a/d: runtime does not import\n// @forgeax/engine-image nor @forgeax/engine-codec/encode).\n//\n// M3 sequencing constraint (plan R-9): the 'auto' derivation is implemented and\n// tested here, but the sidecar DEFAULT stays 'none'. The default flip to 'auto'\n// is M5 (w38); doing it here would make every existing texture encode to Basis\n// ahead of loader support and redden the whole fixture fleet.\n\nimport type { BasisEncodeMode } from '@forgeax/engine-codec/encode';\nimport { basisEncode } from '@forgeax/engine-codec/encode';\n\nconst COMPRESSION_MODES = ['auto', 'etc1s', 'uastc', 'none'] as const;\n\n/** The sidecar control-plane value (ImageMetadata.compressionMode). */\nexport type CompressionMode = (typeof COMPRESSION_MODES)[number];\n\nconst RESOLVED_ENCODE_MODES = ['etc1s', 'uastc', 'uastc-hdr', 'none'] as const;\n\n/** The resolved delivery encoding after 'auto' derivation. `'none'` = no encode. */\nexport type ResolvedEncodeMode = (typeof RESOLVED_ENCODE_MODES)[number];\n\n/** Source signals that drive 'auto' derivation (D-12) and encoder params. */\nexport interface EncodeSourceInfo {\n  /** Color transfer of the source (from the sidecar importSettings). */\n  readonly colorSpace: 'srgb' | 'linear';\n  /** Whether the source is an HDR image (.hdr -> rgba16float). */\n  readonly isHdr: boolean;\n}\n\n/**\n * Resolve the sidecar `compressionMode` into a concrete delivery encoding.\n *\n * D-12 'auto' derivation (zero new required inputs, derived from existing\n * sidecar signals):\n *   - HDR source            -> 'uastc-hdr'  (BC6H target downstream)\n *   - colorSpace 'srgb'     -> 'etc1s'      (albedo / UI color)\n *   - colorSpace 'linear'   -> 'uastc'      (normals / ORM / data)\n *\n * Explicit modes pass through, except an explicit 'uastc' on an HDR source\n * resolves to 'uastc-hdr' (there is no LDR UASTC path for HDR pixels). 'none'\n * and 'etc1s' pass through verbatim.\n */\nexport function resolveEncodeMode(\n  mode: CompressionMode,\n  source: EncodeSourceInfo,\n): ResolvedEncodeMode {\n  switch (mode) {\n    case COMPRESSION_MODES[3]:\n      return RESOLVED_ENCODE_MODES[3];\n    case COMPRESSION_MODES[1]:\n      return RESOLVED_ENCODE_MODES[0];\n    case COMPRESSION_MODES[2]:\n      return source.isHdr ? RESOLVED_ENCODE_MODES[2] : RESOLVED_ENCODE_MODES[1];\n    case COMPRESSION_MODES[0]:\n      if (source.isHdr) return RESOLVED_ENCODE_MODES[2];\n      return source.colorSpace === 'srgb' ? RESOLVED_ENCODE_MODES[0] : RESOLVED_ENCODE_MODES[1];\n  }\n}\n\n/** Encoder parameters for a resolved delivery encoding. */\nexport interface BasisEncodeParams {\n  /** The codec-side delivery encoding. */\n  readonly mode: BasisEncodeMode;\n  /** Write the sRGB transfer function (LDR color only). */\n  readonly srgb: boolean;\n  /** ETC1S perceptual (sRGB) metric. */\n  readonly perceptual: boolean;\n  /** Wrap the UASTC-LDR payload in KTX2 zstd supercompression. */\n  readonly uastcSupercompression: boolean;\n  /** Encoder-side mip generation. M3 keeps this false (offline mips land in M5). */\n  readonly mipGen: boolean;\n}\n\n/**\n * Map the sidecar mode + source into encoder parameters. Returns `null` for the\n * 'none' path -- the caller keeps the uncompressed `.bin` path and never calls\n * the encoder.\n */\nexport function basisEncodeParamsFor(\n  mode: CompressionMode,\n  source: EncodeSourceInfo,\n): BasisEncodeParams | null {\n  const resolved = resolveEncodeMode(mode, source);\n  const srgbColor = source.colorSpace === 'srgb';\n  switch (resolved) {\n    case RESOLVED_ENCODE_MODES[3]:\n      return null;\n    case RESOLVED_ENCODE_MODES[0]:\n      return {\n        mode: RESOLVED_ENCODE_MODES[0],\n        srgb: srgbColor,\n        perceptual: srgbColor,\n        uastcSupercompression: false,\n        mipGen: false,\n      };\n    case RESOLVED_ENCODE_MODES[1]:\n      return {\n        mode: 'uastc-ldr',\n        srgb: srgbColor,\n        perceptual: srgbColor,\n        uastcSupercompression: true,\n        mipGen: false,\n      };\n    case RESOLVED_ENCODE_MODES[2]:\n      return {\n        mode: RESOLVED_ENCODE_MODES[2],\n        srgb: false,\n        perceptual: false,\n        uastcSupercompression: false,\n        mipGen: false,\n      };\n  }\n}\n\n/** A successful encode result: KTX2 bytes + the resolved delivery encoding. */\nexport interface EncodedTexture {\n  readonly ktx2: Uint8Array;\n  readonly mode: ResolvedEncodeMode;\n}\n\n/**\n * Maximum source pixels the wasm32 Basis encoder accepts (4096x4096 = 16.78 Mpx\n * = 1024*1024*16). This mirrors the raised `BASISU_ENCODER_MAX_SOURCE_IMAGE_PIXELS`\n * ceiling patched into the encoder WASM (packages/codec/scripts/build-wasm.mjs).\n * Sources above this are rejected fast with a structured `ktx2-encode-source-too-large`\n * error rather than reaching the encoder and getting a silent 0-byte failure.\n */\nexport const MAX_ENCODE_SOURCE_PIXELS = 4096 * 4096;\n\n/** Failure result carrying a short reason (encoder-side or invalid request). */\nexport interface EncodeFailure {\n  readonly code: 'ktx2-encode-failed' | 'codec-init-failed' | 'ktx2-encode-source-too-large';\n  readonly mode: ResolvedEncodeMode;\n  readonly reason: string;\n}\n\nexport type EncodeTextureResult =\n  | { readonly ok: true; readonly value: EncodedTexture }\n  | { readonly ok: false; readonly error: EncodeFailure };\n\n/**\n * Encode source pixels into a Basis KTX2 texture per the sidecar mode.\n *\n * `pixels` is tight-packed RGBA: 8-bit RGBA for LDR sources, rgba16float bytes\n * for HDR sources. Returns `{ ok: false }` with `mode: 'none'` if the sidecar\n * mode resolves to 'none' -- the importer treats that as \"no encode, keep the\n * .bin path\" rather than an error (see importer callsite w18).\n */\nexport async function encodeTextureToKtx2(\n  pixels: Uint8Array,\n  width: number,\n  height: number,\n  mode: CompressionMode,\n  source: EncodeSourceInfo,\n): Promise<EncodeTextureResult> {\n  const params = basisEncodeParamsFor(mode, source);\n  if (params === null) {\n    return {\n      ok: false,\n      error: {\n        code: 'ktx2-encode-failed',\n        mode: 'none',\n        reason: 'compressionMode resolved to none',\n      },\n    };\n  }\n  const resolved = resolveEncodeMode(mode, source);\n  // Fail fast above the wasm32 encoder's source-pixel ceiling (4096^2). Above\n  // this the encoder returns 0 bytes silently; surface a structured, actionable\n  // error instead so the importer reports \"reduce resolution or set\n  // compressionMode:'none'\" rather than an opaque encode failure.\n  if (width * height > MAX_ENCODE_SOURCE_PIXELS) {\n    return {\n      ok: false,\n      error: {\n        code: 'ktx2-encode-source-too-large',\n        mode: resolved,\n        reason:\n          `source ${width}x${height} (${width * height} px) exceeds the ${MAX_ENCODE_SOURCE_PIXELS} px ` +\n          '(4096x4096) Basis encode ceiling; reduce the texture resolution to <=4096x4096 ' +\n          \"or set compressionMode:'none' in the sidecar to keep it uncompressed\",\n      },\n    };\n  }\n  const result = await basisEncode(pixels, {\n    mode: params.mode,\n    width,\n    height,\n    srgb: params.srgb,\n    perceptual: params.perceptual,\n    uastcSupercompression: params.uastcSupercompression,\n    mipGen: params.mipGen,\n  });\n  if (!result.ok) {\n    const reason =\n      result.error.detail !== undefined && 'reason' in result.error.detail\n        ? String((result.error.detail as { reason: unknown }).reason)\n        : result.error.code;\n    return {\n      ok: false,\n      error: {\n        code:\n          result.error.code === 'codec-init-failed' ? 'codec-init-failed' : 'ktx2-encode-failed',\n        mode: resolved,\n        reason,\n      },\n    };\n  }\n  return { ok: true, value: { ktx2: result.value, mode: resolved } };\n}\n"]}

package/dist/parse-image.d.ts

@@ -0,0 +1,48 @@
+import type { DecodedImage, ImageColorSpace, ImageError } from '@forgeax/engine-types';
+import type { Result } from './result.js';
+export interface ParseImageOptions {
+    /**
+     * Maximum allowed dimension (width or height). Defaults to 16384 -- the
+     * conservative WebGPU `maxTextureDimension2D` floor across desktop +
+     * high-end mobile (research F-3 / spec). Test fixtures pass smaller
+     * values to exercise the bounds-check code path with tiny fixtures.
+     */
+    readonly maxDimension?: number;
+    /** Optional asset-owned cooked-payload target; source bytes remain unchanged. */
+    readonly downscaleMaxDimension?: number;
+    /**
+     * Sidecar `colorSpace` carried over to the DecodedImage POD. Defaults to
+     * 'srgb' (typical baseColor / albedo path; plan-strategy section 2.5).
+     */
+    readonly colorSpace?: ImageColorSpace;
+    /**
+     * Sidecar `mipmap` flag carried over to DecodedImage. Defaults to true
+     * (auto-generate via runtime mipmap-generator; plan-strategy section 2.6).
+     */
+    readonly mipmap?: boolean;
+    /**
+     * Optional source path to embed in error.detail.path (decode-failed /
+     * format-unsupported variants). decodeImageFromFile fills this in;
+     * in-memory parseImage callers leave it empty.
+     */
+    readonly path?: string;
+}
+/**
+ * Pure synchronous image decoder. Translates raw byte stream + mime hint
+ * into a tight-packed RGBA `DecodedImage` POD. Surfaces all four
+ * ImageErrorCode members through the structured `Result<DecodedImage,
+ * ImageError>` return (charter P3 explicit failure; AGENTS.md "Return
+ * Result, never throw").
+ *
+ * Decoder selection follows the mime hint:
+ * - `image/png` -> upng-js `UPNG.decode` + `UPNG.toRGBA8`
+ * - `image/jpeg` -> jpeg-js `decode` with `formatAsRGBA: true`
+ * - `image/x-tga` -> the built-in TGA true-color/grayscale decoder
+ * - other -> `image-format-unsupported`
+ *
+ * Decoded bytes are always tight-packed RGBA (`bytes.length === width *
+ * height * 4`). `colorSpace` and `mipmap` are carried from the supplied
+ * `ParseImageOptions` (decodeImageFromFile passes the sidecar settings).
+ */
+export declare function parseImage(bytes: Uint8Array, mime: string, opts?: ParseImageOptions): Result<DecodedImage, ImageError>;
+//# sourceMappingURL=parse-image.d.ts.map

package/dist/parse-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-image.d.ts","sourceRoot":"","sources":["../src/parse-image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAUvF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,iFAAiF;IACjF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,iBAAsB,GAC3B,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAmGlC"}

package/dist/parse-image.mjs

@@ -0,0 +1,231 @@
+import * as jpeg from 'jpeg-js';
+import * as UPNG from 'upng-js';
+import { err, ok, IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+
+// src/parse-image.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', '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"
+};
+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/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", "image/x-tga"];
+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 if (mime === "image/jpeg") {
+      const jpegMod = jpeg.default ?? jpeg;
+      const decoded = jpegMod.decode(bytes, { useTArray: true, formatAsRGBA: true });
+      width = decoded.width;
+      height = decoded.height;
+      rgba = decoded.data;
+    } else {
+      const decoded = decodeTga(bytes);
+      width = decoded.width;
+      height = decoded.height;
+      rgba = decoded.bytes;
+    }
+  } 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
+  });
+}
+function decodeTga(bytes) {
+  if (bytes.length < 18) throw new Error("TGA header is truncated");
+  const colorMapType = bytes[1];
+  const imageType = bytes[2];
+  const idLength = bytes[0] ?? 0;
+  const width = (bytes[12] ?? 0) | (bytes[13] ?? 0) << 8;
+  const height = (bytes[14] ?? 0) | (bytes[15] ?? 0) << 8;
+  const pixelDepth = bytes[16] ?? 0;
+  const descriptor = bytes[17] ?? 0;
+  if (colorMapType !== 0) throw new Error("color-mapped TGA is unsupported");
+  if (width < 1 || height < 1) throw new Error("TGA dimensions must be positive");
+  const isTrueColor = imageType === 2 || imageType === 10;
+  const isGray = imageType === 3 || imageType === 11;
+  if (!isTrueColor && !isGray) throw new Error(`TGA image type ${imageType} is unsupported`);
+  if (isTrueColor && pixelDepth !== 24 && pixelDepth !== 32) {
+    throw new Error(`TGA true-color depth ${pixelDepth} is unsupported`);
+  }
+  if (isGray && pixelDepth !== 8)
+    throw new Error(`TGA grayscale depth ${pixelDepth} is unsupported`);
+  const bytesPerPixel = pixelDepth / 8;
+  let offset = 18 + idLength;
+  const pixelCount = width * height;
+  const out = new Uint8Array(pixelCount * 4);
+  const topOrigin = (descriptor & 32) !== 0;
+  const rightOrigin = (descriptor & 16) !== 0;
+  let filePixel = 0;
+  const writePixel = (pixel) => {
+    if (filePixel >= pixelCount) throw new Error("TGA pixel data has too many pixels");
+    const fileX = filePixel % width;
+    const fileY = Math.floor(filePixel / width);
+    const x = rightOrigin ? width - 1 - fileX : fileX;
+    const y = topOrigin ? fileY : height - 1 - fileY;
+    const destination = (y * width + x) * 4;
+    if (isGray) {
+      const value = pixel[0] ?? 0;
+      out[destination] = value;
+      out[destination + 1] = value;
+      out[destination + 2] = value;
+      out[destination + 3] = 255;
+    } else {
+      out[destination] = pixel[2] ?? 0;
+      out[destination + 1] = pixel[1] ?? 0;
+      out[destination + 2] = pixel[0] ?? 0;
+      out[destination + 3] = bytesPerPixel === 4 ? pixel[3] ?? 255 : 255;
+    }
+    filePixel += 1;
+  };
+  const readPixel = () => {
+    if (offset + bytesPerPixel > bytes.length) throw new Error("TGA pixel data is truncated");
+    const pixel = bytes.slice(offset, offset + bytesPerPixel);
+    offset += bytesPerPixel;
+    return pixel;
+  };
+  if (imageType === 2 || imageType === 3) {
+    while (filePixel < pixelCount) writePixel(readPixel());
+  } else {
+    while (filePixel < pixelCount) {
+      if (offset >= bytes.length) throw new Error("TGA RLE packet header is truncated");
+      const packet = bytes[offset++] ?? 0;
+      const count = (packet & 127) + 1;
+      if (filePixel + count > pixelCount) throw new Error("TGA RLE packet exceeds image bounds");
+      if ((packet & 128) !== 0) {
+        const pixel = readPixel();
+        for (let i = 0; i < count; i++) writePixel(pixel);
+      } else {
+        for (let i = 0; i < count; i++) writePixel(readPixel());
+      }
+    }
+  }
+  if (filePixel !== pixelCount) throw new Error("TGA pixel count mismatch");
+  return { width, height, bytes: out };
+}
+
+export { parseImage };
+//# sourceMappingURL=parse-image.mjs.map
+//# sourceMappingURL=parse-image.mjs.map

package/dist/parse-image.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/resize-image.ts","../src/parse-image.ts"],"names":[],"mappings":"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","file":"parse-image.mjs","sourcesContent":["import type { ImageErrorCode, ImageErrorDetailFor, ImageErrorFor } from '@forgeax/engine-types';\nimport { IMAGE_ERROR_HINTS } from '@forgeax/engine-types';\n\n// Per-code .expected string literals SSOT.\n// Mirrors ASSET_ERROR_HINTS / IMAGE_ERROR_HINTS shape (charter P5 consistent\n// abstraction). AI users surface .expected when a structured error needs to\n// describe the precondition that was violated.\nconst IMAGE_ERROR_EXPECTED: Readonly<Record<ImageErrorCode, string>> = {\n  'image-decode-failed': 'PNG / JPG byte stream decodes successfully',\n  'image-format-unsupported':\n    \"mime is one of ['image/png', 'image/jpeg', 'image/x-tga']; uploadTexture format <-> colorSpace family agrees\",\n  'image-dimension-out-of-bounds':\n    'width and height fall under device caps maxTextureDimension2D (or 16384 hard cap)',\n  'image-meta-missing':\n    \"<source>.meta.json sidecar (importer: 'image') exists in the same directory\",\n  'image-hdr-decode-failed': 'Radiance RGBE header is valid and pixel data decodes successfully',\n  // feat-20260521-sprite-atlas-animation M1 T-03 — vite-plugin-image atlas\n  // hook .expected literals (plan-strategy section 2 D-2 + AC-10 a/b/c).\n  // ImageErrorImpl construction path is unchanged: the new atlas-* errors\n  // flow through `new ImageErrorImpl({ code: 'atlas-...', ...detail })` and\n  // pick the .expected string up from this Record at construction time\n  // (charter P3 explicit failure SSOT — AI users surface .expected next to\n  // .hint after switch (err.code) without parsing the message).\n  'atlas-empty-input': 'images.length >= 1',\n  'atlas-size-exceeded':\n    'image width x height <= maxAtlasSize^2 and each image fits in the atlas footprint',\n  'atlas-region-mismatch': 'sum(regions[i].w x regions[i].h) <= atlasWidth x atlasHeight',\n};\n\n/** Runtime implementation of the correlated `ImageErrorFor<C>` envelope. */\nexport class ImageErrorImpl<C extends ImageErrorCode = ImageErrorCode>\n  extends Error\n  implements ImageErrorFor<C>\n{\n  readonly code: C;\n  readonly expected: string;\n  readonly hint: string;\n  readonly detail: ImageErrorDetailFor<C>;\n\n  constructor(detail: ImageErrorDetailFor<C>) {\n    const code = detail.code;\n    const expected = IMAGE_ERROR_EXPECTED[code];\n    const hint = IMAGE_ERROR_HINTS[code];\n    super(`[ImageError ${code}] expected: ${expected}; hint: ${hint}`);\n    this.name = 'ImageError';\n    this.code = code;\n    this.expected = expected;\n    this.hint = hint;\n    this.detail = detail;\n  }\n}\n\n/** Construct a structured image error while preserving its code/detail pair. */\nexport function imageError<C extends ImageErrorCode>(\n  detail: ImageErrorDetailFor<C>,\n): ImageErrorFor<C> {\n  return new ImageErrorImpl<C>(detail);\n}\n\nexport { IMAGE_ERROR_EXPECTED };\n","/** Deterministically downscale tight-packed RGBA pixels with bilinear sampling. */\nexport function downscaleRgba(\n  bytes: Uint8Array,\n  width: number,\n  height: number,\n  maxDimension: number,\n): { readonly bytes: Uint8Array; readonly width: number; readonly height: number } {\n  if (width <= maxDimension && height <= maxDimension) {\n    return { bytes, width, height };\n  }\n\n  const scale = maxDimension / Math.max(width, height);\n  const targetWidth = Math.max(1, Math.round(width * scale));\n  const targetHeight = Math.max(1, Math.round(height * scale));\n  const output = new Uint8Array(targetWidth * targetHeight * 4);\n  const source = (x: number, y: number, channel: number): number =>\n    bytes[(y * width + x) * 4 + channel] ?? 0;\n\n  for (let y = 0; y < targetHeight; y += 1) {\n    const sourceY = ((y + 0.5) * height) / targetHeight - 0.5;\n    const y0 = Math.max(0, Math.floor(sourceY));\n    const y1 = Math.min(height - 1, y0 + 1);\n    const yWeight = Math.max(0, Math.min(1, sourceY - y0));\n    for (let x = 0; x < targetWidth; x += 1) {\n      const sourceX = ((x + 0.5) * width) / targetWidth - 0.5;\n      const x0 = Math.max(0, Math.floor(sourceX));\n      const x1 = Math.min(width - 1, x0 + 1);\n      const xWeight = Math.max(0, Math.min(1, sourceX - x0));\n      const outputOffset = (y * targetWidth + x) * 4;\n      for (let channel = 0; channel < 4; channel += 1) {\n        const top = source(x0, y0, channel) * (1 - xWeight) + source(x1, y0, channel) * xWeight;\n        const bottom = source(x0, y1, channel) * (1 - xWeight) + source(x1, y1, channel) * xWeight;\n        output[outputOffset + channel] = Math.round(top * (1 - yWeight) + bottom * yWeight);\n      }\n    }\n  }\n\n  return { bytes: output, width: targetWidth, height: targetHeight };\n}\n","import type { DecodedImage, ImageColorSpace, ImageError } from '@forgeax/engine-types';\nimport * as jpeg from 'jpeg-js';\n// Static imports of upng-js + jpeg-js. tsup external keeps both as runtime\n// require() calls so the browser bundle still tree-shakes them out when\n// only image-decoder-browser.ts (createImageBitmap) is reached at runtime.\n// Synchronous decode is required by the parseImage signature contract (see\n// plan-strategy section 3.3).\nimport * as UPNG from 'upng-js';\nimport { imageError } from './errors.js';\nimport { downscaleRgba } from './resize-image.js';\nimport type { Result } from './result.js';\nimport { err, ok } from './result.js';\n\nexport interface ParseImageOptions {\n  /**\n   * Maximum allowed dimension (width or height). Defaults to 16384 -- the\n   * conservative WebGPU `maxTextureDimension2D` floor across desktop +\n   * high-end mobile (research F-3 / spec). Test fixtures pass smaller\n   * values to exercise the bounds-check code path with tiny fixtures.\n   */\n  readonly maxDimension?: number;\n\n  /** Optional asset-owned cooked-payload target; source bytes remain unchanged. */\n  readonly downscaleMaxDimension?: number;\n\n  /**\n   * Sidecar `colorSpace` carried over to the DecodedImage POD. Defaults to\n   * 'srgb' (typical baseColor / albedo path; plan-strategy section 2.5).\n   */\n  readonly colorSpace?: ImageColorSpace;\n\n  /**\n   * Sidecar `mipmap` flag carried over to DecodedImage. Defaults to true\n   * (auto-generate via runtime mipmap-generator; plan-strategy section 2.6).\n   */\n  readonly mipmap?: boolean;\n\n  /**\n   * Optional source path to embed in error.detail.path (decode-failed /\n   * format-unsupported variants). decodeImageFromFile fills this in;\n   * in-memory parseImage callers leave it empty.\n   */\n  readonly path?: string;\n}\n\nconst DEFAULT_MAX_DIMENSION = 16384;\n\nconst SUPPORTED_MIMES: readonly string[] = ['image/png', 'image/jpeg', 'image/x-tga'];\n\ninterface UpngDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly data: Uint8Array;\n}\n\ninterface JpegDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly data: Uint8Array;\n}\n\n/**\n * Pure synchronous image decoder. Translates raw byte stream + mime hint\n * into a tight-packed RGBA `DecodedImage` POD. Surfaces all four\n * ImageErrorCode members through the structured `Result<DecodedImage,\n * ImageError>` return (charter P3 explicit failure; AGENTS.md \"Return\n * Result, never throw\").\n *\n * Decoder selection follows the mime hint:\n * - `image/png` -> upng-js `UPNG.decode` + `UPNG.toRGBA8`\n * - `image/jpeg` -> jpeg-js `decode` with `formatAsRGBA: true`\n * - `image/x-tga` -> the built-in TGA true-color/grayscale decoder\n * - other -> `image-format-unsupported`\n *\n * Decoded bytes are always tight-packed RGBA (`bytes.length === width *\n * height * 4`). `colorSpace` and `mipmap` are carried from the supplied\n * `ParseImageOptions` (decodeImageFromFile passes the sidecar settings).\n */\nexport function parseImage(\n  bytes: Uint8Array,\n  mime: string,\n  opts: ParseImageOptions = {},\n): Result<DecodedImage, ImageError> {\n  if (!SUPPORTED_MIMES.includes(mime)) {\n    return err(\n      imageError({\n        code: 'image-format-unsupported',\n        actualMime: mime,\n        ...(opts.path !== undefined ? { path: opts.path } : {}),\n      }),\n    );\n  }\n\n  let width = 0;\n  let height = 0;\n  let rgba: Uint8Array;\n\n  try {\n    if (mime === 'image/png') {\n      const upngMod: {\n        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;\n        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];\n      } = ((UPNG as unknown as { default?: typeof UPNG }).default ?? UPNG) as unknown as {\n        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;\n        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];\n      };\n      const decoded = upngMod.decode(bytes);\n      width = decoded.width;\n      height = decoded.height;\n      const frames = upngMod.toRGBA8(decoded);\n      const first = frames[0];\n      if (first === undefined) {\n        return err(\n          imageError({\n            code: 'image-decode-failed',\n            reason: 'UPNG.toRGBA8 returned no frames',\n            ...(opts.path !== undefined ? { path: opts.path } : {}),\n          }),\n        );\n      }\n      rgba = new Uint8Array(first);\n    } else if (mime === 'image/jpeg') {\n      // image/jpeg\n      const jpegMod: {\n        decode: (\n          b: Uint8Array | ArrayBuffer,\n          o?: { useTArray?: boolean; formatAsRGBA?: boolean },\n        ) => JpegDecoded;\n      } = ((jpeg as unknown as { default?: typeof jpeg }).default ?? jpeg) as unknown as {\n        decode: (\n          b: Uint8Array | ArrayBuffer,\n          o?: { useTArray?: boolean; formatAsRGBA?: boolean },\n        ) => JpegDecoded;\n      };\n      const decoded = jpegMod.decode(bytes, { useTArray: true, formatAsRGBA: true });\n      width = decoded.width;\n      height = decoded.height;\n      rgba = decoded.data;\n    } else {\n      const decoded = decodeTga(bytes);\n      width = decoded.width;\n      height = decoded.height;\n      rgba = decoded.bytes;\n    }\n  } catch (e) {\n    return err(\n      imageError({\n        code: 'image-decode-failed',\n        reason: e instanceof Error ? e.message : String(e),\n        ...(opts.path !== undefined ? { path: opts.path } : {}),\n      }),\n    );\n  }\n\n  const downscaleLimit = opts.downscaleMaxDimension;\n  if (downscaleLimit !== undefined && Number.isInteger(downscaleLimit) && downscaleLimit > 0) {\n    const downscaled = downscaleRgba(rgba, width, height, downscaleLimit);\n    rgba = downscaled.bytes;\n    width = downscaled.width;\n    height = downscaled.height;\n  }\n\n  const limit = opts.maxDimension ?? DEFAULT_MAX_DIMENSION;\n  if (width > limit || height > limit) {\n    return err(\n      imageError({\n        code: 'image-dimension-out-of-bounds',\n        requested: { width, height },\n        limit,\n      }),\n    );\n  }\n\n  return ok({\n    bytes: rgba,\n    width,\n    height,\n    mime: mime as 'image/png' | 'image/jpeg' | 'image/x-tga',\n    colorSpace: opts.colorSpace ?? 'srgb',\n    mipmap: opts.mipmap ?? true,\n  });\n}\n\ninterface TgaDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly bytes: Uint8Array;\n}\n\n/**\n * Decode the portable TGA subset used by common FBX exports.\n *\n * The decoder owns the format boundary instead of trusting the extension: it\n * validates the header, supports uncompressed and RLE true-colour (24/32-bit)\n * plus grayscale (8-bit), and applies the origin bits from the image\n * descriptor while producing a top-left RGBA POD.\n */\nfunction decodeTga(bytes: Uint8Array): TgaDecoded {\n  if (bytes.length < 18) throw new Error('TGA header is truncated');\n\n  const colorMapType = bytes[1];\n  const imageType = bytes[2];\n  const idLength = bytes[0] ?? 0;\n  const width = (bytes[12] ?? 0) | ((bytes[13] ?? 0) << 8);\n  const height = (bytes[14] ?? 0) | ((bytes[15] ?? 0) << 8);\n  const pixelDepth = bytes[16] ?? 0;\n  const descriptor = bytes[17] ?? 0;\n  if (colorMapType !== 0) throw new Error('color-mapped TGA is unsupported');\n  if (width < 1 || height < 1) throw new Error('TGA dimensions must be positive');\n\n  const isTrueColor = imageType === 2 || imageType === 10;\n  const isGray = imageType === 3 || imageType === 11;\n  if (!isTrueColor && !isGray) throw new Error(`TGA image type ${imageType} is unsupported`);\n  if (isTrueColor && pixelDepth !== 24 && pixelDepth !== 32) {\n    throw new Error(`TGA true-color depth ${pixelDepth} is unsupported`);\n  }\n  if (isGray && pixelDepth !== 8)\n    throw new Error(`TGA grayscale depth ${pixelDepth} is unsupported`);\n\n  const bytesPerPixel = pixelDepth / 8;\n  let offset = 18 + idLength;\n  const pixelCount = width * height;\n  const out = new Uint8Array(pixelCount * 4);\n  const topOrigin = (descriptor & 0x20) !== 0;\n  const rightOrigin = (descriptor & 0x10) !== 0;\n  let filePixel = 0;\n\n  const writePixel = (pixel: Uint8Array): void => {\n    if (filePixel >= pixelCount) throw new Error('TGA pixel data has too many pixels');\n    const fileX = filePixel % width;\n    const fileY = Math.floor(filePixel / width);\n    const x = rightOrigin ? width - 1 - fileX : fileX;\n    const y = topOrigin ? fileY : height - 1 - fileY;\n    const destination = (y * width + x) * 4;\n    if (isGray) {\n      const value = pixel[0] ?? 0;\n      out[destination] = value;\n      out[destination + 1] = value;\n      out[destination + 2] = value;\n      out[destination + 3] = 255;\n    } else {\n      out[destination] = pixel[2] ?? 0;\n      out[destination + 1] = pixel[1] ?? 0;\n      out[destination + 2] = pixel[0] ?? 0;\n      out[destination + 3] = bytesPerPixel === 4 ? (pixel[3] ?? 255) : 255;\n    }\n    filePixel += 1;\n  };\n\n  const readPixel = (): Uint8Array => {\n    if (offset + bytesPerPixel > bytes.length) throw new Error('TGA pixel data is truncated');\n    const pixel = bytes.slice(offset, offset + bytesPerPixel);\n    offset += bytesPerPixel;\n    return pixel;\n  };\n\n  if (imageType === 2 || imageType === 3) {\n    while (filePixel < pixelCount) writePixel(readPixel());\n  } else {\n    while (filePixel < pixelCount) {\n      if (offset >= bytes.length) throw new Error('TGA RLE packet header is truncated');\n      const packet = bytes[offset++] ?? 0;\n      const count = (packet & 0x7f) + 1;\n      if (filePixel + count > pixelCount) throw new Error('TGA RLE packet exceeds image bounds');\n      if ((packet & 0x80) !== 0) {\n        const pixel = readPixel();\n        for (let i = 0; i < count; i++) writePixel(pixel);\n      } else {\n        for (let i = 0; i < count; i++) writePixel(readPixel());\n      }\n    }\n  }\n\n  if (filePixel !== pixelCount) throw new Error('TGA pixel count mismatch');\n  return { width, height, bytes: out };\n}\n"]}

package/dist/reimport-reuse-meta.d.ts

@@ -0,0 +1,81 @@
+import type { DecodedImage, ImageColorSpace } from '@forgeax/engine-types';
+/**
+ * Existing `*.meta.json` (importer: 'image') sub-asset record (free-form sub-shape; the
+ * meta.schema.json $defs/subAsset locks `guid` + `sourceIndex` + `kind` only).
+ * Image importer treats the open shape as a key-bearing tuple; the gltf-loader
+ * feat works on the same shape.
+ */
+export interface ExistingSubAsset {
+    readonly guid: string;
+    readonly sourceIndex: number;
+    readonly kind: string;
+    readonly name?: string;
+    readonly sourceKey?: string;
+}
+/**
+ * Existing `*.meta.json` (importer: 'image') package record. Mirrors the
+ * meta.schema.json $defs/ExternalAssetPackage shape (research F-9). Only
+ * the fields consumed by the reimport reuse algorithm are typed here;
+ * importSettings stays a free-form open shape.
+ */
+export interface ExistingExternalAssetPackage {
+    readonly schemaVersion: string;
+    readonly kind: 'external-asset-package';
+    readonly importer: 'image';
+    readonly source: string;
+    readonly importSettings: Readonly<Record<string, unknown>>;
+    readonly subAssets: readonly ExistingSubAsset[];
+}
+/**
+ * Sub-asset record emitted into the regenerated `*.meta.json` (importer: 'image')
+ * `subAssets[]` slot. Shape matches `ExistingSubAsset` so two consecutive
+ * reimports of byte-identical bytes produce byte-identical JSON
+ * (AC-16 byte-stable reimport guarantee).
+ */
+export interface EmittedSubAsset {
+    readonly guid: string;
+    readonly sourceIndex: number;
+    readonly kind: string;
+    readonly name?: string;
+    readonly sourceKey?: string;
+}
+/**
+ * Two-phase reimport reuse algorithm (plan-strategy section 2.2 D-4
+ * mirroring the in-flight gltf-loader algorithm).
+ *
+ * For each fresh sub-asset key the importer would emit, this function:
+ *  1. Searches the `existing.subAssets[]` for a `subAssetKeyEqual` hit.
+ *  2. On hit -- reuses the existing GUID byte-for-byte.
+ *  3. On miss -- mints a fresh UUIDv7 via `AssetGuid.random()`.
+ *
+ * Image disk schema currently emits a single `kind='texture'` sub-asset per
+ * source (cubemap face / array layer reserved for future feat); the
+ * algorithm scales to multi-sub-asset sources without modification (charter
+ * P5 consistent abstraction).
+ *
+ * Returns the regenerated `subAssets[]` array. The caller (toAssetPack /
+ * runAssetImport) splices it into the `*.meta.json` (importer: 'image') envelope.
+ */
+export declare function reimportReuseMeta(decoded: DecodedImage, existing: ExistingExternalAssetPackage | undefined): readonly EmittedSubAsset[];
+/**
+ * HDR colorSpace validator for *.image.meta.json sidecar importSettings
+ * (plan-strategy D-8 -- HDR files must use colorSpace=linear).
+ *
+ * Extension is matched case-insensitively against the HDR set
+ * (`.hdr`, `.exr`). When the extension belongs to the HDR set:
+ * - `colorSpace='linear'` -> ok, returns `'linear'`
+ * - any other colorSpace -> structured rejection with expected/actual
+ *
+ * Non-HDR extensions pass through the colorSpace unchanged. Downstream
+ * callers (decodeImageFromFile, parseImage) invoke this at the
+ * sidecar-read entry to fail-fast when an .hdr meta carries srgb.
+ */
+export declare function validateColorSpaceForHdr(ext: string, colorSpace: ImageColorSpace): {
+    ok: true;
+    value: ImageColorSpace;
+} | {
+    ok: false;
+    expected: string;
+    actual: string;
+};
+//# sourceMappingURL=reimport-reuse-meta.d.ts.map

package/dist/reimport-reuse-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reimport-reuse-meta.d.ts","sourceRoot":"","sources":["../src/reimport-reuse-meta.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAM3E;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,4BAA4B,GAAG,SAAS,GACjD,SAAS,eAAe,EAAE,CA0D5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,eAAe,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAaxF"}

package/dist/resize-image.d.ts

@@ -0,0 +1,7 @@
+/** Deterministically downscale tight-packed RGBA pixels with bilinear sampling. */
+export declare function downscaleRgba(bytes: Uint8Array, width: number, height: number, maxDimension: number): {
+    readonly bytes: Uint8Array;
+    readonly width: number;
+    readonly height: number;
+};
+//# sourceMappingURL=resize-image.d.ts.map