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

package/dist/__tests__/basis-encode-fast-preset.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=basis-encode-fast-preset.unit.test.d.ts.map

package/dist/__tests__/basis-encode-fast-preset.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis-encode-fast-preset.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/basis-encode-fast-preset.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/basis-encode-lifecycle.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=basis-encode-lifecycle.unit.test.d.ts.map

package/dist/__tests__/basis-encode-lifecycle.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis-encode-lifecycle.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/basis-encode-lifecycle.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/basis-transcoder.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=basis-transcoder.unit.test.d.ts.map

package/dist/__tests__/basis-transcoder.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis-transcoder.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/basis-transcoder.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/block-format.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=block-format.unit.test.d.ts.map

package/dist/__tests__/block-format.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-format.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/block-format.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/byte-identical-falsification.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=byte-identical-falsification.test.d.ts.map

package/dist/__tests__/byte-identical-falsification.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-identical-falsification.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/byte-identical-falsification.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/codec-errors.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec-errors.test-d.d.ts.map

package/dist/__tests__/codec-errors.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-errors.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/codec-errors.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/codec-errors.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec-errors.unit.test.d.ts.map

package/dist/__tests__/codec-errors.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-errors.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/codec-errors.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/compression-field.unit.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * w9 TDD: compression field type-domain + no-as access (AC-01).
+ *
+ * Validates that AssetCompression union type = 'none' | 'zstd' appears at all
+ * 5 field locations (research Finding 1), and that consumption paths never
+ * require `as` assertion.
+ *
+ * TDD red state: these tests encode the expected structural contract. After
+ * w12 adds the real `compression` fields to types/index.ts and asset-registry.ts,
+ * the runtime assertions pass (no TS compile errors, field access without `as`).
+ *
+ * Strategy: define local mirror types matching the expected API shape, then
+ * verify that the shape itself is correct. After w12 lands, the real types
+ * will match this contract; the test stays structurally green.
+ *
+ * D-10: all fixtures programmatic, no binary files.
+ */
+export {};
+//# sourceMappingURL=compression-field.unit.test.d.ts.map

package/dist/__tests__/compression-field.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression-field.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/compression-field.unit.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/__tests__/encode-pixel-limit.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=encode-pixel-limit.unit.test.d.ts.map

package/dist/__tests__/encode-pixel-limit.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode-pixel-limit.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/encode-pixel-limit.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/encode-roundtrip.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=encode-roundtrip.unit.test.d.ts.map

package/dist/__tests__/encode-roundtrip.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode-roundtrip.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/encode-roundtrip.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ktx2-basis-capability-matrix.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ktx2-basis-capability-matrix.unit.test.d.ts.map

package/dist/__tests__/ktx2-basis-capability-matrix.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-basis-capability-matrix.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ktx2-basis-capability-matrix.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ktx2-errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ktx2-errors.test.d.ts.map

package/dist/__tests__/ktx2-errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-errors.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ktx2-errors.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ktx2-parse-scheme0.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ktx2-parse-scheme0.test.d.ts.map

package/dist/__tests__/ktx2-parse-scheme0.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-parse-scheme0.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ktx2-parse-scheme0.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ktx2-parse-scheme2.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ktx2-parse-scheme2.test.d.ts.map

package/dist/__tests__/ktx2-parse-scheme2.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-parse-scheme2.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ktx2-parse-scheme2.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ktx2-scheme1-and-transcode-errors.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ktx2-scheme1-and-transcode-errors.unit.test.d.ts.map

package/dist/__tests__/ktx2-scheme1-and-transcode-errors.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-scheme1-and-transcode-errors.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ktx2-scheme1-and-transcode-errors.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ktx2-to-texture.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ktx2-to-texture.integration.test.d.ts.map

package/dist/__tests__/ktx2-to-texture.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ktx2-to-texture.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ktx2-to-texture.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/transcode-select-target.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transcode-select-target.unit.test.d.ts.map

package/dist/__tests__/transcode-select-target.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcode-select-target.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/transcode-select-target.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/wasm-init-smoke.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=wasm-init-smoke.test.d.ts.map

package/dist/__tests__/wasm-init-smoke.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-init-smoke.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/wasm-init-smoke.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/zstd-deterministic.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=zstd-deterministic.unit.test.d.ts.map

