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

package/scripts/fetch-wasm.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// fetch-wasm.mjs — Download the pre-built basis-wasm pkg/ bundle from GitHub
+// Releases so no-Emscripten consumers (Studio setup, editor standalone, CI
+// typecheck) can resolve @forgeax/engine-codec without an emcc toolchain and,
+// crucially, without the multi-minute -O3 basis_universal encoder compile.
+//
+// Like @forgeax/engine-wgpu-wasm, the codec pkg/ carries multiple files (two
+// emscripten glue .mjs + two .wasm, nested one level under encode/) that cannot
+// be regenerated from a single .wasm, so the release asset is the WHOLE pkg/
+// packed as a content-keyed .tar.gz; this script downloads and extracts it into
+// packages/codec/pkg/.
+//
+// The content key (see content-key.mjs) is the SSOT shared with the CI publish
+// job, so producer and consumer always agree on the asset name.
+//
+// Usage:
+//   pnpm -F @forgeax/engine-codec fetch-wasm
+//   node scripts/fetch-wasm.mjs
+//
+// Environment:
+//   GITHUB_TOKEN — optional Bearer token for private-repo auth. Falls back to
+//   `gh auth token`. Anonymous requests work for public repos.
+//   FORGEAX_SKIP_CODEC_WASM_FETCH — if set, exit 0 immediately (used by the
+//   non-fatal opt-out path when the toolchain owner wants to build locally).
+//
+// Exit codes: 0 on success (or skip); 1 on any FetchError. Callers that want a
+// build fallback treat a non-zero exit as "release unavailable, compile via
+// build:wasm" (graceful degradation: architecture-principles #9).
+
+import { rm, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { FetchError, getGitOrigin, getReleaseAsset, downloadAsset, extractTarball } from '../../../scripts/lib/fetch-wasm-lib.mjs';
+import { PKG_ROOT, RELEASE_TAG, resolveAsset } from './content-key.mjs';
+
+const PKG_DIR = join(PKG_ROOT, 'pkg');
+const TMP_TARBALL = join(PKG_ROOT, '.pkg-fetch.tar.gz');
+
+const PKG_LABEL = 'basis-wasm';
+const BUILD_HINT =
+  'compile locally with `pnpm -F @forgeax/engine-codec build:wasm` (needs the Emscripten emcc toolchain)';
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (process.env.FORGEAX_SKIP_CODEC_WASM_FETCH) {
+    console.log('fetch-wasm: FORGEAX_SKIP_CODEC_WASM_FETCH set — skipping.');
+    return;
+  }
+
+  console.log('Resolving git origin...');
+  const { owner, repo } = getGitOrigin();
+  console.log(`  origin: ${owner}/${repo}`);
+
+  console.log('Computing content key (fetch-basis.mjs + build-wasm.mjs)...');
+  const { sha256, assetName } = await resolveAsset();
+  console.log(`  content SHA256: ${sha256}`);
+  console.log(`  asset name:     ${assetName}`);
+
+  console.log(`Fetching release tag "${RELEASE_TAG}" from ${owner}/${repo}...`);
+  const asset = await getReleaseAsset(owner, repo, RELEASE_TAG, assetName, {
+    pkgLabel: PKG_LABEL,
+    buildHint: BUILD_HINT,
+    missingAssetHint:
+      'The codec build scripts have uncommitted changes, or the release for this content is not yet published.',
+  });
+
+  console.log(`Downloading ${assetName} (${(asset.size / 1024).toFixed(0)} KB)...`);
+  await downloadAsset(asset, TMP_TARBALL, {
+    owner,
+    repo,
+    tag: RELEASE_TAG,
+    pkgLabel: PKG_LABEL,
+    buildHint: BUILD_HINT,
+  });
+
+  console.log(`Extracting into ${PKG_DIR} ...`);
+  await extractTarball(TMP_TARBALL, PKG_DIR);
+  await rm(TMP_TARBALL, { force: true });
+
+  const members = await readdir(PKG_DIR);
+  console.log(`  pkg/ now holds: ${members.join(', ')}`);
+  console.log('Done.');
+}
+
+main().catch(async (e) => {
+  await rm(TMP_TARBALL, { force: true }).catch(() => {});
+  if (e instanceof FetchError) {
+    console.error(`\n[${e.code}] ${e.message}`);
+    console.error(`Hint: ${e.hint}`);
+  } else {
+    console.error('\nUnexpected error:', e.message || e);
+  }
+  process.exit(1);
+});

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

