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

package/src/__tests__/zstd-deterministic.unit.test.ts

@@ -0,0 +1,49 @@
+import { compressZstd } from '@forgeax/engine-codec/encode';
+import { describe, expect, it } from 'vitest';
+
+/** Generate deterministic f32-ish bytes (vertex-like float data). */
+function makeF32Data(elementCount: number): Uint8Array {
+  const floats = new Float32Array(elementCount);
+  for (let i = 0; i < elementCount; i++) {
+    floats[i] = Math.sin(i * 0.1) * 10.0 + (i % 100) * 0.01;
+  }
+  return new Uint8Array(floats.buffer, floats.byteOffset, floats.byteLength);
+}
+
+describe('zstd encode deterministic (w3)', () => {
+  it('5x compress same input produces byte-identical output (AC-07)', async () => {
+    const input = makeF32Data(4096); // 16384 bytes of f32 vertex-like data
+    const results: Uint8Array[] = [];
+    for (let i = 0; i < 5; i++) {
+      const r = await compressZstd(input);
+      expect(r.ok).toBe(true);
+      if (!r.ok) throw new Error(`compress failed at iteration ${i}`);
+      results.push(r.value);
+    }
+    // All 5 outputs must be byte-identical
+    const first = results[0];
+    if (!first) throw new Error('unreachable: results[0] exists after 5 pushes');
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i]).toEqual(first);
+    }
+  });
+
+  it('different inputs produce different compressed output (discriminability)', async () => {
+    const inputA = makeF32Data(4096);
+    const inputB = makeF32Data(4097); // different data
+    const rA = await compressZstd(inputA);
+    const rB = await compressZstd(inputB);
+    expect(rA.ok).toBe(true);
+    expect(rB.ok).toBe(true);
+    if (!rA.ok || !rB.ok) throw new Error('compress failed');
+    expect(rA.value).not.toEqual(rB.value);
+  });
+
+  it('compressed output is smaller than input for f32 array data (compression sanity)', async () => {
+    const input = makeF32Data(8192); // 32768 bytes
+    const r = await compressZstd(input);
+    expect(r.ok).toBe(true);
+    if (!r.ok) throw new Error('compress failed');
+    expect(r.value.length).toBeLessThan(input.length);
+  });
+});

package/src/__tests__/zstd-encode-singleton.unit.test.ts

@@ -0,0 +1,63 @@
+import {
+  _setZstdEncoderImporter,
+  _zstdEncodeInitCount,
+  compressZstd,
+} from '@forgeax/engine-codec/encode';
+import { afterEach, describe, expect, it } from 'vitest';
+
+function makeBytes(size: number): Uint8Array {
+  const bytes = new Uint8Array(size);
+  for (let i = 0; i < size; i++) {
+    bytes[i] = (i * 37 + 13) & 0xff;
+  }
+  return bytes;
+}
+
+function hasZstdMagic(bytes: Uint8Array): boolean {
+  return bytes[0] === 0x28 && bytes[1] === 0xb5 && bytes[2] === 0x2f && bytes[3] === 0xfd;
+}
+
+afterEach(() => {
+  _setZstdEncoderImporter();
+});
+
+describe('zstd encoder deferred-init singleton', () => {
+  it('does not initialize until the first compression', () => {
+    _setZstdEncoderImporter();
+    expect(_zstdEncodeInitCount()).toBe(0);
+  });
+
+  it('shares one WASM init across concurrent first compressions', async () => {
+    _setZstdEncoderImporter();
+    const input = makeBytes(65536);
+    const results = await Promise.all(Array.from({ length: 8 }, () => compressZstd(input)));
+
+    expect(_zstdEncodeInitCount()).toBe(1);
+    for (const result of results) {
+      expect(result.ok).toBe(true);
+      if (!result.ok) throw new Error('zstd compression failed');
+      expect(hasZstdMagic(result.value)).toBe(true);
+      expect(result.value.some((byte) => byte !== 0)).toBe(true);
+    }
+  });
+
+  it('clears a failed init so the next compression retries', async () => {
+    let attempts = 0;
+    _setZstdEncoderImporter(() => ({
+      init: async () => {
+        attempts++;
+        if (attempts === 1) throw new Error('simulated zstd init failure');
+      },
+      compress: () => new Uint8Array([0x28, 0xb5, 0x2f, 0xfd]),
+    }));
+
+    const first = await compressZstd(makeBytes(8));
+    expect(first.ok).toBe(false);
+    expect(_zstdEncodeInitCount()).toBe(1);
+
+    const second = await compressZstd(makeBytes(8));
+    expect(second.ok).toBe(true);
+    expect(attempts).toBe(2);
+    expect(_zstdEncodeInitCount()).toBe(2);
+  });
+});

