@forgeax/engine-rhi-debug 0.0.0-dev.8d955ade1c79

package/src/__tests__/coverage-invariant.test-d.ts

@@ -0,0 +1,115 @@
+// Type-level coverage invariant: every method on the three RHI encoder
+// interfaces must map to either a captured RhiCallEvent kind or a
+// DEFERRED_COMMANDS member. If a future method is added to any encoder
+// without a matching entry, Exclude<keyof<Interface>, ...> becomes non-never
+// and tsc fails — no human memory needed.
+//
+// AC-01: Uncovered = never for all three interfaces.
+// AC-02: falsification variant proves the guard is sensitive.
+//
+// Two non-1:1 mappings per plan-strategy D-1:
+//   1. Method `end` -> kind `endRenderPass` / `endComputePass`
+//   2. Render-pass `pushDebugGroup` / `popDebugGroup` / `insertDebugMarker`
+//      -> kind `passPushDebugGroup` / `passPopDebugGroup` / `passInsertDebugMarker`
+//   3. Compute-pass `setPipeline` -> kind `setComputePipeline`
+//      (method name identical on both interfaces, different kinds)
+
+import type {
+  RhiCommandEncoder,
+  RhiComputePassEncoder,
+  RhiRenderPassEncoder,
+} from '@forgeax/engine-rhi';
+import { describe, expectTypeOf, it } from 'vitest';
+
+// ---- CapturedMethods: all RHI method names that have a RhiCallEvent kind ----
+
+type CapturedMethods =
+  // RhiCommandEncoder methods (11 captured)
+  | 'beginRenderPass'
+  | 'beginComputePass'
+  | 'copyBufferToBuffer' // overloaded, one keyof entry
+  | 'copyBufferToTexture'
+  | 'copyTextureToBuffer'
+  | 'copyTextureToTexture'
+  | 'clearBuffer'
+  | 'pushDebugGroup' // encoder-level, maps to kind 'pushDebugGroup'
+  | 'popDebugGroup' // encoder-level, maps to kind 'popDebugGroup'
+  | 'insertDebugMarker' // encoder-level, maps to kind 'insertDebugMarker'
+  | 'finish'
+  // RhiRenderPassEncoder methods (16 captured)
+  | 'setPipeline' // render pass: kind='setPipeline'; compute pass: kind='setComputePipeline'
+  | 'setVertexBuffer'
+  | 'setIndexBuffer'
+  | 'setBindGroup' // overloaded, one keyof entry
+  | 'draw'
+  | 'drawIndexed'
+  | 'setViewport'
+  | 'setScissorRect'
+  | 'setBlendConstant'
+  | 'setStencilReference'
+  | 'drawIndirect'
+  | 'drawIndexedIndirect'
+  // pushDebugGroup/popDebugGroup/insertDebugMarker on render pass exist as
+  // methods BUT map to pass*DebugGroup kinds. The keyof name is still
+  // pushDebugGroup/popDebugGroup/insertDebugMarker (covered above).
+  | 'end' // render pass: kind='endRenderPass'; compute pass: kind='endComputePass'
+  // RhiComputePassEncoder methods (1 unique, others shared above)
+  | 'dispatchWorkgroups'
+  | 'dispatchWorkgroupsIndirect';
+
+// ---- DeferredMethods: RHI method names in DEFERRED_COMMANDS (AC-06) ----
+
+type DeferredMethods =
+  | 'beginOcclusionQuery'
+  | 'endOcclusionQuery'
+  | 'executeBundles'
+  | 'writeTimestamp'
+  | 'resolveQuerySet';
+
+// ---- Per-interface coverage assertions (AC-01) ----
+
+describe('RhiCommandEncoder coverage', () => {
+  it('every method is captured or deferred (AC-01)', () => {
+    type Uncovered = Exclude<keyof RhiCommandEncoder, CapturedMethods | DeferredMethods>;
+    expectTypeOf<Uncovered>().toEqualTypeOf<never>();
+  });
+});
+
+describe('RhiRenderPassEncoder coverage', () => {
+  it('every method is captured or deferred (AC-01)', () => {
+    type Uncovered = Exclude<keyof RhiRenderPassEncoder, CapturedMethods | DeferredMethods>;
+    expectTypeOf<Uncovered>().toEqualTypeOf<never>();
+  });
+});
+
+describe('RhiComputePassEncoder coverage', () => {
+  it('every method is captured or deferred (AC-01)', () => {
+    type Uncovered = Exclude<keyof RhiComputePassEncoder, CapturedMethods | DeferredMethods>;
+    expectTypeOf<Uncovered>().toEqualTypeOf<never>();
+  });
+});
+
+// ---- AC-02 falsification: prove the guard catches omissions ----
+
+describe('AC-02 falsification', () => {
+  it('forgetting a method from CapturedMethods makes Uncovered non-never', () => {
+    // Simulate: forget to include 'copyBufferToBuffer' in CapturedMethods.
+    // Then Exclude should surface 'copyBufferToBuffer' (non-never).
+    type ForgotCopyBufferToBuffer = Exclude<CapturedMethods, 'copyBufferToBuffer'>;
+    type DetectedForgotten = Exclude<
+      keyof RhiCommandEncoder,
+      ForgotCopyBufferToBuffer | DeferredMethods
+    >;
+    // The forgotten method is detected — DetectedForgotten equals 'copyBufferToBuffer'
+    expectTypeOf<DetectedForgotten>().toEqualTypeOf<'copyBufferToBuffer'>();
+    // And it is not never — the guard is sensitive
+    expectTypeOf<DetectedForgotten>().not.toEqualTypeOf<never>();
+  });
+
+  it('original CapturedMethods is complete (DetectedForgotten was just the one we removed)', () => {
+    // Sanity check: without the deliberate omission, Uncovered = never.
+    // This doubles as a regression test that CapturedMethods is correctly maintained.
+    type Uncovered = Exclude<keyof RhiCommandEncoder, CapturedMethods | DeferredMethods>;
+    expectTypeOf<Uncovered>().toEqualTypeOf<never>();
+  });
+});

