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

package/src/block-format.ts

@@ -0,0 +1,128 @@
+/**
+ * Block-compressed texture format parameter table (D-6 shared SSOT).
+ *
+ * One table maps every WebGPU block-compressed `GPUTextureFormat` to its
+ * texel-block dimensions and compressed bytes-per-block. Both the texture
+ * upload path and the equirect upload path (M5) derive `bytesPerRow` /
+ * `rowsPerImage` from this single table -- block math is defined once
+ * (Derive, Don't Duplicate).
+ *
+ * Format list follows the WebGPU spec "Compressed Texture Formats" section.
+ * PVRTC and ASTC-HDR are intentionally absent (OOS-5 / not exposed by WebGPU
+ * core). Uncompressed formats are not in the table -- callers branch on
+ * `isCompressedFormat` first and handle the linear `width * bytesPerPixel`
+ * case themselves.
+ */
+
+/** Texel-block dimensions + compressed size for one block-compressed format. */
+export interface BlockParams {
+  readonly blockW: number;
+  readonly blockH: number;
+  readonly bytesPerBlock: number;
+}
+
+/**
+ * Block parameter table for every WebGPU block-compressed format.
+ *
+ * BC / ETC2 / EAC blocks are all 4x4 texels; ASTC block dimensions are encoded
+ * in the format name (`astc-<W>x<H>-...`) and every ASTC block is 16 bytes.
+ * bytesPerBlock: 8 for the 0.5-bpp formats (BC1, BC4, ETC2-rgb8, ETC2-rgb8a1,
+ * EAC-r11), 16 for the 1-bpp formats (BC2/3/5/6H/7, ETC2-rgba8, EAC-rg11, ASTC).
+ */
+const BLOCK_TABLE: ReadonlyMap<GPUTextureFormat, BlockParams> = new Map<
+  GPUTextureFormat,
+  BlockParams
+>([
+  // -- BC (S3TC / RGTC / BPTC) --
+  ['bc1-rgba-unorm', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['bc1-rgba-unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['bc2-rgba-unorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc2-rgba-unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc3-rgba-unorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc3-rgba-unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc4-r-unorm', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['bc4-r-snorm', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['bc5-rg-unorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc5-rg-snorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc6h-rgb-ufloat', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc6h-rgb-float', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc7-rgba-unorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['bc7-rgba-unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+
+  // -- ETC2 / EAC --
+  ['etc2-rgb8unorm', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['etc2-rgb8unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['etc2-rgb8a1unorm', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['etc2-rgb8a1unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['etc2-rgba8unorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['etc2-rgba8unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['eac-r11unorm', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['eac-r11snorm', { blockW: 4, blockH: 4, bytesPerBlock: 8 }],
+  ['eac-rg11unorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['eac-rg11snorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+
+  // -- ASTC (all 16 bytes/block; block dims from the format name) --
+  ['astc-4x4-unorm', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['astc-4x4-unorm-srgb', { blockW: 4, blockH: 4, bytesPerBlock: 16 }],
+  ['astc-5x4-unorm', { blockW: 5, blockH: 4, bytesPerBlock: 16 }],
+  ['astc-5x4-unorm-srgb', { blockW: 5, blockH: 4, bytesPerBlock: 16 }],
+  ['astc-5x5-unorm', { blockW: 5, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-5x5-unorm-srgb', { blockW: 5, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-6x5-unorm', { blockW: 6, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-6x5-unorm-srgb', { blockW: 6, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-6x6-unorm', { blockW: 6, blockH: 6, bytesPerBlock: 16 }],
+  ['astc-6x6-unorm-srgb', { blockW: 6, blockH: 6, bytesPerBlock: 16 }],
+  ['astc-8x5-unorm', { blockW: 8, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-8x5-unorm-srgb', { blockW: 8, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-8x6-unorm', { blockW: 8, blockH: 6, bytesPerBlock: 16 }],
+  ['astc-8x6-unorm-srgb', { blockW: 8, blockH: 6, bytesPerBlock: 16 }],
+  ['astc-8x8-unorm', { blockW: 8, blockH: 8, bytesPerBlock: 16 }],
+  ['astc-8x8-unorm-srgb', { blockW: 8, blockH: 8, bytesPerBlock: 16 }],
+  ['astc-10x5-unorm', { blockW: 10, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-10x5-unorm-srgb', { blockW: 10, blockH: 5, bytesPerBlock: 16 }],
+  ['astc-10x6-unorm', { blockW: 10, blockH: 6, bytesPerBlock: 16 }],
+  ['astc-10x6-unorm-srgb', { blockW: 10, blockH: 6, bytesPerBlock: 16 }],
+  ['astc-10x8-unorm', { blockW: 10, blockH: 8, bytesPerBlock: 16 }],
+  ['astc-10x8-unorm-srgb', { blockW: 10, blockH: 8, bytesPerBlock: 16 }],
+  ['astc-10x10-unorm', { blockW: 10, blockH: 10, bytesPerBlock: 16 }],
+  ['astc-10x10-unorm-srgb', { blockW: 10, blockH: 10, bytesPerBlock: 16 }],
+  ['astc-12x10-unorm', { blockW: 12, blockH: 10, bytesPerBlock: 16 }],
+  ['astc-12x10-unorm-srgb', { blockW: 12, blockH: 10, bytesPerBlock: 16 }],
+  ['astc-12x12-unorm', { blockW: 12, blockH: 12, bytesPerBlock: 16 }],
+  ['astc-12x12-unorm-srgb', { blockW: 12, blockH: 12, bytesPerBlock: 16 }],
+]);
+
+/**
+ * Look up the block parameters for a format. Returns `null` for uncompressed
+ * formats (the table only holds block-compressed entries).
+ */
+export function blockParamsForFormat(format: GPUTextureFormat): BlockParams | null {
+  return BLOCK_TABLE.get(format) ?? null;
+}
+
+/** Guard: true iff `format` is a block-compressed format in the table. */
+export function isCompressedFormat(format: GPUTextureFormat): boolean {
+  return BLOCK_TABLE.has(format);
+}
+
+/**
+ * Bytes per row for a compressed mip level of the given pixel width:
+ * `ceil(width / blockW) * bytesPerBlock`. Tail texels pad up to a full block.
+ * Returns `null` for uncompressed formats (no block entry) -- callers branch on
+ * `isCompressedFormat` first.
+ */
+export function bytesPerRow(format: GPUTextureFormat, width: number): number | null {
+  const params = BLOCK_TABLE.get(format);
+  if (params === undefined) return null;
+  return Math.ceil(width / params.blockW) * params.bytesPerBlock;
+}
+
+/**
+ * Block rows for a compressed mip level of the given pixel height:
+ * `ceil(height / blockH)`. Returns `null` for uncompressed formats.
+ */
+export function rowsPerImage(format: GPUTextureFormat, height: number): number | null {
+  const params = BLOCK_TABLE.get(format);
+  if (params === undefined) return null;
+  return Math.ceil(height / params.blockH);
+}

package/src/encode/basis-encode.ts

@@ -0,0 +1,264 @@
+/**
+ * Low-level basis encoder binding (build-time, D-5): raw pixels -> Basis KTX2.
+ *
+ * `basisEncode` wraps the self-built encoder WASM (scripts/build-wasm.mjs ->
+ * pkg/encode/basis_encoder.{mjs,wasm}) with a Result-returning function over the
+ * three delivery encodings this Loop produces (ETC1S / UASTC-LDR-4x4 /
+ * UASTC-HDR-4x4). It is the codec-side counterpart of `compressZstd`: it lives
+ * in the `@forgeax/engine-codec/encode` subpath (isolation path d guards runtime
+ * from statically importing it), and it carries the WASM + enum plumbing so the
+ * image-side arm (`encodeTextureToKtx2`, w18) can stay pure image semantics.
+ *
+ * Determinism (AC-02 / R-11): pthreads are disabled at build time and the
+ * per-encode threading is turned off here (`controlThreading(false, 0)`), so the
+ * same pixels + same options encode byte-identically. KTX2 carries no timestamp.
+ *
+ * Lazy-init (D-10, mirrors basis-transcoder): the encoder WASM module is
+ * dynamic-imported on the first encode and cached; subsequent encodes reuse the
+ * instance. The module .mjs is a MODULARIZE factory, node-legal here (build-time
+ * only, never bundled into the browser runtime by the isolation gate).
+ */
+
+import type { CodecResult } from '../errors.js';
+import { codecError } from '../errors.js';
+import type { TranscodeModel } from '../transcode.js';
+import type { BasisEncoder, BasisEncoderModule, BasisModuleFactory } from '../wasm/basis-types.js';
+
+/** Which delivery encoding to produce. Mirrors the transcode source models (D-3). */
+export type BasisEncodeMode = TranscodeModel;
+
+// --- Fast-preset encode-effort constants (R-9) -------------------------------
+// The 'auto' default (M5 w38) sends every existing texture through Basis encode,
+// and the single-threaded encoder's default effort levels made the model-loading
+// demo build run 10+ minutes. These three constants drop each arm to its lowest
+// effort tier. Determinism (AC-02 / R-11) is unaffected -- effort tiers change
+// the search budget, not the output nondeterminism (double-encode stays
+// byte-identical; verified). Values anchor to the vendored encoder enums so a
+// pin bump that renames a tier surfaces here.
+
+/**
+ * ETC1S perf-vs-size effort level (`m_etc1s_compression_level`, range [0,6],
+ * vendored default 2 -- basisu_frontend.h). This lever is orthogonal to visual
+ * quality: quality is fixed by `setQualityLevel` below; a lower compression
+ * level only trades a marginally larger file for a much faster encode.
+ */
+const ETC1S_COMPRESSION_LEVEL_FASTEST = 0;
+
+/**
+ * UASTC-LDR pack level (`cPackUASTCLevelFastest`, the low nibble of
+ * `m_pack_uastc_ldr_4x4_flags`, vendored default `cPackUASTCLevelDefault` = 2 --
+ * basisu_uastc_enc.h). Unlike the ETC1S lever this DOES lower reconstruction
+ * quality (~43.5 dB vs ~47.5 dB avg), so R-9's per-fixture escape hatch
+ * (`compressionMode:'none'`) / D-12 upgrade path exists for any smoke that can
+ * not converge in epsilon at this tier.
+ */
+const PACK_UASTC_LDR_LEVEL_FASTEST = 0;
+
+/**
+ * UASTC-HDR quality level (`m_uastc_hdr_4x4_options` level, range [0,4],
+ * vendored default 1 -- basisu_uastc_hdr_4x4_enc.h). Level 0 is the fastest
+ * search tier; block-format bytes are unchanged in size, only encode time drops.
+ */
+const UASTC_HDR_QUALITY_LEVEL_FASTEST = 0;
+
+/** Encode options -- pixel layout + delivery encoding + transfer / mip flags. */
+export interface BasisEncodeOptions {
+  readonly mode: BasisEncodeMode;
+  readonly width: number;
+  readonly height: number;
+  /** Write the sRGB transfer function into the KTX2 + DFD (LDR color only). */
+  readonly srgb: boolean;
+  /** ETC1S perceptual (sRGB) error metric vs linear PSNR. Ignored for UASTC. */
+  readonly perceptual: boolean;
+  /** Wrap the UASTC-LDR payload in KTX2 zstd supercompression. Ignored otherwise. */
+  readonly uastcSupercompression: boolean;
+  /** Generate a mip chain in the encoder. M3 keeps this false (offline mips are w18/M5). */
+  readonly mipGen: boolean;
+}
+
+/** How the encoder WASM module is loaded. Overridable in tests. @internal */
+type EncoderImporter = () => Promise<BasisEncoderModule>;
+
+const ENCODER_GLUE = new URL('../../pkg/encode/basis_encoder.mjs', import.meta.url);
+const ENCODER_WASM = new URL('../../pkg/encode/basis_encoder.wasm', import.meta.url);
+
+const defaultImporter: EncoderImporter = async () => {
+  const factory = (
+    (await import(/* @vite-ignore */ ENCODER_GLUE.href)) as {
+      default: BasisModuleFactory<BasisEncoderModule>;
+    }
+  ).default;
+  const mod = await factory({ locateFile: () => ENCODER_WASM.href });
+  mod.initializeBasis();
+  return mod;
+};
+
+let importer: EncoderImporter = defaultImporter;
+
+/** Lazy-init singleton (D-10): null = never attempted, cleared on failure to retry. @internal */
+let _initPromise: Promise<BasisEncoderModule> | null = null;
+
+/** Count of importer invocations; observed in tests to prove single-init. @internal */
+let initCount = 0;
+
+/**
+ * Lazy-init the Basis encoder WASM module (D-10 main-thread singleton).
+ * First call dynamic-imports + initializes; subsequent calls return the cache.
+ */
+export function initBasisEncoder(): Promise<BasisEncoderModule> {
+  if (_initPromise !== null) return _initPromise;
+  initCount++;
+  _initPromise = importer().catch((cause: unknown) => {
+    _initPromise = null;
+    throw new Error('codec-init-failed', { cause });
+  });
+  return _initPromise;
+}
+
+/**
+ * Test-only: number of times the encoder importer has been invoked.
+ * @internal
+ */
+export function _basisEncoderInitCount(): number {
+  return initCount;
+}
+
+/**
+ * Test-only: reset the lazy singleton and optionally override the importer.
+ * Call with no argument to restore the real WASM importer.
+ * @internal
+ */
+export function _setBasisEncoderImporter(next?: EncoderImporter): void {
+  importer = next ?? defaultImporter;
+  _initPromise = null;
+  initCount = 0;
+}
+
+/** Map a delivery encoding to the encoder `basis_tex_format` enum value. */
+function formatModeValue(mod: BasisEncoderModule, mode: BasisEncodeMode): number {
+  const f = mod.basis_tex_format;
+  switch (mode) {
+    case 'etc1s':
+      return f.cETC1S.value;
+    case 'uastc-ldr':
+      return f.cUASTC_LDR_4x4.value;
+    case 'uastc-hdr':
+      return f.cUASTC_HDR_4x4.value;
+  }
+}
+
+/**
+ * Encode raw pixels into a Basis KTX2 container.
+ *
+ * `pixels` is tight-packed RGBA: 8-bit `R,G,B,A` per texel for LDR modes
+ * (`etc1s` / `uastc-ldr`), IEEE-754 binary16 RGBA (rgba16float bytes) for
+ * `uastc-hdr`. On any encoder-side failure returns a `ktx2-encode-failed`
+ * CodecError carrying the mode + a short reason.
+ */
+export async function basisEncode(
+  pixels: Uint8Array,
+  options: BasisEncodeOptions,
+): Promise<CodecResult<Uint8Array>> {
+  let mod: BasisEncoderModule;
+  try {
+    mod = await initBasisEncoder();
+  } catch {
+    return codecError('codec-init-failed', { stage: 'dynamic-import-basis-encoder' });
+  }
+
+  const { mode, width, height, srgb, perceptual, uastcSupercompression, mipGen } = options;
+  if (width <= 0 || height <= 0) {
+    return codecError('ktx2-encode-failed', {
+      mode,
+      reason: `invalid dimensions ${width}x${height}`,
+    });
+  }
+
+  let encoder: BasisEncoder;
+  try {
+    encoder = new mod.BasisEncoder();
+  } catch {
+    return codecError('ktx2-encode-failed', {
+      mode,
+      reason: 'encoder constructor failed',
+    });
+  }
+  let result: CodecResult<Uint8Array> = codecError('ktx2-encode-failed', {
+    mode,
+    reason: 'encoder returned 0 bytes',
+  });
+  try {
+    // Single-threaded for deterministic, byte-identical output (AC-02 / R-11).
+    encoder.controlThreading(false, 0);
+
+    let sourceAccepted: boolean;
+    if (mode === 'uastc-hdr') {
+      // img_type 0 = cHITRGBAHalfFloat: the source is rgba16float bytes; no
+      // LDR->HDR upconversion (already linear half-float from the image arm).
+      sourceAccepted = encoder.setSliceSourceImageHDR(0, pixels, width, height, 0, false, 1.0);
+    } else {
+      // img_type 0 = cRGBA32: tight-packed 8-bit RGBA.
+      sourceAccepted = encoder.setSliceSourceImage(0, pixels, width, height, 0);
+    }
+
+    if (!sourceAccepted) {
+      result = codecError('ktx2-encode-failed', {
+        mode,
+        reason:
+          mode === 'uastc-hdr' ? 'setSliceSourceImageHDR failed' : 'setSliceSourceImage failed',
+      });
+    } else {
+      encoder.setCreateKTX2File(true);
+      encoder.setFormatMode(formatModeValue(mod, mode));
+      encoder.setMipGen(mipGen);
+
+      if (mode === 'etc1s') {
+        encoder.setQualityLevel(128);
+        // Fastest perf tier (R-9): quality stays fixed by setQualityLevel above;
+        // the compression level only trades a marginally larger file for a much
+        // faster encode (the 'auto' default routes every texture through here).
+        encoder.setETC1SCompressionLevel(ETC1S_COMPRESSION_LEVEL_FASTEST);
+        encoder.setPerceptual(perceptual);
+      } else if (mode === 'uastc-ldr') {
+        encoder.setKTX2UASTCSupercompression(uastcSupercompression);
+        // Fastest pack tier (R-9). Unlike ETC1S this lowers quality; per-fixture
+        // opt-out / D-12 upgrade covers any smoke that will not converge.
+        encoder.setPackUASTCFlags(PACK_UASTC_LDR_LEVEL_FASTEST);
+        encoder.setPerceptual(perceptual);
+      } else {
+        // uastc-hdr: fastest HDR search tier (R-9); block bytes unchanged in size.
+        encoder.setUASTCHDRQualityLevel(UASTC_HDR_QUALITY_LEVEL_FASTEST);
+      }
+      // sRGB transfer function into the KTX2 header + DFD (LDR color arm).
+      encoder.setKTX2AndBasisSRGBTransferFunc(srgb);
+
+      // encode() copies into the provided buffer and returns the byte length (0 on
+      // failure). A 4 MiB scratch buffer covers a single-slice mip-0 image at the
+      // sizes this offline arm handles; grow-on-overflow retries once.
+      let capacity = 1 << 22;
+      let out = new Uint8Array(capacity);
+      let n = encoder.encode(out);
+      if (n === 0) {
+        capacity = 1 << 25;
+        out = new Uint8Array(capacity);
+        n = encoder.encode(out);
+      }
+      if (n === 0) {
+        result = codecError('ktx2-encode-failed', { mode, reason: 'encoder returned 0 bytes' });
+      } else {
+        result = { ok: true, value: out.slice(0, n) };
+      }
+    }
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    result = codecError('ktx2-encode-failed', { mode, reason });
+  }
+  try {
+    encoder.delete();
+  } catch {
+    if (result.ok) {
+      result = codecError('ktx2-encode-failed', { mode, reason: 'encoder cleanup failed' });
+    }
+  }
+  return result;
+}

package/src/encode/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @forgeax/engine-codec/encode
+ *
+ * Build-time encoding subpath: zstd compression + Basis KTX2 texture encode.
+ * Gated from runtime import by `check-image-pipeline-isolation.mjs` path d.
+ */
+
+export {
+  _setZstdEncoderImporter,
+  _zstdEncodeInitCount,
+  compressZstd,
+} from '../encode-impl.js';
+export type { BasisEncodeMode, BasisEncodeOptions } from './basis-encode.js';
+export {
+  _basisEncoderInitCount,
+  _setBasisEncoderImporter,
+  basisEncode,
+  initBasisEncoder,
+} from './basis-encode.js';

package/src/encode-impl.ts

@@ -0,0 +1,103 @@
+import { createRequire } from 'node:module';
+import type { CodecResult } from './errors.js';
+import { codecError } from './errors.js';
+
+/**
+ * CJS require for @bokuweb/zstd-wasm (build-time Node.js only).
+ *
+ * @bokuweb/zstd-wasm is distributed as a CommonJS package with a `.wasm`
+ * sidecar. We use createRequire to load it from ESM, since it does not
+ * provide ESM exports.
+ */
+const zstdRequire = createRequire(import.meta.url);
+
+interface ZstdWasm {
+  init(): Promise<void>;
+  compress(buf: Uint8Array, level?: number): Uint8Array;
+}
+
+/** How the build-time zstd WASM encoder module is loaded. @internal */
+type ZstdImporter = () => ZstdWasm;
+
+const defaultImporter: ZstdImporter = () => zstdRequire('@bokuweb/zstd-wasm');
+
+let importer: ZstdImporter = defaultImporter;
+
+/** Lazy-init singleton handle for the build-time zstd WASM encoder. @internal */
+let _zstd: ZstdWasm | null = null;
+/**
+ * Shared while the encoder WASM is initializing; cleared after a failed attempt.
+ * The dependency mutates module-level emscripten exports and memory views on
+ * every init, so a second init can bind calls to one instance and reads to another.
+ * @internal
+ */
+let _initPromise: Promise<ZstdWasm> | null = null;
+/** Test-only count of encoder WASM initialization attempts. @internal */
+let initCount = 0;
+
+function getZstd(): Promise<ZstdWasm> {
+  if (_zstd !== null) {
+    return Promise.resolve(_zstd);
+  }
+  if (_initPromise !== null) {
+    return _initPromise;
+  }
+
+  initCount++;
+  _initPromise = Promise.resolve()
+    .then(() => {
+      const mod = importer();
+      return mod.init().then(() => {
+        _zstd = mod;
+        return mod;
+      });
+    })
+    .catch((cause: unknown) => {
+      // Clear cached failure so a later import can retry (do not permanently cache).
+      _initPromise = null;
+      throw new Error('codec-init-failed', { cause });
+    });
+  return _initPromise;
+}
+
+/**
+ * Test-only: number of zstd encoder WASM initialization attempts.
+ * @internal
+ */
+export function _zstdEncodeInitCount(): number {
+  return initCount;
+}
+
+/**
+ * Test-only: reset the encoder singleton and optionally override its importer.
+ * @internal
+ */
+export function _setZstdEncoderImporter(next?: ZstdImporter): void {
+  importer = next ?? defaultImporter;
+  _zstd = null;
+  _initPromise = null;
+  initCount = 0;
+}
+
+/**
+ * Compress bytes with zstd using a fixed compression level (level 3 = default).
+ *
+ * Build-time only. Uses @bokuweb/zstd-wasm pinned at 0.0.27 for
+ * deterministic output (same input + same level = byte-identical output).
+ *
+ * Returns `{ ok: true, value: compressed }` on success.
+ * Returns `{ ok: false, error: { code: 'decompression-failed', ... } }` on failure
+ * (encoding failures mapped to decompression-failed per D-8, same code different detail).
+ */
+export async function compressZstd(bytes: Uint8Array): Promise<CodecResult<Uint8Array>> {
+  try {
+    const zstd = await getZstd();
+    const result = zstd.compress(bytes, 3);
+    return { ok: true, value: result };
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    return codecError('decompression-failed', {
+      reason: `zstd compression failed: ${reason}`,
+    });
+  }
+}

package/src/errors.ts

@@ -0,0 +1,79 @@
+/**
+ * Codec error model — closed union per D-8.
+ *
+ * All codec error codes live here as the SSOT. Runtime never extends the types
+ * shared union; codec errors are nested in existing asset error detail.
+ *
+ * Union is order-locked and add-only-minor for Loop 2 additions.
+ */
+
+/** Per-code narrowed detail payloads. */
+interface CodecErrorDetails {
+  'decompression-failed': { readonly reason: string };
+  'codec-init-failed': { readonly stage: string };
+  'ktx2-parse-failed': { readonly reason: string };
+  'ktx2-unsupported-scheme': { readonly scheme: number };
+  'transcode-failed': { readonly sourceFormat: string; readonly targetFormat: string };
+  'ktx2-encode-failed': { readonly mode: string; readonly reason: string };
+}
+
+/** Order-locked closed union of codec error codes. */
+export type CodecErrorCode = keyof CodecErrorDetails;
+
+/** Structured codec error with executable hint + per-code narrowed detail. */
+export type CodecError = {
+  [C in CodecErrorCode]: {
+    readonly ok: false;
+    readonly error: {
+      readonly code: C;
+      readonly expected: string;
+      readonly hint: string;
+      readonly detail: CodecErrorDetails[C];
+    };
+  };
+}[CodecErrorCode];
+
+type CodecErrorFor<C extends CodecErrorCode> = Extract<
+  CodecError,
+  { readonly error: { readonly code: C } }
+>;
+
+/** Success branch of a Result<T, CodecError>. */
+export interface CodecOk<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+/** Result type for codec operations — discriminated union on `.ok`. */
+export type CodecResult<T> = CodecOk<T> | CodecError;
+
+/** Error factory — produces a full CodecError object for the given code + detail. */
+export function codecError<C extends CodecErrorCode>(
+  code: C,
+  detail: CodecErrorDetails[C],
+): CodecErrorFor<C> {
+  const hints: Record<CodecErrorCode, string> = {
+    'decompression-failed':
+      'Check catalog row compression field and asset binary consistency; re-run asset import.',
+    'codec-init-failed':
+      'Uncompressed assets are still loadable. Verify the codec module is installed correctly.',
+    'ktx2-parse-failed':
+      'Check that the KTX2 file is valid and not truncated. Re-import the texture asset.',
+    'ktx2-unsupported-scheme':
+      'This supercompression scheme requires a future codec upgrade. Check the codec README Loop 2 extension points.',
+    'transcode-failed':
+      'Basis transcode failed for this source/target format pair. Verify the KTX2 payload is a valid Basis (ETC1S / UASTC) texture and re-import the asset.',
+    'ktx2-encode-failed':
+      'Basis encode failed for this compression mode. Verify the source image dimensions / pixel format match the mode (LDR rgba8 vs HDR rgba16float) and retry the asset import.',
+  };
+
+  return {
+    ok: false,
+    error: {
+      code,
+      expected: 'valid compressed data or supported compression scheme',
+      hint: hints[code],
+      detail,
+    },
+  } as CodecErrorFor<C>;
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @forgeax/engine-codec
+ *
+ * Runtime-safe zstd decode + KTX2 container parse for the forgeax asset pipeline.
+ * Build-time zstd encode lives in the `./encode` subpath.
+ */
+
+export type {
+  BasisSourceInspection,
+  BasisSourceMeta,
+  TranscodedBasisTexture,
+  TranscodedMip,
+  TranscodedTexture,
+} from './basis-transcoder.js';
+export {
+  initBasisTranscoder,
+  inspectBasisSource,
+  transcodeBasis,
+  transcodeKtx2,
+} from './basis-transcoder.js';
+export type { BlockParams } from './block-format.js';
+export {
+  blockParamsForFormat,
+  bytesPerRow,
+  isCompressedFormat,
+  rowsPerImage,
+} from './block-format.js';
+export type { CodecError, CodecErrorCode, CodecOk, CodecResult } from './errors.js';
+export { codecError } from './errors.js';
+export { KTX2_IDENTIFIER, ktx2ColorSpace, ktx2LevelsToRGBA, parseKtx2 } from './ktx2.js';
+export type {
+  TranscodeCaps,
+  TranscodeChannels,
+  TranscodeModel,
+  TranscodeSource,
+} from './transcode.js';
+export { selectTranscodeTarget } from './transcode.js';
+export { decompressZstd } from './zstd.js';