@forgeax/engine-image 0.1.2

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/__tests__/asset-decoders.unit.test.d.ts

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

package/dist/runtime/__tests__/asset-decoders.unit.test.d.ts.map

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

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/runtime/decode-image-bytes.d.ts

@@ -0,0 +1,7 @@
+import type { ImageError, Result, TextureAsset } from '@forgeax/engine-types';
+/** Image-owned runtime boundary from encoded bytes to a TextureAsset POD. */
+export declare function decodeImageBytes(bytes: Uint8Array | ArrayBuffer, mime: string, opts?: {
+    readonly colorSpace?: 'srgb' | 'linear';
+    readonly mipmap?: boolean;
+}): Promise<Result<TextureAsset, ImageError>>;
+//# sourceMappingURL=decode-image-bytes.d.ts.map

package/dist/runtime/decode-image-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-image-bytes.d.ts","sourceRoot":"","sources":["../../src/runtime/decode-image-bytes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAgB9E,6EAA6E;AAC7E,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAChF,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAmB3C"}

package/dist/runtime/image-error.d.ts

@@ -0,0 +1,3 @@
+import type { ImageErrorCode, ImageErrorDetailFor, ImageErrorFor } from '@forgeax/engine-types';
+export declare function runtimeImageError<C extends ImageErrorCode>(detail: ImageErrorDetailFor<C>): ImageErrorFor<C>;
+//# sourceMappingURL=image-error.d.ts.map

package/dist/runtime/image-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-error.d.ts","sourceRoot":"","sources":["../../src/runtime/image-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGhG,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,cAAc,EACxD,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC7B,aAAa,CAAC,CAAC,CAAC,CAElB"}

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"}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@forgeax/engine-image",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Disk-to-memory image importer for forgeax-engine: parseImage / decodeImageFromFile / toAssetPack three pure functions + sub-asset-key + reimport-reuse-meta + correlated ImageError closed union.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./parse-image": {
+      "types": "./dist/parse-image.d.ts",
+      "node": {
+        "import": "./dist/parse-image.mjs"
+      },
+      "default": null
+    },
+    "./decode-image-from-file": {
+      "types": "./dist/decode-image-from-file.d.ts",
+      "node": {
+        "import": "./dist/decode-image-from-file.mjs"
+      },
+      "default": null
+    },
+    "./hdr-decoder": {
+      "types": "./dist/hdr-decoder.d.ts",
+      "import": "./dist/hdr-decoder.mjs"
+    },
+    "./image-importer": {
+      "types": "./dist/image-importer.d.ts",
+      "node": {
+        "import": "./dist/image-importer.mjs"
+      },
+      "default": null
+    },
+    "./ktx2-encode": {
+      "types": "./dist/ktx2-encode.d.ts",
+      "node": {
+        "import": "./dist/ktx2-encode.mjs"
+      },
+      "default": null
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-codec": "0.1.2",
+    "@forgeax/engine-math": "0.1.2",
+    "@forgeax/engine-pack": "0.1.2",
+    "@forgeax/engine-types": "0.1.2",
+    "jpeg-js": "^0.4.4",
+    "pako": "^1.0.11",
+    "upng-js": "^2.1.0"
+  },
+  "devDependencies": {
+    "@forgeax/engine-import": "0.1.2",
+    "@types/node": "^20.14.0",
+    "@webgpu/types": "^0.1.71"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip",
+        "expected": 2881,
+        "baseline": {
+          "source": ".forgeax-harness/forgeax-loop/feat-20260515-learn-render-getting-started/plan-strategy.md#5.4",
+          "threshold": 307200
+        }
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package, no runtime canvas; fps is reported by hello-* / learn-render apps that consume DecodedImage POD"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "image decode is one-shot importer-side work; bench focus stays on @forgeax/engine-math for perf-critical hot paths"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; the disk-to-memory pipeline isolation is policed by node scripts/check-image-pipeline-isolation.mjs in M2 milestoneCISweep"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; this is a production MVP per plan-strategy D-4 / D-12 (image importer + ImageErrorCode independent closed union)"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -b"
+  }
+}