package/src/__tests__/coverage-invariant.unit.test.ts

@@ -0,0 +1,45 @@
+// AC-06: DEFERRED_COMMANDS set assertion.
+//
+// Verifies the deferred-commands constant contains exactly the 5 OOS
+// commands (beginOcclusionQuery, endOcclusionQuery, executeBundles,
+// writeTimestamp, resolveQuerySet) — no more, no less. Any drift in
+// the constant (missing member, extra member) will fail this test,
+// catching both accidental removal and accidental addition of commands
+// that should either be fully captured or documented as explicitly
+// out-of-scope.
+
+import { describe, expect, it } from 'vitest';
+import { DEFERRED_COMMANDS } from '../types';
+
+describe('DEFERRED_COMMANDS (AC-06)', () => {
+  it('contains exactly the 5 OOS commands', () => {
+    expect(DEFERRED_COMMANDS.size).toBe(5);
+
+    const expected = new Set([
+      'beginOcclusionQuery',
+      'endOcclusionQuery',
+      'executeBundles',
+      'writeTimestamp',
+      'resolveQuerySet',
+    ]);
+
+    for (const cmd of expected) {
+      expect(DEFERRED_COMMANDS.has(cmd)).toBe(true);
+    }
+  });
+
+  it('has no unexpected members', () => {
+    // Every member must be in the AC-06 contract set.
+    const allowed = new Set([
+      'beginOcclusionQuery',
+      'endOcclusionQuery',
+      'executeBundles',
+      'writeTimestamp',
+      'resolveQuerySet',
+    ]);
+
+    for (const cmd of DEFERRED_COMMANDS) {
+      expect(allowed.has(cmd)).toBe(true);
+    }
+  });
+});

package/src/__tests__/e2e.browser.test.ts