package/src/__tests__/zstd-roundtrip.unit.test.ts

@@ -0,0 +1,87 @@
+import { decompressZstd } from '@forgeax/engine-codec';
+// compressZstd comes from the encode subpath (build-time).
+// In vitest context this resolves to packages/codec/src/encode/index.ts.
+import { compressZstd } from '@forgeax/engine-codec/encode';
+import { describe, expect, it } from 'vitest';
+
+/** Generate deterministic test bytes of given length. */
+function makeBytes(size: number): Uint8Array {
+  const arr = new Uint8Array(size);
+  for (let i = 0; i < size; i++) {
+    arr[i] = (i * 37 + 13) & 0xff;
+  }
+  return arr;
+}
+
+/** Unwrap a CodecResult, throwing on error for test simplicity. */
+async function unwrapZstd(result: Awaited<ReturnType<typeof decompressZstd>>): Promise<Uint8Array> {
+  if (!result.ok) {
+    throw new Error(`unexpected codec error: ${result.error.code} — ${result.error.detail}`);
+  }
+  return result.value;
+}
+
+describe('zstd round-trip (w2)', () => {
+  it('round-trip byte-identical for non-empty input (1 byte)', async () => {
+    const original = makeBytes(1);
+    const comp = await compressZstd(original);
+    expect(comp.ok).toBe(true);
+    if (!comp.ok) throw new Error('compress failed');
+    const decompressed = await unwrapZstd(await decompressZstd(comp.value));
+    expect(decompressed).toEqual(original);
+  });
+
+  it('round-trip byte-identical for 1024 bytes', async () => {
+    const original = makeBytes(1024);
+    const comp = await compressZstd(original);
+    expect(comp.ok).toBe(true);
+    if (!comp.ok) throw new Error('compress failed');
+    const decompressed = await unwrapZstd(await decompressZstd(comp.value));
+    expect(decompressed).toEqual(original);
+  });
+
+  it('round-trip byte-identical for 65536 bytes', async () => {
+    const original = makeBytes(65536);
+    const comp = await compressZstd(original);
+    expect(comp.ok).toBe(true);
+    if (!comp.ok) throw new Error('compress failed');
+    const decompressed = await unwrapZstd(await decompressZstd(comp.value));
+    expect(decompressed).toEqual(original);
+  });
+
+  it('0-byte input round-trip returns 0-byte (E4)', async () => {
+    const original = new Uint8Array(0);
+    const comp = await compressZstd(original);
+    expect(comp.ok).toBe(true);
+    if (!comp.ok) throw new Error('compress failed');
+    const decompressed = await unwrapZstd(await decompressZstd(comp.value));
+    expect(decompressed.length).toBe(0);
+    expect(decompressed).toEqual(original);
+  });
+
+  it('non-zstd garbage input returns decompression-failed error', async () => {
+    const garbage = new Uint8Array([0x00, 0x01, 0x02, 0x03, 0xff]);
+    const result = await decompressZstd(garbage);
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      throw new Error('expected error for garbage input');
+    }
+    expect(result.error.code).toBe('decompression-failed');
+  });
+
+  it('FALSIFICATION: corrupt 1 byte of valid compressed output, round-trip must FAIL', async () => {
+    const original = makeBytes(4096);
+    const comp = await compressZstd(original);
+    expect(comp.ok).toBe(true);
+    if (!comp.ok) throw new Error('compress failed');
+    // Corrupt byte 1 of the compressed stream
+    const corrupted = new Uint8Array(comp.value);
+    if (corrupted.length > 1) {
+      const val = corrupted[1];
+      if (val !== undefined) corrupted[1] = val ^ 0xff;
+    }
+    const result = await decompressZstd(corrupted);
+    // Must NOT silently return original bytes — correctness requires error
+    expect(result.ok).toBe(false);
+  });
+});

package/src/__tests__/zstd-singleton.unit.test.ts

