@forgeax/engine-codec 0.1.2

package/src/__tests__/encode-pixel-limit.unit.test.ts

@@ -0,0 +1,117 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseKtx2 } from '@forgeax/engine-codec';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { BasisEncoderModule, BasisModuleFactory } from '../wasm/basis-types.js';
+
+// @perf-budget-skip: intentional large-source WASM encoder boundary gate.
+/**
+ * Encoder source-pixel ceiling gate (CI-red fix, human decision).
+ *
+ * The wasm32 Basis encoder caps total source texels at
+ * BASISU_ENCODER_MAX_SOURCE_IMAGE_PIXELS. The vendored default was 4 Mpx (higher
+ * limit 12 Mpx), below a 4096x4096 = 16.78 Mpx game texture, so encode() returned
+ * 0 bytes -> ktx2-encode-failed. build-wasm.mjs now raises both non-wasm64 limits
+ * to 16 Mpx (1024*1024*16) at build time. This test proves the raised WASM really
+ * encodes a 4096x4096 source: ETC1S encode returns a non-empty KTX2 that parseKtx2
+ * accepts.
+ *
+ * pkg/ is a gitignored emcc build artifact (AC-12); the case skips when it is not
+ * built (contributor without emsdk) and runs in the CI build-artifacts job.
+ */
+
+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));
+
+/** KTX2 BasisLZ supercompression scheme (ETC1S rides scheme=1). */
+const SCHEME_BASISLZ = 1;
+
+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 (opaque, cheap to build for large sizes). */
+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;
+}
+
+function encodeEtc1s(mod: BasisEncoderModule, img: Uint8Array, w: number, h: number): number {
+  const e = new mod.BasisEncoder();
+  try {
+    e.controlThreading(false, 0);
+    e.setSliceSourceImage(0, img, w, h, 0);
+    e.setCreateKTX2File(true);
+    e.setFormatMode(mod.basis_tex_format.cETC1S.value);
+    e.setQualityLevel(128);
+    e.setETC1SCompressionLevel(0);
+    e.setPerceptual(true);
+    e.setMipGen(false);
+    // A 4096x4096 ETC1S KTX2 stays well under 32 MiB; give it headroom.
+    const out = new Uint8Array(1 << 25);
+    const n = e.encode(out);
+    if (n <= 0) return 0;
+    return n;
+  } finally {
+    e.delete();
+  }
+}
+
+describe.skipIf(!pkgBuilt)('encoder source-pixel ceiling raised to 4096^2', () => {
+  let mod: BasisEncoderModule;
+
+  beforeAll(async () => {
+    mod = await loadEncoder();
+  });
+
+  it('encodes a 4096x4096 (16.78 Mpx) source to a non-empty ETC1S KTX2', async () => {
+    const w = 4096;
+    const h = 4096;
+    const img = makeRgba(w, h);
+    const out = new Uint8Array(1 << 25);
+    const e = new mod.BasisEncoder();
+    let n = 0;
+    try {
+      e.controlThreading(false, 0);
+      e.setSliceSourceImage(0, img, w, h, 0);
+      e.setCreateKTX2File(true);
+      e.setFormatMode(mod.basis_tex_format.cETC1S.value);
+      e.setQualityLevel(128);
+      e.setETC1SCompressionLevel(0);
+      e.setPerceptual(true);
+      e.setMipGen(false);
+      n = e.encode(out);
+    } finally {
+      e.delete();
+    }
+    // The whole point: this returns 0 with the un-patched 4/12 Mpx limit.
+    expect(n).toBeGreaterThan(0);
+    const parsed = await parseKtx2(out.slice(0, n));
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.value.header.supercompressionScheme).toBe(SCHEME_BASISLZ);
+    expect(parsed.value.header.pixelWidth).toBe(w);
+    expect(parsed.value.header.pixelHeight).toBe(h);
+  }, 120_000);
+
+  it('a small source still encodes (sanity: raised limit did not break the low path)', () => {
+    expect(encodeEtc1s(mod, makeRgba(16, 16), 16, 16)).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,239 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseKtx2, transcodeKtx2 } from '@forgeax/engine-codec';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { BasisEncoderModule, BasisModuleFactory } from '../wasm/basis-types.js';
+
+/**
+ * M3 encode round-trip + determinism gate (w15).
+ *
+ * Exercises the whole offline-encode arm end to end against the M1 encoder WASM
+ * and the M2 transcoder:
+ *
+ *   (a) AC-01 round-trip -- encode an RGB/RGBA test image into a Basis KTX2
+ *       container (ETC1S / UASTC-LDR), parse it with parseKtx2, and transcode
+ *       the levels with transcodeKtx2. parseKtx2 must NOT reject the ETC1S
+ *       payload with `ktx2-unsupported-scheme` (scheme=1 gate, M2 w13).
+ *   (b) AC-02 determinism -- the same input bytes encoded twice are byte-equal
+ *       (fixed encoder params, no timestamp / no random dither; R-11).
+ *   (c) DFD model -- ETC1S / UASTC-LDR / UASTC-HDR produce distinct DFD color
+ *       models (163 / 166 / 167) empirically verified against the pinned
+ *       encoder (D-2 / D-3).
+ *
+ * This file uses the raw M1 encoder WASM directly (like wasm-init-smoke); it
+ * does not exercise the w17 basisEncode wrapper (that is w17's own AC). It does
+ * NOT test compression ratio (M2 w9) or image quality (M6).
+ *
+ * pkg/ is a gitignored emcc build artifact (AC-12). When it is not built
+ * (contributor without emsdk) the WASM cases skip; CI builds it in the
+ * build-artifacts job so the gate runs there.
+ */
+
+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));
+
+/** DFD color models the pinned basis encoder writes per delivery encoding (D-3). */
+const DFD_MODEL_ETC1S = 163;
+const DFD_MODEL_UASTC_LDR = 166;
+const DFD_MODEL_UASTC_HDR = 167;
+
+/** KTX2 supercompression schemes (spec section 2.9). */
+const SCHEME_NONE = 0;
+const SCHEME_BASISLZ = 1;
+const SCHEME_ZSTD = 2;
+
+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;
+}
+
+/** A deterministic WxH RGBA half-float image (rgba16float bytes) for HDR encode. */
+function makeHdrF16(w: number, h: number): Uint8Array {
+  // Half-float is IEEE 754 binary16; build the pattern directly so this helper
+  // stays free of a runtime math dependency (the values are small, exactly
+  // representable magnitudes).
+  const out = new Uint16Array(w * h * 4);
+  const toF16 = (v: number): number => f32ToF16(v);
+  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);
+}
+
+/** Minimal f32 -> f16 bit encoder (round-to-nearest-even not needed for exact values). */
+function f32ToF16(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);
+}
+
+function encodeEtc1s(mod: BasisEncoderModule, img: Uint8Array, w: number, h: number): Uint8Array {
+  const e = new mod.BasisEncoder();
+  e.setSliceSourceImage(0, img, w, h, 0);
+  e.setCreateKTX2File(true);
+  e.setFormatMode(mod.basis_tex_format.cETC1S.value);
+  e.setQualityLevel(128);
+  e.setPerceptual(true);
+  e.setMipGen(false);
+  const out = new Uint8Array(1 << 20);
+  const n = e.encode(out);
+  e.delete();
+  if (n <= 0) throw new Error('ETC1S encode failed');
+  return out.slice(0, n);
+}
+
+function encodeUastcLdr(
+  mod: BasisEncoderModule,
+  img: Uint8Array,
+  w: number,
+  h: number,
+): Uint8Array {
+  const e = new mod.BasisEncoder();
+  e.setSliceSourceImage(0, img, w, h, 0);
+  e.setCreateKTX2File(true);
+  e.setKTX2UASTCSupercompression(true);
+  e.setFormatMode(mod.basis_tex_format.cUASTC_LDR_4x4.value);
+  e.setPerceptual(true);
+  e.setMipGen(false);
+  const out = new Uint8Array(1 << 20);
+  const n = e.encode(out);
+  e.delete();
+  if (n <= 0) throw new Error('UASTC-LDR encode failed');
+  return out.slice(0, n);
+}
+
+function encodeUastcHdr(
+  mod: BasisEncoderModule,
+  img: Uint8Array,
+  w: number,
+  h: number,
+): Uint8Array {
+  const e = new mod.BasisEncoder();
+  // img_type 0 = cHITRGBAHalfFloat (rgba16float source).
+  e.setSliceSourceImageHDR(0, img, w, h, 0, false, 1.0);
+  e.setCreateKTX2File(true);
+  e.setFormatMode(mod.basis_tex_format.cUASTC_HDR_4x4.value);
+  e.setMipGen(false);
+  const out = new Uint8Array(1 << 20);
+  const n = e.encode(out);
+  e.delete();
+  if (n <= 0) throw new Error('UASTC-HDR encode failed');
+  return out.slice(0, n);
+}
+
+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)('encode round-trip + determinism (M3 w15)', () => {
+  let mod: BasisEncoderModule;
+
+  beforeAll(async () => {
+    mod = await loadEncoder();
+  });
+
+  it('AC-01: ETC1S encode -> parseKtx2 (scheme=1 accepted) -> transcode round-trip', async () => {
+    const ktx2 = encodeEtc1s(mod, makeRgba(16, 16), 16, 16);
+    const parsed = await parseKtx2(ktx2);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    // scheme=1 (BasisLZ) is opened by the M2 gate; must not be rejected.
+    expect(parsed.value.header.supercompressionScheme).toBe(SCHEME_BASISLZ);
+    expect(parsed.value.dfd?.colorModel).toBe(DFD_MODEL_ETC1S);
+
+    const transcoded = await transcodeKtx2(parsed.value, 'bc7-rgba-unorm');
+    expect(transcoded.ok).toBe(true);
+    if (!transcoded.ok) return;
+    expect(transcoded.value.format).toBe('bc7-rgba-unorm');
+    expect(transcoded.value.mips.length).toBeGreaterThan(0);
+    expect(transcoded.value.mips[0]?.data.length).toBeGreaterThan(0);
+  });
+
+  it('AC-01: UASTC-LDR encode -> parseKtx2 -> transcode round-trip', async () => {
+    const ktx2 = encodeUastcLdr(mod, makeRgba(16, 16), 16, 16);
+    const parsed = await parseKtx2(ktx2);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    // UASTC-LDR with supercompression rides scheme=2 (Zstandard), also accepted.
+    expect(parsed.value.header.supercompressionScheme).toBe(SCHEME_ZSTD);
+    expect(parsed.value.dfd?.colorModel).toBe(DFD_MODEL_UASTC_LDR);
+
+    const transcoded = await transcodeKtx2(parsed.value, 'bc7-rgba-unorm');
+    expect(transcoded.ok).toBe(true);
+    if (!transcoded.ok) return;
+    expect(transcoded.value.format).toBe('bc7-rgba-unorm');
+    expect(transcoded.value.mips[0]?.data.length).toBeGreaterThan(0);
+  });
+
+  it('AC-02: double encode is byte-equal (ETC1S)', () => {
+    const img = makeRgba(16, 16);
+    const a = encodeEtc1s(mod, img, 16, 16);
+    const b = encodeEtc1s(mod, img, 16, 16);
+    expect(bytesEqual(a, b)).toBe(true);
+  });
+
+  it('AC-02: double encode is byte-equal (UASTC-LDR)', () => {
+    const img = makeRgba(16, 16);
+    const a = encodeUastcLdr(mod, img, 16, 16);
+    const b = encodeUastcLdr(mod, img, 16, 16);
+    expect(bytesEqual(a, b)).toBe(true);
+  });
+
+  it('DFD model differs per delivery encoding (163 / 166 / 167)', async () => {
+    const etc1s = await parseKtx2(encodeEtc1s(mod, makeRgba(8, 8), 8, 8));
+    const uastcLdr = await parseKtx2(encodeUastcLdr(mod, makeRgba(8, 8), 8, 8));
+    const uastcHdr = await parseKtx2(encodeUastcHdr(mod, makeHdrF16(8, 8), 8, 8));
+    expect(etc1s.ok && uastcLdr.ok && uastcHdr.ok).toBe(true);
+    if (!(etc1s.ok && uastcLdr.ok && uastcHdr.ok)) return;
+    expect(etc1s.value.dfd?.colorModel).toBe(DFD_MODEL_ETC1S);
+    expect(uastcLdr.value.dfd?.colorModel).toBe(DFD_MODEL_UASTC_LDR);
+    expect(uastcHdr.value.dfd?.colorModel).toBe(DFD_MODEL_UASTC_HDR);
+    // The three models are pairwise distinct.
+    const models = new Set([
+      etc1s.value.dfd?.colorModel,
+      uastcLdr.value.dfd?.colorModel,
+      uastcHdr.value.dfd?.colorModel,
+    ]);
+    expect(models.size).toBe(3);
+    // HDR container carries no supercompression by default.
+    expect(uastcHdr.value.header.supercompressionScheme).toBe(SCHEME_NONE);
+  });
+});

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