@@ -0,0 +1,239 @@
+/// <reference types="@webgpu/types" />
+
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { buildFrameModel } from '../frame-model';
+import { decodeTape } from '../protocol/codec';
+import type { Tape } from '../protocol/types';
+import { attachRecorder, type RecordableBackend } from '../recorder/session';
+import { openReplay } from '../replay/session';
+
+const GPU_AVAILABLE = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+const SIZE = 64;
+
+const VERTEX_SHADER = /* wgsl */ `
+@vertex
+fn main(@builtin(vertex_index) vertexIndex: u32) -> @builtin(position) vec4<f32> {
+  var positions = array<vec2<f32>, 3>(
+    vec2<f32>(-0.8, -0.8),
+    vec2<f32>(0.8, -0.8),
+    vec2<f32>(0.0, 0.8),
+  );
+  return vec4<f32>(positions[vertexIndex], 0.0, 1.0);
+}`;
+
+const FRAGMENT_SHADER = /* wgsl */ `
+@group(0) @binding(0) var sourceTexture: texture_2d<f32>;
+@group(0) @binding(1) var sourceSampler: sampler;
+
+@fragment
+fn main() -> @location(0) vec4<f32> {
+  return textureSample(sourceTexture, sourceSampler, vec2<f32>(0.5, 0.5));
+}`;
+
+interface CapturedBrowserTape {
+  readonly backend: RecordableBackend;
+  readonly device: RhiDevice;
+  readonly tape: Tape;
+}
+
+function must<T>(
+  result:
+    | { readonly ok: true; readonly value: T }
+    | { readonly ok: false; readonly error: unknown },
+  label: string,
+): T {
+  if (result.ok) return result.value;
+  const error = result.error as {
+    readonly code?: unknown;
+    readonly hint?: unknown;
+    readonly detail?: unknown;
+  };
+  throw new Error(
+    `${label}: ${String(error.code ?? 'unknown')} ${String(error.hint ?? '')} ${JSON.stringify(error.detail ?? null)}`,
+  );
+}
+
+async function loadBackend(): Promise<RecordableBackend> {
+  const backend = await import('@forgeax/engine-rhi-webgpu');
+  return backend as unknown as RecordableBackend;
+}
+
+async function captureBrowserTape(): Promise<CapturedBrowserTape> {
+  const backend = await loadBackend();
+  const attachment = must(attachRecorder(backend), 'attachRecorder');
+  const adapter = must(await attachment.backend.rhi.requestAdapter(), 'requestAdapter');
+  const device = must(await adapter.requestDevice(), 'requestDevice');
+  const capture = attachment.captureFrame();
+  must(await attachment.frameBoundary(), 'capture snapshot boundary');
+
+  const renderTarget = must(
+    device.createTexture({
+      size: { width: SIZE, height: SIZE, depthOrArrayLayers: 1 },
+      format: 'rgba8unorm',
+      usage: 0x11,
+    }),
+    'create render target',
+  );
+  const renderTargetView = must(
+    device.createTextureView(renderTarget, {}),
+    'create render target view',
+  );
+  const sourceTexture = must(
+    device.createTexture({
+      size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+      format: 'rgba8unorm',
+      usage: 0x06,
+    }),
+    'create source texture',
+  );
+  const sourceView = must(device.createTextureView(sourceTexture, {}), 'create source view');
+  const sampler = must(device.createSampler({}), 'create sampler');
+  const vertex = must(
+    await attachment.backend.createShaderModule(device, { code: VERTEX_SHADER }),
+    'create vertex shader',
+  );
+  const fragment = must(
+    await attachment.backend.createShaderModule(device, { code: FRAGMENT_SHADER }),
+    'create fragment shader',
+  );
+  const bindGroupLayout = must(
+    device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: 0x02, texture: { sampleType: 'float', viewDimension: '2d' } },
+        { binding: 1, visibility: 0x02, sampler: { type: 'filtering' } },
+      ],
+    }),
+    'create bind group layout',
+  );
+  const bindGroup = must(
+    device.createBindGroup({
+      layout: bindGroupLayout,
+      entries: [
+        { binding: 0, resource: { kind: 'textureView', value: sourceView } },
+        { binding: 1, resource: { kind: 'sampler', value: sampler } },
+      ],
+    } as never),
+    'create bind group',
+  );
+  const pipelineLayout = must(
+    device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
+    'create pipeline layout',
+  );
+  const pipeline = must(
+    device.createRenderPipeline({
+      layout: pipelineLayout,
+      vertex: { module: vertex, entryPoint: 'main', buffers: [] },
+      fragment: { module: fragment, entryPoint: 'main', targets: [{ format: 'rgba8unorm' }] },
+      primitive: { topology: 'triangle-list' },
+    } as never),
+    'create render pipeline',
+  );
+
+  const textureData = new Uint8Array([255, 32, 16, 255]);
+  must(
+    device.queue.writeTexture(
+      { texture: sourceTexture, mipLevel: 0, origin: { x: 0, y: 0, z: 0 } } as never,
+      textureData,
+      { offset: 0, bytesPerRow: 4, rowsPerImage: 1 },
+      { width: 1, height: 1, depthOrArrayLayers: 1 },
+    ),
+    'write source texture',
+  );
+  const encoder = must(device.createCommandEncoder({}), 'create command encoder');
+  const pass = encoder.beginRenderPass({
+    colorAttachments: [
+      {
+        view: renderTargetView,
+        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+        loadOp: 'clear',
+        storeOp: 'store',
+      },
+    ],
+  } as never);
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, bindGroup, []);
+  pass.draw(3, 1, 0, 0);
+  pass.end();
+  const command = must(encoder.finish(), 'finish command encoder');
+  must(device.queue.submit([command]), 'submit command buffer');
+  await device.queue.onSubmittedWorkDone();
+  must(await attachment.frameBoundary(), 'capture recording boundary');
+  const encoded = must(await capture, 'capture frame');
+  const decoded = must(decodeTape(encoded.bytes), 'strict v7 decode');
+  await attachment.dispose();
+  return { backend, device, tape: decoded };
+}
+
+function hasVisibleRgb(pixels: Uint8Array): boolean {
+  for (let index = 0; index < pixels.length; index += 4) {
+    if ((pixels[index] ?? 0) > 4 || (pixels[index + 1] ?? 0) > 4 || (pixels[index + 2] ?? 0) > 4) {
+      return true;
+    }
+  }
+  return false;
+}
+
+describe.skipIf(!GPU_AVAILABLE)('M4 browser capture and replay gate', () => {
+  it('captures one raw v7 tape, indexes binding/work state, replays it on a fresh device, and reads a lit RT', async () => {
+    const captured = await captureBrowserTape();
+    const model = buildFrameModel(captured.tape);
+    expect(captured.tape.header.formatVersion).toBe(7);
+    expect(captured.tape.events.length).toBeGreaterThan(0);
+    expect(model.works.some((work) => work.kind === 'draw' || work.kind === 'drawIndexed')).toBe(
+      true,
+    );
+    expect(captured.tape.events.some((event) => event.kind === 'setBindGroup')).toBe(true);
+    expect(model.works.length).toBeGreaterThan(0);
+
+    const adapter = must(await captured.backend.rhi.requestAdapter(), 'fresh requestAdapter');
+    const freshDevice = must(await adapter.requestDevice(), 'fresh requestDevice');
+    const session = must(
+      await openReplay(captured.tape, {
+        device: freshDevice,
+        createShaderModule: captured.backend.createShaderModule,
+      }),
+      'open fresh replay session',
+    );
+    const work = must(await session.inspectWork(0, ['bindings', 'pixels']), 'inspect work index 0');
+    expect(work.workIndex).toBe(0);
+    expect(work.passIndex).toBeGreaterThanOrEqual(0);
+    expect(work.attachment?.kind).toBe('texture');
+    expect(work.attachment?.width).toBe(SIZE);
+    expect(work.attachment?.height).toBe(SIZE);
+    expect(work.attachment?.provenance.selectedWorkIndex).toBe(0);
+    expect(work.attachment?.provenance.resourceId).toBeDefined();
+    expect(work.attachment?.provenance.subresource).toBeNull();
+    expect(hasVisibleRgb(work.attachment?.bytes ?? new Uint8Array())).toBe(true);
+    await session.dispose();
+  }, 60_000);
+
+  it('makes a missing texture binding fail the fresh replay path', async () => {
+    const captured = await captureBrowserTape();
+    const falsifiedEvents = captured.tape.events.map((event) =>
+      event.kind === 'setBindGroup'
+        ? { ...event, bindGroupHandleId: 'binding:falsified-texture' }
+        : event,
+    );
+    expect(falsifiedEvents.some((event) => event.kind === 'setBindGroup')).toBe(true);
+    const falsifiedTape: Tape = {
+      ...captured.tape,
+      header: { ...captured.tape.header, eventCount: falsifiedEvents.length },
+      events: falsifiedEvents,
+    };
+    const adapter = must(await captured.backend.rhi.requestAdapter(), 'falsifier requestAdapter');
+    const device = must(await adapter.requestDevice(), 'falsifier requestDevice');
+    const replay = await openReplay(falsifiedTape, {
+      device,
+      createShaderModule: captured.backend.createShaderModule,
+    });
+    if (replay.ok) {
+      const result = await replay.value.inspectWork(0, ['pixels']);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBeDefined();
+      await replay.value.dispose();
+    } else {
+      expect(replay.error.code).toBeDefined();
+    }
+  }, 60_000);
+});

