@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/gpu-pass-timing-observation.unit.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  GpuPassTimingFrame,
+  GpuPassTimingObservation,
+} from '../record/gpu-pass-timing/index.js';
+import type { FrameReceipt } from '../render-contract.js';
+import { createGpuPassTimingObservationStore, observeGpuPassTimingDisabled } from '../renderer.js';
+
+function receipt(frameId: number): FrameReceipt {
+  return {
+    frameId,
+    deviceGeneration: 3,
+    completed: Promise.resolve({ ok: true, value: undefined }),
+  } as FrameReceipt;
+}
+
+function frame(frameId: number, graphGeneration = frameId): GpuPassTimingFrame {
+  return {
+    schemaVersion: '1.0',
+    frameId,
+    deviceGeneration: 3,
+    graphGeneration,
+    backendKind: 'webgpu',
+    timestampPeriodNanoseconds: 1,
+    passCapacity: 4,
+    executedPassCount: 0,
+    measuredPassCount: 0,
+    droppedPassCount: 0,
+    passes: [],
+    measuredPassNanoseconds: 0,
+  };
+}
+
+function complete(frameId: number, graphGeneration = frameId): GpuPassTimingObservation {
+  return { status: 'complete', frame: frame(frameId, graphGeneration) };
+}
+
+function partial(frameId: number): GpuPassTimingObservation {
+  return {
+    status: 'partial',
+    frame: frame(frameId),
+    reason: {
+      code: 'timing-in-flight-exhausted',
+      expected: 'a bounded timing slot is available',
+      hint: 'observe a later receipt',
+      detail: {},
+    },
+  };
+}
+
+describe('receipt-bound GPU pass timing observation', () => {
+  it('observes an opt-out receipt without constructing a timing retention store', async () => {
+    const current = receipt(6);
+    const timingResult = await observeGpuPassTimingDisabled(
+      current,
+      { include: ['timings'] },
+      () => 3,
+    );
+    const drawResult = await observeGpuPassTimingDisabled(current, { include: ['draws'] }, () => 3);
+
+    expect(timingResult).toMatchObject({
+      ok: true,
+      value: {
+        frameId: 6,
+        deviceGeneration: 3,
+        timings: { status: 'unavailable', reason: { code: 'gpu-timing-not-enabled' } },
+      },
+    });
+    expect(drawResult).toMatchObject({
+      ok: true,
+      value: { frameId: 6, deviceGeneration: 3 },
+    });
+    if (drawResult.ok) expect(drawResult.value).not.toHaveProperty('timings');
+  });
+
+  it('keeps receipt, device, and graph identity attached to the requested frame', async () => {
+    const store = createGpuPassTimingObservationStore({
+      retentionFrames: 8,
+      currentDeviceGeneration: () => 3,
+    });
+    const first = receipt(41);
+    const second = receipt(42);
+    store.register(first, async () => complete(41, 101));
+    store.register(second, async () => complete(42, 102));
+
+    const firstResult = await store.observe(first, { include: ['timings'] });
+    const secondResult = await store.observe(second, { include: ['timings'] });
+
+    expect(firstResult.ok).toBe(true);
+    expect(secondResult.ok).toBe(true);
+    if (!firstResult.ok || !secondResult.ok) return;
+    expect(firstResult.value).toMatchObject({
+      frameId: 41,
+      deviceGeneration: 3,
+      timings: { status: 'complete', frame: { frameId: 41, graphGeneration: 101 } },
+    });
+    expect(secondResult.value).toMatchObject({
+      frameId: 42,
+      timings: { status: 'complete', frame: { frameId: 42, graphGeneration: 102 } },
+    });
+  });
+
+  it('does not materialize timings or activate a future frame when timings are omitted', async () => {
+    const store = createGpuPassTimingObservationStore({
+      retentionFrames: 8,
+      currentDeviceGeneration: () => 3,
+    });
+    const current = receipt(7);
+    let sourceCalls = 0;
+    store.register(current, async () => {
+      sourceCalls += 1;
+      return complete(7);
+    });
+
+    const result = await store.observe(current, { include: ['draws'] });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).not.toHaveProperty('timings');
+    expect(sourceCalls).toBe(0);
+  });
+
+  it('waits only for the requested receipt when receipts complete concurrently', async () => {
+    let releaseFirst!: () => void;
+    let releaseSecond!: () => void;
+    const firstCompleted = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    const secondCompleted = new Promise<void>((resolve) => {
+      releaseSecond = resolve;
+    });
+    const first = {
+      ...receipt(1),
+      completed: firstCompleted.then(() => ({ ok: true, value: undefined })),
+    } as FrameReceipt;
+    const second = {
+      ...receipt(2),
+      completed: secondCompleted.then(() => ({ ok: true, value: undefined })),
+    } as FrameReceipt;
+    const store = createGpuPassTimingObservationStore({
+      retentionFrames: 8,
+      currentDeviceGeneration: () => 3,
+    });
+    let firstSourceCalls = 0;
+    let secondSourceCalls = 0;
+    store.register(first, async () => {
+      firstSourceCalls += 1;
+      return complete(1);
+    });
+    store.register(second, async () => {
+      secondSourceCalls += 1;
+      return complete(2);
+    });
+
+    const firstObservation = store.observe(first, { include: ['timings'] });
+    const secondObservation = store.observe(second, { include: ['timings'] });
+    releaseSecond();
+    const secondResult = await secondObservation;
+    expect(secondResult.ok).toBe(true);
+    expect(firstSourceCalls).toBe(0);
+    expect(secondSourceCalls).toBe(1);
+    releaseFirst();
+    expect((await firstObservation).ok).toBe(true);
+  });
+
+  it('surfaces not-enabled, unsupported, complete, partial, and failed statuses', async () => {
+    const store = createGpuPassTimingObservationStore({
+      retentionFrames: 8,
+      currentDeviceGeneration: () => 3,
+    });
+    const notEnabled = receipt(1);
+    const unsupported = receipt(2);
+    const completeReceipt = receipt(3);
+    const partialReceipt = receipt(4);
+    const failedReceipt = receipt(5);
+    store.register(notEnabled);
+    store.register(unsupported, async () => ({
+      status: 'unavailable',
+      reason: {
+        code: 'timestamp-query-unsupported',
+        expected: 'the active device exposes timestamp-query',
+        hint: 'use a backend that supports timestamp-query',
+        detail: {},
+      },
+      capability: { timestampQuery: false, timestampPeriodNanoseconds: null },
+    }));
+    store.register(completeReceipt, async () => complete(3));
+    store.register(partialReceipt, async () => partial(4));
+    store.register(failedReceipt, async () => ({
+      status: 'failed',
+      error: {
+        code: 'timestamp-readback-failed',
+        expected: 'the resolved timing buffer can be read',
+        hint: 'observe a later receipt',
+        detail: {},
+      },
+    }));
+
+    const results = await Promise.all(
+      [notEnabled, unsupported, completeReceipt, partialReceipt, failedReceipt].map((item) =>
+        store.observe(item, { include: ['timings'] }),
+      ),
+    );
+
+    expect(results.map((result) => (result.ok ? result.value.timings?.status : 'error'))).toEqual([
+      'unavailable',
+      'unavailable',
+      'complete',
+      'partial',
+      'failed',
+    ]);
+  });
+
+  it('returns a bounded retention failure after the receipt leaves the ring', async () => {
+    const store = createGpuPassTimingObservationStore({
+      retentionFrames: 2,
+      currentDeviceGeneration: () => 3,
+    });
+    const expired = receipt(1);
+    store.register(expired, async () => complete(1));
+    store.register(receipt(2), async () => complete(2));
+    store.register(receipt(3), async () => complete(3));
+
+    const result = await store.observe(expired, { include: ['timings'] });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.timings).toMatchObject({
+      status: 'failed',
+      error: { code: 'timing-retention-expired' },
+    });
+  });
+});

