@forgeax/engine-codec 0.1.2

package/src/__tests__/ktx2-to-texture.integration.test.ts

@@ -0,0 +1,384 @@
+import { decompressZstd, ktx2LevelsToRGBA, parseKtx2 } from '@forgeax/engine-codec';
+import { compressZstd } from '@forgeax/engine-codec/encode';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+/**
+ * KTX2 2.0 identifier magic.
+ */
+const KTX2_IDENTIFIER = new Uint8Array([
+  0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+
+function writeU32(out: Uint8Array, offset: number, value: number): void {
+  new DataView(out.buffer, out.byteOffset + offset, 4).setUint32(0, value, true);
+}
+
+function writeU64(out: Uint8Array, offset: number, value: number): void {
+  const lo = value >>> 0;
+  const hi = (value - lo) / 0x100000000;
+  new DataView(out.buffer, out.byteOffset + offset, 8).setUint32(0, lo, true);
+  new DataView(out.buffer, out.byteOffset + offset + 4, 4).setUint32(0, hi, true);
+}
+
+/**
+ * Build a scheme=0 KTX2 fixture with the given texture dimensions and pixel pattern.
+ * Returns the raw bytes.
+ */
+function buildKtx2Scheme0Bytes(
+  width: number,
+  height: number,
+  pixelFn: (x: number, y: number, px: number) => void,
+): Uint8Array {
+  const pixelBytes = width * height * 4;
+  const dfdBlockSize = 40;
+  const dfdTotalSize = 4 + dfdBlockSize;
+
+  const headerEnd = 12 + 9 * 4 + 4 * 4 + 2 * 8; // 80
+  const levelIndexEnd = headerEnd + 1 * 24; // 104
+  const dfdByteOffset = levelIndexEnd;
+  const dfdByteLength = dfdTotalSize;
+  const kvdByteOffset = dfdByteOffset + dfdByteLength;
+  const kvdByteLength = 0;
+  const levelPayloadOffset = kvdByteOffset + kvdByteLength;
+  const totalSize = levelPayloadOffset + pixelBytes;
+
+  const buf = new Uint8Array(totalSize);
+  buf.set(KTX2_IDENTIFIER, 0);
+
+  writeU32(buf, 12, 37); // VK_FORMAT_R8G8B8A8_UNORM
+  writeU32(buf, 16, 4);
+  writeU32(buf, 20, width);
+  writeU32(buf, 24, height);
+  writeU32(buf, 28, 0);
+  writeU32(buf, 32, 0);
+  writeU32(buf, 36, 1);
+  writeU32(buf, 40, 1);
+  writeU32(buf, 44, 0); // scheme=0
+
+  writeU32(buf, 48, dfdByteOffset);
+  writeU32(buf, 52, dfdByteLength);
+  writeU32(buf, 56, kvdByteOffset);
+  writeU32(buf, 60, kvdByteLength);
+  writeU64(buf, 64, 0);
+  writeU64(buf, 72, 0);
+
+  writeU64(buf, 80, levelPayloadOffset);
+  writeU64(buf, 88, pixelBytes);
+  writeU64(buf, 96, pixelBytes);
+
+  // DFD
+  writeU32(buf, dfdByteOffset, dfdTotalSize);
+  writeU32(buf, dfdByteOffset + 4, 0);
+  writeU32(buf, dfdByteOffset + 8, (40 << 16) | 2);
+  writeU32(buf, dfdByteOffset + 12, (1 << 16) | (1 << 8) | 1); // RGBSDA, BT709, LINEAR
+  writeU32(buf, dfdByteOffset + 16, 0);
+  writeU32(buf, dfdByteOffset + 20, 4);
+  writeU32(buf, dfdByteOffset + 24, 0);
+  writeU32(buf, dfdByteOffset + 28, 7 << 12);
+  writeU32(buf, dfdByteOffset + 32, 0);
+  writeU32(buf, dfdByteOffset + 36, 0);
+  writeU32(buf, dfdByteOffset + 40, 0xffffffff);
+
+  // Pixels
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const px = levelPayloadOffset + (y * width + x) * 4;
+      pixelFn(x, y, px);
+      // Apply to buffer
+      // pixelFn sets buf[px..px+3]
+    }
+  }
+
+  // Apply pixel function after buffer creation
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const px = levelPayloadOffset + (y * width + x) * 4;
+      pixelFn(x, y, px);
+    }
+  }
+
+  return buf;
+}
+
+describe('KTX2→TextureAsset loading + AC-04 structural check (w24)', () => {
+  // Build scheme=0 fixture for 64x64
+  const W = 64;
+  const H = 64;
+  const pixelBytes = W * H * 4;
+  let scheme0Bytes: Uint8Array;
+  let expectedRaw: Uint8Array;
+  let scheme2Bytes: Uint8Array;
+
+  beforeAll(async () => {
+    // Build scheme=0
+    const buf0 = buildKtx2Scheme0Bytes(W, H, (_x: number, _y: number, _px: number) => {
+      // filled by loop below
+    });
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const pxOffset = 148 + (y * W + x) * 4;
+        buf0[pxOffset] = (x * 3 + y * 7) & 0xff;
+        buf0[pxOffset + 1] = (x * 5 + y * 11) & 0xff;
+        buf0[pxOffset + 2] = (x * 13 + y * 17) & 0xff;
+        buf0[pxOffset + 3] = 255;
+      }
+    }
+    scheme0Bytes = buf0;
+
+    expectedRaw = new Uint8Array(pixelBytes);
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const px = (y * W + x) * 4;
+        expectedRaw[px] = (x * 3 + y * 7) & 0xff;
+        expectedRaw[px + 1] = (x * 5 + y * 11) & 0xff;
+        expectedRaw[px + 2] = (x * 13 + y * 17) & 0xff;
+        expectedRaw[px + 3] = 255;
+      }
+    }
+
+    // Build scheme=2: compress expectedRaw with zstd
+    const compResult = await compressZstd(expectedRaw);
+    if (!compResult.ok) throw new Error('compress failed');
+
+    const compressedPayload = compResult.value;
+    const scheme2TotalSize = 148 + compressedPayload.length;
+    const buf2 = new Uint8Array(scheme2TotalSize);
+    buf2.set(KTX2_IDENTIFIER, 0);
+
+    writeU32(buf2, 12, 37);
+    writeU32(buf2, 16, 4);
+    writeU32(buf2, 20, W);
+    writeU32(buf2, 24, H);
+    writeU32(buf2, 28, 0);
+    writeU32(buf2, 32, 0);
+    writeU32(buf2, 36, 1);
+    writeU32(buf2, 40, 1);
+    writeU32(buf2, 44, 2); // scheme=2
+
+    const dfdBlockSize = 40;
+    const dfdTotalSize = 4 + dfdBlockSize;
+    writeU32(buf2, 48, 104);
+    writeU32(buf2, 52, dfdTotalSize);
+    writeU32(buf2, 56, 148);
+    writeU32(buf2, 60, 0);
+    writeU64(buf2, 64, 0);
+    writeU64(buf2, 72, 0);
+
+    writeU64(buf2, 80, 148);
+    writeU64(buf2, 88, compressedPayload.length);
+    writeU64(buf2, 96, pixelBytes);
+
+    writeU32(buf2, 104, dfdTotalSize);
+    writeU32(buf2, 108, 0);
+    writeU32(buf2, 112, (40 << 16) | 2);
+    writeU32(buf2, 116, (1 << 16) | (1 << 8) | 1);
+    writeU32(buf2, 120, 0);
+    writeU32(buf2, 124, 4);
+    writeU32(buf2, 128, 0);
+    writeU32(buf2, 132, 7 << 12);
+    writeU32(buf2, 136, 0);
+    writeU32(buf2, 140, 0);
+    writeU32(buf2, 144, 0xffffffff);
+
+    buf2.set(compressedPayload, 148);
+    scheme2Bytes = buf2;
+  });
+
+  describe('ktx2LevelsToRGBA', () => {
+    it('returns full RGBA byte array for scheme=0, level=0', async () => {
+      const parsed = await parseKtx2(scheme0Bytes);
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) throw new Error('parse failed');
+
+      const rgba = await ktx2LevelsToRGBA(parsed.value, 0);
+      expect(rgba.ok).toBe(true);
+      if (!rgba.ok) throw new Error('levelsToRGBA failed');
+
+      expect(rgba.value.length).toBe(pixelBytes);
+      // Verify all bytes match
+      for (let i = 0; i < pixelBytes; i++) {
+        // biome-ignore lint/style/noNonNullAssertion: index within bounds verified by length check above
+        expect(rgba.value[i]).toBe(expectedRaw[i]!);
+      }
+    });
+
+    it('returns decompressed RGBA for scheme=2, level=0', async () => {
+      const parsed = await parseKtx2(scheme2Bytes);
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) throw new Error('parse failed');
+
+      const rgba = await ktx2LevelsToRGBA(parsed.value, 0);
+      expect(rgba.ok).toBe(true);
+      if (!rgba.ok) throw new Error('levelsToRGBA failed');
+
+      expect(rgba.value.length).toBe(pixelBytes);
+      for (let i = 0; i < pixelBytes; i++) {
+        // biome-ignore lint/style/noNonNullAssertion: index within bounds verified by length check above
+        expect(rgba.value[i]).toBe(expectedRaw[i]!);
+      }
+    });
+
+    it('scheme=0 and scheme=2 produce byte-identical output', async () => {
+      const p0 = await parseKtx2(scheme0Bytes);
+      expect(p0.ok).toBe(true);
+      const p2 = await parseKtx2(scheme2Bytes);
+      expect(p2.ok).toBe(true);
+
+      if (!p0.ok || !p2.ok) throw new Error('parse failed');
+
+      const r0 = await ktx2LevelsToRGBA(p0.value, 0);
+      const r2 = await ktx2LevelsToRGBA(p2.value, 0);
+      expect(r0.ok).toBe(true);
+      expect(r2.ok).toBe(true);
+      if (!r0.ok || !r2.ok) throw new Error('levelsToRGBA failed');
+
+      expect(r0.value.length).toBe(r2.value.length);
+      for (let i = 0; i < r0.value.length; i++) {
+        // biome-ignore lint/style/noNonNullAssertion: index within bounds verified by length check above
+        expect(r0.value[i]).toBe(r2.value[i]!);
+      }
+    });
+  });
+
+  describe('textureLoader KTX2 dispatch simulation', () => {
+    /**
+     * Simulates the textureLoader KTX2 dispatch branch:
+     * 1. Check first 12 bytes against KTX2 magic
+     * 2. Call parseKtx2
+     * 3. Call ktx2LevelsToRGBA to get RGBA bytes
+     * 4. Assemble a TextureAsset POD (no KTX2-specific fields)
+     */
+    function isKtx2(bytes: Uint8Array): boolean {
+      if (bytes.length < 12) return false;
+      for (let i = 0; i < 12; i++) {
+        const b = KTX2_IDENTIFIER[i];
+        if (b === undefined || bytes[i] !== b) return false;
+      }
+      return true;
+    }
+
+    interface TextureAsset {
+      kind: 'texture';
+      width: number;
+      height: number;
+      format: string;
+      data: Uint8Array;
+      mipLevelCount: number;
+    }
+
+    it('detects KTX2 magic and produces TextureAsset from scheme=0 bytes', async () => {
+      expect(isKtx2(scheme0Bytes)).toBe(true);
+
+      const parsed = await parseKtx2(scheme0Bytes);
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) throw new Error('parse failed');
+
+      const rgba = await ktx2LevelsToRGBA(parsed.value, 0);
+      expect(rgba.ok).toBe(true);
+      if (!rgba.ok) throw new Error('levelsToRGBA failed');
+
+      const tex: TextureAsset = {
+        kind: 'texture',
+        width: parsed.value.header.pixelWidth,
+        height: parsed.value.header.pixelHeight,
+        format: 'rgba8unorm',
+        data: rgba.value,
+        mipLevelCount: parsed.value.header.levelCount,
+      };
+
+      expect(tex.kind).toBe('texture');
+      expect(tex.width).toBe(W);
+      expect(tex.height).toBe(H);
+      expect(tex.format).toBe('rgba8unorm');
+      expect(tex.data.length).toBe(pixelBytes);
+      expect(tex.mipLevelCount).toBe(1);
+    });
+
+    it('produces TextureAsset with zero KTX2-specific fields', async () => {
+      const parsed = await parseKtx2(scheme0Bytes);
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) throw new Error('parse failed');
+
+      const rgba = await ktx2LevelsToRGBA(parsed.value, 0);
+      expect(rgba.ok).toBe(true);
+      if (!rgba.ok) throw new Error('levelsToRGBA failed');
+
+      const tex: TextureAsset = {
+        kind: 'texture',
+        width: parsed.value.header.pixelWidth,
+        height: parsed.value.header.pixelHeight,
+        format: 'rgba8unorm',
+        data: rgba.value,
+        mipLevelCount: parsed.value.header.levelCount,
+      };
+
+      // Verify no KTX2-specific fields exist on the POD
+      const keys = Object.keys(tex).sort();
+      expect(keys).toEqual(['data', 'format', 'height', 'kind', 'mipLevelCount', 'width']);
+      // No 'ktx2', 'supercompression', 'dfd', etc.
+      expect(keys).not.toContain('ktx2');
+      expect(keys).not.toContain('supercompression');
+    });
+
+    it('KTX2 detection rejects non-KTX2 bytes (backward compat path)', async () => {
+      const pngLike = new Uint8Array(20);
+      pngLike[0] = 0x89;
+      pngLike[1] = 0x50; // "PNG" like
+      expect(isKtx2(pngLike)).toBe(false);
+    });
+
+    it('KTX2 detection rejects bytes shorter than 12', async () => {
+      const short = new Uint8Array(11);
+      expect(isKtx2(short)).toBe(false);
+    });
+  });
+
+  describe('AC-04 structural: single zstd decode implementation', () => {
+    it('decompressZstd import references same function used by both asset-layer and KTX2', () => {
+      // AC-04: ktx2.ts imports decompressZstd from codec's zstd.ts.
+      // Both asset-layer (fetchBinary gate) and KTX2 (ktx2LevelsToRGBA)
+      // use the SAME function. This is verified by code-level import:
+      // - ktx2.ts imports from `./zstd.js`
+      // - asset-registry.ts imports via codec package main entry
+      //
+      // Since we can't runtime-inspect import sources easily in vitest,
+      // this test verifies the function exists and is callable (both paths
+      // work). The structural check (single source) is enforced by:
+      // 1. `grep 'decompressZstd' packages/codec/src/ktx2.ts` shows import
+      //    from `./zstd.js` (same module as asset-layer)
+      // 2. Codec main entry re-exports from zstd.ts (single export source)
+      expect(typeof decompressZstd).toBe('function');
+    });
+
+    it('decompressZstd successfully round-trips through KTX2 path', async () => {
+      // Prove that the codec's decompressZstd (which KTX2 uses internally)
+      // works — this implicitly verifies AC-04 because ktx2LevelsToRGBA
+      // calls the same decompressZstd used by the asset layer.
+      const parsed = await parseKtx2(scheme2Bytes);
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) throw new Error('parse failed');
+
+      const rgba = await ktx2LevelsToRGBA(parsed.value, 0);
+      expect(rgba.ok).toBe(true);
+      if (!rgba.ok) throw new Error('levelsToRGBA failed');
+
+      // Now independently decompress the level payload
+      const l0 = parsed.value.levelIndex[0];
+      if (!l0) throw new Error('levelIndex[0] missing');
+      const compressedPayload = scheme2Bytes.slice(
+        Number(l0.byteOffset),
+        Number(l0.byteOffset) + Number(l0.byteLength),
+      );
+      const directDecomp = await decompressZstd(compressedPayload);
+      expect(directDecomp.ok).toBe(true);
+      if (!directDecomp.ok) throw new Error('decompress failed');
+
+      // Both paths should produce identical output
+      expect(directDecomp.value.length).toBe(rgba.value.length);
+      for (let i = 0; i < directDecomp.value.length; i++) {
+        // biome-ignore lint/style/noNonNullAssertion: index within bounds verified by length check above
+        expect(directDecomp.value[i]).toBe(rgba.value[i]!);
+      }
+    });
+  });
+});