package/src/__tests__/error-code-narrowing.test-d.ts

@@ -0,0 +1,32 @@
+import { expectTypeOf, it } from 'vitest';
+import type { RhiDebugError, RhiDebugErrorCode } from '../errors';
+
+it('keeps the eleven error codes closed', () => {
+  expectTypeOf<RhiDebugErrorCode>().toEqualTypeOf<
+    | 'capture-unavailable'
+    | 'capture-busy'
+    | 'capture-snapshot-failed'
+    | 'capture-timeout'
+    | 'tape-invalid'
+    | 'tape-version-unsupported'
+    | 'replay-capability-mismatch'
+    | 'replay-event-failed'
+    | 'replay-position-invalid'
+    | 'readback-failed'
+    | 'readback-unsupported'
+  >();
+});
+
+it('narrows detail with the error code', () => {
+  const error = null as unknown as RhiDebugError;
+  if (error.code === 'tape-version-unsupported') {
+    expectTypeOf(error.detail).toMatchTypeOf<
+      { foundVersion: number; expectedVersion: number } | undefined
+    >();
+  }
+  if (error.code === 'replay-position-invalid') {
+    expectTypeOf(error.detail).toMatchTypeOf<
+      { requested: number; available: number } | undefined
+    >();
+  }
+});

package/src/__tests__/errors-v7.test-d.ts

