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

package/dist/encode/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/encode-impl.ts","../../src/encode/basis-encode.ts"],"names":["defaultImporter","importer","_initPromise","initCount"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Codec error model — closed union per D-8.\n *\n * All codec error codes live here as the SSOT. Runtime never extends the types\n * shared union; codec errors are nested in existing asset error detail.\n *\n * Union is order-locked and add-only-minor for Loop 2 additions.\n */\n\n/** Per-code narrowed detail payloads. */\ninterface CodecErrorDetails {\n  'decompression-failed': { readonly reason: string };\n  'codec-init-failed': { readonly stage: string };\n  'ktx2-parse-failed': { readonly reason: string };\n  'ktx2-unsupported-scheme': { readonly scheme: number };\n  'transcode-failed': { readonly sourceFormat: string; readonly targetFormat: string };\n  'ktx2-encode-failed': { readonly mode: string; readonly reason: string };\n}\n\n/** Order-locked closed union of codec error codes. */\nexport type CodecErrorCode = keyof CodecErrorDetails;\n\n/** Structured codec error with executable hint + per-code narrowed detail. */\nexport type CodecError = {\n  [C in CodecErrorCode]: {\n    readonly ok: false;\n    readonly error: {\n      readonly code: C;\n      readonly expected: string;\n      readonly hint: string;\n      readonly detail: CodecErrorDetails[C];\n    };\n  };\n}[CodecErrorCode];\n\ntype CodecErrorFor<C extends CodecErrorCode> = Extract<\n  CodecError,\n  { readonly error: { readonly code: C } }\n>;\n\n/** Success branch of a Result<T, CodecError>. */\nexport interface CodecOk<T> {\n  readonly ok: true;\n  readonly value: T;\n}\n\n/** Result type for codec operations — discriminated union on `.ok`. */\nexport type CodecResult<T> = CodecOk<T> | CodecError;\n\n/** Error factory — produces a full CodecError object for the given code + detail. */\nexport function codecError<C extends CodecErrorCode>(\n  code: C,\n  detail: CodecErrorDetails[C],\n): CodecErrorFor<C> {\n  const hints: Record<CodecErrorCode, string> = {\n    'decompression-failed':\n      'Check catalog row compression field and asset binary consistency; re-run asset import.',\n    'codec-init-failed':\n      'Uncompressed assets are still loadable. Verify the codec module is installed correctly.',\n    'ktx2-parse-failed':\n      'Check that the KTX2 file is valid and not truncated. Re-import the texture asset.',\n    'ktx2-unsupported-scheme':\n      'This supercompression scheme requires a future codec upgrade. Check the codec README Loop 2 extension points.',\n    'transcode-failed':\n      '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.',\n    'ktx2-encode-failed':\n      '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.',\n  };\n\n  return {\n    ok: false,\n    error: {\n      code,\n      expected: 'valid compressed data or supported compression scheme',\n      hint: hints[code],\n      detail,\n    },\n  } as CodecErrorFor<C>;\n}\n","import { createRequire } from 'node:module';\nimport type { CodecResult } from './errors.js';\nimport { codecError } from './errors.js';\n\n/**\n * CJS require for @bokuweb/zstd-wasm (build-time Node.js only).\n *\n * @bokuweb/zstd-wasm is distributed as a CommonJS package with a `.wasm`\n * sidecar. We use createRequire to load it from ESM, since it does not\n * provide ESM exports.\n */\nconst zstdRequire = createRequire(import.meta.url);\n\ninterface ZstdWasm {\n  init(): Promise<void>;\n  compress(buf: Uint8Array, level?: number): Uint8Array;\n}\n\n/** How the build-time zstd WASM encoder module is loaded. @internal */\ntype ZstdImporter = () => ZstdWasm;\n\nconst defaultImporter: ZstdImporter = () => zstdRequire('@bokuweb/zstd-wasm');\n\nlet importer: ZstdImporter = defaultImporter;\n\n/** Lazy-init singleton handle for the build-time zstd WASM encoder. @internal */\nlet _zstd: ZstdWasm | null = null;\n/**\n * Shared while the encoder WASM is initializing; cleared after a failed attempt.\n * The dependency mutates module-level emscripten exports and memory views on\n * every init, so a second init can bind calls to one instance and reads to another.\n * @internal\n */\nlet _initPromise: Promise<ZstdWasm> | null = null;\n/** Test-only count of encoder WASM initialization attempts. @internal */\nlet initCount = 0;\n\nfunction getZstd(): Promise<ZstdWasm> {\n  if (_zstd !== null) {\n    return Promise.resolve(_zstd);\n  }\n  if (_initPromise !== null) {\n    return _initPromise;\n  }\n\n  initCount++;\n  _initPromise = Promise.resolve()\n    .then(() => {\n      const mod = importer();\n      return mod.init().then(() => {\n        _zstd = mod;\n        return mod;\n      });\n    })\n    .catch((cause: unknown) => {\n      // Clear cached failure so a later import can retry (do not permanently cache).\n      _initPromise = null;\n      throw new Error('codec-init-failed', { cause });\n    });\n  return _initPromise;\n}\n\n/**\n * Test-only: number of zstd encoder WASM initialization attempts.\n * @internal\n */\nexport function _zstdEncodeInitCount(): number {\n  return initCount;\n}\n\n/**\n * Test-only: reset the encoder singleton and optionally override its importer.\n * @internal\n */\nexport function _setZstdEncoderImporter(next?: ZstdImporter): void {\n  importer = next ?? defaultImporter;\n  _zstd = null;\n  _initPromise = null;\n  initCount = 0;\n}\n\n/**\n * Compress bytes with zstd using a fixed compression level (level 3 = default).\n *\n * Build-time only. Uses @bokuweb/zstd-wasm pinned at 0.0.27 for\n * deterministic output (same input + same level = byte-identical output).\n *\n * Returns `{ ok: true, value: compressed }` on success.\n * Returns `{ ok: false, error: { code: 'decompression-failed', ... } }` on failure\n * (encoding failures mapped to decompression-failed per D-8, same code different detail).\n */\nexport async function compressZstd(bytes: Uint8Array): Promise<CodecResult<Uint8Array>> {\n  try {\n    const zstd = await getZstd();\n    const result = zstd.compress(bytes, 3);\n    return { ok: true, value: result };\n  } catch (e) {\n    const reason = e instanceof Error ? e.message : String(e);\n    return codecError('decompression-failed', {\n      reason: `zstd compression failed: ${reason}`,\n    });\n  }\n}\n","/**\n * Low-level basis encoder binding (build-time, D-5): raw pixels -> Basis KTX2.\n *\n * `basisEncode` wraps the self-built encoder WASM (scripts/build-wasm.mjs ->\n * pkg/encode/basis_encoder.{mjs,wasm}) with a Result-returning function over the\n * three delivery encodings this Loop produces (ETC1S / UASTC-LDR-4x4 /\n * UASTC-HDR-4x4). It is the codec-side counterpart of `compressZstd`: it lives\n * in the `@forgeax/engine-codec/encode` subpath (isolation path d guards runtime\n * from statically importing it), and it carries the WASM + enum plumbing so the\n * image-side arm (`encodeTextureToKtx2`, w18) can stay pure image semantics.\n *\n * Determinism (AC-02 / R-11): pthreads are disabled at build time and the\n * per-encode threading is turned off here (`controlThreading(false, 0)`), so the\n * same pixels + same options encode byte-identically. KTX2 carries no timestamp.\n *\n * Lazy-init (D-10, mirrors basis-transcoder): the encoder WASM module is\n * dynamic-imported on the first encode and cached; subsequent encodes reuse the\n * instance. The module .mjs is a MODULARIZE factory, node-legal here (build-time\n * only, never bundled into the browser runtime by the isolation gate).\n */\n\nimport type { CodecResult } from '../errors.js';\nimport { codecError } from '../errors.js';\nimport type { TranscodeModel } from '../transcode.js';\nimport type { BasisEncoder, BasisEncoderModule, BasisModuleFactory } from '../wasm/basis-types.js';\n\n/** Which delivery encoding to produce. Mirrors the transcode source models (D-3). */\nexport type BasisEncodeMode = TranscodeModel;\n\n// --- Fast-preset encode-effort constants (R-9) -------------------------------\n// The 'auto' default (M5 w38) sends every existing texture through Basis encode,\n// and the single-threaded encoder's default effort levels made the model-loading\n// demo build run 10+ minutes. These three constants drop each arm to its lowest\n// effort tier. Determinism (AC-02 / R-11) is unaffected -- effort tiers change\n// the search budget, not the output nondeterminism (double-encode stays\n// byte-identical; verified). Values anchor to the vendored encoder enums so a\n// pin bump that renames a tier surfaces here.\n\n/**\n * ETC1S perf-vs-size effort level (`m_etc1s_compression_level`, range [0,6],\n * vendored default 2 -- basisu_frontend.h). This lever is orthogonal to visual\n * quality: quality is fixed by `setQualityLevel` below; a lower compression\n * level only trades a marginally larger file for a much faster encode.\n */\nconst ETC1S_COMPRESSION_LEVEL_FASTEST = 0;\n\n/**\n * UASTC-LDR pack level (`cPackUASTCLevelFastest`, the low nibble of\n * `m_pack_uastc_ldr_4x4_flags`, vendored default `cPackUASTCLevelDefault` = 2 --\n * basisu_uastc_enc.h). Unlike the ETC1S lever this DOES lower reconstruction\n * quality (~43.5 dB vs ~47.5 dB avg), so R-9's per-fixture escape hatch\n * (`compressionMode:'none'`) / D-12 upgrade path exists for any smoke that can\n * not converge in epsilon at this tier.\n */\nconst PACK_UASTC_LDR_LEVEL_FASTEST = 0;\n\n/**\n * UASTC-HDR quality level (`m_uastc_hdr_4x4_options` level, range [0,4],\n * vendored default 1 -- basisu_uastc_hdr_4x4_enc.h). Level 0 is the fastest\n * search tier; block-format bytes are unchanged in size, only encode time drops.\n */\nconst UASTC_HDR_QUALITY_LEVEL_FASTEST = 0;\n\n/** Encode options -- pixel layout + delivery encoding + transfer / mip flags. */\nexport interface BasisEncodeOptions {\n  readonly mode: BasisEncodeMode;\n  readonly width: number;\n  readonly height: number;\n  /** Write the sRGB transfer function into the KTX2 + DFD (LDR color only). */\n  readonly srgb: boolean;\n  /** ETC1S perceptual (sRGB) error metric vs linear PSNR. Ignored for UASTC. */\n  readonly perceptual: boolean;\n  /** Wrap the UASTC-LDR payload in KTX2 zstd supercompression. Ignored otherwise. */\n  readonly uastcSupercompression: boolean;\n  /** Generate a mip chain in the encoder. M3 keeps this false (offline mips are w18/M5). */\n  readonly mipGen: boolean;\n}\n\n/** How the encoder WASM module is loaded. Overridable in tests. @internal */\ntype EncoderImporter = () => Promise<BasisEncoderModule>;\n\nconst ENCODER_GLUE = new URL('../../pkg/encode/basis_encoder.mjs', import.meta.url);\nconst ENCODER_WASM = new URL('../../pkg/encode/basis_encoder.wasm', import.meta.url);\n\nconst defaultImporter: EncoderImporter = async () => {\n  const factory = (\n    (await import(/* @vite-ignore */ ENCODER_GLUE.href)) as {\n      default: BasisModuleFactory<BasisEncoderModule>;\n    }\n  ).default;\n  const mod = await factory({ locateFile: () => ENCODER_WASM.href });\n  mod.initializeBasis();\n  return mod;\n};\n\nlet importer: EncoderImporter = defaultImporter;\n\n/** Lazy-init singleton (D-10): null = never attempted, cleared on failure to retry. @internal */\nlet _initPromise: Promise<BasisEncoderModule> | null = null;\n\n/** Count of importer invocations; observed in tests to prove single-init. @internal */\nlet initCount = 0;\n\n/**\n * Lazy-init the Basis encoder WASM module (D-10 main-thread singleton).\n * First call dynamic-imports + initializes; subsequent calls return the cache.\n */\nexport function initBasisEncoder(): Promise<BasisEncoderModule> {\n  if (_initPromise !== null) return _initPromise;\n  initCount++;\n  _initPromise = importer().catch((cause: unknown) => {\n    _initPromise = null;\n    throw new Error('codec-init-failed', { cause });\n  });\n  return _initPromise;\n}\n\n/**\n * Test-only: number of times the encoder importer has been invoked.\n * @internal\n */\nexport function _basisEncoderInitCount(): number {\n  return initCount;\n}\n\n/**\n * Test-only: reset the lazy singleton and optionally override the importer.\n * Call with no argument to restore the real WASM importer.\n * @internal\n */\nexport function _setBasisEncoderImporter(next?: EncoderImporter): void {\n  importer = next ?? defaultImporter;\n  _initPromise = null;\n  initCount = 0;\n}\n\n/** Map a delivery encoding to the encoder `basis_tex_format` enum value. */\nfunction formatModeValue(mod: BasisEncoderModule, mode: BasisEncodeMode): number {\n  const f = mod.basis_tex_format;\n  switch (mode) {\n    case 'etc1s':\n      return f.cETC1S.value;\n    case 'uastc-ldr':\n      return f.cUASTC_LDR_4x4.value;\n    case 'uastc-hdr':\n      return f.cUASTC_HDR_4x4.value;\n  }\n}\n\n/**\n * Encode raw pixels into a Basis KTX2 container.\n *\n * `pixels` is tight-packed RGBA: 8-bit `R,G,B,A` per texel for LDR modes\n * (`etc1s` / `uastc-ldr`), IEEE-754 binary16 RGBA (rgba16float bytes) for\n * `uastc-hdr`. On any encoder-side failure returns a `ktx2-encode-failed`\n * CodecError carrying the mode + a short reason.\n */\nexport async function basisEncode(\n  pixels: Uint8Array,\n  options: BasisEncodeOptions,\n): Promise<CodecResult<Uint8Array>> {\n  let mod: BasisEncoderModule;\n  try {\n    mod = await initBasisEncoder();\n  } catch {\n    return codecError('codec-init-failed', { stage: 'dynamic-import-basis-encoder' });\n  }\n\n  const { mode, width, height, srgb, perceptual, uastcSupercompression, mipGen } = options;\n  if (width <= 0 || height <= 0) {\n    return codecError('ktx2-encode-failed', {\n      mode,\n      reason: `invalid dimensions ${width}x${height}`,\n    });\n  }\n\n  let encoder: BasisEncoder;\n  try {\n    encoder = new mod.BasisEncoder();\n  } catch {\n    return codecError('ktx2-encode-failed', {\n      mode,\n      reason: 'encoder constructor failed',\n    });\n  }\n  let result: CodecResult<Uint8Array> = codecError('ktx2-encode-failed', {\n    mode,\n    reason: 'encoder returned 0 bytes',\n  });\n  try {\n    // Single-threaded for deterministic, byte-identical output (AC-02 / R-11).\n    encoder.controlThreading(false, 0);\n\n    let sourceAccepted: boolean;\n    if (mode === 'uastc-hdr') {\n      // img_type 0 = cHITRGBAHalfFloat: the source is rgba16float bytes; no\n      // LDR->HDR upconversion (already linear half-float from the image arm).\n      sourceAccepted = encoder.setSliceSourceImageHDR(0, pixels, width, height, 0, false, 1.0);\n    } else {\n      // img_type 0 = cRGBA32: tight-packed 8-bit RGBA.\n      sourceAccepted = encoder.setSliceSourceImage(0, pixels, width, height, 0);\n    }\n\n    if (!sourceAccepted) {\n      result = codecError('ktx2-encode-failed', {\n        mode,\n        reason:\n          mode === 'uastc-hdr' ? 'setSliceSourceImageHDR failed' : 'setSliceSourceImage failed',\n      });\n    } else {\n      encoder.setCreateKTX2File(true);\n      encoder.setFormatMode(formatModeValue(mod, mode));\n      encoder.setMipGen(mipGen);\n\n      if (mode === 'etc1s') {\n        encoder.setQualityLevel(128);\n        // Fastest perf tier (R-9): quality stays fixed by setQualityLevel above;\n        // the compression level only trades a marginally larger file for a much\n        // faster encode (the 'auto' default routes every texture through here).\n        encoder.setETC1SCompressionLevel(ETC1S_COMPRESSION_LEVEL_FASTEST);\n        encoder.setPerceptual(perceptual);\n      } else if (mode === 'uastc-ldr') {\n        encoder.setKTX2UASTCSupercompression(uastcSupercompression);\n        // Fastest pack tier (R-9). Unlike ETC1S this lowers quality; per-fixture\n        // opt-out / D-12 upgrade covers any smoke that will not converge.\n        encoder.setPackUASTCFlags(PACK_UASTC_LDR_LEVEL_FASTEST);\n        encoder.setPerceptual(perceptual);\n      } else {\n        // uastc-hdr: fastest HDR search tier (R-9); block bytes unchanged in size.\n        encoder.setUASTCHDRQualityLevel(UASTC_HDR_QUALITY_LEVEL_FASTEST);\n      }\n      // sRGB transfer function into the KTX2 header + DFD (LDR color arm).\n      encoder.setKTX2AndBasisSRGBTransferFunc(srgb);\n\n      // encode() copies into the provided buffer and returns the byte length (0 on\n      // failure). A 4 MiB scratch buffer covers a single-slice mip-0 image at the\n      // sizes this offline arm handles; grow-on-overflow retries once.\n      let capacity = 1 << 22;\n      let out = new Uint8Array(capacity);\n      let n = encoder.encode(out);\n      if (n === 0) {\n        capacity = 1 << 25;\n        out = new Uint8Array(capacity);\n        n = encoder.encode(out);\n      }\n      if (n === 0) {\n        result = codecError('ktx2-encode-failed', { mode, reason: 'encoder returned 0 bytes' });\n      } else {\n        result = { ok: true, value: out.slice(0, n) };\n      }\n    }\n  } catch (e) {\n    const reason = e instanceof Error ? e.message : String(e);\n    result = codecError('ktx2-encode-failed', { mode, reason });\n  }\n  try {\n    encoder.delete();\n  } catch {\n    if (result.ok) {\n      result = codecError('ktx2-encode-failed', { mode, reason: 'encoder cleanup failed' });\n    }\n  }\n  return result;\n}\n"]}

