@forgeax/engine-codec 0.1.2

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

@@ -0,0 +1,502 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import {
+  _basisTranscoderInitCount,
+  _setBasisTranscoderImporter,
+  initBasisTranscoder,
+  transcodeBasis,
+  transcodeKtx2,
+} from '../basis-transcoder.js';
+import type { Ktx2Parsed } from '../ktx2.js';
+import { parseKtx2 } from '../ktx2.js';
+import type {
+  BasisEncoderModule,
+  BasisModuleFactory,
+  BasisTranscoderModule,
+} 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);
+  });
+});
+
+const TEST_TARGET = 'bc7-rgba-unorm' as const;
+const TEST_SENTINEL = 'm112-controlled-wasm-throw';
+const TEST_CLOSE_SENTINEL = 'm119-controlled-close-throw';
+const TEST_FORMAT = { cTFBC7_RGBA: { value: 7 } };
+
+function fakeParsed(rawBytes: Uint8Array): Ktx2Parsed {
+  return { rawBytes, dfd: { colorModel: 166 } } as unknown as Ktx2Parsed;
+}
+
+function createKtx2OperationModule() {
+  let shouldThrow = true;
+  let shouldCloseThrow = false;
+  const state = {
+    closeCount: 0,
+    inputBytes: [] as Uint8Array[],
+    targetEnums: [] as number[],
+    transcodeLevels: [] as number[],
+  };
+
+  class FakeKtx2File {
+    constructor(bytes: Uint8Array) {
+      state.inputBytes.push(bytes);
+    }
+
+    close(): void {
+      state.closeCount++;
+      if (shouldCloseThrow) throw TEST_CLOSE_SENTINEL;
+    }
+
+    isValid(): boolean {
+      return true;
+    }
+
+    startTranscoding(): number {
+      return 1;
+    }
+
+    getLevels(): number {
+      return 2;
+    }
+
+    getImageLevelInfo(
+      level: number,
+      _layer: number,
+      _face: number,
+    ): { origWidth: number; origHeight: number } {
+      return level === 0 ? { origWidth: 8, origHeight: 4 } : { origWidth: 4, origHeight: 2 };
+    }
+
+    getImageTranscodedSizeInBytes(
+      level: number,
+      _layer: number,
+      _face: number,
+      format: number,
+    ): number {
+      state.targetEnums.push(format);
+      return level === 0 ? 16 : 4;
+    }
+
+    transcodeImage(
+      dst: Uint8Array,
+      level: number,
+      _layer: number,
+      _face: number,
+      _format: number,
+      _getAlphaForOpaqueFormats: number,
+      _channel0: number,
+      _channel1: number,
+    ): number {
+      state.transcodeLevels.push(level);
+      if (shouldThrow && level === 1) throw TEST_SENTINEL;
+      dst.fill(level + 1);
+      return 1;
+    }
+
+    getWidth(): number {
+      return 8;
+    }
+
+    getHeight(): number {
+      return 4;
+    }
+  }
+
+  const module = {
+    transcoder_texture_format: TEST_FORMAT,
+    KTX2File: FakeKtx2File,
+  } as unknown as BasisTranscoderModule;
+  return {
+    module,
+    state,
+    repair(): void {
+      shouldThrow = false;
+    },
+    refuseClose(): void {
+      shouldCloseThrow = true;
+    },
+    repairClose(): void {
+      shouldCloseThrow = false;
+    },
+  };
+}
+
+function createBasisOperationModule() {
+  let shouldThrow = true;
+  let shouldCloseThrow = false;
+  const state = {
+    closeCount: 0,
+    inputBytes: [] as Uint8Array[],
+    targetEnums: [] as number[],
+    transcodeLevels: [] as number[],
+  };
+
+  class FakeBasisFile {
+    constructor(bytes: Uint8Array) {
+      state.inputBytes.push(bytes);
+    }
+
+    close(): void {
+      state.closeCount++;
+      if (shouldCloseThrow) throw TEST_CLOSE_SENTINEL;
+    }
+
+    getNumImages(): number {
+      return 1;
+    }
+
+    getNumLevels(_imageIndex: number): number {
+      return 2;
+    }
+
+    getImageWidth(_imageIndex: number, level: number): number {
+      return level === 0 ? 8 : 4;
+    }
+
+    getImageHeight(_imageIndex: number, level: number): number {
+      return level === 0 ? 4 : 2;
+    }
+
+    startTranscoding(): number {
+      return 1;
+    }
+
+    getImageTranscodedSizeInBytes(_imageIndex: number, level: number, format: number): number {
+      state.targetEnums.push(format);
+      return level === 0 ? 16 : 4;
+    }
+
+    transcodeImage(
+      dst: Uint8Array,
+      _imageIndex: number,
+      level: number,
+      _format: number,
+      _decodeFlags: number,
+    ): number {
+      state.transcodeLevels.push(level);
+      if (shouldThrow && level === 1) throw TEST_SENTINEL;
+      dst.fill(level + 1);
+      return 1;
+    }
+  }
+
+  const module = {
+    transcoder_texture_format: TEST_FORMAT,
+    KTX2File: class {},
+    BasisFile: FakeBasisFile,
+  } as unknown as BasisTranscoderModule;
+  return {
+    module,
+    state,
+    repair(): void {
+      shouldThrow = false;
+    },
+    refuseClose(): void {
+      shouldCloseThrow = true;
+    },
+    repairClose(): void {
+      shouldCloseThrow = false;
+    },
+  };
+}
+
+function createConstructorThrowingModule(): BasisTranscoderModule {
+  class ThrowingKtx2File {
+    constructor(_bytes: Uint8Array) {
+      throw TEST_SENTINEL;
+    }
+  }
+
+  class ThrowingBasisFile {
+    constructor(_bytes: Uint8Array) {
+      throw TEST_SENTINEL;
+    }
+  }
+
+  return {
+    transcoder_texture_format: TEST_FORMAT,
+    KTX2File: ThrowingKtx2File,
+    BasisFile: ThrowingBasisFile,
+  } as unknown as BasisTranscoderModule;
+}
+
+describe('transcode throw containment and same-module retry (M112)', () => {
+  it('contains KTX2 operation throws, closes once, and retries the same input/module deterministically', async () => {
+    const rawBytes = new Uint8Array([1, 2, 3]);
+    const parsed = fakeParsed(rawBytes);
+    const fixture = createKtx2OperationModule();
+    let importerCalls = 0;
+    _setBasisTranscoderImporter(() => {
+      importerCalls++;
+      return Promise.resolve(fixture.module);
+    });
+
+    fixture.refuseClose();
+    const failed = await transcodeKtx2(parsed, TEST_TARGET);
+    expect(failed.ok).toBe(false);
+    if (failed.ok) throw new Error('expected operation throw to return a CodecError');
+    expect(failed.error.code).toBe('transcode-failed');
+    expect(failed.error.detail).toEqual({
+      sourceFormat: 'dfd-model-166',
+      targetFormat: TEST_TARGET,
+    });
+    expect(JSON.stringify(failed)).not.toContain(TEST_SENTINEL);
+    expect(JSON.stringify(failed)).not.toContain(TEST_CLOSE_SENTINEL);
+    expect(fixture.state.closeCount).toBe(1);
+    expect(fixture.state.transcodeLevels).toEqual([0, 1]);
+
+    fixture.repair();
+    const cleanupFailed = await transcodeKtx2(parsed, TEST_TARGET);
+    expect(cleanupFailed.ok).toBe(false);
+    if (cleanupFailed.ok) throw new Error('expected close throw to return a CodecError');
+    expect(cleanupFailed.error.code).toBe('transcode-failed');
+    expect(cleanupFailed.error.detail).toEqual({
+      sourceFormat: 'dfd-model-166',
+      targetFormat: TEST_TARGET,
+    });
+    expect(JSON.stringify(cleanupFailed)).not.toContain(TEST_CLOSE_SENTINEL);
+    expect(fixture.state.closeCount).toBe(2);
+
+    fixture.repairClose();
+    const repaired = await transcodeKtx2(parsed, TEST_TARGET);
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok) throw new Error('expected repaired KTX2 transcode to succeed');
+    expect(repaired.value.format).toBe(TEST_TARGET);
+    expect(repaired.value.width).toBe(8);
+    expect(repaired.value.height).toBe(4);
+    expect(
+      repaired.value.mips.map(({ level, width, height, data }) => ({
+        level,
+        width,
+        height,
+        data: [...data],
+      })),
+    ).toEqual([
+      { level: 0, width: 8, height: 4, data: new Array(16).fill(1) },
+      { level: 1, width: 4, height: 2, data: new Array(4).fill(2) },
+    ]);
+
+    const third = await transcodeKtx2(parsed, TEST_TARGET);
+    expect(third).toEqual(repaired);
+    expect(importerCalls).toBe(1);
+    expect(_basisTranscoderInitCount()).toBe(1);
+    expect(fixture.state.inputBytes).toHaveLength(4);
+    expect(fixture.state.inputBytes.every((bytes) => bytes === rawBytes)).toBe(true);
+    expect(fixture.state.targetEnums).toEqual([7, 7, 7, 7, 7, 7, 7, 7]);
+    expect(fixture.state.closeCount).toBe(4);
+  });
+
+  it('contains raw Basis operation throws and retries the same bytes/module deterministically', async () => {
+    const rawBytes = new Uint8Array([4, 5, 6]);
+    const fixture = createBasisOperationModule();
+    let importerCalls = 0;
+    _setBasisTranscoderImporter(() => {
+      importerCalls++;
+      return Promise.resolve(fixture.module);
+    });
+
+    fixture.refuseClose();
+    const failed = await transcodeBasis(rawBytes, TEST_TARGET);
+    expect(failed.ok).toBe(false);
+    if (failed.ok) throw new Error('expected raw Basis operation throw to return a CodecError');
+    expect(failed.error.code).toBe('transcode-failed');
+    expect(failed.error.detail).toEqual({ sourceFormat: 'raw-basis', targetFormat: TEST_TARGET });
+    expect(JSON.stringify(failed)).not.toContain(TEST_SENTINEL);
+    expect(JSON.stringify(failed)).not.toContain(TEST_CLOSE_SENTINEL);
+    expect(fixture.state.closeCount).toBe(1);
+    expect(fixture.state.transcodeLevels).toEqual([0, 1]);
+
+    fixture.repair();
+    const cleanupFailed = await transcodeBasis(rawBytes, TEST_TARGET);
+    expect(cleanupFailed.ok).toBe(false);
+    if (cleanupFailed.ok) throw new Error('expected close throw to return a CodecError');
+    expect(cleanupFailed.error.code).toBe('transcode-failed');
+    expect(cleanupFailed.error.detail).toEqual({
+      sourceFormat: 'raw-basis',
+      targetFormat: TEST_TARGET,
+    });
+    expect(JSON.stringify(cleanupFailed)).not.toContain(TEST_CLOSE_SENTINEL);
+    expect(fixture.state.closeCount).toBe(2);
+
+    fixture.repairClose();
+    const repaired = await transcodeBasis(rawBytes, TEST_TARGET);
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok) throw new Error('expected repaired raw Basis transcode to succeed');
+    expect(
+      repaired.value.mips.map(({ level, width, height, data }) => ({
+        level,
+        width,
+        height,
+        data: [...data],
+      })),
+    ).toEqual([
+      { level: 0, width: 8, height: 4, data: new Array(16).fill(1) },
+      { level: 1, width: 4, height: 2, data: new Array(4).fill(2) },
+    ]);
+
+    const third = await transcodeBasis(rawBytes, TEST_TARGET);
+    expect(third).toEqual(repaired);
+    expect(importerCalls).toBe(1);
+    expect(_basisTranscoderInitCount()).toBe(1);
+    expect(fixture.state.inputBytes).toHaveLength(4);
+    expect(fixture.state.inputBytes.every((bytes) => bytes === rawBytes)).toBe(true);
+    expect(fixture.state.targetEnums).toEqual([7, 7, 7, 7, 7, 7, 7, 7]);
+    expect(fixture.state.closeCount).toBe(4);
+  });
+
+  it('contains KTX2 and raw Basis constructor throws without attempting close', async () => {
+    const module = createConstructorThrowingModule();
+    _setBasisTranscoderImporter(() => Promise.resolve(module));
+
+    const ktx2 = await transcodeKtx2(fakeParsed(new Uint8Array([7])), TEST_TARGET);
+    expect(ktx2.ok).toBe(false);
+    if (ktx2.ok) throw new Error('expected KTX2 constructor throw to return a CodecError');
+    expect(ktx2.error.code).toBe('transcode-failed');
+    expect(ktx2.error.detail).toEqual({ sourceFormat: 'dfd-model-166', targetFormat: TEST_TARGET });
+
+    const basis = await transcodeBasis(new Uint8Array([8]), TEST_TARGET);
+    expect(basis.ok).toBe(false);
+    if (basis.ok) throw new Error('expected Basis constructor throw to return a CodecError');
+    expect(basis.error.code).toBe('transcode-failed');
+    expect(basis.error.detail).toEqual({ sourceFormat: 'raw-basis', targetFormat: TEST_TARGET });
+    expect(JSON.stringify({ ktx2, basis })).not.toContain(TEST_SENTINEL);
+  });
+});
+
+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);
+  });
+});