@@ -0,0 +1,19 @@
+import { expectTypeOf, it } from 'vitest';
+import type { RhiDebugError, RhiDebugErrorCode } from '../errors';
+
+it('has the frozen eleven-member error union', () => {
+  expectTypeOf<RhiDebugErrorCode>().toEqualTypeOf<
+    | 'capture-unavailable'
+    | 'capture-busy'
+    | 'capture-snapshot-failed'
+    | 'capture-timeout'
+    | 'tape-invalid'
+    | 'tape-version-unsupported'
+    | 'replay-capability-mismatch'
+    | 'replay-event-failed'
+    | 'replay-position-invalid'
+    | 'readback-failed'
+    | 'readback-unsupported'
+  >();
+  expectTypeOf<RhiDebugError['detail']>().not.toEqualTypeOf<unknown>();
+});

package/src/__tests__/errors-v7.unit.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { createRhiDebugError } from '../errors';
+
+describe('RhiDebugError', () => {
+  it('exposes the closed code and recovery fields', () => {
+    const error = createRhiDebugError('tape-version-unsupported', {
+      foundVersion: 5,
+      expectedVersion: 7,
+    });
+    expect(error.code).toBe('tape-version-unsupported');
+    expect(error.expected).toContain('7');
+    expect(error.hint).toContain('source revision');
+    expect(error.detail).toMatchObject({ foundVersion: 5, expectedVersion: 7 });
+  });
+});