package/src/__tests__/compression-mode.unit.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { basisEncodeParamsFor, resolveEncodeMode } from '../ktx2-encode.js';
+
+/**
+ * compressionMode sidecar + 'auto' derivation unit tests (M3 w16).
+ *
+ * Tests the pure image-side derivation the offline encode arm relies on
+ * (D-12), independent of the WASM encoder (round-trip bytes are w15's job;
+ * import-texture wiring is w20's job; no browser DOM):
+ *
+ *   - the four sidecar values ('auto' / 'etc1s' / 'uastc' / 'none') each
+ *     resolve to a delivery encoding;
+ *   - 'auto' derives deterministically from existing sidecar signals (D-12):
+ *     colorSpace 'srgb' -> ETC1S (albedo / UI), colorSpace 'linear' -> UASTC
+ *     (normals / ORM / data), HDR source -> UASTC-HDR;
+ *   - the 'none' path resolves to 'none' and yields NO encoder params (the
+ *     importer keeps the existing .bin path -- the encoder is not called);
+ *   - the encoder param mapping (basis tex format / srgb transfer flag / mip
+ *     gen) is correct per resolved mode.
+ *
+ * Note (M3 sequencing constraint): 'auto' derivation is implemented + tested
+ * here but is NOT the default value. The sidecar default stays 'none' until
+ * M5 (w38) flips it -- this milestone must not make existing textures encode
+ * to basis ahead of loader support (plan R-9).
+ */
+
+describe('resolveEncodeMode -- four sidecar values (M3 w16)', () => {
+  it("explicit 'etc1s' resolves to etc1s", () => {
+    expect(resolveEncodeMode('etc1s', { colorSpace: 'srgb', isHdr: false })).toBe('etc1s');
+    expect(resolveEncodeMode('etc1s', { colorSpace: 'linear', isHdr: false })).toBe('etc1s');
+  });
+
+  it("explicit 'uastc' resolves to uastc (LDR) or uastc-hdr for an HDR source", () => {
+    expect(resolveEncodeMode('uastc', { colorSpace: 'linear', isHdr: false })).toBe('uastc');
+    expect(resolveEncodeMode('uastc', { colorSpace: 'srgb', isHdr: false })).toBe('uastc');
+    expect(resolveEncodeMode('uastc', { colorSpace: 'linear', isHdr: true })).toBe('uastc-hdr');
+  });
+
+  it("explicit 'none' resolves to none", () => {
+    expect(resolveEncodeMode('none', { colorSpace: 'srgb', isHdr: false })).toBe('none');
+    expect(resolveEncodeMode('none', { colorSpace: 'linear', isHdr: true })).toBe('none');
+  });
+});
+
+describe("resolveEncodeMode -- 'auto' derivation (D-12, M3 w16)", () => {
+  it('srgb color source -> etc1s', () => {
+    expect(resolveEncodeMode('auto', { colorSpace: 'srgb', isHdr: false })).toBe('etc1s');
+  });
+
+  it('linear (data) source -> uastc', () => {
+    expect(resolveEncodeMode('auto', { colorSpace: 'linear', isHdr: false })).toBe('uastc');
+  });
+
+  it('HDR source -> uastc-hdr (regardless of colorSpace)', () => {
+    expect(resolveEncodeMode('auto', { colorSpace: 'linear', isHdr: true })).toBe('uastc-hdr');
+    expect(resolveEncodeMode('auto', { colorSpace: 'srgb', isHdr: true })).toBe('uastc-hdr');
+  });
+});
+
+describe('basisEncodeParamsFor -- mode -> encoder params (M3 w16)', () => {
+  it("'none' yields no encoder params (encoder is not called)", () => {
+    expect(basisEncodeParamsFor('none', { colorSpace: 'srgb', isHdr: false })).toBeNull();
+  });
+
+  it('etc1s maps to the ETC1S tex format with perceptual metrics for srgb color', () => {
+    const p = basisEncodeParamsFor('etc1s', { colorSpace: 'srgb', isHdr: false });
+    expect(p).not.toBeNull();
+    if (p === null) return;
+    expect(p.mode).toBe('etc1s');
+    expect(p.srgb).toBe(true);
+    expect(p.perceptual).toBe(true);
+    expect(p.uastcSupercompression).toBe(false);
+    expect(p.mipGen).toBe(false);
+  });
+
+  it('etc1s on a linear source drops the srgb transfer + perceptual flags', () => {
+    const p = basisEncodeParamsFor('etc1s', { colorSpace: 'linear', isHdr: false });
+    expect(p).not.toBeNull();
+    if (p === null) return;
+    expect(p.mode).toBe('etc1s');
+    expect(p.srgb).toBe(false);
+    expect(p.perceptual).toBe(false);
+  });
+
+  it('uastc maps to the UASTC-LDR tex format with zstd supercompression', () => {
+    const p = basisEncodeParamsFor('uastc', { colorSpace: 'linear', isHdr: false });
+    expect(p).not.toBeNull();
+    if (p === null) return;
+    expect(p.mode).toBe('uastc-ldr');
+    expect(p.srgb).toBe(false);
+    expect(p.uastcSupercompression).toBe(true);
+  });
+
+  it("'uastc' on an HDR source maps to the UASTC-HDR tex format with no srgb transfer", () => {
+    // 'uastc-hdr' is a derived delivery encoding, not a sidecar value; it is
+    // reached via the 'uastc' (or 'auto') sidecar mode on an HDR source.
+    const p = basisEncodeParamsFor('uastc', { colorSpace: 'linear', isHdr: true });
+    expect(p).not.toBeNull();
+    if (p === null) return;
+    expect(p.mode).toBe('uastc-hdr');
+    expect(p.srgb).toBe(false);
+    expect(p.uastcSupercompression).toBe(false);
+  });
+});

