@forgeax/engine-image 0.1.4 → 0.1.7

package/dist/parse-image.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/resize-image.ts","../src/parse-image.ts"],"names":[],"mappings":"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","file":"parse-image.mjs","sourcesContent":["import type { ImageErrorCode, ImageErrorDetailFor, ImageErrorFor } from '@forgeax/engine-types';\nimport { IMAGE_ERROR_HINTS } from '@forgeax/engine-types';\n\n// Per-code .expected string literals SSOT.\n// Mirrors ASSET_ERROR_HINTS / IMAGE_ERROR_HINTS shape (charter P5 consistent\n// abstraction). AI users surface .expected when a structured error needs to\n// describe the precondition that was violated.\nconst IMAGE_ERROR_EXPECTED: Readonly<Record<ImageErrorCode, string>> = {\n  'image-decode-failed': 'PNG / JPG byte stream decodes successfully',\n  'image-format-unsupported':\n    \"mime is one of ['image/png', 'image/jpeg', 'image/x-tga']; uploadTexture format <-> colorSpace family agrees\",\n  'image-dimension-out-of-bounds':\n    'width and height fall under device caps maxTextureDimension2D (or 16384 hard cap)',\n  'image-meta-missing':\n    \"<source>.meta.json sidecar (importer: 'image') exists in the same directory\",\n  'image-hdr-decode-failed': 'Radiance RGBE header is valid and pixel data decodes successfully',\n  // feat-20260521-sprite-atlas-animation M1 T-03 — vite-plugin-image atlas\n  // hook .expected literals (plan-strategy section 2 D-2 + AC-10 a/b/c).\n  // ImageErrorImpl construction path is unchanged: the new atlas-* errors\n  // flow through `new ImageErrorImpl({ code: 'atlas-...', ...detail })` and\n  // pick the .expected string up from this Record at construction time\n  // (charter P3 explicit failure SSOT — AI users surface .expected next to\n  // .hint after switch (err.code) without parsing the message).\n  'atlas-empty-input': 'images.length >= 1',\n  'atlas-size-exceeded':\n    'image width x height <= maxAtlasSize^2 and each image fits in the atlas footprint',\n  'atlas-region-mismatch': 'sum(regions[i].w x regions[i].h) <= atlasWidth x atlasHeight',\n};\n\n/** Runtime implementation of the correlated `ImageErrorFor<C>` envelope. */\nexport class ImageErrorImpl<C extends ImageErrorCode = ImageErrorCode>\n  extends Error\n  implements ImageErrorFor<C>\n{\n  readonly code: C;\n  readonly expected: string;\n  readonly hint: string;\n  readonly detail: ImageErrorDetailFor<C>;\n\n  constructor(detail: ImageErrorDetailFor<C>) {\n    const code = detail.code;\n    const expected = IMAGE_ERROR_EXPECTED[code];\n    const hint = IMAGE_ERROR_HINTS[code];\n    super(`[ImageError ${code}] expected: ${expected}; hint: ${hint}`);\n    this.name = 'ImageError';\n    this.code = code;\n    this.expected = expected;\n    this.hint = hint;\n    this.detail = detail;\n  }\n}\n\n/** Construct a structured image error while preserving its code/detail pair. */\nexport function imageError<C extends ImageErrorCode>(\n  detail: ImageErrorDetailFor<C>,\n): ImageErrorFor<C> {\n  return new ImageErrorImpl<C>(detail);\n}\n\nexport { IMAGE_ERROR_EXPECTED };\n","/** Deterministically downscale tight-packed RGBA pixels with bilinear sampling. */\nexport function downscaleRgba(\n  bytes: Uint8Array,\n  width: number,\n  height: number,\n  maxDimension: number,\n): { readonly bytes: Uint8Array; readonly width: number; readonly height: number } {\n  if (width <= maxDimension && height <= maxDimension) {\n    return { bytes, width, height };\n  }\n\n  const scale = maxDimension / Math.max(width, height);\n  const targetWidth = Math.max(1, Math.round(width * scale));\n  const targetHeight = Math.max(1, Math.round(height * scale));\n  const output = new Uint8Array(targetWidth * targetHeight * 4);\n  const source = (x: number, y: number, channel: number): number =>\n    bytes[(y * width + x) * 4 + channel] ?? 0;\n\n  for (let y = 0; y < targetHeight; y += 1) {\n    const sourceY = ((y + 0.5) * height) / targetHeight - 0.5;\n    const y0 = Math.max(0, Math.floor(sourceY));\n    const y1 = Math.min(height - 1, y0 + 1);\n    const yWeight = Math.max(0, Math.min(1, sourceY - y0));\n    for (let x = 0; x < targetWidth; x += 1) {\n      const sourceX = ((x + 0.5) * width) / targetWidth - 0.5;\n      const x0 = Math.max(0, Math.floor(sourceX));\n      const x1 = Math.min(width - 1, x0 + 1);\n      const xWeight = Math.max(0, Math.min(1, sourceX - x0));\n      const outputOffset = (y * targetWidth + x) * 4;\n      for (let channel = 0; channel < 4; channel += 1) {\n        const top = source(x0, y0, channel) * (1 - xWeight) + source(x1, y0, channel) * xWeight;\n        const bottom = source(x0, y1, channel) * (1 - xWeight) + source(x1, y1, channel) * xWeight;\n        output[outputOffset + channel] = Math.round(top * (1 - yWeight) + bottom * yWeight);\n      }\n    }\n  }\n\n  return { bytes: output, width: targetWidth, height: targetHeight };\n}\n","import type { DecodedImage, ImageColorSpace, ImageError } from '@forgeax/engine-types';\nimport * as jpeg from 'jpeg-js';\n// Static imports of upng-js + jpeg-js. tsup external keeps both as runtime\n// require() calls so the browser bundle still tree-shakes them out when\n// only image-decoder-browser.ts (createImageBitmap) is reached at runtime.\n// Synchronous decode is required by the parseImage signature contract (see\n// plan-strategy section 3.3).\nimport * as UPNG from 'upng-js';\nimport { imageError } from './errors.js';\nimport { downscaleRgba } from './resize-image.js';\nimport type { Result } from './result.js';\nimport { err, ok } from './result.js';\n\nexport interface ParseImageOptions {\n  /**\n   * Maximum allowed dimension (width or height). Defaults to 16384 -- the\n   * conservative WebGPU `maxTextureDimension2D` floor across desktop +\n   * high-end mobile (research F-3 / spec). Test fixtures pass smaller\n   * values to exercise the bounds-check code path with tiny fixtures.\n   */\n  readonly maxDimension?: number;\n\n  /** Optional asset-owned cooked-payload target; source bytes remain unchanged. */\n  readonly downscaleMaxDimension?: number;\n\n  /**\n   * Sidecar `colorSpace` carried over to the DecodedImage POD. Defaults to\n   * 'srgb' (typical baseColor / albedo path; plan-strategy section 2.5).\n   */\n  readonly colorSpace?: ImageColorSpace;\n\n  /**\n   * Sidecar `mipmap` flag carried over to DecodedImage. Defaults to true\n   * (auto-generate via runtime mipmap-generator; plan-strategy section 2.6).\n   */\n  readonly mipmap?: boolean;\n\n  /**\n   * Optional source path to embed in error.detail.path (decode-failed /\n   * format-unsupported variants). decodeImageFromFile fills this in;\n   * in-memory parseImage callers leave it empty.\n   */\n  readonly path?: string;\n}\n\nconst DEFAULT_MAX_DIMENSION = 16384;\n\nconst SUPPORTED_MIMES: readonly string[] = ['image/png', 'image/jpeg', 'image/x-tga'];\n\ninterface UpngDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly data: Uint8Array;\n}\n\ninterface JpegDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly data: Uint8Array;\n}\n\n/**\n * Pure synchronous image decoder. Translates raw byte stream + mime hint\n * into a tight-packed RGBA `DecodedImage` POD. Surfaces all four\n * ImageErrorCode members through the structured `Result<DecodedImage,\n * ImageError>` return (charter P3 explicit failure; AGENTS.md \"Return\n * Result, never throw\").\n *\n * Decoder selection follows the mime hint:\n * - `image/png` -> upng-js `UPNG.decode` + `UPNG.toRGBA8`\n * - `image/jpeg` -> jpeg-js `decode` with `formatAsRGBA: true`\n * - `image/x-tga` -> the built-in TGA true-color/grayscale decoder\n * - other -> `image-format-unsupported`\n *\n * Decoded bytes are always tight-packed RGBA (`bytes.length === width *\n * height * 4`). `colorSpace` and `mipmap` are carried from the supplied\n * `ParseImageOptions` (decodeImageFromFile passes the sidecar settings).\n */\nexport function parseImage(\n  bytes: Uint8Array,\n  mime: string,\n  opts: ParseImageOptions = {},\n): Result<DecodedImage, ImageError> {\n  if (!SUPPORTED_MIMES.includes(mime)) {\n    return err(\n      imageError({\n        code: 'image-format-unsupported',\n        actualMime: mime,\n        ...(opts.path !== undefined ? { path: opts.path } : {}),\n      }),\n    );\n  }\n\n  let width = 0;\n  let height = 0;\n  let rgba: Uint8Array;\n\n  try {\n    if (mime === 'image/png') {\n      const upngMod: {\n        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;\n        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];\n      } = ((UPNG as unknown as { default?: typeof UPNG }).default ?? UPNG) as unknown as {\n        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;\n        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];\n      };\n      const decoded = upngMod.decode(bytes);\n      width = decoded.width;\n      height = decoded.height;\n      const frames = upngMod.toRGBA8(decoded);\n      const first = frames[0];\n      if (first === undefined) {\n        return err(\n          imageError({\n            code: 'image-decode-failed',\n            reason: 'UPNG.toRGBA8 returned no frames',\n            ...(opts.path !== undefined ? { path: opts.path } : {}),\n          }),\n        );\n      }\n      rgba = new Uint8Array(first);\n    } else if (mime === 'image/jpeg') {\n      // image/jpeg\n      const jpegMod: {\n        decode: (\n          b: Uint8Array | ArrayBuffer,\n          o?: { useTArray?: boolean; formatAsRGBA?: boolean },\n        ) => JpegDecoded;\n      } = ((jpeg as unknown as { default?: typeof jpeg }).default ?? jpeg) as unknown as {\n        decode: (\n          b: Uint8Array | ArrayBuffer,\n          o?: { useTArray?: boolean; formatAsRGBA?: boolean },\n        ) => JpegDecoded;\n      };\n      const decoded = jpegMod.decode(bytes, { useTArray: true, formatAsRGBA: true });\n      width = decoded.width;\n      height = decoded.height;\n      rgba = decoded.data;\n    } else {\n      const decoded = decodeTga(bytes);\n      width = decoded.width;\n      height = decoded.height;\n      rgba = decoded.bytes;\n    }\n  } catch (e) {\n    return err(\n      imageError({\n        code: 'image-decode-failed',\n        reason: e instanceof Error ? e.message : String(e),\n        ...(opts.path !== undefined ? { path: opts.path } : {}),\n      }),\n    );\n  }\n\n  const downscaleLimit = opts.downscaleMaxDimension;\n  if (downscaleLimit !== undefined && Number.isInteger(downscaleLimit) && downscaleLimit > 0) {\n    const downscaled = downscaleRgba(rgba, width, height, downscaleLimit);\n    rgba = downscaled.bytes;\n    width = downscaled.width;\n    height = downscaled.height;\n  }\n\n  const limit = opts.maxDimension ?? DEFAULT_MAX_DIMENSION;\n  if (width > limit || height > limit) {\n    return err(\n      imageError({\n        code: 'image-dimension-out-of-bounds',\n        requested: { width, height },\n        limit,\n      }),\n    );\n  }\n\n  return ok({\n    bytes: rgba,\n    width,\n    height,\n    mime: mime as 'image/png' | 'image/jpeg' | 'image/x-tga',\n    colorSpace: opts.colorSpace ?? 'srgb',\n    mipmap: opts.mipmap ?? true,\n  });\n}\n\ninterface TgaDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly bytes: Uint8Array;\n}\n\n/**\n * Decode the portable TGA subset used by common FBX exports.\n *\n * The decoder owns the format boundary instead of trusting the extension: it\n * validates the header, supports uncompressed and RLE true-colour (24/32-bit)\n * plus grayscale (8-bit), and applies the origin bits from the image\n * descriptor while producing a top-left RGBA POD.\n */\nfunction decodeTga(bytes: Uint8Array): TgaDecoded {\n  if (bytes.length < 18) throw new Error('TGA header is truncated');\n\n  const colorMapType = bytes[1];\n  const imageType = bytes[2];\n  const idLength = bytes[0] ?? 0;\n  const width = (bytes[12] ?? 0) | ((bytes[13] ?? 0) << 8);\n  const height = (bytes[14] ?? 0) | ((bytes[15] ?? 0) << 8);\n  const pixelDepth = bytes[16] ?? 0;\n  const descriptor = bytes[17] ?? 0;\n  if (colorMapType !== 0) throw new Error('color-mapped TGA is unsupported');\n  if (width < 1 || height < 1) throw new Error('TGA dimensions must be positive');\n\n  const isTrueColor = imageType === 2 || imageType === 10;\n  const isGray = imageType === 3 || imageType === 11;\n  if (!isTrueColor && !isGray) throw new Error(`TGA image type ${imageType} is unsupported`);\n  if (isTrueColor && pixelDepth !== 24 && pixelDepth !== 32) {\n    throw new Error(`TGA true-color depth ${pixelDepth} is unsupported`);\n  }\n  if (isGray && pixelDepth !== 8)\n    throw new Error(`TGA grayscale depth ${pixelDepth} is unsupported`);\n\n  const bytesPerPixel = pixelDepth / 8;\n  let offset = 18 + idLength;\n  const pixelCount = width * height;\n  const out = new Uint8Array(pixelCount * 4);\n  const topOrigin = (descriptor & 0x20) !== 0;\n  const rightOrigin = (descriptor & 0x10) !== 0;\n  let filePixel = 0;\n\n  const writePixel = (pixel: Uint8Array): void => {\n    if (filePixel >= pixelCount) throw new Error('TGA pixel data has too many pixels');\n    const fileX = filePixel % width;\n    const fileY = Math.floor(filePixel / width);\n    const x = rightOrigin ? width - 1 - fileX : fileX;\n    const y = topOrigin ? fileY : height - 1 - fileY;\n    const destination = (y * width + x) * 4;\n    if (isGray) {\n      const value = pixel[0] ?? 0;\n      out[destination] = value;\n      out[destination + 1] = value;\n      out[destination + 2] = value;\n      out[destination + 3] = 255;\n    } else {\n      out[destination] = pixel[2] ?? 0;\n      out[destination + 1] = pixel[1] ?? 0;\n      out[destination + 2] = pixel[0] ?? 0;\n      out[destination + 3] = bytesPerPixel === 4 ? (pixel[3] ?? 255) : 255;\n    }\n    filePixel += 1;\n  };\n\n  const readPixel = (): Uint8Array => {\n    if (offset + bytesPerPixel > bytes.length) throw new Error('TGA pixel data is truncated');\n    const pixel = bytes.slice(offset, offset + bytesPerPixel);\n    offset += bytesPerPixel;\n    return pixel;\n  };\n\n  if (imageType === 2 || imageType === 3) {\n    while (filePixel < pixelCount) writePixel(readPixel());\n  } else {\n    while (filePixel < pixelCount) {\n      if (offset >= bytes.length) throw new Error('TGA RLE packet header is truncated');\n      const packet = bytes[offset++] ?? 0;\n      const count = (packet & 0x7f) + 1;\n      if (filePixel + count > pixelCount) throw new Error('TGA RLE packet exceeds image bounds');\n      if ((packet & 0x80) !== 0) {\n        const pixel = readPixel();\n        for (let i = 0; i < count; i++) writePixel(pixel);\n      } else {\n        for (let i = 0; i < count; i++) writePixel(readPixel());\n      }\n    }\n  }\n\n  if (filePixel !== pixelCount) throw new Error('TGA pixel count mismatch');\n  return { width, height, bytes: out };\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/resize-image.ts","../src/parse-image.ts"],"names":[],"mappings":"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","file":"parse-image.mjs","sourcesContent":["import type { ImageErrorCode, ImageErrorDetailFor, ImageErrorFor } from '@forgeax/engine-types';\nimport { IMAGE_ERROR_HINTS } from '@forgeax/engine-types';\n\n// Per-code .expected string literals SSOT.\n// Mirrors ASSET_ERROR_HINTS / IMAGE_ERROR_HINTS shape (charter P5 consistent\n// abstraction). AI users surface .expected when a structured error needs to\n// describe the precondition that was violated.\nconst IMAGE_ERROR_EXPECTED: Readonly<Record<ImageErrorCode, string>> = {\n  'image-decode-failed': 'PNG / JPG byte stream decodes successfully',\n  'image-format-unsupported':\n    \"mime is one of ['image/png', 'image/jpeg']; uploadTexture format <-> colorSpace family agrees\",\n  'image-dimension-out-of-bounds':\n    'width and height fall under device caps maxTextureDimension2D (or 16384 hard cap)',\n  'image-meta-missing':\n    \"<source>.meta.json sidecar (importer: 'image') exists in the same directory\",\n  'image-hdr-decode-failed': 'Radiance RGBE header is valid and pixel data decodes successfully',\n  // feat-20260521-sprite-atlas-animation M1 T-03 — vite-plugin-image atlas\n  // hook .expected literals (plan-strategy section 2 D-2 + AC-10 a/b/c).\n  // ImageErrorImpl construction path is unchanged: the new atlas-* errors\n  // flow through `new ImageErrorImpl({ code: 'atlas-...', ...detail })` and\n  // pick the .expected string up from this Record at construction time\n  // (charter P3 explicit failure SSOT — AI users surface .expected next to\n  // .hint after switch (err.code) without parsing the message).\n  'atlas-empty-input': 'images.length >= 1',\n  'atlas-size-exceeded':\n    'image width x height <= maxAtlasSize^2 and each image fits in the atlas footprint',\n  'atlas-region-mismatch': 'sum(regions[i].w x regions[i].h) <= atlasWidth x atlasHeight',\n};\n\n/** Runtime implementation of the correlated `ImageErrorFor<C>` envelope. */\nexport class ImageErrorImpl<C extends ImageErrorCode = ImageErrorCode>\n  extends Error\n  implements ImageErrorFor<C>\n{\n  readonly code: C;\n  readonly expected: string;\n  readonly hint: string;\n  readonly detail: ImageErrorDetailFor<C>;\n\n  constructor(detail: ImageErrorDetailFor<C>) {\n    const code = detail.code;\n    const expected = IMAGE_ERROR_EXPECTED[code];\n    const hint = IMAGE_ERROR_HINTS[code];\n    super(`[ImageError ${code}] expected: ${expected}; hint: ${hint}`);\n    this.name = 'ImageError';\n    this.code = code;\n    this.expected = expected;\n    this.hint = hint;\n    this.detail = detail;\n  }\n}\n\n/** Construct a structured image error while preserving its code/detail pair. */\nexport function imageError<C extends ImageErrorCode>(\n  detail: ImageErrorDetailFor<C>,\n): ImageErrorFor<C> {\n  return new ImageErrorImpl<C>(detail);\n}\n\nexport { IMAGE_ERROR_EXPECTED };\n","/** Deterministically downscale tight-packed RGBA pixels with bilinear sampling. */\nexport function downscaleRgba(\n  bytes: Uint8Array,\n  width: number,\n  height: number,\n  maxDimension: number,\n): { readonly bytes: Uint8Array; readonly width: number; readonly height: number } {\n  if (width <= maxDimension && height <= maxDimension) {\n    return { bytes, width, height };\n  }\n\n  const scale = maxDimension / Math.max(width, height);\n  const targetWidth = Math.max(1, Math.round(width * scale));\n  const targetHeight = Math.max(1, Math.round(height * scale));\n  const output = new Uint8Array(targetWidth * targetHeight * 4);\n  const source = (x: number, y: number, channel: number): number =>\n    bytes[(y * width + x) * 4 + channel] ?? 0;\n\n  for (let y = 0; y < targetHeight; y += 1) {\n    const sourceY = ((y + 0.5) * height) / targetHeight - 0.5;\n    const y0 = Math.max(0, Math.floor(sourceY));\n    const y1 = Math.min(height - 1, y0 + 1);\n    const yWeight = Math.max(0, Math.min(1, sourceY - y0));\n    for (let x = 0; x < targetWidth; x += 1) {\n      const sourceX = ((x + 0.5) * width) / targetWidth - 0.5;\n      const x0 = Math.max(0, Math.floor(sourceX));\n      const x1 = Math.min(width - 1, x0 + 1);\n      const xWeight = Math.max(0, Math.min(1, sourceX - x0));\n      const outputOffset = (y * targetWidth + x) * 4;\n      for (let channel = 0; channel < 4; channel += 1) {\n        const top = source(x0, y0, channel) * (1 - xWeight) + source(x1, y0, channel) * xWeight;\n        const bottom = source(x0, y1, channel) * (1 - xWeight) + source(x1, y1, channel) * xWeight;\n        output[outputOffset + channel] = Math.round(top * (1 - yWeight) + bottom * yWeight);\n      }\n    }\n  }\n\n  return { bytes: output, width: targetWidth, height: targetHeight };\n}\n","import type { DecodedImage, ImageColorSpace, ImageError } from '@forgeax/engine-types';\nimport * as jpeg from 'jpeg-js';\n// Static imports of upng-js + jpeg-js. tsup external keeps both as runtime\n// require() calls so the browser bundle still tree-shakes them out when\n// only image-decoder-browser.ts (createImageBitmap) is reached at runtime.\n// Synchronous decode is required by the parseImage signature contract (see\n// plan-strategy section 3.3).\nimport * as UPNG from 'upng-js';\nimport { imageError } from './errors.js';\nimport { downscaleRgba } from './resize-image.js';\nimport type { Result } from './result.js';\nimport { err, ok } from './result.js';\n\nexport interface ParseImageOptions {\n  /**\n   * Maximum allowed dimension (width or height). Defaults to 16384 -- the\n   * conservative WebGPU `maxTextureDimension2D` floor across desktop +\n   * high-end mobile (research F-3 / spec). Test fixtures pass smaller\n   * values to exercise the bounds-check code path with tiny fixtures.\n   */\n  readonly maxDimension?: number;\n\n  /** Optional asset-owned cooked-payload target; source bytes remain unchanged. */\n  readonly downscaleMaxDimension?: number;\n\n  /**\n   * Sidecar `colorSpace` carried over to the DecodedImage POD. Defaults to\n   * 'srgb' (typical baseColor / albedo path; plan-strategy section 2.5).\n   */\n  readonly colorSpace?: ImageColorSpace;\n\n  /**\n   * Sidecar `mipmap` flag carried over to DecodedImage. Defaults to true\n   * (auto-generate via runtime mipmap-generator; plan-strategy section 2.6).\n   */\n  readonly mipmap?: boolean;\n\n  /**\n   * Optional source path to embed in error.detail.path (decode-failed /\n   * format-unsupported variants). decodeImageFromFile fills this in;\n   * in-memory parseImage callers leave it empty.\n   */\n  readonly path?: string;\n}\n\nconst DEFAULT_MAX_DIMENSION = 16384;\n\nconst SUPPORTED_MIMES: readonly string[] = ['image/png', 'image/jpeg'];\n\ninterface UpngDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly data: Uint8Array;\n}\n\ninterface JpegDecoded {\n  readonly width: number;\n  readonly height: number;\n  readonly data: Uint8Array;\n}\n\n/**\n * Pure synchronous image decoder. Translates raw byte stream + mime hint\n * into a tight-packed RGBA `DecodedImage` POD. Surfaces all four\n * ImageErrorCode members through the structured `Result<DecodedImage,\n * ImageError>` return (charter P3 explicit failure; AGENTS.md \"Return\n * Result, never throw\").\n *\n * Decoder selection follows the mime hint:\n * - `image/png` -> upng-js `UPNG.decode` + `UPNG.toRGBA8`\n * - `image/jpeg` -> jpeg-js `decode` with `formatAsRGBA: true`\n * - other -> `image-format-unsupported`\n *\n * Decoded bytes are always tight-packed RGBA (`bytes.length === width *\n * height * 4`). `colorSpace` and `mipmap` are carried from the supplied\n * `ParseImageOptions` (decodeImageFromFile passes the sidecar settings).\n */\nexport function parseImage(\n  bytes: Uint8Array,\n  mime: string,\n  opts: ParseImageOptions = {},\n): Result<DecodedImage, ImageError> {\n  if (!SUPPORTED_MIMES.includes(mime)) {\n    return err(\n      imageError({\n        code: 'image-format-unsupported',\n        actualMime: mime,\n        ...(opts.path !== undefined ? { path: opts.path } : {}),\n      }),\n    );\n  }\n\n  let width = 0;\n  let height = 0;\n  let rgba: Uint8Array;\n\n  try {\n    if (mime === 'image/png') {\n      const upngMod: {\n        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;\n        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];\n      } = ((UPNG as unknown as { default?: typeof UPNG }).default ?? UPNG) as unknown as {\n        decode: (b: Uint8Array | ArrayBuffer) => UpngDecoded;\n        toRGBA8: (i: UpngDecoded) => ArrayBuffer[];\n      };\n      const decoded = upngMod.decode(bytes);\n      width = decoded.width;\n      height = decoded.height;\n      const frames = upngMod.toRGBA8(decoded);\n      const first = frames[0];\n      if (first === undefined) {\n        return err(\n          imageError({\n            code: 'image-decode-failed',\n            reason: 'UPNG.toRGBA8 returned no frames',\n            ...(opts.path !== undefined ? { path: opts.path } : {}),\n          }),\n        );\n      }\n      rgba = new Uint8Array(first);\n    } else {\n      // image/jpeg\n      const jpegMod: {\n        decode: (\n          b: Uint8Array | ArrayBuffer,\n          o?: { useTArray?: boolean; formatAsRGBA?: boolean },\n        ) => JpegDecoded;\n      } = ((jpeg as unknown as { default?: typeof jpeg }).default ?? jpeg) as unknown as {\n        decode: (\n          b: Uint8Array | ArrayBuffer,\n          o?: { useTArray?: boolean; formatAsRGBA?: boolean },\n        ) => JpegDecoded;\n      };\n      const decoded = jpegMod.decode(bytes, { useTArray: true, formatAsRGBA: true });\n      width = decoded.width;\n      height = decoded.height;\n      rgba = decoded.data;\n    }\n  } catch (e) {\n    return err(\n      imageError({\n        code: 'image-decode-failed',\n        reason: e instanceof Error ? e.message : String(e),\n        ...(opts.path !== undefined ? { path: opts.path } : {}),\n      }),\n    );\n  }\n\n  const downscaleLimit = opts.downscaleMaxDimension;\n  if (downscaleLimit !== undefined && Number.isInteger(downscaleLimit) && downscaleLimit > 0) {\n    const downscaled = downscaleRgba(rgba, width, height, downscaleLimit);\n    rgba = downscaled.bytes;\n    width = downscaled.width;\n    height = downscaled.height;\n  }\n\n  const limit = opts.maxDimension ?? DEFAULT_MAX_DIMENSION;\n  if (width > limit || height > limit) {\n    return err(\n      imageError({\n        code: 'image-dimension-out-of-bounds',\n        requested: { width, height },\n        limit,\n      }),\n    );\n  }\n\n  return ok({\n    bytes: rgba,\n    width,\n    height,\n    mime: mime as 'image/png' | 'image/jpeg',\n    colorSpace: opts.colorSpace ?? 'srgb',\n    mipmap: opts.mipmap ?? true,\n  });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-image",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -54,16 +54,16 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-codec": "0.1.4",
-    "@forgeax/engine-math": "0.1.4",
-    "@forgeax/engine-pack": "0.1.4",
-    "@forgeax/engine-types": "0.1.4",
+    "@forgeax/engine-codec": "0.1.7",
+    "@forgeax/engine-math": "0.1.7",
+    "@forgeax/engine-pack": "0.1.7",
+    "@forgeax/engine-types": "0.1.7",
     "jpeg-js": "^0.4.4",
     "pako": "^1.0.11",
     "upng-js": "^2.1.0"
   },
   "devDependencies": {
-    "@forgeax/engine-import": "0.1.4",
+    "@forgeax/engine-import": "0.1.7",
     "@types/node": "^20.14.0",
     "@webgpu/types": "^0.1.71"
   },