package/src/__tests__/errors.unit.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import { createRhiDebugError, type RhiDebugError } from '../errors';
+
+function describeError(error: RhiDebugError): string {
+  switch (error.code) {
+    case 'capture-unavailable':
+    case 'capture-busy':
+    case 'capture-snapshot-failed':
+    case 'capture-timeout':
+    case 'tape-invalid':
+    case 'tape-version-unsupported':
+    case 'replay-capability-mismatch':
+    case 'replay-event-failed':
+    case 'replay-position-invalid':
+    case 'readback-failed':
+    case 'readback-unsupported':
+      return `${error.code}:${error.hint}`;
+  }
+}
+
+describe('RhiDebugError', () => {
+  it('keeps capture failures structured at the snapshot boundary', () => {
+    const error = createRhiDebugError('capture-snapshot-failed', {
+      stage: 'snapshot',
+      cause: 'texture readback failed during map',
+      handleId: 'texture:7',
+      resourceKind: 'texture',
+    });
+
+    expect(error.code).toBe('capture-snapshot-failed');
+    expect(error.expected).toContain('capture');
+    expect(error.detail).toEqual({
+      stage: 'snapshot',
+      cause: 'texture readback failed during map',
+      handleId: 'texture:7',
+      resourceKind: 'texture',
+    });
+  });
+
+  it('keeps tape graph failures in the tape validation owner', () => {
+    const error = createRhiDebugError('tape-invalid', {
+      stage: 'validate',
+      cause: 'handleId texture:7 has no create event',
+      handleId: 'texture:7',
+      eventIndex: 42,
+    });
+
+    expect(error.detail.stage).toBe('validate');
+    expect(error.detail.handleId).toBe('texture:7');
+    expect(error.detail.eventIndex).toBe(42);
+  });
+
+  it('keeps bounded snapshot timeout progress machine-readable', () => {
+    const error = createRhiDebugError('capture-timeout', {
+      stage: 'snapshot',
+      cause: 'queue drain exceeded the bound',
+      timeoutMs: 1000,
+      progress: {
+        snapshotStage: 'queue-drain',
+        totalResources: 4,
+        completedResources: 1,
+        skippedResources: 0,
+        currentHandleId: 'buffer:readback',
+        currentKind: 'buffer',
+        currentSizeBytes: 128,
+        elapsedMs: 1001,
+      },
+    });
+
+    expect(error.detail.progress?.currentHandleId).toBe('buffer:readback');
+    expect(error.detail.timeoutMs).toBe(1000);
+  });
+
+  it('supports an exhaustive consumer switch over the closed union', () => {
+    const error = createRhiDebugError('readback-unsupported', {
+      stage: 'readback',
+      format: 'depth24plus',
+      reason: 'the backend has no depth blit path',
+    });
+
+    expect(describeError(error)).toContain('readback-unsupported');
+  });
+});

package/src/__tests__/event-semantics-coverage.unit.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { EVENT_SEMANTICS, eventKinds, isWorkEvent } from '../protocol/event-semantics';
+
+describe('event semantics coverage', () => {
+  it('has one semantic entry for every closed event kind', () => {
+    expect(Object.keys(EVENT_SEMANTICS).sort()).toEqual([...eventKinds].sort());
+  });
+
+  it('counts direct, indexed, indirect, and compute work without draw aliases', () => {
+    expect(
+      [
+        'draw',
+        'drawIndexed',
+        'drawIndirect',
+        'drawIndexedIndirect',
+        'dispatchWorkgroups',
+        'dispatchWorkgroupsIndirect',
+      ].every((kind) => isWorkEvent(kind as never)),
+    ).toBe(true);
+    expect(isWorkEvent('beginRenderPass')).toBe(false);
+  });
+});

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

