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

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,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAElE,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1E,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,98 @@
+import { basisEncode } from '@forgeax/engine-codec/encode';
+
+// src/ktx2-encode.ts
+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 } };
+}
+
+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":"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","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\n/** The sidecar control-plane value (ImageMetadata.compressionMode). */\nexport type CompressionMode = 'auto' | 'etc1s' | 'uastc' | 'none';\n\n/** The resolved delivery encoding after 'auto' derivation. `'none'` = no encode. */\nexport type ResolvedEncodeMode = 'etc1s' | 'uastc' | 'uastc-hdr' | 'none';\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 'none':\n      return 'none';\n    case 'etc1s':\n      return 'etc1s';\n    case 'uastc':\n      return source.isHdr ? 'uastc-hdr' : 'uastc';\n    case 'auto':\n      if (source.isHdr) return 'uastc-hdr';\n      return source.colorSpace === 'srgb' ? 'etc1s' : 'uastc';\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 'none':\n      return null;\n    case 'etc1s':\n      return {\n        mode: 'etc1s',\n        srgb: srgbColor,\n        perceptual: srgbColor,\n        uastcSupercompression: false,\n        mipGen: false,\n      };\n    case 'uastc':\n      return {\n        mode: 'uastc-ldr',\n        srgb: srgbColor,\n        perceptual: srgbColor,\n        uastcSupercompression: true,\n        mipGen: false,\n      };\n    case 'uastc-hdr':\n      return {\n        mode: 'uastc-hdr',\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,47 @@
+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`
+ * - 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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,iBAAsB,GAC3B,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CA8FlC"}

package/dist/parse-image.mjs

@@ -0,0 +1,154 @@
+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']; 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"];
+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
+  });
+}
+
+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']; 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'];\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 * - 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 {\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    }\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',\n    colorSpace: opts.colorSpace ?? 'srgb',\n    mipmap: opts.mipmap ?? true,\n  });\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

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

@@ -0,0 +1 @@
+{"version":3,"file":"resize-image.d.ts","sourceRoot":"","sources":["../src/resize-image.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAgCjF"}

package/dist/result.d.ts

@@ -0,0 +1,2 @@
+export { err, ok, type Result, type ResultErr, type ResultOk, } from '@forgeax/engine-types';
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,GAAG,EACH,EAAE,EACF,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,QAAQ,GACd,MAAM,uBAAuB,CAAC"}

package/dist/runtime/asset-decoders.d.ts

@@ -0,0 +1,4 @@
+import { type AssetDecoderContribution, type EquirectAsset, type TextureAsset } from '@forgeax/engine-types';
+export declare const textureContribution: AssetDecoderContribution<TextureAsset, 'texture'>;
+export declare const equirectContribution: AssetDecoderContribution<EquirectAsset, 'equirect'>;
+//# sourceMappingURL=asset-decoders.d.ts.map

package/dist/runtime/asset-decoders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-decoders.d.ts","sourceRoot":"","sources":["../../src/runtime/asset-decoders.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,wBAAwB,EAK7B,KAAK,aAAa,EAGlB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAkH/B,eAAO,MAAM,mBAAmB,EAAE,wBAAwB,CAAC,YAAY,EAAE,SAAS,CAYjF,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,wBAAwB,CAAC,aAAa,EAAE,UAAU,CAYpF,CAAC"}

package/dist/source-key.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Derive the semantic identity for an image producer output.
+ *
+ * The role is the producer-owned identity. Source path and sourceIndex are
+ * locators only and must not be folded into this key.
+ */
+export interface ImageSourceKeyLocator {
+    readonly sourcePath?: string;
+    readonly sourceIndex?: number;
+}
+export type ImageSourceKeyResult = {
+    readonly ok: true;
+    readonly keys: readonly string[];
+} | {
+    readonly ok: false;
+    readonly code: 'missing-source-key' | 'duplicate-source-key';
+    readonly roles: readonly string[];
+};
+export declare function deriveImageSourceKey(role: string, _locator?: ImageSourceKeyLocator): string | undefined;
+export declare function deriveImageSourceKeys(roles: readonly string[]): ImageSourceKeyResult;
+//# sourceMappingURL=source-key.d.ts.map

package/dist/source-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-key.d.ts","sourceRoot":"","sources":["../src/source-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACvD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,CAAC;AAEN,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,MAAM,GAAG,SAAS,CAIpB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,oBAAoB,CAYpF"}

package/dist/sub-asset-key.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Sub-asset-key shape mirroring the in-flight gltf-loader feat (plan-strategy
+ * section 2.2 D-4 same-shape). Each sub-asset emitted into a `*.meta.json`
+ * sidecar (uniformly `<source>.meta.json` across image / gltf arms,
+ * dispatched on top-level `importer` field per feat-20260521) carries a
+ * `{kind, name?, indexFallback}` triple so the importer can deterministically
+ * match an existing sub-asset across reimports (charter P5 producer/consumer
+ * split + AC-14 cross-feat alignment).
+ *
+ * The image disk schema is currently single-sub-asset; this file collapses
+ * to `kind='texture'` + `indexFallback='textures/0'` so the same matching
+ * algorithm is reusable when the future cubemap / array-layer feat lands
+ * (plan-strategy R5 free-form schema).
+ */
+export interface SubAssetKey {
+    /** Discriminator literal -- 'texture' for engine-image; 'mesh' / 'material' / 'scene' / 'image' for gltf-loader. */
+    readonly kind: string;
+    /** Optional human-readable name field; absent when the source has no symbolic identifier. */
+    readonly name?: string;
+    /** Path-style fallback identifier (e.g. 'images/0' / 'meshes/0'); always non-empty. */
+    readonly indexFallback: string;
+}
+export interface SubAssetKeyInput {
+    readonly kind: string;
+    readonly sourceIndex: number;
+    readonly name?: string;
+}
+/**
+ * Construct a sub-asset key from importer input. The `indexFallback` is
+ * synthesised from the kind literal + sourceIndex so two importers
+ * (image / gltf-loader) emit identical fallback strings for the same
+ * `(kind, sourceIndex)` pair (AC-14).
+ */
+export declare function subAssetKey(input: SubAssetKeyInput): SubAssetKey;
+/**
+ * Two-phase equality predicate used by reimportReuseMeta for GUID
+ * preservation across reimports:
+ *
+ * Phase 1 -- (kind + name + idx) full match: identical in all three fields
+ * Phase 2 -- (kind + idx) match: same kind + indexFallback, name absent or
+ *            equal (collapses when both sides omit name)
+ * Phase 3 -- otherwise: false (importer mints fresh UUIDv7)
+ *
+ * The two phases are folded into a single boolean predicate here; the
+ * reimportReuseMeta caller iterates the existing subAssets list and picks
+ * the first hit (deterministic order; matches AC-16 byte-identical
+ * reimport).
+ */
+export declare function subAssetKeyEqual(a: SubAssetKey, b: SubAssetKey): boolean;
+//# sourceMappingURL=sub-asset-key.d.ts.map

package/dist/sub-asset-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-asset-key.d.ts","sourceRoot":"","sources":["../src/sub-asset-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,oHAAoH;IACpH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAMhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAQxE"}

package/dist/to-asset-pack.d.ts

@@ -0,0 +1,61 @@
+import type { AssetCompression, DecodedImage, ImageMeta } from '@forgeax/engine-types';
+/**
+ * External-asset-package envelope shape mirroring the
+ * `packages/pack/schema/meta.schema.json` $defs/ExternalAssetPackage.
+ * Consumed by `forgeax-engine-remote-asset import` (CLI entry, M3b) +
+ * the image importer in M2 build-time path. The internal-text-package
+ * variant ($defs/InternalTextPackage) is owned by the gltf-loader feat.
+ */
+export interface ExternalAssetPackage {
+    readonly schemaVersion: string;
+    readonly kind: 'external-asset-package';
+    readonly importer: 'image';
+    readonly source: string;
+    readonly importSettings: ImageImportSettings;
+    readonly subAssets: readonly ExternalSubAsset[];
+}
+/**
+ * Free-form image importer settings persisted into `*.meta.json` (importer: 'image')
+ * `importSettings`. Matches `ImageMeta` POD field-for-field (charter P5
+ * single SSOT) but the open Record shape allows future minor adds (cubemap
+ * face / array layer / custom colorSpace) without breaking existing meta
+ * files (plan-strategy R5).
+ */
+export interface ImageImportSettings extends Readonly<Record<string, unknown>> {
+    readonly colorSpace: ImageMeta['colorSpace'];
+    readonly mipmap: ImageMeta['mipmap'];
+    readonly addressMode: ImageMeta['addressMode'];
+    readonly filterMode: ImageMeta['filterMode'];
+    readonly downscaleMaxDimension?: number;
+    /**
+     * Explicit per-asset compression override (AC-01: importSettings carries
+     * compression intent). When omitted, the build-time compression strategy
+     * table decides by artifact kind (mesh -> zstd, texture -> none). When set,
+     * this value wins over the default table for this asset.
+     */
+    readonly compression?: AssetCompression;
+}
+export interface ExternalSubAsset {
+    readonly guid: string;
+    readonly sourceIndex: number;
+    readonly kind: string;
+    readonly name?: string;
+}
+/**
+ * Pure function that translates a DecodedImage POD + ImageMeta POD into
+ * an external-asset-package envelope ready to be JSON-stringified into a
+ * `*.meta.json` sidecar with importer: 'image' (plan-strategy section 3.2 sequence A; AC-13
+ * disk schema reuse).
+ *
+ * The single sub-asset emitted carries:
+ *  - `guid` -- copied verbatim from `meta.guid` (the producer guarantees
+ *    the GUID is freshly minted or reused via `reimportReuseMeta`)
+ *  - `sourceIndex: 0` (single-sub-asset shape; cubemap / array reserved
+ *    for future feat)
+ *  - `kind: 'texture'` (closed literal for image-importer emit)
+ *
+ * Two consecutive calls with identical inputs produce JSON.stringify
+ * byte-equal output (AC-16 idempotent reimport).
+ */
+export declare function toAssetPack(decoded: DecodedImage, meta: ImageMeta): ExternalAssetPackage;
+//# sourceMappingURL=to-asset-pack.d.ts.map

package/dist/to-asset-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-asset-pack.d.ts","sourceRoot":"","sources":["../src/to-asset-pack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,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,mBAAmB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IAC7C,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;CACzC;AAED,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;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,GAAG,oBAAoB,CA+BxF"}