@@ -0,0 +1,105 @@
+import { compressZstd } from '@forgeax/engine-codec/encode';
+import { afterEach, describe, expect, it } from 'vitest';
+import { _setZstdImporter, _zstdInitCount, decompressZstd } from '../zstd.js';
+
+/**
+ * zstd lazy-init singleton test (w5).
+ *
+ * Validates that the decompressZstd implementation:
+ * 1. Does NOT trigger the fzstd importer until the first decompress call (AC-12 zero-cost).
+ * 2. Loads the decompressor exactly once even under concurrent first callers.
+ * 3. Retries on init failure (does NOT permanently cache the failure).
+ *
+ * The `_setZstdImporter` / `_zstdInitCount` internal hooks make the module-private
+ * singleton observable so these are real assertions, not behavioral guesses.
+ */
+
+/** Generate deterministic test bytes. */
+function makeBytes(size: number): Uint8Array {
+  const arr = new Uint8Array(size);
+  for (let i = 0; i < size; i++) {
+    arr[i] = (i * 37 + 13) & 0xff;
+  }
+  return arr;
+}
+
+afterEach(() => {
+  // Restore the real fzstd importer + reset counters so tests do not leak state.
+  _setZstdImporter();
+});
+
+describe('zstd deferred-init singleton (w5)', () => {
+  it('AC-12 zero-cost: importer is not invoked until the first decompress call', () => {
+    _setZstdImporter(); // reset counter to 0
+    expect(typeof decompressZstd).toBe('function');
+    // Importing / referencing the function must not have loaded the decompressor.
+    expect(_zstdInitCount()).toBe(0);
+  });
+
+  it('first call to decompressZstd triggers init exactly once and decompresses correctly', async () => {
+    _setZstdImporter();
+    const input = makeBytes(256);
+    const comp = await compressZstd(input);
+    if (!comp.ok) throw new Error('compress failed for test setup');
+
+    const result = await decompressZstd(comp.value);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('decompress failed');
+    expect(result.value).toEqual(input);
+    expect(_zstdInitCount()).toBe(1);
+  });
+
+  it('N concurrent first calls share a single init (importer invoked once) (AC-12)', async () => {
+    // Inject a slow importer so all 5 calls race while init is still in-flight.
+    const realFzstd = await import('fzstd');
+    _setZstdImporter(
+      () =>
+        new Promise((resolve) => {
+          setTimeout(() => resolve(realFzstd.decompress), 10);
+        }),
+    );
+
+    const input = makeBytes(256);
+    const comp = await compressZstd(input);
+    if (!comp.ok) throw new Error('compress failed for test setup');
+
+    const results = await Promise.all(Array.from({ length: 5 }, () => decompressZstd(comp.value)));
+
+    // The importer must have been invoked exactly once despite 5 concurrent callers.
+    expect(_zstdInitCount()).toBe(1);
+    for (const r of results) {
+      expect(r.ok).toBe(true);
+      if (!r.ok) throw new Error('decompress failed');
+      expect(r.value).toEqual(input);
+    }
+  });
+
+  it('init failure returns codec-init-failed and the next call retries (not permanently cached)', async () => {
+    let attempts = 0;
+    const realFzstd = await import('fzstd');
+    _setZstdImporter(() => {
+      attempts++;
+      if (attempts === 1) {
+        return Promise.reject(new Error('simulated fzstd load failure'));
+      }
+      return Promise.resolve(realFzstd.decompress);
+    });
+
+    const input = makeBytes(128);
+    const comp = await compressZstd(input);
+    if (!comp.ok) throw new Error('compress failed for test setup');
+
+    // First call: importer rejects -> codec-init-failed, cached failure cleared.
+    const failed = await decompressZstd(comp.value);
+    expect(failed.ok).toBe(false);
+    if (failed.ok) throw new Error('expected first call to fail');
+    expect(failed.error.code).toBe('codec-init-failed');
+
+    // Second call: importer retried (not permanently cached) -> succeeds.
+    const retried = await decompressZstd(comp.value);
+    expect(retried.ok).toBe(true);
+    if (!retried.ok) throw new Error('retry decompress failed');
+    expect(retried.value).toEqual(input);
+    expect(attempts).toBe(2);
+  });
+});

package/src/basis-transcoder.ts