package/src/__tests__/runtime-validation.unit.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { KTX2_IDENTIFIER, parseKtx2 } from '../index';
+
+describe('codec runtime validation owner', () => {
+  it('rejects a non-KTX2 artifact with the codec-owned error', async () => {
+    const result = await parseKtx2(new Uint8Array([0, 1, 2, 3]));
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('ktx2-parse-failed');
+    expect(result.error.expected).toContain('valid compressed data');
+  });
+
+  it('keeps the KTX2 signature as the codec validation boundary', () => {
+    expect(KTX2_IDENTIFIER).toEqual(
+      new Uint8Array([0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a]),
+    );
+  });
+});

package/src/__tests__/transcode-select-target.unit.test.ts

@@ -0,0 +1,167 @@
+import {
+  selectTranscodeTarget,
+  type TranscodeCaps,
+  type TranscodeSource,
+} from '@forgeax/engine-codec';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * selectTranscodeTarget priority-chain unit tests (w8).
+ *
+ * AC-04 application point: node imports the pure function directly and asserts
+ * the returned GPUTextureFormat for each caps combination. No DOM / node:path
+ * dependency is imported here -- that absence is the necessary evidence that the
+ * function is browser+node dual-safe (the isolation gate proves the source side).
+ *
+ * The priority chains (plan-strategy §2 D-4 + requirements §range table):
+ *   RGBA : ASTC-4x4 -> BC7 -> ETC2 -> RGBA8   (D-4: bc present => BC7 first)
+ *   RG   : BC5 -> EAC-RG11 -> RG8             (D-4: bc present => BC5 first)
+ *   R    : BC4 -> EAC-R11 -> R8               (D-4: bc present => BC4 first)
+ *   HDR  : BC6H -> rgba16float
+ *
+ * srgb/linear only varies the RGBA color arm (data channels R/RG and HDR carry
+ * no sRGB variant in WebGPU). The srgb flag is derived upstream from the DFD
+ * transfer function; this function receives it as an explicit boolean.
+ */
+
+const BC_ONLY: TranscodeCaps = { bc: true, etc2: false, astc: false };
+const ETC2_ONLY: TranscodeCaps = { bc: false, etc2: true, astc: false };
+const ASTC_ONLY: TranscodeCaps = { bc: false, etc2: false, astc: true };
+const NO_CAP: TranscodeCaps = { bc: false, etc2: false, astc: false };
+const BC_AND_ETC2: TranscodeCaps = { bc: true, etc2: true, astc: false };
+const BC_AND_ASTC: TranscodeCaps = { bc: true, etc2: false, astc: true };
+const ASTC_AND_ETC2: TranscodeCaps = { bc: false, etc2: true, astc: true };
+
+function ldrRgba(srgb: boolean): TranscodeSource {
+  return { model: 'uastc-ldr', srgb, channels: 'rgba' };
+}
+
+describe('selectTranscodeTarget — LDR RGBA arm (w8)', () => {
+  it('bc-only + srgb => bc7-rgba-unorm-srgb', () => {
+    expect(selectTranscodeTarget(ldrRgba(true), BC_ONLY)).toBe('bc7-rgba-unorm-srgb');
+  });
+
+  it('bc-only + linear => bc7-rgba-unorm', () => {
+    expect(selectTranscodeTarget(ldrRgba(false), BC_ONLY)).toBe('bc7-rgba-unorm');
+  });
+
+  it('etc2-only + srgb => etc2-rgba8unorm-srgb', () => {
+    expect(selectTranscodeTarget(ldrRgba(true), ETC2_ONLY)).toBe('etc2-rgba8unorm-srgb');
+  });
+
+  it('etc2-only + linear => etc2-rgba8unorm', () => {
+    expect(selectTranscodeTarget(ldrRgba(false), ETC2_ONLY)).toBe('etc2-rgba8unorm');
+  });
+
+  it('astc-only + srgb => astc-4x4-unorm-srgb', () => {
+    expect(selectTranscodeTarget(ldrRgba(true), ASTC_ONLY)).toBe('astc-4x4-unorm-srgb');
+  });
+
+  it('astc-only + linear => astc-4x4-unorm', () => {
+    expect(selectTranscodeTarget(ldrRgba(false), ASTC_ONLY)).toBe('astc-4x4-unorm');
+  });
+
+  it('no cap + srgb => rgba8unorm-srgb (fallback is a format, not an error)', () => {
+    expect(selectTranscodeTarget(ldrRgba(true), NO_CAP)).toBe('rgba8unorm-srgb');
+  });
+
+  it('no cap + linear => rgba8unorm', () => {
+    expect(selectTranscodeTarget(ldrRgba(false), NO_CAP)).toBe('rgba8unorm');
+  });
+});
+
+describe('selectTranscodeTarget — D-4 Mesa guard: BC present => prefer BC (w8)', () => {
+  it('bc+etc2 (Mesa software-decode trap) => bc7, NOT etc2', () => {
+    const target = selectTranscodeTarget(ldrRgba(true), BC_AND_ETC2);
+    expect(target).toBe('bc7-rgba-unorm-srgb');
+    expect(target).not.toBe('etc2-rgba8unorm-srgb');
+  });
+
+  it('bc+astc (Apple Silicon dual hardware) => bc7, NOT astc', () => {
+    const target = selectTranscodeTarget(ldrRgba(false), BC_AND_ASTC);
+    expect(target).toBe('bc7-rgba-unorm');
+    expect(target).not.toBe('astc-4x4-unorm');
+  });
+
+  it('astc+etc2 (no bc) follows table order ASTC before ETC2', () => {
+    expect(selectTranscodeTarget(ldrRgba(true), ASTC_AND_ETC2)).toBe('astc-4x4-unorm-srgb');
+  });
+});
+
+describe('selectTranscodeTarget — single/dual-channel arms (w8)', () => {
+  const rg = (srgb: boolean): TranscodeSource => ({ model: 'uastc-ldr', srgb, channels: 'rg' });
+  const r = (srgb: boolean): TranscodeSource => ({ model: 'uastc-ldr', srgb, channels: 'r' });
+
+  it('RG bc-only => bc5-rg-unorm (no srgb variant even when srgb=true)', () => {
+    expect(selectTranscodeTarget(rg(true), BC_ONLY)).toBe('bc5-rg-unorm');
+    expect(selectTranscodeTarget(rg(false), BC_ONLY)).toBe('bc5-rg-unorm');
+  });
+
+  it('RG etc2-only => eac-rg11unorm', () => {
+    expect(selectTranscodeTarget(rg(false), ETC2_ONLY)).toBe('eac-rg11unorm');
+  });
+
+  it('RG astc-only => rg8unorm (ASTC not in the RG chain)', () => {
+    expect(selectTranscodeTarget(rg(false), ASTC_ONLY)).toBe('rg8unorm');
+  });
+
+  it('RG no cap => rg8unorm', () => {
+    expect(selectTranscodeTarget(rg(false), NO_CAP)).toBe('rg8unorm');
+  });
+
+  it('RG bc+etc2 => bc5-rg-unorm (D-4 BC first)', () => {
+    expect(selectTranscodeTarget(rg(false), BC_AND_ETC2)).toBe('bc5-rg-unorm');
+  });
+
+  it('R bc-only => bc4-r-unorm', () => {
+    expect(selectTranscodeTarget(r(false), BC_ONLY)).toBe('bc4-r-unorm');
+  });
+
+  it('R etc2-only => eac-r11unorm', () => {
+    expect(selectTranscodeTarget(r(false), ETC2_ONLY)).toBe('eac-r11unorm');
+  });
+
+  it('R astc-only => r8unorm (ASTC not in the R chain)', () => {
+    expect(selectTranscodeTarget(r(false), ASTC_ONLY)).toBe('r8unorm');
+  });
+
+  it('R no cap => r8unorm', () => {
+    expect(selectTranscodeTarget(r(false), NO_CAP)).toBe('r8unorm');
+  });
+
+  it('R bc+etc2 => bc4-r-unorm (D-4 BC first)', () => {
+    expect(selectTranscodeTarget(r(false), BC_AND_ETC2)).toBe('bc4-r-unorm');
+  });
+});
+
+describe('selectTranscodeTarget — HDR arm (w8)', () => {
+  const hdr: TranscodeSource = { model: 'uastc-hdr', srgb: false, channels: 'rgba' };
+
+  it('HDR bc-only => bc6h-rgb-ufloat', () => {
+    expect(selectTranscodeTarget(hdr, BC_ONLY)).toBe('bc6h-rgb-ufloat');
+  });
+
+  it('HDR bc+etc2 => bc6h-rgb-ufloat (D-4 BC first)', () => {
+    expect(selectTranscodeTarget(hdr, BC_AND_ETC2)).toBe('bc6h-rgb-ufloat');
+  });
+
+  it('HDR etc2-only => rgba16float (no bc; ASTC-HDR is OOS)', () => {
+    expect(selectTranscodeTarget(hdr, ETC2_ONLY)).toBe('rgba16float');
+  });
+
+  it('HDR astc-only => rgba16float (no bc)', () => {
+    expect(selectTranscodeTarget(hdr, ASTC_ONLY)).toBe('rgba16float');
+  });
+
+  it('HDR no cap => rgba16float', () => {
+    expect(selectTranscodeTarget(hdr, NO_CAP)).toBe('rgba16float');
+  });
+});
+
+describe('selectTranscodeTarget — ETC1S and UASTC-LDR share the LDR chain (w8)', () => {
+  it('etc1s model routes through the same LDR RGBA arm as uastc-ldr', () => {
+    const etc1s: TranscodeSource = { model: 'etc1s', srgb: true, channels: 'rgba' };
+    expect(selectTranscodeTarget(etc1s, BC_ONLY)).toBe('bc7-rgba-unorm-srgb');
+    expect(selectTranscodeTarget(etc1s, NO_CAP)).toBe('rgba8unorm-srgb');
+  });
+});