package/dist/__tests__/zstd-deterministic.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-deterministic.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/zstd-deterministic.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/zstd-encode-singleton.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=zstd-encode-singleton.unit.test.d.ts.map

package/dist/__tests__/zstd-encode-singleton.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-encode-singleton.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/zstd-encode-singleton.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/zstd-roundtrip.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=zstd-roundtrip.unit.test.d.ts.map

package/dist/__tests__/zstd-roundtrip.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-roundtrip.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/zstd-roundtrip.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/zstd-singleton.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=zstd-singleton.unit.test.d.ts.map

package/dist/__tests__/zstd-singleton.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-singleton.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/zstd-singleton.unit.test.ts"],"names":[],"mappings":""}

package/dist/basis-transcoder.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Basis transcoder glue: lazy-init singleton (D-10) + per-mip KTX2 transcode.
+ *
+ * `initBasisTranscoder` dynamic-imports the self-built transcoder WASM module on
+ * first call and caches it; the second call returns the same instance without
+ * re-importing (D-10 main-thread lazy-init -- `Engine.create` does not preload,
+ * the first Basis payload triggers this). No worker pool (OOS -- forgeax has no
+ * worker infrastructure). Both node and browser can `import` this module: the
+ * WASM glue is a MODULARIZE factory whose `.mjs` path resolves in both.
+ *
+ * `transcodeKtx2` opens a parsed KTX2 container's raw bytes as a basis KTX2File,
+ * starts transcoding, and transcodes every mip level (mip-major) into the target
+ * `GPUTextureFormat`. It returns the block (or pixel) byte arrays per level; it
+ * does not upload -- the runtime upload path (M5) consumes these with the block
+ * table.
+ */
+import type { CodecResult } from './errors.js';
+import type { Ktx2Parsed } from './ktx2.js';
+import type { BasisFile, BasisTranscoderModule } from './wasm/basis-types.js';
+/** How the transcoder WASM module is loaded. Overridable in tests. */
+type TranscoderImporter = () => Promise<BasisTranscoderModule>;
+/**
+ * Lazy-init the Basis transcoder WASM module (D-10 main-thread singleton).
+ * First call dynamic-imports + initializes; subsequent calls return the cache.
+ */
+export declare function initBasisTranscoder(): Promise<BasisTranscoderModule>;
+/**
+ * Test-only: number of times the transcoder importer has been invoked. Proves
+ * the lazy singleton loads the module at most once (D-10).
+ * @internal
+ */
+export declare function _basisTranscoderInitCount(): number;
+/**
+ * Test-only: reset the lazy singleton and optionally override the importer.
+ * Call with no argument to restore the real WASM importer.
+ * @internal
+ */
+export declare function _setBasisTranscoderImporter(next?: TranscoderImporter): void;
+/** One transcoded mip level (mip-major output). */
+export interface TranscodedMip {
+    readonly level: number;
+    readonly width: number;
+    readonly height: number;
+    /** Transcoded block (compressed) or pixel (uncompressed) bytes for this level. */
+    readonly data: Uint8Array;
+}
+/** Result of transcoding a KTX2 container into a target GPU format. */
+export interface TranscodedTexture {
+    readonly format: GPUTextureFormat;
+    readonly width: number;
+    readonly height: number;
+    /** Mip levels, base (level 0 / largest) first. */
+    readonly mips: readonly TranscodedMip[];
+}
+export interface BasisSourceMeta {
+    readonly colorSpace: 'srgb' | 'linear';
+}
+export interface BasisSourceInspection {
+    readonly colorSpace: BasisSourceMeta['colorSpace'];
+    readonly profile: 'etc1s' | 'uastc-ldr';
+    readonly width: number;
+    readonly height: number;
+    readonly levelCount: number;
+    readonly imageCount: number;
+}
+/** Result of transcoding a raw Basis file into one engine texture format. */
+export interface TranscodedBasisTexture {
+    readonly format: GPUTextureFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly mips: readonly TranscodedMip[];
+}
+/** Inspect a raw Basis source without inferring color from the binary payload. */
+export declare function inspectBasisSource(file: BasisFile, meta: Partial<BasisSourceMeta>, profile: BasisSourceInspection['profile']): CodecResult<BasisSourceInspection>;
+/**
+ * Transcode every mip level of a parsed KTX2 container into `targetFormat`.
+ *
+ * Uses `parsed.rawBytes` as the basis KTX2File source. Returns one entry per mip
+ * level (base first). On any basis-side failure returns a `transcode-failed`
+ * CodecError carrying the source DFD color model and the target format.
+ */
+export declare function transcodeKtx2(parsed: Ktx2Parsed, targetFormat: GPUTextureFormat): Promise<CodecResult<TranscodedTexture>>;
+/** Transcode a raw `.basis` file; source color remains a Meta author fact. */
+export declare function transcodeBasis(bytes: Uint8Array, targetFormat: GPUTextureFormat): Promise<CodecResult<TranscodedBasisTexture>>;
+export {};
+//# sourceMappingURL=basis-transcoder.d.ts.map