@@ -0,0 +1,315 @@
+/**
+ * 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 { codecError } from './errors.js';
+import type { Ktx2Parsed } from './ktx2.js';
+import type { BasisFile, BasisModuleFactory, BasisTranscoderModule } from './wasm/basis-types.js';
+
+/** How the transcoder WASM module is loaded. Overridable in tests. */
+type TranscoderImporter = () => Promise<BasisTranscoderModule>;
+
+const TRANSCODER_GLUE = new URL('../pkg/basis_transcoder.mjs', import.meta.url);
+const TRANSCODER_WASM = new URL('../pkg/basis_transcoder.wasm', import.meta.url);
+
+const defaultImporter: TranscoderImporter = async () => {
+  const factory = (
+    (await import(/* @vite-ignore */ TRANSCODER_GLUE.href)) as {
+      default: BasisModuleFactory<BasisTranscoderModule>;
+    }
+  ).default;
+  const mod = await factory({ locateFile: () => TRANSCODER_WASM.href });
+  mod.initializeBasis();
+  return mod;
+};
+
+let importer: TranscoderImporter = defaultImporter;
+
+/**
+ * Lazy-init singleton (D-10): null = never attempted, Promise = init in flight,
+ * resolved = ready, rejected = cleared so the next call retries.
+ * @internal
+ */
+let _initPromise: Promise<BasisTranscoderModule> | null = null;
+
+/** Count of importer invocations; observed in tests to prove single-init. @internal */
+let initCount = 0;
+
+/**
+ * Lazy-init the Basis transcoder WASM module (D-10 main-thread singleton).
+ * First call dynamic-imports + initializes; subsequent calls return the cache.
+ */
+export function initBasisTranscoder(): Promise<BasisTranscoderModule> {
+  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 transcoder importer has been invoked. Proves
+ * the lazy singleton loads the module at most once (D-10).
+ * @internal
+ */
+export function _basisTranscoderInitCount(): 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 _setBasisTranscoderImporter(next?: TranscoderImporter): void {
+  importer = next ?? defaultImporter;
+  _initPromise = null;
+  initCount = 0;
+}
+
+/** 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 function inspectBasisSource(
+  file: BasisFile,
+  meta: Partial<BasisSourceMeta>,
+  profile: BasisSourceInspection['profile'],
+): CodecResult<BasisSourceInspection> {
+  if (meta.colorSpace !== 'srgb' && meta.colorSpace !== 'linear') {
+    return codecError('ktx2-parse-failed', {
+      reason: 'raw Basis source requires Meta.colorSpace=srgb|linear',
+    });
+  }
+  if (file.getNumImages() <= 0 || file.getNumLevels(0) <= 0) {
+    return codecError('ktx2-parse-failed', { reason: 'invalid raw Basis source shape' });
+  }
+  return {
+    ok: true,
+    value: {
+      colorSpace: meta.colorSpace,
+      profile,
+      width: file.getImageWidth(0, 0),
+      height: file.getImageHeight(0, 0),
+      levelCount: file.getNumLevels(0),
+      imageCount: file.getNumImages(),
+    },
+  };
+}
+
+/**
+ * Map a selected `GPUTextureFormat` to a basis `transcoder_texture_format` enum
+ * value. sRGB variants share the transcode target (sRGB is a view/DFD concern,
+ * not a distinct transcode format). Uncompressed single/dual-channel fallbacks
+ * (r8/rg8) route through RGBA32 -- basis has no r8/rg8 uncompressed target; the
+ * runtime upload path (M5) reconciles channel selection.
+ */
+function basisTargetFor(mod: BasisTranscoderModule, format: GPUTextureFormat): number | null {
+  const e = mod.transcoder_texture_format;
+  switch (format) {
+    case 'bc7-rgba-unorm':
+    case 'bc7-rgba-unorm-srgb':
+      return e.cTFBC7_RGBA.value;
+    case 'bc5-rg-unorm':
+      return e.cTFBC5_RG.value;
+    case 'bc4-r-unorm':
+      return e.cTFBC4_R.value;
+    case 'bc6h-rgb-ufloat':
+      return e.cTFBC6H.value;
+    case 'etc2-rgba8unorm':
+    case 'etc2-rgba8unorm-srgb':
+      return e.cTFETC2_RGBA.value;
+    case 'astc-4x4-unorm':
+    case 'astc-4x4-unorm-srgb':
+      return e.cTFASTC_4x4_RGBA.value;
+    case 'rgba16float':
+      return e.cTFRGBA_HALF.value;
+    case 'rgba8unorm':
+    case 'rgba8unorm-srgb':
+    case 'rg8unorm':
+    case 'r8unorm':
+      return e.cTFRGBA32.value;
+    default:
+      return null;
+  }
+}
+
+/**
+ * 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 async function transcodeKtx2(
+  parsed: Ktx2Parsed,
+  targetFormat: GPUTextureFormat,
+): Promise<CodecResult<TranscodedTexture>> {
+  let mod: BasisTranscoderModule;
+  try {
+    mod = await initBasisTranscoder();
+  } catch {
+    return codecError('codec-init-failed', { stage: 'dynamic-import-basis-transcoder' });
+  }
+
+  const targetEnum = basisTargetFor(mod, targetFormat);
+  if (targetEnum === null) {
+    return codecError('transcode-failed', {
+      sourceFormat: `dfd-model-${parsed.dfd?.colorModel ?? 'unknown'}`,
+      targetFormat,
+    });
+  }
+
+  const file = new mod.KTX2File(parsed.rawBytes);
+  try {
+    if (!file.isValid()) {
+      return codecError('transcode-failed', {
+        sourceFormat: 'invalid-ktx2-file',
+        targetFormat,
+      });
+    }
+    if (file.startTranscoding() === 0) {
+      return codecError('transcode-failed', {
+        sourceFormat: 'start-transcoding-failed',
+        targetFormat,
+      });
+    }
+
+    const levels = file.getLevels();
+    const mips: TranscodedMip[] = [];
+    for (let level = 0; level < levels; level++) {
+      const info = file.getImageLevelInfo(level, 0, 0);
+      const size = file.getImageTranscodedSizeInBytes(level, 0, 0, targetEnum);
+      const dst = new Uint8Array(size);
+      const ok = file.transcodeImage(dst, level, 0, 0, targetEnum, 0, -1, -1);
+      if (ok === 0) {
+        return codecError('transcode-failed', {
+          sourceFormat: `dfd-model-${parsed.dfd?.colorModel ?? 'unknown'}-level-${level}`,
+          targetFormat,
+        });
+      }
+      mips.push({ level, width: info.origWidth, height: info.origHeight, data: dst });
+    }
+
+    return {
+      ok: true,
+      value: {
+        format: targetFormat,
+        width: file.getWidth(),
+        height: file.getHeight(),
+        mips,
+      },
+    };
+  } finally {
+    file.close();
+  }
+}
+
+/** Transcode a raw `.basis` file; source color remains a Meta author fact. */
+export async function transcodeBasis(
+  bytes: Uint8Array,
+  targetFormat: GPUTextureFormat,
+): Promise<CodecResult<TranscodedBasisTexture>> {
+  let mod: BasisTranscoderModule;
+  try {
+    mod = await initBasisTranscoder();
+  } catch {
+    return codecError('codec-init-failed', { stage: 'dynamic-import-basis-transcoder' });
+  }
+  const targetEnum = basisTargetFor(mod, targetFormat);
+  if (targetEnum === null || mod.BasisFile === undefined) {
+    return codecError('transcode-failed', {
+      sourceFormat: 'raw-basis',
+      targetFormat,
+    });
+  }
+  const file = new mod.BasisFile(bytes);
+  try {
+    if (file.getNumImages() <= 0 || file.getNumLevels(0) <= 0) {
+      return codecError('transcode-failed', { sourceFormat: 'invalid-basis-file', targetFormat });
+    }
+    if (file.startTranscoding() === 0) {
+      return codecError('transcode-failed', {
+        sourceFormat: 'start-transcoding-failed',
+        targetFormat,
+      });
+    }
+    const mips: TranscodedMip[] = [];
+    for (let level = 0; level < file.getNumLevels(0); level++) {
+      const width = file.getImageWidth(0, level);
+      const height = file.getImageHeight(0, level);
+      const size = file.getImageTranscodedSizeInBytes(0, level, targetEnum);
+      const data = new Uint8Array(size);
+      if (file.transcodeImage(data, 0, level, targetEnum, 0) === 0) {
+        return codecError('transcode-failed', {
+          sourceFormat: `raw-basis-level-${level}`,
+          targetFormat,
+        });
+      }
+      mips.push({ level, width, height, data });
+    }
+    return {
+      ok: true,
+      value: {
+        format: targetFormat,
+        width: mips[0]?.width ?? 0,
+        height: mips[0]?.height ?? 0,
+        mips,
+      },
+    };
+  } finally {
+    file.close();
+  }
+}