@@ -0,0 +1,85 @@
+// format-info.unit.test.ts — per-channel metadata for host-side color decode.
+//
+// formatInfo sits beside bytesPerTexel (the replay-critical byte-size SSOT). The
+// key invariant: for every plain (non-packed) format, channels * per-channel-bytes
+// equals bytesPerTexel — the two tables must never drift apart.
+
+import { describe, expect, it } from 'vitest';
+import {
+  bytesPerTexel,
+  computeTextureLayout,
+  formatInfo,
+  textureBlockLayout,
+} from '../texel-layout';
+
+describe('formatInfo', () => {
+  it('returns channels + channelType for representative formats', () => {
+    expect(formatInfo('rgba8unorm')).toEqual({ channels: 4, channelType: 'unorm' });
+    expect(formatInfo('bgra8unorm')).toEqual({ channels: 4, channelType: 'unorm', bgra: true });
+    expect(formatInfo('r32float')).toEqual({ channels: 1, channelType: 'float' });
+    expect(formatInfo('rg16float')).toEqual({ channels: 2, channelType: 'float' });
+    expect(formatInfo('rgba16float')).toEqual({ channels: 4, channelType: 'float' });
+    expect(formatInfo('r8uint')).toEqual({ channels: 1, channelType: 'uint' });
+    expect(formatInfo('rgba8snorm')).toEqual({ channels: 4, channelType: 'snorm' });
+  });
+
+  it('flags packed formats', () => {
+    expect(formatInfo('rgb10a2unorm')).toEqual({
+      channels: 4,
+      channelType: 'unorm',
+      packed: 'rgb10a2unorm',
+    });
+    expect(formatInfo('rg11b10ufloat')).toEqual({
+      channels: 3,
+      channelType: 'ufloat',
+      packed: 'rg11b10ufloat',
+    });
+  });
+
+  it('returns undefined for compressed / depth / unknown formats', () => {
+    expect(formatInfo('bc7-rgba-unorm')).toBeUndefined();
+    expect(formatInfo('depth32float')).toBeUndefined();
+    expect(formatInfo('depth24plus-stencil8')).toBeUndefined();
+    expect(formatInfo(undefined)).toBeUndefined();
+    expect(formatInfo('not-a-format')).toBeUndefined();
+  });
+
+  it('derives compressed block layout for snapshot and seed', () => {
+    expect(textureBlockLayout('bc7-rgba-unorm-srgb')).toEqual({
+      blockWidth: 4,
+      blockHeight: 4,
+      bytesPerBlock: 16,
+    });
+    const layout = computeTextureLayout('bc7-rgba-unorm-srgb', 7, 5, 1, 1);
+    expect(layout).toMatchObject({
+      blockWidth: 4,
+      blockHeight: 4,
+      bytesPerBlock: 16,
+      totalBytes: 64,
+    });
+    expect(layout?.slices[0]).toMatchObject({ width: 7, height: 5, byteLength: 64 });
+  });
+
+  it('plain formats: channels * per-channel-bytes == bytesPerTexel (no table drift)', () => {
+    const plain: string[] = [
+      'r8unorm',
+      'rg8unorm',
+      'rgba8unorm',
+      'bgra8unorm',
+      'r16uint',
+      'rg16float',
+      'rgba16float',
+      'r32float',
+      'rg32uint',
+      'rgba32float',
+    ];
+    for (const fmt of plain) {
+      const info = formatInfo(fmt);
+      const total = bytesPerTexel(fmt as never);
+      if (!info || total === undefined) throw new Error(`missing tables for ${fmt}`);
+      expect(total % info.channels).toBe(0);
+      // per-channel width is total/channels; reconstructing the total must match.
+      expect((total / info.channels) * info.channels).toBe(total);
+    }
+  });
+});

package/src/__tests__/frame-model-parity.test-d.ts

@@ -0,0 +1,20 @@
+import { expectTypeOf, it } from 'vitest';
+import type { FrameModel } from '../frame-model';
+
+type HasKey<T, K extends PropertyKey> = K extends keyof T ? true : false;
+type IsReadonlyMap<T> = T extends ReadonlyMap<unknown, unknown> ? true : false;
+
+it('exposes only the canonical JSON-safe model shape', () => {
+  expectTypeOf<HasKey<FrameModel, 'commands'>>().toEqualTypeOf<true>();
+  expectTypeOf<HasKey<FrameModel, 'passes'>>().toEqualTypeOf<true>();
+  expectTypeOf<HasKey<FrameModel, 'resources'>>().toEqualTypeOf<true>();
+  expectTypeOf<HasKey<FrameModel, 'works'>>().toEqualTypeOf<true>();
+  expectTypeOf<HasKey<FrameModel, 'tree'>>().toEqualTypeOf<false>();
+  expectTypeOf<HasKey<FrameModel, 'draws'>>().toEqualTypeOf<false>();
+  expectTypeOf<HasKey<FrameModel, 'meta'>>().toEqualTypeOf<false>();
+  expectTypeOf<HasKey<FrameModel, 'resourceLifecycle'>>().toEqualTypeOf<true>();
+  expectTypeOf<IsReadonlyMap<FrameModel['resources']>>().toEqualTypeOf<false>();
+  expectTypeOf<FrameModel['works'][number]['workIndex']>().toEqualTypeOf<number>();
+  expectTypeOf<FrameModel['works'][number]['eventIndex']>().toEqualTypeOf<number>();
+  expectTypeOf<FrameModel['works'][number]['passIndex']>().toEqualTypeOf<number>();
+});