package/dist/encode-impl.d.ts

@@ -0,0 +1,30 @@
+import type { CodecResult } from './errors.js';
+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;
+/**
+ * Test-only: number of zstd encoder WASM initialization attempts.
+ * @internal
+ */
+export declare function _zstdEncodeInitCount(): number;
+/**
+ * Test-only: reset the encoder singleton and optionally override its importer.
+ * @internal
+ */
+export declare function _setZstdEncoderImporter(next?: ZstdImporter): void;
+/**
+ * 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 declare function compressZstd(bytes: Uint8Array): Promise<CodecResult<Uint8Array>>;
+export {};
+//# sourceMappingURL=encode-impl.d.ts.map

package/dist/encode-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode-impl.d.ts","sourceRoot":"","sources":["../src/encode-impl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAY/C,UAAU,QAAQ;IAChB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;CACvD;AAED,uEAAuE;AACvE,KAAK,YAAY,GAAG,MAAM,QAAQ,CAAC;AA2CnC;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,CAKjE;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAWtF"}

package/dist/errors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 declare function codecError<C extends CodecErrorCode>(code: C, detail: CodecErrorDetails[C]): CodecErrorFor<C>;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yCAAyC;AACzC,UAAU,iBAAiB;IACzB,sBAAsB,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,mBAAmB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,mBAAmB,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,yBAAyB,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,kBAAkB,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACrF,oBAAoB,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAED,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,iBAAiB,CAAC;AAErD,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG;KACtB,CAAC,IAAI,cAAc,GAAG;QACrB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE;YACd,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;YACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;YAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;SACvC,CAAC;KACH;CACF,CAAC,cAAc,CAAC,CAAC;AAElB,KAAK,aAAa,CAAC,CAAC,SAAS,cAAc,IAAI,OAAO,CACpD,UAAU,EACV;IAAE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;KAAE,CAAA;CAAE,CACzC,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,uEAAuE;AACvE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;AAErD,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EACjD,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,aAAa,CAAC,CAAC,CAAC,CAyBlB"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,aAAa,EACb,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,kBAAkB,EAClB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACzF,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}