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

package/src/index.ts

@@ -0,0 +1,44 @@
+// @forgeax/engine-image -- main entry public surface.
+//
+// Browser-safe pure functions translate disk-side image bytes + sidecar
+// settings into POD that the runtime AssetRegistry.uploadTexture 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';
+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,217 @@
+// 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';
+
+/** The sidecar control-plane value (ImageMetadata.compressionMode). */
+export type CompressionMode = 'auto' | 'etc1s' | 'uastc' | 'none';
+
+/** The resolved delivery encoding after 'auto' derivation. `'none'` = no encode. */
+export type ResolvedEncodeMode = 'etc1s' | 'uastc' | 'uastc-hdr' | 'none';
+
+/** 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 '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';
+  }
+}
+
+/** 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 '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,
+      };
+  }
+}
+
+/** 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,176 @@
+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'];
+
+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`
+ * - 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 {
+      // 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;
+    }
+  } 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',
+    colorSpace: opts.colorSpace ?? 'srgb',
+    mipmap: opts.mipmap ?? true,
+  });
+}

package/src/reimport-reuse-meta.ts

@@ -0,0 +1,160 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { DecodedImage, ImageColorSpace } from '@forgeax/engine-types';
+
+import { deriveImageSourceKey } from './source-key.js';
+import type { SubAssetKey } from './sub-asset-key.js';
+import { subAssetKey, subAssetKeyEqual } from './sub-asset-key.js';
+
+/**
+ * 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 function reimportReuseMeta(
+  decoded: DecodedImage,
+  existing: ExistingExternalAssetPackage | undefined,
+): readonly EmittedSubAsset[] {
+  // Image disk schema is single-sub-asset; the future multi-asset path
+  // iterates a producer-side list of sub-asset keys instead of a single one.
+  const freshKeys: readonly SubAssetKey[] = [subAssetKey({ kind: 'texture', sourceIndex: 0 })];
+
+  const out: EmittedSubAsset[] = [];
+  const sourceKey = deriveImageSourceKey('texture');
+
+  for (let i = 0; i < freshKeys.length; i++) {
+    const fresh = freshKeys[i];
+    if (fresh === undefined) continue;
+
+    let reuseGuid: string | undefined;
+    if (existing !== undefined) {
+      for (const candidate of existing.subAssets) {
+        if (sourceKey !== undefined && candidate.sourceKey === sourceKey) {
+          reuseGuid = candidate.guid;
+          break;
+        }
+        const candidateKey = subAssetKey({
+          kind: candidate.kind,
+          sourceIndex: candidate.sourceIndex,
+          ...(candidate.name !== undefined ? { name: candidate.name } : {}),
+        });
+        if (subAssetKeyEqual(fresh, candidateKey)) {
+          reuseGuid = candidate.guid;
+          break;
+        }
+      }
+    }
+
+    const guid = reuseGuid ?? AssetGuid.format(AssetGuid.random());
+    const emit: EmittedSubAsset =
+      fresh.name !== undefined
+        ? {
+            guid,
+            sourceIndex: i,
+            kind: fresh.kind,
+            name: fresh.name,
+            ...(sourceKey === undefined ? {} : { sourceKey }),
+          }
+        : {
+            guid,
+            sourceIndex: i,
+            kind: fresh.kind,
+            ...(sourceKey === undefined ? {} : { sourceKey }),
+          };
+    out.push(emit);
+  }
+
+  // Ensure decoded ref is consumed (decoded.bytes is the producer signal that
+  // a sub-asset exists; without bytes there is nothing to emit). The
+  // signature keeps `decoded` in the public surface so the future cubemap /
+  // array-layer feat can derive its multi-sub-asset list from `decoded`
+  // metadata without a breaking change (charter P5 consistent abstraction).
+  void decoded;
+
+  return out;
+}
+
+/**
+ * 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 function validateColorSpaceForHdr(
+  ext: string,
+  colorSpace: ImageColorSpace,
+): { ok: true; value: ImageColorSpace } | { ok: false; expected: string; actual: string } {
+  const lower = ext.toLowerCase();
+  if (lower === '.hdr' || lower === '.exr') {
+    if (colorSpace !== 'linear') {
+      return {
+        ok: false,
+        expected: 'colorSpace=linear for HDR source files',
+        actual: `colorSpace=${colorSpace}`,
+      };
+    }
+    return { ok: true, value: 'linear' };
+  }
+  return { ok: true, value: colorSpace };
+}

package/src/resize-image.ts

@@ -0,0 +1,39 @@
+/** Deterministically downscale tight-packed RGBA pixels with bilinear sampling. */
+export function downscaleRgba(
+  bytes: Uint8Array,
+  width: number,
+  height: number,
+  maxDimension: number,
+): { readonly bytes: Uint8Array; readonly width: number; readonly height: number } {
+  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: number, y: number, channel: number): number =>
+    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 };
+}

package/src/result.ts

@@ -0,0 +1,13 @@
+// Result<T, E> + ok / err live in `@forgeax/engine-types` (tweak-20260612-result-
+// into-types). They were duplicated here as a lite (plain-object, no `unwrap`)
+// variant; consolidated upstream into the same shape used by rhi / ecs / naga.
+// The barrel here re-exports them so existing
+// `import { err, ok, Result, ResultOk, ResultErr } from '@forgeax/engine-image'`
+// consumers (and intra-package `./result.js` imports) stay unchanged.
+export {
+  err,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+} from '@forgeax/engine-types';