@forgeax/engine-image 0.1.2

package/src/index.ts

@@ -0,0 +1,46 @@
+// @forgeax/engine-image -- main entry public surface.
+//
+// Browser-safe pure functions translate disk-side image bytes + sidecar
+// settings into POD that the runtime Render DeviceScope path consumes
+// (plan-strategy section 3.2 sequence A; charter P5 producer /
+// consumer split). Node-only decoders (parseImage / decodeImageFromFile)
+// are split into Node-only sub-exports per feat-20260524-browser-safe-subexports
+// and are NOT re-exported from this main entry -- import them via:
+//   - `@forgeax/engine-image/parse-image`            (Node-only sub-export)
+//   - `@forgeax/engine-image/decode-image-from-file` (Node-only sub-export)
+//
+// Main entry surface (browser-safe):
+//   - decodeImageInBrowser           -- browser-mode createImageBitmap path
+//   - toAssetPack(decoded, meta)     -- POD -> external-asset-package envelope
+//   - subAssetKey / subAssetKeyEqual -- gltf-aligned sub-asset matching
+//   - reimportReuseMeta              -- two-phase GUID preservation
+//   - imageError / ImageErrorImpl    -- structured 4-field error class
+//   - decodeHdr                      -- HDR sub-export passthrough (legacy)
+//   - loadJpeg / loadUpng            -- lazy Node decoder loaders (legacy; OOS-2)
+
+export { IMAGE_ERROR_EXPECTED, ImageErrorImpl, imageError } from './errors.js';
+export { decodeHdr } from './hdr-decoder.js';
+export { decodeImageInBrowser } from './image-decoder-browser.js';
+export type { JpegModule, UpngModule } from './image-decoder-node.js';
+export { loadJpeg, loadUpng } from './image-decoder-node.js';
+export type {
+  EmittedSubAsset,
+  ExistingExternalAssetPackage,
+  ExistingSubAsset,
+} from './reimport-reuse-meta.js';
+export { reimportReuseMeta } from './reimport-reuse-meta.js';
+export type { Result, ResultErr, ResultOk } from './result.js';
+export { err, ok } from './result.js';
+export { equirectContribution, textureContribution } from './runtime/asset-decoders.js';
+export { decodeImageBytes } from './runtime/decode-image-bytes.js';
+export { runtimeImageError } from './runtime/image-error.js';
+export type { ImageSourceKeyLocator } from './source-key.js';
+export { deriveImageSourceKey } from './source-key.js';
+export type { SubAssetKey, SubAssetKeyInput } from './sub-asset-key.js';
+export { subAssetKey, subAssetKeyEqual } from './sub-asset-key.js';
+export type {
+  ExternalAssetPackage,
+  ExternalSubAsset,
+  ImageImportSettings,
+} from './to-asset-pack.js';
+export { toAssetPack } from './to-asset-pack.js';

package/src/ktx2-encode.ts