package/src/__tests__/gpu-pass-timing-session.unit.test.ts

@@ -0,0 +1,438 @@
+import type {
+  Buffer,
+  MappedBuffer,
+  QuerySet,
+  RhiCommandEncoder,
+  RhiDevice,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createGpuPassTimingSession,
+  type GpuPassTimingCapture,
+} from '../record/gpu-pass-timing/session.js';
+
+function makeDevice() {
+  const calls: string[] = [];
+  const buffers: Array<{ size: number; usage: number }> = [];
+  const device = {
+    caps: {
+      backendKind: 'webgpu',
+      timestampQuery: true,
+      timestampPeriodNanoseconds: 1,
+    },
+    createQuerySet: vi.fn(() => {
+      calls.push('create-query-set');
+      return { ok: true, value: {} as QuerySet };
+    }),
+    createBuffer: vi.fn((descriptor: { size: number; usage: number }) => {
+      buffers.push(descriptor);
+      calls.push('create-buffer');
+      return { ok: true, value: {} as Buffer };
+    }),
+    destroyQuerySet: vi.fn(() => {
+      calls.push('destroy-query-set');
+      return { ok: true, value: undefined };
+    }),
+    destroyBuffer: vi.fn(() => {
+      calls.push('destroy-buffer');
+      return { ok: true, value: undefined };
+    }),
+    queue: {
+      onSubmittedWorkDone: vi.fn(async () => undefined),
+    },
+  } as unknown as RhiDevice;
+  return { calls, buffers, device };
+}
+
+function encoder() {
+  return {
+    resolveQuerySet: vi.fn(() => ({ ok: true, value: undefined })),
+    copyBufferToBuffer: vi.fn(),
+    encodeEmptyComputePass: vi.fn(),
+  } as unknown as RhiCommandEncoder;
+}
+
+const identity = {
+  frameId: 12,
+  deviceGeneration: 3,
+  graphGeneration: 4,
+};
+
+describe('GPU pass timing session', () => {
+  it('allocates one query set and two aligned buffers per bounded slot', () => {
+    const { device, buffers } = makeDevice();
+    const created = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 2,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    });
+
+    expect(created.ok).toBe(true);
+    expect(device.createQuerySet).toHaveBeenCalledWith({ type: 'timestamp', count: 4 });
+    expect(buffers).toEqual([
+      { size: 256, usage: expect.any(Number) },
+      { size: 256, usage: expect.any(Number) },
+    ]);
+  });
+
+  it('does not wait or consume a query when all slots are in flight', () => {
+    const { device } = makeDevice();
+    const session = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 1,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const first = session.beginFrame(identity).unwrap();
+    const second = session.beginFrame({ ...identity, frameId: 13 });
+
+    expect(second).toMatchObject({ ok: false, error: { code: 'timing-in-flight-exhausted' } });
+    expect(device.queue.onSubmittedWorkDone).not.toHaveBeenCalled();
+    expect(first.snapshot()).toMatchObject({ frameId: 12, passes: [] });
+  });
+
+  it('records actual pass identity and resolves the used pair on the same encoder tail', () => {
+    const { device } = makeDevice();
+    const session = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 2,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    capture.recordPass({ passName: 'geometry', passKind: 'raster', executionIndex: 0 });
+    capture.recordPass({ passName: 'post', passKind: 'compute', executionIndex: 1 });
+    const commandEncoder = encoder();
+
+    expect(capture.encodeTail(commandEncoder)).toMatchObject({ ok: true });
+    expect(commandEncoder.resolveQuerySet).toHaveBeenCalledWith(
+      expect.anything(),
+      0,
+      4,
+      expect.anything(),
+      0,
+    );
+    expect(capture.snapshot()).toMatchObject({
+      executedPassCount: 2,
+      passes: [
+        { passName: 'geometry', passKind: 'raster', executionIndex: 0 },
+        { passName: 'post', passKind: 'compute', executionIndex: 1 },
+      ],
+    });
+  });
+
+  it('marks both boundaries of an interior copy with dedicated marker passes', () => {
+    const { device } = makeDevice();
+    const session = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 3,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    const first = { passName: 'first', passKind: 'raster' as const, executionIndex: 0 };
+    const copy = { passName: 'copy', passKind: 'copy' as const, executionIndex: 1 };
+    const last = { passName: 'last', passKind: 'raster' as const, executionIndex: 2 };
+    capture.recordPass(first);
+    capture.recordPass(copy);
+    capture.recordPass(last);
+
+    const copyWrites = capture.timestampWrites(copy);
+    expect(copyWrites).toMatchObject({
+      beginningOfPassWriteIndex: 2,
+      endOfPassWriteIndex: 3,
+    });
+
+    const commandEncoder = {
+      ...encoder(),
+      encodeEmptyComputePass: vi.fn(),
+    } as unknown as RhiCommandEncoder;
+    capture.copyBoundaryBefore(copy, commandEncoder);
+    capture.copyBoundaryAfter(copy, commandEncoder);
+    const markerCalls = (commandEncoder.encodeEmptyComputePass as ReturnType<typeof vi.fn>).mock
+      .calls;
+    expect(markerCalls[0]?.[0]).toMatchObject({
+      timestampWrites: { endOfPassWriteIndex: 2 },
+    });
+    expect(markerCalls[1]?.[0]).toMatchObject({
+      timestampWrites: { beginningOfPassWriteIndex: 3 },
+    });
+    expect(markerCalls[0]?.[0]).not.toHaveProperty('label');
+    expect(markerCalls[1]?.[0]).not.toHaveProperty('label');
+    expect(capture.encodeTail(commandEncoder)).toMatchObject({ ok: true });
+    expect(commandEncoder.encodeEmptyComputePass).toHaveBeenCalledTimes(2);
+    expect(commandEncoder.resolveQuerySet).toHaveBeenCalledWith(
+      expect.anything(),
+      0,
+      6,
+      expect.anything(),
+      0,
+    );
+    expect(commandEncoder.copyBufferToBuffer).toHaveBeenCalledWith(
+      expect.anything(),
+      0,
+      expect.anything(),
+      0,
+      48,
+    );
+  });
+
+  it('reuses slot-owned marker descriptors while updating only their query indices', () => {
+    const { device } = makeDevice();
+    const session = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 3,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const copy = { passName: 'copy', passKind: 'copy' as const, executionIndex: 1 };
+    const recordCopy = (capture: GpuPassTimingCapture) => {
+      capture.recordPass({ passName: 'first', passKind: 'raster', executionIndex: 0 });
+      capture.recordPass(copy);
+      capture.recordPass({ passName: 'last', passKind: 'raster', executionIndex: 2 });
+    };
+    const first = session.beginFrame({ ...identity, frameId: 20 }).unwrap();
+    recordCopy(first);
+    const firstEncoder = {
+      ...encoder(),
+      encodeEmptyComputePass: vi.fn(),
+    } as unknown as RhiCommandEncoder;
+    first.copyBoundaryBefore(copy, firstEncoder);
+    first.copyBoundaryAfter(copy, firstEncoder);
+    const firstCalls = (firstEncoder.encodeEmptyComputePass as ReturnType<typeof vi.fn>).mock.calls;
+    first.encodeTail(firstEncoder);
+    first.abort();
+
+    const second = session.beginFrame({ ...identity, frameId: 21 }).unwrap();
+    recordCopy(second);
+    const secondEncoder = {
+      ...encoder(),
+      encodeEmptyComputePass: vi.fn(),
+    } as unknown as RhiCommandEncoder;
+    second.copyBoundaryBefore(copy, secondEncoder);
+    second.copyBoundaryAfter(copy, secondEncoder);
+    const secondCalls = (secondEncoder.encodeEmptyComputePass as ReturnType<typeof vi.fn>).mock
+      .calls;
+
+    expect(secondCalls[0]?.[0]).toBe(firstCalls[0]?.[0]);
+    expect(secondCalls[1]?.[0]).toBe(firstCalls[1]?.[0]);
+    expect(firstCalls[0]?.[0]).toMatchObject({
+      timestampWrites: { endOfPassWriteIndex: 2 },
+    });
+    expect(firstCalls[1]?.[0]).toMatchObject({
+      timestampWrites: { beginningOfPassWriteIndex: 3 },
+    });
+  });
+
+  it.each([
+    ['begin', 1],
+    ['end', 2],
+  ] as const)('turns a raw %s marker throw into a copy-only unmeasured fact', async (phase, failureCall) => {
+    const { device } = makeDevice();
+    const map = vi.fn(async (_buffer: Buffer) =>
+      ok({
+        getMappedRange: () => {
+          const bytes = new ArrayBuffer(256);
+          const view = new DataView(bytes);
+          view.setBigUint64(16, 10n, true);
+          view.setBigUint64(24, 20n, true);
+          return { ok: true, value: bytes };
+        },
+        unmap: vi.fn(),
+      } as unknown as MappedBuffer),
+    );
+    const session = createGpuPassTimingSession(
+      device,
+      { maxPassesPerFrame: 2, maxFramesInFlight: 1, retentionFrames: 8 },
+      { mapReadback: map },
+    ).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    const copy = { passName: 'copy', passKind: 'copy' as const, executionIndex: 0 };
+    const scene = { passName: 'scene', passKind: 'raster' as const, executionIndex: 1 };
+    capture.recordPass(copy);
+    capture.recordPass(scene);
+    let calls = 0;
+    const commandEncoder = {
+      ...encoder(),
+      encodeEmptyComputePass: vi.fn(() => {
+        calls += 1;
+        if (calls === failureCall) throw new Error(`raw ${phase} marker failed`);
+      }),
+    } as unknown as RhiCommandEncoder;
+
+    capture.copyBoundaryBefore(copy, commandEncoder);
+    capture.copyBoundaryAfter(copy, commandEncoder);
+    expect(capture.encodeTail(commandEncoder)).toMatchObject({ ok: true });
+    capture.markSubmitted(Promise.resolve());
+
+    await expect(capture.observe()).resolves.toMatchObject({
+      ok: true,
+      value: {
+        measuredPassCount: 1,
+        passes: [
+          {
+            passName: 'copy',
+            status: 'unmeasured',
+            reason: {
+              code: 'timestamp-write-unavailable',
+              detail: { phase },
+              cause: { message: `raw ${phase} marker failed` },
+            },
+          },
+          { passName: 'scene', status: 'measured', measurementSource: 'pass-boundary' },
+        ],
+      },
+    });
+  });
+
+  it('keeps a failed copy timestamp boundary unmeasured instead of parsing untouched ticks', async () => {
+    const { device } = makeDevice();
+    const session = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 1,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    const copy = { passName: 'copy', passKind: 'copy' as const, executionIndex: 0 };
+    capture.recordPass(copy);
+    expect(capture.timestampWrites(copy)).toBeDefined();
+    capture.markTimestampWriteFailure(copy, 'begin', { code: 'timestamp-write-failed' });
+    capture.markTimestampWriteFailure(copy, 'end', { code: 'second-timestamp-write-failed' });
+
+    const commandEncoder = encoder();
+    expect(capture.encodeTail(commandEncoder)).toMatchObject({ ok: true });
+    expect(commandEncoder.resolveQuerySet).not.toHaveBeenCalled();
+    capture.markSubmitted();
+
+    await expect(capture.observe()).resolves.toMatchObject({
+      ok: true,
+      value: {
+        executedPassCount: 1,
+        measuredPassCount: 0,
+        passes: [
+          {
+            passName: 'copy',
+            status: 'unmeasured',
+            reason: { code: 'timestamp-write-unavailable', detail: { phase: 'begin' } },
+          },
+        ],
+      },
+    });
+  });
+
+  it('preserves a failed copy entry while reading the remaining measured entries', async () => {
+    const { device } = makeDevice();
+    const map = vi.fn(async (_buffer: Buffer) =>
+      ok({
+        getMappedRange: () => {
+          const bytes = new ArrayBuffer(256);
+          const view = new DataView(bytes);
+          view.setBigUint64(16, 10n, true);
+          view.setBigUint64(24, 20n, true);
+          return { ok: true, value: bytes };
+        },
+        unmap: vi.fn(),
+      } as unknown as MappedBuffer),
+    );
+    const session = createGpuPassTimingSession(
+      device,
+      { maxPassesPerFrame: 2, maxFramesInFlight: 1, retentionFrames: 8 },
+      { mapReadback: map },
+    ).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    const failedCopy = { passName: 'copy', passKind: 'copy' as const, executionIndex: 0 };
+    const measuredPass = { passName: 'scene', passKind: 'raster' as const, executionIndex: 1 };
+    capture.recordPass(failedCopy);
+    capture.recordPass(measuredPass);
+    expect(capture.timestampWrites(failedCopy)).toBeDefined();
+    capture.markTimestampWriteFailure(failedCopy, 'end', new Error('end write failed'));
+    expect(capture.timestampWrites(measuredPass)).toBeDefined();
+    expect(capture.encodeTail(encoder())).toMatchObject({ ok: true });
+    capture.markSubmitted();
+
+    const observed = await capture.observe();
+    expect(observed).toMatchObject({
+      ok: true,
+      value: {
+        executedPassCount: 2,
+        measuredPassCount: 1,
+        passes: [
+          { passName: 'copy', status: 'unmeasured' },
+          {
+            passName: 'scene',
+            status: 'measured',
+            measurementSource: 'pass-boundary',
+            durationNanoseconds: 10,
+          },
+        ],
+      },
+    });
+    if (observed.ok) expect(observed.value.passes[1]).not.toHaveProperty('reason');
+  });
+
+  it('reuses a caller-provided queue completion for readback', async () => {
+    const { device } = makeDevice();
+    const map = vi.fn(async (_buffer: Buffer) =>
+      ok({
+        getMappedRange: () => {
+          const bytes = new ArrayBuffer(256);
+          const view = new DataView(bytes);
+          view.setBigUint64(0, 10n, true);
+          view.setBigUint64(8, 20n, true);
+          return { ok: true, value: bytes };
+        },
+        unmap: vi.fn(),
+      } as unknown as MappedBuffer),
+    );
+    const session = createGpuPassTimingSession(
+      device,
+      { maxPassesPerFrame: 1, maxFramesInFlight: 1, retentionFrames: 8 },
+      { mapReadback: map },
+    ).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    const pass = { passName: 'scene', passKind: 'raster' as const, executionIndex: 0 };
+    capture.recordPass(pass);
+    expect(capture.timestampWrites(pass)).toBeDefined();
+    expect(capture.encodeTail(encoder())).toMatchObject({ ok: true });
+
+    capture.markSubmitted(Promise.resolve());
+
+    expect(device.queue.onSubmittedWorkDone).not.toHaveBeenCalled();
+    await expect(capture.observe()).resolves.toMatchObject({
+      ok: true,
+      value: {
+        measuredPassCount: 1,
+        passes: [
+          {
+            status: 'measured',
+            passName: 'scene',
+            measurementSource: 'pass-boundary',
+          },
+        ],
+      },
+    });
+    expect(map).toHaveBeenCalledTimes(1);
+  });
+
+  it('terminalizes submit, map, consumer, abort, and reuse paths exactly once', async () => {
+    const { device } = makeDevice();
+    const map = vi.fn(async (_buffer: Buffer) =>
+      ok({
+        getMappedRange: () => ({ ok: true, value: new ArrayBuffer(256) }),
+        unmap: vi.fn(),
+      } as unknown as MappedBuffer),
+    );
+    const session = createGpuPassTimingSession(
+      device,
+      {
+        maxPassesPerFrame: 1,
+        maxFramesInFlight: 1,
+        retentionFrames: 8,
+      },
+      { mapReadback: map },
+    ).unwrap();
+    const capture = session.beginFrame(identity).unwrap();
+    capture.abort({ code: 'timestamp-readback-failed' });
+    capture.abort({ code: 'timestamp-readback-failed' });
+    await expect(capture.observe()).resolves.toMatchObject({ ok: false });
+    expect(map).not.toHaveBeenCalled();
+    expect(capture.snapshot()).toMatchObject({ frameId: 12 });
+  });
+});

package/src/__tests__/gpu-pass-timing.browser.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { runBrowserGpuPassTiming } from './gpu-pass-timing-browser-runner.js';
+
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe.skipIf(!browserReady)('GPU pass timing Browser dev-server runner', () => {
+  it('keeps receipt facts and unsupported timing structured without stopping draw', async () => {
+    const result = await runBrowserGpuPassTiming();
+    expect(result.frames).toBe(3);
+    if (result.supported) {
+      expect(result.unavailable).toBe(false);
+      expect(result.measuredPasses).toBeGreaterThan(0);
+    } else {
+      expect(result.unavailable).toBe(true);
+      expect(result.measuredPasses).toBe(0);
+    }
+    expect(result.visible).toBe(true);
+  });
+
+  it('keeps raster suppression as a test-only falsifier, never timing evidence', async () => {
+    const result = await runBrowserGpuPassTiming({ suppressRaster: true });
+    expect(result.rasterSuppressed).toBe(true);
+    expect(result.frames).toBe(3);
+    if (result.supported) expect(result.measuredPasses).toBeGreaterThan(0);
+  });
+});