package/src/__tests__/wasm-init-smoke.test.ts

@@ -0,0 +1,102 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import type {
+  BasisEncoderModule,
+  BasisModuleFactory,
+  BasisTranscoderModule,
+} from '../wasm/basis-types.js';
+
+/**
+ * M1 closing red-green gate: the two self-built basis WASM modules (transcoder +
+ * encoder) init in node, and the encoder produces a KTX2 container whose first
+ * bytes are the KTX2 identifier magic. This validates the whole M1 WASM
+ * self-build base end to end without touching M2/M3 code.
+ *
+ * pkg/ is a gitignored emcc build artifact (zero-binary, AC-12). When it has
+ * not been built (contributor without emsdk), skip rather than false-fail --
+ * CI builds it in the build-artifacts job (w6) so the gate runs there.
+ */
+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));
+
+/** KTX2 2.0 identifier: «KTX 20»\r\n\x1A\n (spec section 1). */
+const KTX2_IDENTIFIER = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];
+
+async function loadTranscoder(): Promise<BasisTranscoderModule> {
+  const factory = (
+    (await import(/* @vite-ignore */ TRANSCODER_GLUE.href)) as {
+      default: BasisModuleFactory<BasisTranscoderModule>;
+    }
+  ).default;
+  const mod = await factory({
+    locateFile: () => new URL('../../pkg/basis_transcoder.wasm', import.meta.url).href,
+  });
+  mod.initializeBasis();
+  return mod;
+}
+
+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 8x8 RGBA test image. */
+function makeRgba8x8(): Uint8Array {
+  const w = 8;
+  const h = 8;
+  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;
+}
+
+describe.skipIf(!pkgBuilt)('basis WASM init smoke (M1)', () => {
+  it('transcoder module inits with KTX2File + format enum', async () => {
+    const tc = await loadTranscoder();
+    expect(tc).not.toBeNull();
+    expect(typeof tc.KTX2File).toBe('function');
+    expect(typeof tc.transcoder_texture_format.cTFBC7_RGBA.value).toBe('number');
+  });
+
+  it('encoder module inits with BasisEncoder + format enum', async () => {
+    const enc = await loadEncoder();
+    expect(enc).not.toBeNull();
+    expect(typeof enc.BasisEncoder).toBe('function');
+    expect(typeof enc.basis_tex_format.cUASTC_LDR_4x4.value).toBe('number');
+  });
+
+  it('encoder produces a KTX2 container with the identifier magic', async () => {
+    const enc = await loadEncoder();
+    const encoder = new enc.BasisEncoder();
+    const img = makeRgba8x8();
+    encoder.setSliceSourceImage(0, img, 8, 8, 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();
+
+    expect(n).toBeGreaterThan(KTX2_IDENTIFIER.length);
+    const head = Array.from(out.slice(0, KTX2_IDENTIFIER.length));
+    expect(head).toEqual(KTX2_IDENTIFIER);
+  });
+});