package/src/__tests__/encode-source-too-large.unit.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  type EncodeSourceInfo,
+  encodeTextureToKtx2,
+  MAX_ENCODE_SOURCE_PIXELS,
+} from '../ktx2-encode.js';
+
+/**
+ * Encoder source-pixel fail-fast gate (CI-red fix, human decision).
+ *
+ * The wasm32 Basis encoder ceiling is 4096x4096 = 16.78 Mpx (MAX_ENCODE_SOURCE_PIXELS);
+ * above it the raw encoder returns 0 bytes silently. `encodeTextureToKtx2` pre-checks
+ * width*height and, when it exceeds the ceiling, returns a structured
+ * `ktx2-encode-source-too-large` error WITHOUT calling the encoder -- so the failure is
+ * actionable ("reduce resolution or set compressionMode:'none'") instead of an opaque
+ * 0-byte encode failure. This test asserts both the boundary behavior and that the
+ * encoder is never reached for an over-limit source.
+ *
+ * The over-limit path is exercised with a tiny buffer + explicit dimensions: the
+ * pre-check only reads width*height, never the pixel bytes, so no real megapixel
+ * allocation is needed and no WASM is loaded.
+ */
+
+// Spy on the codec encode binding: an over-limit source must never reach it.
+const basisEncodeSpy = vi.fn();
+vi.mock('@forgeax/engine-codec/encode', () => ({
+  basisEncode: (...args: unknown[]) => basisEncodeSpy(...args),
+}));
+
+const SRGB: EncodeSourceInfo = { colorSpace: 'srgb', isHdr: false };
+
+describe('encodeTextureToKtx2 -- source-pixel ceiling fail-fast', () => {
+  it('MAX_ENCODE_SOURCE_PIXELS is 4096x4096 (16.78 Mpx)', () => {
+    expect(MAX_ENCODE_SOURCE_PIXELS).toBe(4096 * 4096);
+    expect(MAX_ENCODE_SOURCE_PIXELS).toBe(16_777_216);
+  });
+
+  it('rejects a >4096^2 source with ktx2-encode-source-too-large, without calling the encoder', async () => {
+    basisEncodeSpy.mockClear();
+    // 8192x8192 = 67 Mpx, well over the ceiling. A 4-byte stub buffer suffices:
+    // the pre-check reads only the dimensions.
+    const r = await encodeTextureToKtx2(new Uint8Array(4), 8192, 8192, 'etc1s', SRGB);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.code).toBe('ktx2-encode-source-too-large');
+    expect(r.error.mode).toBe('etc1s');
+    expect(r.error.reason).toContain('8192x8192');
+    expect(r.error.reason).toContain('4096x4096');
+    expect(basisEncodeSpy).not.toHaveBeenCalled();
+  });
+
+  it('rejects the first over-limit size just past the ceiling (4097x4096)', async () => {
+    basisEncodeSpy.mockClear();
+    const r = await encodeTextureToKtx2(new Uint8Array(4), 4097, 4096, 'etc1s', SRGB);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.code).toBe('ktx2-encode-source-too-large');
+    expect(basisEncodeSpy).not.toHaveBeenCalled();
+  });
+
+  it('an exactly-4096^2 source passes the ceiling and reaches the encoder', async () => {
+    basisEncodeSpy.mockClear();
+    basisEncodeSpy.mockResolvedValue({ ok: true, value: new Uint8Array([1, 2, 3]) });
+    const r = await encodeTextureToKtx2(new Uint8Array(4), 4096, 4096, 'etc1s', SRGB);
+    expect(basisEncodeSpy).toHaveBeenCalledTimes(1);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.mode).toBe('etc1s');
+  });
+
+  it("the 'none' path still short-circuits before the ceiling check", async () => {
+    basisEncodeSpy.mockClear();
+    // Over-limit dimensions but mode 'none' -> resolves to null params first.
+    const r = await encodeTextureToKtx2(new Uint8Array(4), 8192, 8192, 'none', SRGB);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.code).toBe('ktx2-encode-failed');
+    expect(r.error.mode).toBe('none');
+    expect(basisEncodeSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,148 @@
+import type {
+  DecodedImage,
+  ImageError,
+  ImageErrorCode,
+  ImageErrorDetail,
+  ImageErrorDetailFor,
+  ImageErrorFor,
+  ImageMeta,
+} from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+
+// Type-only tests. Verify the 8-member ImageErrorCode closed union compiles
+// an exhaustive switch without a default arm (charter P4 explicit failure).
+// Verifies the discriminated ImageErrorDetail narrowing per .code (charter
+// P3 machine-readable union > prose; AGENTS.md Error model row pattern).
+//
+// feat-20260521-sprite-atlas-animation M1 T-03 update: union grew from 5 to
+// 8 with the atlas-* triplet (atlas-empty-input / atlas-size-exceeded /
+// atlas-region-mismatch). The exact-member assertion + exhaustive switch
+// arms below mirror the SSOT in @forgeax/engine-types ImageErrorCode +
+// ImageErrorDetail so a future minor add still fails this file at compile
+// time until the new arm + .expected + .hint rows are supplied.
+
+describe('ImageErrorCode + ImageErrorDetail closed union compile contract', () => {
+  it('ImageErrorCode is the exact 8-member union literal set', () => {
+    expectTypeOf<ImageErrorCode>().toEqualTypeOf<
+      | 'image-decode-failed'
+      | 'image-format-unsupported'
+      | 'image-dimension-out-of-bounds'
+      | 'image-meta-missing'
+      | 'image-hdr-decode-failed'
+      | 'atlas-empty-input'
+      | 'atlas-size-exceeded'
+      | 'atlas-region-mismatch'
+    >();
+  });
+
+  it('exhaustive switch on err.code compiles with no default arm (charter P4)', () => {
+    function recover(code: ImageErrorCode): string {
+      switch (code) {
+        case 'image-decode-failed':
+          return 'check file integrity / re-export from DCC tool';
+        case 'image-format-unsupported':
+          return 'convert to PNG or JPG';
+        case 'image-dimension-out-of-bounds':
+          return 'downscale source under device caps maxDimension';
+        case 'image-meta-missing':
+          return 'run forgeax-engine-remote-asset import <path>';
+        case 'image-hdr-decode-failed':
+          return 'verify Radiance RGBE header and FORMAT=32-bit_rle_rgbe field';
+        case 'atlas-empty-input':
+          return 'verify forgeax-engine-remote-asset atlas --input glob matches at least 1 PNG';
+        case 'atlas-size-exceeded':
+          return 'downscale source or split atlas under maxAtlasSize cap';
+        case 'atlas-region-mismatch':
+          return 'shelfPack regions exceed atlas footprint -- packer safety net';
+      }
+    }
+    expectTypeOf(recover).toBeFunction();
+  });
+
+  it('ImageErrorDetail narrows per .code via discriminated union pattern', () => {
+    function describe_(detail: ImageErrorDetail): string {
+      switch (detail.code) {
+        case 'image-decode-failed':
+          return detail.reason;
+        case 'image-format-unsupported':
+          return detail.actualMime;
+        case 'image-dimension-out-of-bounds':
+          return `${detail.requested.width}x${detail.requested.height} > ${detail.limit}`;
+        case 'image-meta-missing':
+          return `${detail.sourcePath} -> ${detail.expectedSidecarPath}`;
+        case 'image-hdr-decode-failed':
+          return detail.reason;
+        case 'atlas-empty-input':
+          return `atlas-empty:${detail.receivedCount}`;
+        case 'atlas-size-exceeded':
+          return `atlas-size:${detail.name}:${detail.width}x${detail.height}>${detail.maxAtlasSize}`;
+        case 'atlas-region-mismatch':
+          return `atlas-region:${detail.name}:${detail.regionsTotalPixels}>${detail.atlasPixels}`;
+      }
+    }
+    expectTypeOf(describe_).toBeFunction();
+  });
+
+  it('ImageError correlates envelope code and detail shape', () => {
+    function describeError(error: ImageError): string {
+      switch (error.code) {
+        case 'image-decode-failed':
+          return error.detail.reason;
+        case 'image-format-unsupported':
+          return error.detail.actualMime;
+        case 'image-dimension-out-of-bounds':
+          return `${error.detail.requested.width} > ${error.detail.limit}`;
+        case 'image-meta-missing':
+          return error.detail.expectedSidecarPath;
+        case 'image-hdr-decode-failed':
+          return error.detail.reason;
+        case 'atlas-empty-input':
+          return `${error.detail.receivedCount}`;
+        case 'atlas-size-exceeded':
+          return `${error.detail.name}:${error.detail.maxAtlasSize}`;
+        case 'atlas-region-mismatch':
+          return `${error.detail.name}:${error.detail.atlasPixels}`;
+      }
+    }
+
+    expectTypeOf(describeError).toBeFunction();
+    expectTypeOf<ImageErrorDetailFor<'image-decode-failed'>>().toMatchTypeOf<{
+      code: 'image-decode-failed';
+      reason: string;
+    }>();
+    expectTypeOf<ImageErrorFor<'image-format-unsupported'>>().toMatchTypeOf<{
+      code: 'image-format-unsupported';
+      detail: { actualMime: string };
+    }>();
+  });
+
+  it('ImageMeta POD has the 5 free-form fields (guid + 4 importer settings)', () => {
+    expectTypeOf<ImageMeta>().toMatchTypeOf<{
+      guid: string;
+      colorSpace: 'srgb' | 'linear';
+      mipmap: 'auto' | 'none';
+      addressMode: 'repeat' | 'clamp-to-edge' | 'mirror-repeat';
+      filterMode: 'nearest' | 'linear';
+    }>();
+  });
+
+  it('DecodedImage POD has the 6 fields (bytes + dims + mime + colorSpace + mipmap)', () => {
+    expectTypeOf<DecodedImage>().toMatchTypeOf<{
+      bytes: Uint8Array;
+      width: number;
+      height: number;
+      mime: 'image/jpeg' | 'image/png' | 'image/x-tga';
+      colorSpace: 'srgb' | 'linear';
+      mipmap: boolean;
+    }>();
+  });
+
+  it('ImageError 4-field surface (.code / .expected / .hint / .detail) parallels RhiError shape', () => {
+    expectTypeOf<ImageError>().toMatchTypeOf<{
+      code: ImageErrorCode;
+      expected: string;
+      hint: string;
+      detail: ImageErrorDetail;
+    }>();
+  });
+});