package/src/__tests__/image.unit.test.ts

@@ -50,32 +50,6 @@ import { subAssetKey, subAssetKeyEqual } from '../sub-asset-key.js';
 import { toAssetPack } from '../to-asset-pack.js';
 import { makeCorruptPng, makeJpg, makePng } from './make-fixture.js';
 
-function makeMinimalHdr(): Uint8Array {
-  const header = '#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 1 +X 8\n';
-  const encoder = new TextEncoder();
-  const headerBytes = encoder.encode(header);
-  const width = 8;
-  const hi = (width >> 8) & 0xff;
-  const lo = width & 0xff;
-  const prefix = new Uint8Array([0x02, 0x02, hi, lo]);
-  const chRun = new Uint8Array([128 + 8, 128]);
-  const pixelBytes = new Uint8Array(4 + 4 * 2);
-  let off = 0;
-  pixelBytes.set(prefix, off);
-  off += 4;
-  pixelBytes.set(chRun, off);
-  off += 2;
-  pixelBytes.set(chRun, off);
-  off += 2;
-  pixelBytes.set(chRun, off);
-  off += 2;
-  pixelBytes.set(chRun, off);
-  const total = new Uint8Array(headerBytes.length + pixelBytes.length);
-  total.set(headerBytes);
-  total.set(pixelBytes, headerBytes.length);
-  return total;
-}
-
 {
   // ─── from decode-image-from-file.test.ts ───
 
@@ -210,89 +184,6 @@ function makeMinimalHdr(): Uint8Array {
         }
       });
 