package/dist/basis-transcoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis-transcoder.d.ts","sourceRoot":"","sources":["../src/basis-transcoder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAsB,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAElG,sEAAsE;AACtE,KAAK,kBAAkB,GAAG,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;AA4B/D;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAQpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAI3E;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAAC;CACxC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;CACzC;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,EAC9B,OAAO,EAAE,qBAAqB,CAAC,SAAS,CAAC,GACxC,WAAW,CAAC,qBAAqB,CAAC,CAoBpC;AAuCD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,gBAAgB,GAC7B,OAAO,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,CA2DzC;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,CAClC,KAAK,EAAE,UAAU,EACjB,YAAY,EAAE,gBAAgB,GAC7B,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAmD9C"}

package/dist/block-format.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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;
+}
+/**
+ * Look up the block parameters for a format. Returns `null` for uncompressed
+ * formats (the table only holds block-compressed entries).
+ */
+export declare function blockParamsForFormat(format: GPUTextureFormat): BlockParams | null;
+/** Guard: true iff `format` is a block-compressed format in the table. */
+export declare function isCompressedFormat(format: GPUTextureFormat): boolean;
+/**
+ * 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 declare function bytesPerRow(format: GPUTextureFormat, width: number): number | null;
+/**
+ * Block rows for a compressed mip level of the given pixel height:
+ * `ceil(height / blockH)`. Returns `null` for uncompressed formats.
+ */
+export declare function rowsPerImage(format: GPUTextureFormat, height: number): number | null;
+//# sourceMappingURL=block-format.d.ts.map

package/dist/block-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-format.d.ts","sourceRoot":"","sources":["../src/block-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAyED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,GAAG,IAAI,CAEjF;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIlF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIpF"}