@@ -0,0 +1,241 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  inspectBasisSource,
+  ktx2ColorSpace,
+  parseKtx2,
+  selectTranscodeTarget,
+  type TranscodeCaps,
+} from '@forgeax/engine-codec';
+import { basisEncode } from '@forgeax/engine-codec/encode';
+import { describe, expect, it } from 'vitest';
+import type { Ktx2Parsed } from '../ktx2.js';
+import type { BasisEncoderModule, BasisFile, BasisModuleFactory } from '../wasm/basis-types.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));
+
+function parsedWithTransfer(transferFunction: number): Ktx2Parsed {
+  return {
+    header: {
+      vkFormat: 0,
+      typeSize: 1,
+      pixelWidth: 4,
+      pixelHeight: 4,
+      pixelDepth: 0,
+      layerCount: 0,
+      faceCount: 1,
+      levelCount: 1,
+      supercompressionScheme: 1,
+    },
+    index: {
+      dfdByteOffset: 0,
+      dfdByteLength: 0,
+      kvdByteOffset: 0,
+      kvdByteLength: 0,
+      sgdByteOffset: 0,
+      sgdByteLength: 0,
+    },
+    levelIndex: [{ byteOffset: 0, byteLength: 0, uncompressedByteLength: 0 }],
+    dfd: {
+      totalSize: 44,
+      vendorId: 0,
+      descriptorType: 0,
+      versionNumber: 2,
+      descriptorBlockSize: 40,
+      colorModel: 166,
+      colorPrimaries: 1,
+      transferFunction,
+      flags: 0,
+      texelBlockDimension: [3, 3, 0, 0],
+      bytesPlane: [16, 0, 0, 0, 0, 0, 0, 0],
+      samples: [],
+    },
+    kvEntries: [],
+    sgd: null,
+    rawBytes: new Uint8Array(),
+  };
+}
+
+function fakeBasisFile(): BasisFile {
+  return {
+    close: () => undefined,
+    getNumImages: () => 1,
+    getNumLevels: () => 2,
+    getImageWidth: () => 8,
+    getImageHeight: () => 4,
+    getBasisTexFormat: () => 0,
+    getHasAlpha: () => 1,
+    startTranscoding: () => 1,
+    getImageTranscodedSizeInBytes: () => 16,
+    transcodeImage: () => 1,
+  };
+}
+
+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;
+}
+
+async function realKtx2(mode: 'etc1s' | 'uastc-ldr' | 'uastc-hdr'): Promise<Uint8Array> {
+  const pixels =
+    mode === 'uastc-hdr'
+      ? new Uint8Array(4 * 4 * 8)
+      : new Uint8Array(4 * 4 * 4).map((_, index) => (index * 17) & 0xff);
+  const result = await basisEncode(pixels, {
+    mode,
+    width: 4,
+    height: 4,
+    srgb: mode !== 'uastc-hdr',
+    perceptual: mode !== 'uastc-hdr',
+    uastcSupercompression: mode === 'uastc-ldr',
+    mipGen: false,
+  });
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+async function realBasis(): Promise<Uint8Array> {
+  const mod = await loadEncoder();
+  const encoder = new mod.BasisEncoder();
+  try {
+    encoder.setSliceSourceImage(0, new Uint8Array(4 * 4 * 4).fill(127), 4, 4, 0);
+    encoder.setCreateKTX2File(false);
+    encoder.setFormatMode(mod.basis_tex_format.cUASTC_LDR_4x4.value);
+    encoder.setPerceptual(false);
+    encoder.setMipGen(false);
+    const bytes = new Uint8Array(1 << 20);
+    const length = encoder.encode(bytes);
+    if (length <= 0) throw new Error('raw Basis encode failed');
+    return bytes.slice(0, length);
+  } finally {
+    encoder.delete();
+  }
+}
+
+const capabilityCells = [
+  [{ bc: false, etc2: false, astc: false }, 'rgba'],
+  [{ bc: false, etc2: false, astc: true }, 'astc'],
+  [{ bc: true, etc2: false, astc: false }, 'bc'],
+  [{ bc: false, etc2: true, astc: false }, 'etc'],
+  [{ bc: true, etc2: true, astc: true }, 'all'],
+] as const;
+
+function expectedLdrTarget(srgb: boolean, arm: string): string {
+  const suffix = srgb ? '-srgb' : '';
+  switch (arm) {
+    case 'bc':
+    case 'all':
+      return `bc7-rgba-unorm${suffix}`;
+    case 'astc':
+      return `astc-4x4-unorm${suffix}`;
+    case 'etc':
+      return `etc2-rgba8unorm${suffix}`;
+    default:
+      return `rgba8unorm${suffix}`;
+  }
+}
+
+function expectedHdrTarget(arm: string): string {
+  return arm === 'bc' || arm === 'all' ? 'bc6h-rgb-ufloat' : 'rgba16float';
+}
+
+describe('KTX2/Basis capability matrix', () => {
+  it('projects DFD transfer functions without a duplicate source color fact', async () => {
+    expect(ktx2ColorSpace(parsedWithTransfer(1))).toBe('linear');
+    expect(ktx2ColorSpace(parsedWithTransfer(2))).toBe('srgb');
+    expect(ktx2ColorSpace(parsedWithTransfer(0))).toBeUndefined();
+  });
+
+  it('inspects raw Basis dimensions and keeps Meta color-space provenance', () => {
+    const result = inspectBasisSource(fakeBasisFile(), { colorSpace: 'srgb' }, 'etc1s');
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        colorSpace: 'srgb',
+        profile: 'etc1s',
+        width: 8,
+        height: 4,
+        levelCount: 2,
+        imageCount: 1,
+      },
+    });
+  });
+
+  it('rejects raw Basis inspection without an authored color-space fact', () => {
+    const result = inspectBasisSource(fakeBasisFile(), {}, 'uastc-ldr');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('ktx2-parse-failed');
+    expect('reason' in result.error.detail).toBe(true);
+    if ('reason' in result.error.detail)
+      expect(result.error.detail.reason).toContain('Meta.colorSpace');
+  });
+
+  it.each([
+    [{ bc: true, etc2: true, astc: true }, 'bc7-rgba-unorm-srgb'],
+    [{ bc: false, etc2: false, astc: true }, 'astc-4x4-unorm-srgb'],
+    [{ bc: false, etc2: true, astc: false }, 'etc2-rgba8unorm-srgb'],
+    [{ bc: false, etc2: false, astc: false }, 'rgba8unorm-srgb'],
+  ] as const)('selects a deterministic LDR target or explicit RGBA fallback', (caps, target) => {
+    expect(
+      selectTranscodeTarget(
+        { model: 'etc1s', srgb: true, channels: 'rgba' },
+        caps as TranscodeCaps,
+      ),
+    ).toBe(target);
+  });
+
+  it.skipIf(!pkgBuilt)('covers every real input profile across every capability cell', async () => {
+    const inputs = [
+      { id: 'ktx2-etc1s', bytes: await realKtx2('etc1s'), model: 'etc1s', srgb: true },
+      { id: 'ktx2-uastc-ldr', bytes: await realKtx2('uastc-ldr'), model: 'uastc-ldr', srgb: true },
+      { id: 'ktx2-uastc-hdr', bytes: await realKtx2('uastc-hdr'), model: 'uastc-hdr', srgb: false },
+    ] as const;
+
+    for (const input of inputs) {
+      const parsed = await parseKtx2(input.bytes);
+      expect(parsed.ok, input.id).toBe(true);
+      if (!parsed.ok) continue;
+      expect(ktx2ColorSpace(parsed.value), input.id).toBe(input.srgb ? 'srgb' : 'linear');
+      for (const [caps, arm] of capabilityCells) {
+        const target = selectTranscodeTarget(
+          { model: input.model, srgb: input.srgb, channels: 'rgba' },
+          caps,
+        );
+        expect(target, `${input.id}:${arm}`).toBe(
+          input.model === 'uastc-hdr' ? expectedHdrTarget(arm) : expectedLdrTarget(input.srgb, arm),
+        );
+      }
+    }
+
+    const raw = await realBasis();
+    const transcoder = await (await import(/* @vite-ignore */ TRANSCODER_GLUE.href)).default({
+      locateFile: () => new URL('../../pkg/basis_transcoder.wasm', import.meta.url).href,
+    });
+    transcoder.initializeBasis();
+    const file = new transcoder.BasisFile(raw);
+    try {
+      const inspected = inspectBasisSource(file, { colorSpace: 'srgb' }, 'uastc-ldr');
+      expect(inspected.ok, 'raw-basis').toBe(true);
+      for (const [caps, arm] of capabilityCells) {
+        expect(
+          selectTranscodeTarget({ model: 'uastc-ldr', srgb: true, channels: 'rgba' }, caps),
+          `raw-basis:${arm}`,
+        ).toBe(expectedLdrTarget(true, arm));
+      }
+    } finally {
+      file.close();
+    }
+  });
+});