package/src/__tests__/block-format.unit.test.ts

@@ -0,0 +1,215 @@
+import {
+  blockParamsForFormat,
+  bytesPerRow,
+  isCompressedFormat,
+  rowsPerImage,
+} from '@forgeax/engine-codec';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * block-format lookup + byte-ratio unit tests (w9).
+ *
+ * AC-17 VRAM ratio: block-compressed TextureAsset.data (tight-packed, mip 0
+ * only here) is >=4x smaller than same-size RGBA8 for BC7/ASTC-4x4 (both 16
+ * bytes / 16 texels = 1 bpp block vs 4 bpp RGBA8 => 4x), and >=8x for
+ * ETC1S->BC1/ETC1 (8 bytes / 16 texels = 0.5 bpp => 8x).
+ *
+ * AC-08 non-4-multiple sizes: bytesPerRow = ceil(width/blockW) * bytesPerBlock,
+ * rowsPerImage = ceil(height/blockH). Tail blocks (1x1 / 2x2 mip) pad up to a
+ * full block.
+ *
+ * The block table is the shared SSOT (D-6) consumed by both the texture upload
+ * path and the equirect upload path.
+ */
+
+describe('blockParamsForFormat — compressed format dimensions (w9)', () => {
+  it('bc7-rgba-unorm => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('bc7-rgba-unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('bc7-rgba-unorm-srgb => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('bc7-rgba-unorm-srgb')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('bc1-rgba-unorm => 4x4 block, 8 bytes', () => {
+    expect(blockParamsForFormat('bc1-rgba-unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 8,
+    });
+  });
+
+  it('bc4-r-unorm => 4x4 block, 8 bytes', () => {
+    expect(blockParamsForFormat('bc4-r-unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 8,
+    });
+  });
+
+  it('bc5-rg-unorm => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('bc5-rg-unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('bc6h-rgb-ufloat => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('bc6h-rgb-ufloat')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('etc2-rgba8unorm => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('etc2-rgba8unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('etc2-rgb8unorm => 4x4 block, 8 bytes', () => {
+    expect(blockParamsForFormat('etc2-rgb8unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 8,
+    });
+  });
+
+  it('eac-r11unorm => 4x4 block, 8 bytes', () => {
+    expect(blockParamsForFormat('eac-r11unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 8,
+    });
+  });
+
+  it('eac-rg11unorm => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('eac-rg11unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('astc-4x4-unorm => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('astc-4x4-unorm')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('astc-4x4-unorm-srgb => 4x4 block, 16 bytes', () => {
+    expect(blockParamsForFormat('astc-4x4-unorm-srgb')).toEqual({
+      blockW: 4,
+      blockH: 4,
+      bytesPerBlock: 16,
+    });
+  });
+
+  it('uncompressed format (rgba8unorm) returns null block params', () => {
+    expect(blockParamsForFormat('rgba8unorm')).toBeNull();
+  });
+
+  it('uncompressed HDR format (rgba16float) returns null block params', () => {
+    expect(blockParamsForFormat('rgba16float')).toBeNull();
+  });
+});
+
+describe('isCompressedFormat — guard (w9)', () => {
+  it('true for block-compressed formats', () => {
+    expect(isCompressedFormat('bc7-rgba-unorm')).toBe(true);
+    expect(isCompressedFormat('bc1-rgba-unorm')).toBe(true);
+    expect(isCompressedFormat('etc2-rgba8unorm')).toBe(true);
+    expect(isCompressedFormat('astc-4x4-unorm-srgb')).toBe(true);
+    expect(isCompressedFormat('bc6h-rgb-ufloat')).toBe(true);
+    expect(isCompressedFormat('eac-rg11unorm')).toBe(true);
+  });
+
+  it('false for uncompressed formats', () => {
+    expect(isCompressedFormat('rgba8unorm')).toBe(false);
+    expect(isCompressedFormat('rgba8unorm-srgb')).toBe(false);
+    expect(isCompressedFormat('rgba16float')).toBe(false);
+    expect(isCompressedFormat('r8unorm')).toBe(false);
+    expect(isCompressedFormat('rg8unorm')).toBe(false);
+  });
+});
+
+describe('bytesPerRow / rowsPerImage — ceil logic (w9)', () => {
+  it('BC7 64x64: 16 blocks/row * 16 bytes = 256 bytes/row, 16 rows', () => {
+    expect(bytesPerRow('bc7-rgba-unorm', 64)).toBe(256);
+    expect(rowsPerImage('bc7-rgba-unorm', 64)).toBe(16);
+  });
+
+  it('BC7 65x65 (non-4-multiple): ceil(65/4)=17 blocks => 272 bytes/row, 17 rows', () => {
+    expect(bytesPerRow('bc7-rgba-unorm', 65)).toBe(17 * 16);
+    expect(rowsPerImage('bc7-rgba-unorm', 65)).toBe(17);
+  });
+
+  it('BC1 63x63: ceil(63/4)=16 blocks => 128 bytes/row, 16 rows', () => {
+    expect(bytesPerRow('bc1-rgba-unorm', 63)).toBe(16 * 8);
+    expect(rowsPerImage('bc1-rgba-unorm', 63)).toBe(16);
+  });
+
+  it('BC7 1x1 mip tail block pads to a full 4x4 block', () => {
+    expect(bytesPerRow('bc7-rgba-unorm', 1)).toBe(16);
+    expect(rowsPerImage('bc7-rgba-unorm', 1)).toBe(1);
+  });
+
+  it('BC7 2x2 mip tail block pads to a full 4x4 block', () => {
+    expect(bytesPerRow('bc7-rgba-unorm', 2)).toBe(16);
+    expect(rowsPerImage('bc7-rgba-unorm', 2)).toBe(1);
+  });
+
+  it('bytesPerRow throws / returns 0 semantics documented for uncompressed via null', () => {
+    // uncompressed formats have no block table entry; callers must branch on
+    // isCompressedFormat first. bytesPerRow returns null for these.
+    expect(bytesPerRow('rgba8unorm', 64)).toBeNull();
+    expect(rowsPerImage('rgba8unorm', 64)).toBeNull();
+  });
+});
+
+describe('byte-ratio assertions vs RGBA8 tight-pack (AC-17, w9)', () => {
+  function rgba8Bytes(w: number, h: number): number {
+    return w * h * 4;
+  }
+
+  function compressedBytes(format: GPUTextureFormat, w: number, h: number): number {
+    const bpr = bytesPerRow(format, w);
+    const rows = rowsPerImage(format, h);
+    if (bpr === null || rows === null) throw new Error(`no block params for ${format}`);
+    return bpr * rows;
+  }
+
+  it('BC7 256x256 is >=4x smaller than RGBA8 tight-pack', () => {
+    const ratio = rgba8Bytes(256, 256) / compressedBytes('bc7-rgba-unorm', 256, 256);
+    expect(ratio).toBeGreaterThanOrEqual(4);
+  });
+
+  it('ASTC-4x4 256x256 is >=4x smaller than RGBA8 tight-pack', () => {
+    const ratio = rgba8Bytes(256, 256) / compressedBytes('astc-4x4-unorm', 256, 256);
+    expect(ratio).toBeGreaterThanOrEqual(4);
+  });
+
+  it('BC1 (ETC1S->BC1 delivery) 256x256 is >=8x smaller than RGBA8 tight-pack', () => {
+    const ratio = rgba8Bytes(256, 256) / compressedBytes('bc1-rgba-unorm', 256, 256);
+    expect(ratio).toBeGreaterThanOrEqual(8);
+  });
+
+  it('ETC2-rgb8 (ETC1->RGB delivery) 256x256 is >=8x smaller than RGBA8 tight-pack', () => {
+    const ratio = rgba8Bytes(256, 256) / compressedBytes('etc2-rgb8unorm', 256, 256);
+    expect(ratio).toBeGreaterThanOrEqual(8);
+  });
+});