@@ -0,0 +1,221 @@
+// ktx2-encode.ts -- the image-side offline texture encode arm (M3 w18, D-5).
+//
+// This module is the image-semantic layer of the Basis encode path: it maps the
+// sidecar `compressionMode` control-plane value + the source's colorSpace / HDR
+// signal into a delivery encoding (D-12 'auto' derivation), maps that to the
+// encoder parameters, and drives the low-level `basisEncode` binding that lives
+// in `@forgeax/engine-codec/encode` (the WASM + enum plumbing stays in codec;
+// the image semantics stay here -- D-5 "arm in image, binary in codec/encode").
+//
+// It is a NODE-ONLY build-time module (consumed by imageImporter, itself a
+// node-only sub-export). It never touches GPU (isolation path b) and is never
+// bundled into the runtime (isolation path a/d: runtime does not import
+// @forgeax/engine-image nor @forgeax/engine-codec/encode).
+//
+// M3 sequencing constraint (plan R-9): the 'auto' derivation is implemented and
+// tested here, but the sidecar DEFAULT stays 'none'. The default flip to 'auto'
+// is M5 (w38); doing it here would make every existing texture encode to Basis
+// ahead of loader support and redden the whole fixture fleet.
+
+import type { BasisEncodeMode } from '@forgeax/engine-codec/encode';
+import { basisEncode } from '@forgeax/engine-codec/encode';
+
+const COMPRESSION_MODES = ['auto', 'etc1s', 'uastc', 'none'] as const;
+
+/** The sidecar control-plane value (ImageMetadata.compressionMode). */
+export type CompressionMode = (typeof COMPRESSION_MODES)[number];
+
+const RESOLVED_ENCODE_MODES = ['etc1s', 'uastc', 'uastc-hdr', 'none'] as const;
+
+/** The resolved delivery encoding after 'auto' derivation. `'none'` = no encode. */
+export type ResolvedEncodeMode = (typeof RESOLVED_ENCODE_MODES)[number];
+
+/** Source signals that drive 'auto' derivation (D-12) and encoder params. */
+export interface EncodeSourceInfo {
+  /** Color transfer of the source (from the sidecar importSettings). */
+  readonly colorSpace: 'srgb' | 'linear';
+  /** Whether the source is an HDR image (.hdr -> rgba16float). */
+  readonly isHdr: boolean;
+}
+
+/**
+ * Resolve the sidecar `compressionMode` into a concrete delivery encoding.
+ *
+ * D-12 'auto' derivation (zero new required inputs, derived from existing
+ * sidecar signals):
+ *   - HDR source            -> 'uastc-hdr'  (BC6H target downstream)
+ *   - colorSpace 'srgb'     -> 'etc1s'      (albedo / UI color)
+ *   - colorSpace 'linear'   -> 'uastc'      (normals / ORM / data)
+ *
+ * Explicit modes pass through, except an explicit 'uastc' on an HDR source
+ * resolves to 'uastc-hdr' (there is no LDR UASTC path for HDR pixels). 'none'
+ * and 'etc1s' pass through verbatim.
+ */
+export function resolveEncodeMode(
+  mode: CompressionMode,
+  source: EncodeSourceInfo,
+): ResolvedEncodeMode {
+  switch (mode) {
+    case COMPRESSION_MODES[3]:
+      return RESOLVED_ENCODE_MODES[3];
+    case COMPRESSION_MODES[1]:
+      return RESOLVED_ENCODE_MODES[0];
+    case COMPRESSION_MODES[2]:
+      return source.isHdr ? RESOLVED_ENCODE_MODES[2] : RESOLVED_ENCODE_MODES[1];
+    case COMPRESSION_MODES[0]:
+      if (source.isHdr) return RESOLVED_ENCODE_MODES[2];
+      return source.colorSpace === 'srgb' ? RESOLVED_ENCODE_MODES[0] : RESOLVED_ENCODE_MODES[1];
+  }
+}
+
+/** Encoder parameters for a resolved delivery encoding. */
+export interface BasisEncodeParams {
+  /** The codec-side delivery encoding. */
+  readonly mode: BasisEncodeMode;
+  /** Write the sRGB transfer function (LDR color only). */
+  readonly srgb: boolean;
+  /** ETC1S perceptual (sRGB) metric. */
+  readonly perceptual: boolean;
+  /** Wrap the UASTC-LDR payload in KTX2 zstd supercompression. */
+  readonly uastcSupercompression: boolean;
+  /** Encoder-side mip generation. M3 keeps this false (offline mips land in M5). */
+  readonly mipGen: boolean;
+}
+
+/**
+ * Map the sidecar mode + source into encoder parameters. Returns `null` for the
+ * 'none' path -- the caller keeps the uncompressed `.bin` path and never calls
+ * the encoder.
+ */
+export function basisEncodeParamsFor(
+  mode: CompressionMode,
+  source: EncodeSourceInfo,
+): BasisEncodeParams | null {
+  const resolved = resolveEncodeMode(mode, source);
+  const srgbColor = source.colorSpace === 'srgb';
+  switch (resolved) {
+    case RESOLVED_ENCODE_MODES[3]:
+      return null;
+    case RESOLVED_ENCODE_MODES[0]:
+      return {
+        mode: RESOLVED_ENCODE_MODES[0],
+        srgb: srgbColor,
+        perceptual: srgbColor,
+        uastcSupercompression: false,
+        mipGen: false,
+      };
+    case RESOLVED_ENCODE_MODES[1]:
+      return {
+        mode: 'uastc-ldr',
+        srgb: srgbColor,
+        perceptual: srgbColor,
+        uastcSupercompression: true,
+        mipGen: false,
+      };
+    case RESOLVED_ENCODE_MODES[2]:
+      return {
+        mode: RESOLVED_ENCODE_MODES[2],
+        srgb: false,
+        perceptual: false,
+        uastcSupercompression: false,
+        mipGen: false,
+      };
+  }
+}
+
+/** A successful encode result: KTX2 bytes + the resolved delivery encoding. */
+export interface EncodedTexture {
+  readonly ktx2: Uint8Array;
+  readonly mode: ResolvedEncodeMode;
+}
+
+/**
+ * Maximum source pixels the wasm32 Basis encoder accepts (4096x4096 = 16.78 Mpx
+ * = 1024*1024*16). This mirrors the raised `BASISU_ENCODER_MAX_SOURCE_IMAGE_PIXELS`
+ * ceiling patched into the encoder WASM (packages/codec/scripts/build-wasm.mjs).
+ * Sources above this are rejected fast with a structured `ktx2-encode-source-too-large`
+ * error rather than reaching the encoder and getting a silent 0-byte failure.
+ */
+export const MAX_ENCODE_SOURCE_PIXELS = 4096 * 4096;
+
+/** Failure result carrying a short reason (encoder-side or invalid request). */
+export interface EncodeFailure {
+  readonly code: 'ktx2-encode-failed' | 'codec-init-failed' | 'ktx2-encode-source-too-large';
+  readonly mode: ResolvedEncodeMode;
+  readonly reason: string;
+}
+
+export type EncodeTextureResult =
+  | { readonly ok: true; readonly value: EncodedTexture }
+  | { readonly ok: false; readonly error: EncodeFailure };
+
+/**
+ * Encode source pixels into a Basis KTX2 texture per the sidecar mode.
+ *
+ * `pixels` is tight-packed RGBA: 8-bit RGBA for LDR sources, rgba16float bytes
+ * for HDR sources. Returns `{ ok: false }` with `mode: 'none'` if the sidecar
+ * mode resolves to 'none' -- the importer treats that as "no encode, keep the
+ * .bin path" rather than an error (see importer callsite w18).
+ */
+export async function encodeTextureToKtx2(
+  pixels: Uint8Array,
+  width: number,
+  height: number,
+  mode: CompressionMode,
+  source: EncodeSourceInfo,
+): Promise<EncodeTextureResult> {
+  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);
+  // Fail fast above the wasm32 encoder's source-pixel ceiling (4096^2). Above
+  // this the encoder returns 0 bytes silently; surface a structured, actionable
+  // error instead so the importer reports "reduce resolution or set
+  // compressionMode:'none'" rather than an opaque encode failure.
+  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 !== undefined && 'reason' in result.error.detail
+        ? String((result.error.detail as { reason: unknown }).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 } };
+}