package/dist/encode/basis-encode.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 type { TranscodeModel } from '../transcode.js';
+import type { BasisEncoderModule } from '../wasm/basis-types.js';
+/** Which delivery encoding to produce. Mirrors the transcode source models (D-3). */
+export type BasisEncodeMode = TranscodeModel;
+/** 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>;
+/**
+ * Lazy-init the Basis encoder WASM module (D-10 main-thread singleton).
+ * First call dynamic-imports + initializes; subsequent calls return the cache.
+ */
+export declare function initBasisEncoder(): Promise<BasisEncoderModule>;
+/**
+ * Test-only: number of times the encoder importer has been invoked.
+ * @internal
+ */
+export declare function _basisEncoderInitCount(): number;
+/**
+ * Test-only: reset the lazy singleton and optionally override the importer.
+ * Call with no argument to restore the real WASM importer.
+ * @internal
+ */
+export declare function _setBasisEncoderImporter(next?: EncoderImporter): void;
+/**
+ * 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 declare function basisEncode(pixels: Uint8Array, options: BasisEncodeOptions): Promise<CodecResult<Uint8Array>>;
+export {};
+//# sourceMappingURL=basis-encode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"basis-encode.d.ts","sourceRoot":"","sources":["../../src/encode/basis-encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAgB,kBAAkB,EAAsB,MAAM,wBAAwB,CAAC;AAEnG,qFAAqF;AACrF,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAoC7C,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,6EAA6E;AAC7E,KAAK,eAAe,GAAG,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAwBzD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAQ9D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI,CAIrE;AAeD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAuGlC"}

package/dist/encode/index.d.ts

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

package/dist/encode/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/encode/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,WAAW,EACX,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/encode/index.mjs

@@ -0,0 +1,207 @@
+import { createRequire } from 'module';
+
+// src/encode-impl.ts
+
+// src/errors.ts
+function codecError(code, detail) {
+  const hints = {
+    "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
+    }
+  };
+}
+
+// src/encode-impl.ts
+var zstdRequire = createRequire(import.meta.url);
+var defaultImporter = () => zstdRequire("@bokuweb/zstd-wasm");
+var importer = defaultImporter;
+var _zstd = null;
+var _initPromise = null;
+var initCount = 0;
+function getZstd() {
+  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) => {
+    _initPromise = null;
+    throw new Error("codec-init-failed", { cause });
+  });
+  return _initPromise;
+}
+function _zstdEncodeInitCount() {
+  return initCount;
+}
+function _setZstdEncoderImporter(next) {
+  importer = next ?? defaultImporter;
+  _zstd = null;
+  _initPromise = null;
+  initCount = 0;
+}
+async function compressZstd(bytes) {
+  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}`
+    });
+  }
+}
+
+// src/encode/basis-encode.ts
+var ETC1S_COMPRESSION_LEVEL_FASTEST = 0;
+var PACK_UASTC_LDR_LEVEL_FASTEST = 0;
+var UASTC_HDR_QUALITY_LEVEL_FASTEST = 0;
+var ENCODER_GLUE = new URL("../../pkg/encode/basis_encoder.mjs", import.meta.url);
+var ENCODER_WASM = new URL("../../pkg/encode/basis_encoder.wasm", import.meta.url);
+var defaultImporter2 = async () => {
+  const factory = (await import(
+    /* @vite-ignore */
+    ENCODER_GLUE.href
+  )).default;
+  const mod = await factory({ locateFile: () => ENCODER_WASM.href });
+  mod.initializeBasis();
+  return mod;
+};
+var importer2 = defaultImporter2;
+var _initPromise2 = null;
+var initCount2 = 0;
+function initBasisEncoder() {
+  if (_initPromise2 !== null) return _initPromise2;
+  initCount2++;
+  _initPromise2 = importer2().catch((cause) => {
+    _initPromise2 = null;
+    throw new Error("codec-init-failed", { cause });
+  });
+  return _initPromise2;
+}
+function _basisEncoderInitCount() {
+  return initCount2;
+}
+function _setBasisEncoderImporter(next) {
+  importer2 = next ?? defaultImporter2;
+  _initPromise2 = null;
+  initCount2 = 0;
+}
+function formatModeValue(mod, mode) {
+  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;
+  }
+}
+async function basisEncode(pixels, options) {
+  let mod;
+  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;
+  try {
+    encoder = new mod.BasisEncoder();
+  } catch {
+    return codecError("ktx2-encode-failed", {
+      mode,
+      reason: "encoder constructor failed"
+    });
+  }
+  let result = codecError("ktx2-encode-failed", {
+    mode,
+    reason: "encoder returned 0 bytes"
+  });
+  try {
+    encoder.controlThreading(false, 0);
+    let sourceAccepted;
+    if (mode === "uastc-hdr") {
+      sourceAccepted = encoder.setSliceSourceImageHDR(0, pixels, width, height, 0, false, 1);
+    } else {
+      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);
+        encoder.setETC1SCompressionLevel(ETC1S_COMPRESSION_LEVEL_FASTEST);
+        encoder.setPerceptual(perceptual);
+      } else if (mode === "uastc-ldr") {
+        encoder.setKTX2UASTCSupercompression(uastcSupercompression);
+        encoder.setPackUASTCFlags(PACK_UASTC_LDR_LEVEL_FASTEST);
+        encoder.setPerceptual(perceptual);
+      } else {
+        encoder.setUASTCHDRQualityLevel(UASTC_HDR_QUALITY_LEVEL_FASTEST);
+      }
+      encoder.setKTX2AndBasisSRGBTransferFunc(srgb);
+      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;
+}
+
+export { _basisEncoderInitCount, _setBasisEncoderImporter, _setZstdEncoderImporter, _zstdEncodeInitCount, basisEncode, compressZstd, initBasisEncoder };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map