-      it('rejects a parseable schema-invalid sidecar before decode and retries on the same path', async () => {
-        const dir = mkTmpDir('malformed-sidecar-retry');
-        const sourcePath = writeFixture(dir, 'staged.png', readBinDF('wood-1x1.png'));
-        const sidecarPath = `${sourcePath}.meta.json`;
-        const invalidSidecar = new TextEncoder().encode('{}');
-        const validSidecar = {
-          schemaVersion: '1.0.0',
-          kind: 'external-asset-package',
-          importer: 'image',
-          source: 'staged.png',
-          importSettings: {
-            colorSpace: 'linear',
-            mipmap: 'none',
-            addressMode: 'mirror-repeat',
-            filterMode: 'nearest',
-          },
-          subAssets: [
-            {
-              guid: '01928000-7c00-7000-8000-000000000095',
-              sourceIndex: 0,
-              kind: 'texture',
-            },
-          ],
-        };
-        const validSidecarBytes = new TextEncoder().encode(JSON.stringify(validSidecar));
-
-        try {
-          writeFileSync(sidecarPath, invalidSidecar);
-          const rejected = await decodeImageFromFile(sourcePath);
-          expect(rejected.ok).toBe(false);
-          if (rejected.ok) return;
-          expect(rejected.error.code).toBe('image-decode-failed');
-          if (rejected.error.detail.code !== 'image-decode-failed') return;
-          expect(rejected.error.detail.path).toBe(sidecarPath);
-          expect(rejected.error.detail.reason).toMatch(/^sidecar schema validation failed:/);
-
-          writeFileSync(sidecarPath, validSidecarBytes);
-          const recovered = await decodeImageFromFile(sourcePath);
-          expect(recovered.ok).toBe(true);
-          if (!recovered.ok) return;
-          expect(recovered.value.decoded).toMatchObject({
-            width: 1,
-            height: 1,
-            mime: 'image/png',
-            colorSpace: 'linear',
-            mipmap: false,
-          });
-          expect(recovered.value.meta).toEqual({
-            guid: '01928000-7c00-7000-8000-000000000095',
-            colorSpace: 'linear',
-            mipmap: 'none',
-            addressMode: 'mirror-repeat',
-            filterMode: 'nearest',
-          });
-          expect(toAssetPack(recovered.value.decoded, recovered.value.meta)).toEqual({
-            schemaVersion: '1.0.0',
-            kind: 'external-asset-package',
-            importer: 'image',
-            source: '',
-            importSettings: {
-              colorSpace: 'linear',
-              mipmap: 'none',
-              addressMode: 'mirror-repeat',
-              filterMode: 'nearest',
-            },
-            subAssets: [
-              {
-                guid: '01928000-7c00-7000-8000-000000000095',
-                sourceIndex: 0,
-                kind: 'texture',
-              },
-            ],
-          });
-
-          const repeated = await decodeImageFromFile(sourcePath);
-          expect(repeated).toEqual(recovered);
-          expect(readFileSync(sourcePath)).toEqual(Buffer.from(readBinDF('wood-1x1.png')));
-          expect(readFileSync(sidecarPath)).toEqual(Buffer.from(validSidecarBytes));
-        } finally {
-          rmSync(dir, { recursive: true, force: true });
-        }
-      });
-
       it('decodes a valid 1x1 PNG file when sidecar is present, returns DecodedImage + ImageMeta', async () => {
         const dir = mkTmpDir('happy-png');
         try {
@@ -370,51 +261,6 @@ function makeMinimalHdr(): Uint8Array {
         }
       });
 
-      it('keeps HDR equirect sidecars accepted by the file decoder', async () => {
-        const dir = mkTmpDir('happy-hdr');
-        const sourcePath = writeFixture(dir, 'environment.hdr', makeMinimalHdr());
-        const sidecar = {
-          schemaVersion: '1.0.0',
-          kind: 'external-asset-package',
-          importer: 'image',
-          source: 'environment.hdr',
-          importSettings: {
-            colorSpace: 'linear',
-            mipmap: 'none',
-            addressMode: 'repeat',
-            filterMode: 'linear',
-          },
-          subAssets: [
-            {
-              guid: '019e3969-1d43-7610-8810-e80dbd491d91',
-              sourceIndex: 0,
-              kind: 'equirect',
-            },
-          ],
-        };
-        try {
-          writeFixture(
-            dir,
-            'environment.hdr.meta.json',
-            new TextEncoder().encode(JSON.stringify(sidecar)),
-          );
-          const r = await decodeImageFromFile(sourcePath);
-          expect(r.ok).toBe(true);
-          if (!r.ok) return;
-          expect(r.value.decoded.width).toBe(8);
-          expect(r.value.decoded.height).toBe(1);
-          expect(r.value.meta).toEqual({
-            guid: '019e3969-1d43-7610-8810-e80dbd491d91',
-            colorSpace: 'linear',
-            mipmap: 'none',
-            addressMode: 'repeat',
-            filterMode: 'linear',
-          });
-        } finally {
-          rmSync(dir, { recursive: true, force: true });
-        }
-      });
-
       it('returns image-format-unsupported when extension is not .jpg/.jpeg/.png', async () => {
         const dir = mkTmpDir('unsupported-ext');
         try {
@@ -455,6 +301,32 @@ function makeMinimalHdr(): Uint8Array {
 {
   // ─── from hdr-decoder.test.ts ───
 
+  function makeMinimalHdr(): Uint8Array {
+    const header = '#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 1 +X 8\n';
+    const encoder = new TextEncoder();
+    const headerBytes = encoder.encode(header);
+    const width = 8;
+    const hi = (width >> 8) & 0xff;
+    const lo = width & 0xff;
+    const prefix = new Uint8Array([0x02, 0x02, hi, lo]);
+    const chRun = new Uint8Array([128 + 8, 128]);
+    const pixelBytes = new Uint8Array(4 + 4 * 2);
+    let off = 0;
+    pixelBytes.set(prefix, off);
+    off += 4;
+    pixelBytes.set(chRun, off);
+    off += 2;
+    pixelBytes.set(chRun, off);
+    off += 2;
+    pixelBytes.set(chRun, off);
+    off += 2;
+    pixelBytes.set(chRun, off);
+    const total = new Uint8Array(headerBytes.length + pixelBytes.length);
+    total.set(headerBytes);
+    total.set(pixelBytes, headerBytes.length);
+    return total;
+  }
+
   function makeBlackHdr(): Uint8Array {
     const header = '#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 1 +X 8\n';
     const encoder = new TextEncoder();
@@ -897,17 +769,11 @@ function makeMinimalHdr(): Uint8Array {
     describe('imageImporter unknown extension fail-fast', () => {
       const dummyBytes = new Uint8Array([0x00, 0x00, 0x00, 0x00]);
 
-      it('.tga source is recognized and invalid bytes fail during decode', async () => {
+      it('.tga source still throws unsupported source extension', async () => {
         const ctx = makeHdrCtx('texture.tga', dummyBytes, [
           { guid: HDR_GUID, sourceIndex: 0, kind: 'texture' },
         ]);
-        const result = await imageImporter.import(ctx);
-        expect(result.ok).toBe(false);
-        if (result.ok) return;
-        expect(result.error.code).toBe('source-validation-failed');
-        expect(result.error.detail).toMatchObject({
-          diagnostics: [expect.objectContaining({ code: 'image-conversion-decode-ldr' })],
-        });
+        await expect(imageImporter.import(ctx)).rejects.toThrow('unsupported source extension');
       });
 
       it('.bmp source still throws unsupported source extension', async () => {

package/src/decode-image-from-file.ts

@@ -1,7 +1,6 @@
 import { readFile, stat } from 'node:fs/promises';
 import { dirname, extname, join } from 'node:path';
 
-import { validateMeta } from '@forgeax/engine-pack';
 import type { DecodedImage, ImageError, ImageMeta } from '@forgeax/engine-types';
 import { imageError } from './errors.js';
 import { decodeHdr, type HdrDecoded } from './hdr-decoder.js';
@@ -52,13 +51,10 @@ export interface DecodedHdrWithMeta {
   readonly meta: ImageMeta;
 }
 
-const EXT_TO_MIME: Readonly<
-  Record<string, 'image/png' | 'image/jpeg' | 'image/x-tga' | 'image/vnd.radiance'>
-> = {
+const EXT_TO_MIME: Readonly<Record<string, 'image/png' | 'image/jpeg' | 'image/vnd.radiance'>> = {
   '.png': 'image/png',
   '.jpg': 'image/jpeg',
   '.jpeg': 'image/jpeg',
-  '.tga': 'image/x-tga',
   '.hdr': 'image/vnd.radiance',
 };
 
@@ -71,45 +67,6 @@ function deriveSidecarPath(sourcePath: string): string {
   return join(dir, `${base}.meta.json`);
 }
 
-function sidecarSchemaFailureReason(): string {
-  const firstError = validateMeta.errors?.[0];
-  if (firstError === undefined) return 'sidecar schema validation failed';
-  const location = firstError.instancePath === '' ? '/' : firstError.instancePath;
-  return `sidecar schema validation failed: ${firstError.keyword} at ${location}`.slice(0, 256);
-}
-
-function imageSidecarFailureReason(
-  sidecar: SidecarMeta,
-  mime: (typeof EXT_TO_MIME)[keyof typeof EXT_TO_MIME],
-): string | undefined {
-  const subAsset = sidecar.subAssets[0];
-  const settings = sidecar.importSettings;
-  const expectedKind = mime === 'image/vnd.radiance' ? 'equirect' : 'texture';
-  if (sidecar.importer !== 'image') return 'image sidecar importer must be image';
-  if (sidecar.subAssets.length !== 1 || subAsset === undefined) {
-    return 'image sidecar must declare one sub-asset';
-  }
-  if (subAsset.kind !== expectedKind || subAsset.sourceIndex !== 0) {
-    return `image sidecar sub-asset must be ${expectedKind} at sourceIndex 0`;
-  }
-  if (settings.colorSpace !== undefined && !['srgb', 'linear'].includes(settings.colorSpace)) {
-    return 'image sidecar colorSpace must be srgb or linear';
-  }
-  if (settings.mipmap !== undefined && !['auto', 'none'].includes(settings.mipmap)) {
-    return 'image sidecar mipmap must be auto or none';
-  }
-  if (
-    settings.addressMode !== undefined &&
-    !['repeat', 'clamp-to-edge', 'mirror-repeat'].includes(settings.addressMode)
-  ) {
-    return 'image sidecar addressMode is unsupported';
-  }
-  if (settings.filterMode !== undefined && !['nearest', 'linear'].includes(settings.filterMode)) {
-    return 'image sidecar filterMode is unsupported';
-  }
-  return undefined;
-}
-
 /**
  * Async file-system entry to the image importer (plan-strategy section 3.2
  * sequence A; AC-17 path (a) sidecar three-way fallback).
@@ -182,9 +139,9 @@ export async function decodeImageFromFile(
     );
   }
 
-  let parsedSidecar: unknown;
+  let sidecar: SidecarMeta;
   try {
-    parsedSidecar = JSON.parse(sidecarText) as unknown;
+    sidecar = JSON.parse(sidecarText) as SidecarMeta;
   } catch (e) {
     return err(
       imageError({
@@ -195,28 +152,6 @@ export async function decodeImageFromFile(
     );
   }
 
-  if (!validateMeta(parsedSidecar)) {
-    return err(
-      imageError({
-        code: 'image-decode-failed',
-        reason: sidecarSchemaFailureReason(),
-        path: sidecarPath,
-      }),
-    );
-  }
-
-  const sidecar = parsedSidecar as unknown as SidecarMeta;
-  const imageSidecarFailure = imageSidecarFailureReason(sidecar, mime);
-  if (imageSidecarFailure !== undefined) {
-    return err(
-      imageError({
-        code: 'image-decode-failed',
-        reason: imageSidecarFailure,
-        path: sidecarPath,
-      }),
-    );
-  }
-
   const settings = sidecar.importSettings ?? {};
   const colorSpace: ImageMeta['colorSpace'] = settings.colorSpace ?? 'srgb';
   const mipmap: ImageMeta['mipmap'] = settings.mipmap ?? 'auto';

package/src/errors.ts

@@ -8,7 +8,7 @@ import { IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
 const IMAGE_ERROR_EXPECTED: Readonly<Record<ImageErrorCode, string>> = {
   'image-decode-failed': 'PNG / JPG byte stream decodes successfully',
   'image-format-unsupported':
-    "mime is one of ['image/png', 'image/jpeg', 'image/x-tga']; uploadTexture format <-> colorSpace family agrees",
+    "mime is one of ['image/png', 'image/jpeg']; uploadTexture format <-> colorSpace family agrees",
   'image-dimension-out-of-bounds':
     'width and height fall under device caps maxTextureDimension2D (or 16384 hard cap)',
   'image-meta-missing':

package/src/image-decoder-browser.ts

@@ -51,7 +51,7 @@ export async function decodeImageInBrowser(
   // Read pixels back via OffscreenCanvas (browser context) -- 2D context is
   // ubiquitous and avoids the WebGPU readback round-trip during disk-side
   // decode (charter P5 producer / consumer split: GPU upload happens inside
-  // the Render DeviceScope, not in this byte decoder).
+  // @forgeax/engine-runtime AssetRegistry.uploadTexture, not here).
   const canvas =
     typeof OffscreenCanvas !== 'undefined'
       ? new OffscreenCanvas(bitmap.width, bitmap.height)

package/src/image-importer.ts

@@ -48,11 +48,10 @@ import { encodeTextureToKtx2, resolveEncodeMode } from './ktx2-encode.js';
 import { parseImage } from './parse-image.js';
 
 /** Map a source path / mime hint to the parseImage mime literal. */
-function mimeFromSource(source: string): 'image/png' | 'image/jpeg' | 'image/x-tga' | undefined {
+function mimeFromSource(source: string): 'image/png' | 'image/jpeg' | undefined {
   const lower = source.toLowerCase();
   if (lower.endsWith('.png')) return 'image/png';
   if (lower.endsWith('.jpg') || lower.endsWith('.jpeg')) return 'image/jpeg';
-  if (lower.endsWith('.tga')) return 'image/x-tga';
   return undefined;
 }
 
@@ -676,7 +675,7 @@ async function importImage(ctx: ImportContext): Promise<ImportResult> {
   // --- Standard PNG/JPEG path ---
   if (mime === undefined) {
     throw new Error(
-      `imageImporter: unsupported source extension for "${ctx.source}" (expected .png / .jpg / .jpeg / .tga / .hdr / .ktx2 / .basis)`,
+      `imageImporter: unsupported source extension for "${ctx.source}" (expected .png / .jpg / .jpeg / .hdr / .ktx2 / .basis)`,
     );
   }
 
@@ -703,7 +702,7 @@ async function importImage(ctx: ImportContext): Promise<ImportResult> {
         'decode',
         'ldr',
         ctx.source,
-        'valid PNG, JPEG, or TGA bytes to decode into RGBA pixels',
+        'valid PNG or JPEG bytes to decode into RGBA pixels',
         `image:${decoded.error.code}`,
         'repair the source image bytes and retry the import',
       ),

package/src/index.ts

@@ -1,8 +1,8 @@
 // @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 /
+// 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:
@@ -31,9 +31,7 @@ export type {
 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 { 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';

package/src/ktx2-encode.ts

@@ -20,15 +20,11 @@
 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;
+export type CompressionMode = 'auto' | 'etc1s' | 'uastc' | 'none';
 
 /** The resolved delivery encoding after 'auto' derivation. `'none'` = no encode. */
-export type ResolvedEncodeMode = (typeof RESOLVED_ENCODE_MODES)[number];
+export type ResolvedEncodeMode = 'etc1s' | 'uastc' | 'uastc-hdr' | 'none';
 
 /** Source signals that drive 'auto' derivation (D-12) and encoder params. */
 export interface EncodeSourceInfo {
@@ -56,15 +52,15 @@ export function resolveEncodeMode(
   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];
+    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';
   }
 }
 
@@ -94,17 +90,17 @@ export function basisEncodeParamsFor(
   const resolved = resolveEncodeMode(mode, source);
   const srgbColor = source.colorSpace === 'srgb';
   switch (resolved) {
-    case RESOLVED_ENCODE_MODES[3]:
+    case 'none':
       return null;
-    case RESOLVED_ENCODE_MODES[0]:
+    case 'etc1s':
       return {
-        mode: RESOLVED_ENCODE_MODES[0],
+        mode: 'etc1s',
         srgb: srgbColor,
         perceptual: srgbColor,
         uastcSupercompression: false,
         mipGen: false,
       };
-    case RESOLVED_ENCODE_MODES[1]:
+    case 'uastc':
       return {
         mode: 'uastc-ldr',
         srgb: srgbColor,
@@ -112,9 +108,9 @@ export function basisEncodeParamsFor(
         uastcSupercompression: true,
         mipGen: false,
       };
-    case RESOLVED_ENCODE_MODES[2]:
+    case 'uastc-hdr':
       return {
-        mode: RESOLVED_ENCODE_MODES[2],
+        mode: 'uastc-hdr',
         srgb: false,
         perceptual: false,
         uastcSupercompression: false,