package/src/parse-image.ts

@@ -0,0 +1,276 @@
+import type { DecodedImage, ImageColorSpace, ImageError } from '@forgeax/engine-types';
+import * as jpeg from 'jpeg-js';
+// Static imports of upng-js + jpeg-js. tsup external keeps both as runtime
+// require() calls so the browser bundle still tree-shakes them out when
+// only image-decoder-browser.ts (createImageBitmap) is reached at runtime.
+// Synchronous decode is required by the parseImage signature contract (see
+// plan-strategy section 3.3).
+import * as UPNG from 'upng-js';
+import { imageError } from './errors.js';
+import { downscaleRgba } from './resize-image.js';
+import type { Result } from './result.js';
+import { err, ok } 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;
+}
+
+const DEFAULT_MAX_DIMENSION = 16384;
+
+const SUPPORTED_MIMES: readonly string[] = ['image/png', 'image/jpeg', 'image/x-tga'];
+
+interface UpngDecoded {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8Array;
+}
+
+interface JpegDecoded {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8Array;
+}
+
+/**
+ * Pure synchronous image decoder. Translates raw byte stream + mime hint
+ * into a tight-packed RGBA `DecodedImage` POD. Surfaces all four
+ * ImageErrorCode members through the structured `Result<DecodedImage,
+ * ImageError>` return (charter P3 explicit failure; AGENTS.md "Return
+ * Result, never throw").
+ *
+ * Decoder selection follows the mime hint:
+ * - `image/png` -> upng-js `UPNG.decode` + `UPNG.toRGBA8`
+ * - `image/jpeg` -> jpeg-js `decode` with `formatAsRGBA: true`
+ * - `image/x-tga` -> the built-in TGA true-color/grayscale decoder
+ * - other -> `image-format-unsupported`
+ *
+ * Decoded bytes are always tight-packed RGBA (`bytes.length === width *
+ * height * 4`). `colorSpace` and `mipmap` are carried from the supplied
+ * `ParseImageOptions` (decodeImageFromFile passes the sidecar settings).
+ */
+export function parseImage(
+  bytes: Uint8Array,
+  mime: string,
+  opts: ParseImageOptions = {},
+): Result<DecodedImage, ImageError> {
+  if (!SUPPORTED_MIMES.includes(mime)) {
+    return err(
+      imageError({
+        code: 'image-format-unsupported',
+        actualMime: mime,
+        ...(opts.path !== undefined ? { path: opts.path } : {}),
+      }),
+    );
+  }
+
+  let width = 0;
+  let height = 0;
+  let rgba: Uint8Array;
+
+  try {
+    if (mime === 'image/png') {
+      const upngMod: {
+        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;
+        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];
+      } = ((UPNG as unknown as { default?: typeof UPNG }).default ?? UPNG) as unknown as {
+        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;
+        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];
+      };
+      const decoded = upngMod.decode(bytes);
+      width = decoded.width;
+      height = decoded.height;
+      const frames = upngMod.toRGBA8(decoded);
+      const first = frames[0];
+      if (first === undefined) {
+        return err(
+          imageError({
+            code: 'image-decode-failed',
+            reason: 'UPNG.toRGBA8 returned no frames',
+            ...(opts.path !== undefined ? { path: opts.path } : {}),
+          }),
+        );
+      }
+      rgba = new Uint8Array(first);
+    } else if (mime === 'image/jpeg') {
+      // image/jpeg
+      const jpegMod: {
+        decode: (
+          b: Uint8Array | ArrayBuffer,
+          o?: { useTArray?: boolean; formatAsRGBA?: boolean },
+        ) => JpegDecoded;
+      } = ((jpeg as unknown as { default?: typeof jpeg }).default ?? jpeg) as unknown as {
+        decode: (
+          b: Uint8Array | ArrayBuffer,
+          o?: { useTArray?: boolean; formatAsRGBA?: boolean },
+        ) => JpegDecoded;
+      };
+      const decoded = jpegMod.decode(bytes, { useTArray: true, formatAsRGBA: true });
+      width = decoded.width;
+      height = decoded.height;
+      rgba = decoded.data;
+    } else {
+      const decoded = decodeTga(bytes);
+      width = decoded.width;
+      height = decoded.height;
+      rgba = decoded.bytes;
+    }
+  } catch (e) {
+    return err(
+      imageError({
+        code: 'image-decode-failed',
+        reason: e instanceof Error ? e.message : String(e),
+        ...(opts.path !== undefined ? { path: opts.path } : {}),
+      }),
+    );
+  }
+
+  const downscaleLimit = opts.downscaleMaxDimension;
+  if (downscaleLimit !== undefined && 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: mime as 'image/png' | 'image/jpeg' | 'image/x-tga',
+    colorSpace: opts.colorSpace ?? 'srgb',
+    mipmap: opts.mipmap ?? true,
+  });
+}
+
+interface TgaDecoded {
+  readonly width: number;
+  readonly height: number;
+  readonly bytes: Uint8Array;
+}
+
+/**
+ * Decode the portable TGA subset used by common FBX exports.
+ *
+ * The decoder owns the format boundary instead of trusting the extension: it
+ * validates the header, supports uncompressed and RLE true-colour (24/32-bit)
+ * plus grayscale (8-bit), and applies the origin bits from the image
+ * descriptor while producing a top-left RGBA POD.
+ */
+function decodeTga(bytes: Uint8Array): TgaDecoded {
+  if (bytes.length < 18) throw new Error('TGA header is truncated');
+
+  const colorMapType = bytes[1];
+  const imageType = bytes[2];
+  const idLength = bytes[0] ?? 0;
+  const width = (bytes[12] ?? 0) | ((bytes[13] ?? 0) << 8);
+  const height = (bytes[14] ?? 0) | ((bytes[15] ?? 0) << 8);
+  const pixelDepth = bytes[16] ?? 0;
+  const descriptor = bytes[17] ?? 0;
+  if (colorMapType !== 0) throw new Error('color-mapped TGA is unsupported');
+  if (width < 1 || height < 1) throw new Error('TGA dimensions must be positive');
+
+  const isTrueColor = imageType === 2 || imageType === 10;
+  const isGray = imageType === 3 || imageType === 11;
+  if (!isTrueColor && !isGray) throw new Error(`TGA image type ${imageType} is unsupported`);
+  if (isTrueColor && pixelDepth !== 24 && pixelDepth !== 32) {
+    throw new Error(`TGA true-color depth ${pixelDepth} is unsupported`);
+  }
+  if (isGray && pixelDepth !== 8)
+    throw new Error(`TGA grayscale depth ${pixelDepth} is unsupported`);
+
+  const bytesPerPixel = pixelDepth / 8;
+  let offset = 18 + idLength;
+  const pixelCount = width * height;
+  const out = new Uint8Array(pixelCount * 4);
+  const topOrigin = (descriptor & 0x20) !== 0;
+  const rightOrigin = (descriptor & 0x10) !== 0;
+  let filePixel = 0;
+
+  const writePixel = (pixel: Uint8Array): void => {
+    if (filePixel >= pixelCount) throw new Error('TGA pixel data has too many pixels');
+    const fileX = filePixel % width;
+    const fileY = Math.floor(filePixel / width);
+    const x = rightOrigin ? width - 1 - fileX : fileX;
+    const y = topOrigin ? fileY : height - 1 - fileY;
+    const destination = (y * width + x) * 4;
+    if (isGray) {
+      const value = pixel[0] ?? 0;
+      out[destination] = value;
+      out[destination + 1] = value;
+      out[destination + 2] = value;
+      out[destination + 3] = 255;
+    } else {
+      out[destination] = pixel[2] ?? 0;
+      out[destination + 1] = pixel[1] ?? 0;
+      out[destination + 2] = pixel[0] ?? 0;
+      out[destination + 3] = bytesPerPixel === 4 ? (pixel[3] ?? 255) : 255;
+    }
+    filePixel += 1;
+  };
+
+  const readPixel = (): Uint8Array => {
+    if (offset + bytesPerPixel > bytes.length) throw new Error('TGA pixel data is truncated');
+    const pixel = bytes.slice(offset, offset + bytesPerPixel);
+    offset += bytesPerPixel;
+    return pixel;
+  };
+
+  if (imageType === 2 || imageType === 3) {
+    while (filePixel < pixelCount) writePixel(readPixel());
+  } else {
+    while (filePixel < pixelCount) {
+      if (offset >= bytes.length) throw new Error('TGA RLE packet header is truncated');
+      const packet = bytes[offset++] ?? 0;
+      const count = (packet & 0x7f) + 1;
+      if (filePixel + count > pixelCount) throw new Error('TGA RLE packet exceeds image bounds');
+      if ((packet & 0x80) !== 0) {
+        const pixel = readPixel();
+        for (let i = 0; i < count; i++) writePixel(pixel);
+      } else {
+        for (let i = 0; i < count; i++) writePixel(readPixel());
+      }
+    }
+  }
+
+  if (filePixel !== pixelCount) throw new Error('TGA pixel count mismatch');
+  return { width, height, bytes: out };
+}