@@ -0,0 +1,204 @@
+// basis-encode-fast-preset.unit.test.ts -- R-9 fast-preset gate for the w17
+// basisEncode wrapper.
+//
+// M5/w38 flipped the sidecar compressionMode default to 'auto', routing every
+// existing texture through Basis encode. The single-threaded encoder's default
+// effort tiers pushed the model-loading demo build past 10 minutes. R-9 remedy
+// (option 2) drops each arm to its lowest effort tier inside basisEncode:
+//   etc1s     -> setETC1SCompressionLevel(0)  (perf lever, quality unchanged)
+//   uastc-ldr -> setPackUASTCFlags(cPackUASTCLevelFastest)
+//   uastc-hdr -> setUASTCHDRQualityLevel(0)
+//
+// This gate guards the two load-bearing invariants the speedup must NOT break:
+//   (a) the fast-preset output is still a valid Basis KTX2 -- parseKtx2 accepts
+//       it and transcodeKtx2 produces a nonempty BC7 mip (functional).
+//   (b) AC-02 / R-11 determinism survives the effort change -- encoding the same
+//       pixels twice through basisEncode is byte-identical.
+//
+// This exercises the w17 basisEncode WRAPPER (not the raw encoder like w15), so
+// it locks the preset wiring the wrapper adds. pkg/ is a gitignored emcc build
+// artifact (AC-12); the WASM cases skip when it is not built (contributor
+// without emsdk) and run in CI's build-artifacts job.
+
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseKtx2, transcodeKtx2 } from '@forgeax/engine-codec';
+import { basisEncode } from '@forgeax/engine-codec/encode';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { _setBasisEncoderImporter } from '../encode/basis-encode.js';
+
+const ENCODER_GLUE = new URL('../../pkg/encode/basis_encoder.mjs', import.meta.url);
+const TRANSCODER_GLUE = new URL('../../pkg/basis_transcoder.mjs', import.meta.url);
+const pkgBuilt =
+  existsSync(fileURLToPath(ENCODER_GLUE)) && existsSync(fileURLToPath(TRANSCODER_GLUE));
+
+/** A deterministic WxH tight-packed RGBA image. */
+function makeRgba(w: number, h: number): Uint8Array {
+  const img = new Uint8Array(w * h * 4);
+  for (let i = 0; i < w * h; i++) {
+    img[i * 4] = (i * 7) & 255;
+    img[i * 4 + 1] = (i * 13) & 255;
+    img[i * 4 + 2] = (i * 29) & 255;
+    img[i * 4 + 3] = 255;
+  }
+  return img;
+}
+
+/** A deterministic WxH rgba16float image (HDR arm source bytes). */
+function makeHdrF16(w: number, h: number): Uint8Array {
+  const out = new Uint16Array(w * h * 4);
+  const toF16 = (value: number): number => {
+    const f32 = new Float32Array(1);
+    const u32 = new Uint32Array(f32.buffer);
+    f32[0] = value;
+    const x = u32[0] ?? 0;
+    const sign = (x >>> 16) & 0x8000;
+    const exp = (x >>> 23) & 0xff;
+    const mant = x & 0x7fffff;
+    if (exp === 0) return sign;
+    const e = exp - 127 + 15;
+    if (e <= 0) return sign;
+    if (e >= 0x1f) return sign | 0x7c00;
+    return sign | (e << 10) | (mant >> 13);
+  };
+  for (let i = 0; i < w * h; i++) {
+    out[i * 4] = toF16((i % 8) / 8);
+    out[i * 4 + 1] = toF16((i % 4) / 4);
+    out[i * 4 + 2] = toF16(0.5);
+    out[i * 4 + 3] = toF16(1);
+  }
+  return new Uint8Array(out.buffer);
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+describe.skipIf(!pkgBuilt)('basisEncode fast preset (R-9 / w17)', () => {
+  beforeAll(() => {
+    // Use the real WASM importer (default). Reset the singleton so this file's
+    // first encode drives a clean init regardless of test-file ordering.
+    _setBasisEncoderImporter();
+  });
+
+  it('etc1s fast preset round-trips through parseKtx2 + transcodeKtx2', async () => {
+    const r = await basisEncode(makeRgba(16, 16), {
+      mode: 'etc1s',
+      width: 16,
+      height: 16,
+      srgb: true,
+      perceptual: true,
+      uastcSupercompression: false,
+      mipGen: false,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const parsed = await parseKtx2(r.value);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    const transcoded = await transcodeKtx2(parsed.value, 'bc7-rgba-unorm');
+    expect(transcoded.ok).toBe(true);
+    if (!transcoded.ok) return;
+    expect(transcoded.value.mips[0]?.data.length).toBeGreaterThan(0);
+  });
+
+  it('uastc-ldr fast preset round-trips through parseKtx2 + transcodeKtx2', async () => {
+    const r = await basisEncode(makeRgba(16, 16), {
+      mode: 'uastc-ldr',
+      width: 16,
+      height: 16,
+      srgb: true,
+      perceptual: true,
+      uastcSupercompression: true,
+      mipGen: false,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const parsed = await parseKtx2(r.value);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    const transcoded = await transcodeKtx2(parsed.value, 'bc7-rgba-unorm');
+    expect(transcoded.ok).toBe(true);
+    if (!transcoded.ok) return;
+    expect(transcoded.value.mips[0]?.data.length).toBeGreaterThan(0);
+  });
+
+  it('uastc-hdr fast preset round-trips through parseKtx2 + transcodeKtx2', async () => {
+    const r = await basisEncode(makeHdrF16(16, 16), {
+      mode: 'uastc-hdr',
+      width: 16,
+      height: 16,
+      srgb: false,
+      perceptual: false,
+      uastcSupercompression: false,
+      mipGen: false,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const parsed = await parseKtx2(r.value);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    const transcoded = await transcodeKtx2(parsed.value, 'bc6h-rgb-ufloat');
+    expect(transcoded.ok).toBe(true);
+    if (!transcoded.ok) return;
+    expect(transcoded.value.mips[0]?.data.length).toBeGreaterThan(0);
+  });
+
+  it('AC-02: double encode with fast preset is byte-equal (etc1s)', async () => {
+    const img = makeRgba(16, 16);
+    const opts = {
+      mode: 'etc1s',
+      width: 16,
+      height: 16,
+      srgb: true,
+      perceptual: true,
+      uastcSupercompression: false,
+      mipGen: false,
+    } as const;
+    const a = await basisEncode(img, opts);
+    const b = await basisEncode(img, opts);
+    expect(a.ok && b.ok).toBe(true);
+    if (!(a.ok && b.ok)) return;
+    expect(bytesEqual(a.value, b.value)).toBe(true);
+  });
+
+  it('AC-02: double encode with fast preset is byte-equal (uastc-ldr)', async () => {
+    const img = makeRgba(16, 16);
+    const opts = {
+      mode: 'uastc-ldr',
+      width: 16,
+      height: 16,
+      srgb: true,
+      perceptual: true,
+      uastcSupercompression: true,
+      mipGen: false,
+    } as const;
+    const a = await basisEncode(img, opts);
+    const b = await basisEncode(img, opts);
+    expect(a.ok && b.ok).toBe(true);
+    if (!(a.ok && b.ok)) return;
+    expect(bytesEqual(a.value, b.value)).toBe(true);
+  });
+
+  it('AC-02: double encode with fast preset is byte-equal (uastc-hdr)', async () => {
+    const img = makeHdrF16(16, 16);
+    const opts = {
+      mode: 'uastc-hdr',
+      width: 16,
+      height: 16,
+      srgb: false,
+      perceptual: false,
+      uastcSupercompression: false,
+      mipGen: false,
+    } as const;
+    const a = await basisEncode(img, opts);
+    const b = await basisEncode(img, opts);
+    expect(a.ok && b.ok).toBe(true);
+    if (!(a.ok && b.ok)) return;
+    expect(bytesEqual(a.value, b.value)).toBe(true);
+  });
+});

package/src/__tests__/basis-encode-lifecycle.unit.test.ts

@@ -0,0 +1,249 @@
+import type { BasisEncodeMode, BasisEncodeOptions } from '@forgeax/engine-codec/encode';
+import {
+  _basisEncoderInitCount,
+  _setBasisEncoderImporter,
+  basisEncode,
+} from '@forgeax/engine-codec/encode';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const TEST_CONSTRUCTOR_SENTINEL = 'm120-controlled-constructor-throw';
+const TEST_DELETE_SENTINEL = 'm120-controlled-delete-throw';
+const TEST_OPERATION_SENTINEL = 'm120-controlled-operation-throw';
+const CLEANUP_FAILURE_REASON = 'encoder cleanup failed';
+const CONSTRUCTOR_FAILURE_REASON = 'encoder constructor failed';
+const MODES = ['etc1s', 'uastc-ldr', 'uastc-hdr'] as const;
+
+interface FakeEncoderState {
+  readonly constructorIds: number[];
+  readonly deleteIds: number[];
+  readonly sourceCalls: { image: Uint8Array; width: number; height: number; hdr: boolean }[];
+  readonly formatModes: number[];
+  encodeCalls: number;
+  shouldConstructThrow: boolean;
+  shouldDeleteThrow: boolean;
+  shouldSourceFail: boolean;
+  shouldOperationThrow: boolean;
+}
+
+function makeOptions(mode: BasisEncodeMode): BasisEncodeOptions {
+  return {
+    mode,
+    width: 2,
+    height: 2,
+    srgb: mode !== 'uastc-hdr',
+    perceptual: mode !== 'uastc-hdr',
+    uastcSupercompression: mode === 'uastc-ldr',
+    mipGen: false,
+  };
+}
+
+function makePixels(mode: BasisEncodeMode): Uint8Array {
+  return mode === 'uastc-hdr'
+    ? new Uint8Array(2 * 2 * 4 * 2).fill(0x3c)
+    : new Uint8Array(2 * 2 * 4).fill(0x7f);
+}
+
+function createFakeEncoderModule() {
+  const state: FakeEncoderState = {
+    constructorIds: [],
+    deleteIds: [],
+    sourceCalls: [],
+    formatModes: [],
+    encodeCalls: 0,
+    shouldConstructThrow: true,
+    shouldDeleteThrow: false,
+    shouldSourceFail: false,
+    shouldOperationThrow: false,
+  };
+
+  class FakeBasisEncoder {
+    readonly id: number;
+
+    constructor() {
+      const id = state.constructorIds.length + 1;
+      state.constructorIds.push(id);
+      if (state.shouldConstructThrow) throw TEST_CONSTRUCTOR_SENTINEL;
+      this.id = id;
+    }
+
+    controlThreading(_enabled: boolean, _workers: number): void {}
+
+    setSliceSourceImage(
+      _slice: number,
+      image: Uint8Array,
+      width: number,
+      height: number,
+      _imageType: number,
+    ): boolean {
+      state.sourceCalls.push({ image, width, height, hdr: false });
+      return !state.shouldSourceFail;
+    }
+
+    setSliceSourceImageHDR(
+      _slice: number,
+      image: Uint8Array,
+      width: number,
+      height: number,
+      _imageType: number,
+      _ldrSrgbToLinear: boolean,
+      _ldrToHdrNitMultiplier: number,
+    ): boolean {
+      state.sourceCalls.push({ image, width, height, hdr: true });
+      return !state.shouldSourceFail;
+    }
+
+    setFormatMode(mode: number): void {
+      state.formatModes.push(mode);
+    }
+
+    setCreateKTX2File(_enabled: boolean): void {}
+
+    setKTX2UASTCSupercompression(_enabled: boolean): void {}
+
+    setKTX2AndBasisSRGBTransferFunc(_enabled: boolean): void {}
+
+    setPerceptual(_enabled: boolean): void {}
+
+    setMipGen(_enabled: boolean): void {}
+
+    setQualityLevel(_quality: number): void {}
+
+    setETC1SCompressionLevel(_level: number): void {}
+
+    setPackUASTCFlags(_flags: number): void {}
+
+    setUASTCHDRQualityLevel(_level: number): void {}
+
+    encode(destination: Uint8Array): number {
+      state.encodeCalls++;
+      if (state.shouldOperationThrow) throw TEST_OPERATION_SENTINEL;
+      const bytes = new Uint8Array([0xa1, state.formatModes.at(-1) ?? 0, 0x42, 0x99]);
+      destination.set(bytes);
+      return bytes.length;
+    }
+
+    delete(): void {
+      state.deleteIds.push(this.id);
+      if (state.shouldDeleteThrow) throw TEST_DELETE_SENTINEL;
+    }
+  }
+
+  return {
+    state,
+    module: {
+      initializeBasis(): void {},
+      basis_tex_format: {
+        cETC1S: { value: 1 },
+        cUASTC_LDR_4x4: { value: 2 },
+        cUASTC_HDR_4x4: { value: 3 },
+      },
+      BasisEncoder: FakeBasisEncoder,
+      KTX2File: class {},
+    } as never,
+  };
+}
+
+afterEach(() => {
+  _setBasisEncoderImporter();
+});
+
+describe('basisEncode lifecycle throw containment (M120)', () => {
+  it.each(
+    MODES,
+  )('contains lifecycle throws and retries the same %s module deterministically', async (mode) => {
+    const pixels = makePixels(mode);
+    const options = makeOptions(mode);
+    const fixture = createFakeEncoderModule();
+    let importerCalls = 0;
+    _setBasisEncoderImporter(() => {
+      importerCalls++;
+      return Promise.resolve(fixture.module);
+    });
+
+    const constructorFailure = await basisEncode(pixels, options);
+    expect(constructorFailure.ok).toBe(false);
+    if (constructorFailure.ok) throw new Error('expected constructor refusal');
+    expect(constructorFailure.error.code).toBe('ktx2-encode-failed');
+    expect(constructorFailure.error.detail).toEqual({
+      mode,
+      reason: CONSTRUCTOR_FAILURE_REASON,
+    });
+    expect(JSON.stringify(constructorFailure)).not.toContain(TEST_CONSTRUCTOR_SENTINEL);
+    expect(fixture.state.deleteIds).toEqual([]);
+
+    fixture.state.shouldConstructThrow = false;
+    fixture.state.shouldDeleteThrow = true;
+    const cleanupFailure = await basisEncode(pixels, options);
+    expect(cleanupFailure.ok).toBe(false);
+    if (cleanupFailure.ok) throw new Error('expected cleanup refusal');
+    expect(cleanupFailure.error.code).toBe('ktx2-encode-failed');
+    expect(cleanupFailure.error.detail).toEqual({
+      mode,
+      reason: CLEANUP_FAILURE_REASON,
+    });
+    expect(JSON.stringify(cleanupFailure)).not.toContain(TEST_DELETE_SENTINEL);
+    expect(fixture.state.deleteIds).toEqual([2]);
+
+    fixture.state.shouldOperationThrow = true;
+    const primaryFailure = await basisEncode(pixels, options);
+    expect(primaryFailure.ok).toBe(false);
+    if (primaryFailure.ok) throw new Error('expected primary operation refusal');
+    expect(primaryFailure.error.code).toBe('ktx2-encode-failed');
+    expect(primaryFailure.error.detail).toEqual({
+      mode,
+      reason: TEST_OPERATION_SENTINEL,
+    });
+    expect(JSON.stringify(primaryFailure)).toContain(TEST_OPERATION_SENTINEL);
+    expect(JSON.stringify(primaryFailure)).not.toContain(TEST_DELETE_SENTINEL);
+    expect(fixture.state.deleteIds).toEqual([2, 3]);
+
+    fixture.state.shouldOperationThrow = false;
+    fixture.state.shouldDeleteThrow = false;
+    const repaired = await basisEncode(pixels, options);
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok) throw new Error('expected repaired encode to succeed');
+    expect([...repaired.value]).toEqual([
+      0xa1,
+      mode === 'etc1s' ? 1 : mode === 'uastc-ldr' ? 2 : 3,
+      0x42,
+      0x99,
+    ]);
+
+    const third = await basisEncode(pixels, options);
+    expect(third).toEqual(repaired);
+    expect(importerCalls).toBe(1);
+    expect(_basisEncoderInitCount()).toBe(1);
+    expect(fixture.state.constructorIds).toEqual([1, 2, 3, 4, 5]);
+    expect(fixture.state.deleteIds).toEqual([2, 3, 4, 5]);
+    expect(fixture.state.sourceCalls).toHaveLength(4);
+    expect(fixture.state.sourceCalls.every(({ image }) => image === pixels)).toBe(true);
+    expect(
+      fixture.state.sourceCalls.every(({ width, height }) => width === 2 && height === 2),
+    ).toBe(true);
+    expect(fixture.state.sourceCalls.every(({ hdr }) => hdr === (mode === 'uastc-hdr'))).toBe(true);
+    expect(fixture.state.formatModes).toEqual([
+      mode === 'etc1s' ? 1 : mode === 'uastc-ldr' ? 2 : 3,
+      mode === 'etc1s' ? 1 : mode === 'uastc-ldr' ? 2 : 3,
+      mode === 'etc1s' ? 1 : mode === 'uastc-ldr' ? 2 : 3,
+      mode === 'etc1s' ? 1 : mode === 'uastc-ldr' ? 2 : 3,
+    ]);
+    expect(fixture.state.encodeCalls).toBe(4);
+  });
+
+  it.each(MODES)('does not construct an encoder for invalid %s dimensions', async (mode) => {
+    const fixture = createFakeEncoderModule();
+    fixture.state.shouldConstructThrow = false;
+    _setBasisEncoderImporter(() => Promise.resolve(fixture.module));
+
+    const result = await basisEncode(makePixels(mode), {
+      ...makeOptions(mode),
+      width: 0,
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('expected invalid dimensions to fail');
+    expect(result.error.code).toBe('ktx2-encode-failed');
+    expect(result.error.detail).toEqual({ mode, reason: 'invalid dimensions 0x2' });
+    expect(fixture.state.constructorIds).toEqual([]);
+    expect(fixture.state.deleteIds).toEqual([]);
+  });
+});

package/src/__tests__/basis-transcoder.unit.test.ts

@@ -0,0 +1,151 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import {
+  _basisTranscoderInitCount,
+  _setBasisTranscoderImporter,
+  initBasisTranscoder,
+  transcodeKtx2,
+} from '../basis-transcoder.js';
+import { parseKtx2 } from '../ktx2.js';
+import type { BasisEncoderModule, BasisModuleFactory } from '../wasm/basis-types.js';
+
+/**
+ * basis-transcoder glue unit tests (w14).
+ *
+ * Validates:
+ *   1. Lazy-init singleton (D-10): first initBasisTranscoder() loads the WASM
+ *      module once; a second call returns the cache without re-importing.
+ *   2. transcodeKtx2() on a real UASTC KTX2 (encoder-produced) returns non-empty
+ *      per-mip block bytes for a BC7 target.
+ *   3. Module imports cleanly in node (this file runs under the node vitest
+ *      project); the same dynamic-import .mjs path is browser-legal (M5/e2e).
+ *
+ * pkg/ is a gitignored emcc build artifact (AC-12). When it is not built
+ * (contributor without emsdk) the WASM-dependent cases skip; CI builds it in the
+ * build-artifacts job so the gate runs there. The init-counting case uses an
+ * injected fake importer, so it runs regardless of pkg/ presence.
+ */
+
+const TRANSCODER_GLUE = new URL('../../pkg/basis_transcoder.mjs', import.meta.url);
+const ENCODER_GLUE = new URL('../../pkg/encode/basis_encoder.mjs', import.meta.url);
+const pkgBuilt =
+  existsSync(fileURLToPath(TRANSCODER_GLUE)) && existsSync(fileURLToPath(ENCODER_GLUE));
+
+async function loadEncoder(): Promise<BasisEncoderModule> {
+  const factory = (
+    (await import(/* @vite-ignore */ ENCODER_GLUE.href)) as {
+      default: BasisModuleFactory<BasisEncoderModule>;
+    }
+  ).default;
+  const mod = await factory({
+    locateFile: () => new URL('../../pkg/encode/basis_encoder.wasm', import.meta.url).href,
+  });
+  mod.initializeBasis();
+  return mod;
+}
+
+/** A deterministic WxH RGBA image. */
+function makeRgba(w: number, h: number): Uint8Array {
+  const img = new Uint8Array(w * h * 4);
+  for (let i = 0; i < w * h; i++) {
+    img[i * 4] = (i * 7) & 255;
+    img[i * 4 + 1] = (i * 13) & 255;
+    img[i * 4 + 2] = (i * 29) & 255;
+    img[i * 4 + 3] = 255;
+  }
+  return img;
+}
+
+/** Encode a WxH RGBA image into a UASTC KTX2 container (Basis payload). */
+async function encodeUastcKtx2(w: number, h: number): Promise<Uint8Array> {
+  const enc = await loadEncoder();
+  const encoder = new enc.BasisEncoder();
+  encoder.setSliceSourceImage(0, makeRgba(w, h), w, h, 0);
+  encoder.setCreateKTX2File(true);
+  encoder.setKTX2UASTCSupercompression(true);
+  encoder.setFormatMode(enc.basis_tex_format.cUASTC_LDR_4x4.value);
+  encoder.setPerceptual(true);
+  encoder.setMipGen(false);
+  const out = new Uint8Array(1 << 20);
+  const n = encoder.encode(out);
+  encoder.delete();
+  if (n <= 0) throw new Error('encode failed for test setup');
+  return out.slice(0, n);
+}
+
+afterEach(() => {
+  _setBasisTranscoderImporter();
+});
+
+describe('initBasisTranscoder — lazy-init singleton (D-10, w14)', () => {
+  it('importer not invoked until first init call', () => {
+    _setBasisTranscoderImporter(() => Promise.resolve({} as never));
+    expect(_basisTranscoderInitCount()).toBe(0);
+  });
+
+  it('loads exactly once and returns the cache on the second call', async () => {
+    let calls = 0;
+    const fake = { transcoder_texture_format: {}, KTX2File: null } as never;
+    _setBasisTranscoderImporter(() => {
+      calls++;
+      return Promise.resolve(fake);
+    });
+
+    const a = await initBasisTranscoder();
+    const b = await initBasisTranscoder();
+    expect(a).toBe(b);
+    expect(calls).toBe(1);
+    expect(_basisTranscoderInitCount()).toBe(1);
+  });
+
+  it('clears the cached failure so the next call retries', async () => {
+    let calls = 0;
+    _setBasisTranscoderImporter(() => {
+      calls++;
+      return Promise.reject(new Error('boom'));
+    });
+    await expect(initBasisTranscoder()).rejects.toThrow();
+    await expect(initBasisTranscoder()).rejects.toThrow();
+    expect(calls).toBe(2);
+  });
+});
+
+describe.skipIf(!pkgBuilt)('transcodeKtx2 — real UASTC -> BC7 (w14)', () => {
+  let uastcKtx2: Uint8Array;
+
+  beforeAll(async () => {
+    uastcKtx2 = await encodeUastcKtx2(16, 16);
+  });
+
+  it('transcodes every mip level into non-empty BC7 block bytes', async () => {
+    _setBasisTranscoderImporter();
+    const parsed = await parseKtx2(uastcKtx2);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) throw new Error(`parse failed: ${parsed.error.code}`);
+
+    const result = await transcodeKtx2(parsed.value, 'bc7-rgba-unorm');
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error(`transcode failed: ${result.error.code}`);
+
+    expect(result.value.format).toBe('bc7-rgba-unorm');
+    expect(result.value.width).toBe(16);
+    expect(result.value.height).toBe(16);
+    expect(result.value.mips.length).toBeGreaterThanOrEqual(1);
+    const base = result.value.mips[0];
+    expect(base).toBeDefined();
+    if (!base) throw new Error('no base mip');
+    // 16x16 BC7 = 4x4 blocks * 16 bytes = 256 bytes.
+    expect(base.data.length).toBe(256);
+    expect(base.data.byteLength).toBeGreaterThan(0);
+  });
+
+  it('the real WASM importer loads once across two transcodes', async () => {
+    _setBasisTranscoderImporter();
+    const parsed = await parseKtx2(uastcKtx2);
+    if (!parsed.ok) throw new Error('parse failed');
+    await transcodeKtx2(parsed.value, 'bc7-rgba-unorm');
+    await transcodeKtx2(parsed.value, 'bc7-rgba-unorm');
+    expect(_basisTranscoderInitCount()).toBe(1);
+  });
+});