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

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@forgeax/engine-image",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "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.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-math": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79",
+    "jpeg-js": "^0.4.4",
+    "pako": "^1.0.11",
+    "upng-js": "^2.1.0"
+  },
+  "devDependencies": {
+    "@forgeax/engine-import": "0.0.0-dev.8d955ade1c79",
+    "@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;
+    }>();
+  });
+});