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

package/src/recorder/pass.ts

@@ -0,0 +1,241 @@
+// @forgeax/engine-rhi-debug/src/recorder/pass -- render/compute pass proxy owners.
+
+import type {
+  ComputePipeline,
+  RenderPipeline,
+  RhiComputePassEncoder,
+  RhiRenderPassEncoder,
+} from '@forgeax/engine-rhi';
+import type { HandleId } from '../types';
+import type { RecorderInternal } from './core';
+import { getHandleId, pushEvent } from './core';
+
+export function createRenderPassProxy(
+  s: RecorderInternal,
+  realPass: RhiRenderPassEncoder,
+  passHId: HandleId,
+): RhiRenderPassEncoder {
+  return {
+    setPipeline(pipeline: RenderPipeline) {
+      const pid = getHandleId(s, pipeline as object, 'renderPipeline');
+      pushEvent(s, { kind: 'setPipeline', passHandleId: passHId, pipelineHandleId: pid });
+      realPass.setPipeline(pipeline);
+    },
+    setVertexBuffer(slot, buffer, offset, size) {
+      const bid = getHandleId(s, buffer as object, 'buffer');
+      pushEvent(s, {
+        kind: 'setVertexBuffer',
+        passHandleId: passHId,
+        slot,
+        bufferHandleId: bid,
+        offset,
+        size,
+      });
+      realPass.setVertexBuffer(slot, buffer, offset, size);
+    },
+    setIndexBuffer(buffer, format, offset, size) {
+      const bid = getHandleId(s, buffer as object, 'buffer');
+      pushEvent(s, {
+        kind: 'setIndexBuffer',
+        passHandleId: passHId,
+        bufferHandleId: bid,
+        format,
+        offset,
+        size,
+      });
+      realPass.setIndexBuffer(buffer, format, offset, size);
+    },
+    setBindGroup(index, bindGroup, ...rest: unknown[]) {
+      const bgid = getHandleId(s, bindGroup as object, 'bindGroup');
+      let dynOffsets: readonly number[] | undefined;
+      if (rest[0] instanceof Uint32Array) {
+        dynOffsets = Array.from(rest[0] as Uint32Array);
+        (realPass.setBindGroup as (...args: unknown[]) => void)(index, bindGroup, ...rest);
+      } else {
+        const offsets = rest[0] as readonly number[] | undefined;
+        dynOffsets = offsets === undefined ? undefined : Array.from(offsets);
+        realPass.setBindGroup(index, bindGroup, offsets);
+      }
+      pushEvent(s, {
+        kind: 'setBindGroup',
+        passHandleId: passHId,
+        index,
+        bindGroupHandleId: bgid,
+        dynamicOffsets: dynOffsets,
+      });
+    },
+    draw(vertexCount, instanceCount, firstVertex, firstInstance) {
+      pushEvent(s, {
+        kind: 'draw',
+        passHandleId: passHId,
+        vertexCount,
+        instanceCount: instanceCount ?? 1,
+        firstVertex: firstVertex ?? 0,
+        firstInstance: firstInstance ?? 0,
+      });
+      realPass.draw(vertexCount, instanceCount, firstVertex, firstInstance);
+    },
+    drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance) {
+      pushEvent(s, {
+        kind: 'drawIndexed',
+        passHandleId: passHId,
+        indexCount,
+        instanceCount: instanceCount ?? 1,
+        firstIndex: firstIndex ?? 0,
+        baseVertex: baseVertex ?? 0,
+        firstInstance: firstInstance ?? 0,
+      });
+      realPass.drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance);
+    },
+
+    // Pass-through methods (not in v1 event set, but must not break the proxy)
+    setViewport(x, y, w, h, minDepth, maxDepth) {
+      pushEvent(s, {
+        kind: 'setViewport',
+        passHandleId: passHId,
+        x,
+        y,
+        w,
+        h,
+        minDepth: minDepth ?? 0,
+        maxDepth: maxDepth ?? 1,
+      });
+      realPass.setViewport(x, y, w, h, minDepth, maxDepth);
+    },
+    setScissorRect(x, y, w, h) {
+      pushEvent(s, {
+        kind: 'setScissorRect',
+        passHandleId: passHId,
+        x,
+        y,
+        w,
+        h,
+      });
+      realPass.setScissorRect(x, y, w, h);
+    },
+    setBlendConstant(color) {
+      pushEvent(s, {
+        kind: 'setBlendConstant',
+        passHandleId: passHId,
+        color,
+      });
+      realPass.setBlendConstant(color);
+    },
+    setStencilReference(reference) {
+      // Recorded (not a no-op pass-through): stencil pipelines compare against
+      // this dynamic reference, so without it replay defaults ref=0 and a
+      // not-equal/equal stencil test (e.g. the 4.2 stencil-testing outline
+      // pass) silently breaks -- the outline vanishes on replay.
+      pushEvent(s, {
+        kind: 'setStencilReference',
+        passHandleId: passHId,
+        reference,
+      });
+      realPass.setStencilReference(reference);
+    },
+    drawIndirect(indirectBuffer, indirectOffset) {
+      const ibId = getHandleId(s, indirectBuffer as object, 'buffer');
+      pushEvent(s, {
+        kind: 'drawIndirect',
+        passHandleId: passHId,
+        indirectBufferHandleId: ibId,
+        indirectOffset,
+      });
+      realPass.drawIndirect(indirectBuffer, indirectOffset);
+    },
+    drawIndexedIndirect(indirectBuffer, indirectOffset) {
+      const ibId = getHandleId(s, indirectBuffer as object, 'buffer');
+      pushEvent(s, {
+        kind: 'drawIndexedIndirect',
+        passHandleId: passHId,
+        indirectBufferHandleId: ibId,
+        indirectOffset,
+      });
+      realPass.drawIndexedIndirect(indirectBuffer, indirectOffset);
+    },
+    pushDebugGroup(groupLabel) {
+      pushEvent(s, {
+        kind: 'passPushDebugGroup',
+        passHandleId: passHId,
+        groupLabel,
+      });
+      realPass.pushDebugGroup(groupLabel);
+    },
+    popDebugGroup() {
+      pushEvent(s, { kind: 'passPopDebugGroup', passHandleId: passHId });
+      realPass.popDebugGroup();
+    },
+    insertDebugMarker(markerLabel) {
+      pushEvent(s, {
+        kind: 'passInsertDebugMarker',
+        passHandleId: passHId,
+        markerLabel,
+      });
+      realPass.insertDebugMarker(markerLabel);
+    },
+    executeBundles(bundles) {
+      return realPass.executeBundles(bundles);
+    },
+    beginOcclusionQuery(queryIndex) {
+      return realPass.beginOcclusionQuery(queryIndex);
+    },
+    endOcclusionQuery() {
+      return realPass.endOcclusionQuery();
+    },
+    end() {
+      pushEvent(s, { kind: 'endRenderPass', passHandleId: passHId });
+      realPass.end();
+    },
+  };
+}
+
+export function createComputePassProxy(
+  s: RecorderInternal,
+  realPass: RhiComputePassEncoder,
+  passHId: HandleId,
+): RhiComputePassEncoder {
+  return {
+    setPipeline(pipeline: ComputePipeline) {
+      const pid = getHandleId(s, pipeline as object, 'computePipeline');
+      pushEvent(s, { kind: 'setComputePipeline', passHandleId: passHId, pipelineHandleId: pid });
+      realPass.setPipeline(pipeline);
+    },
+    setBindGroup(index, bindGroup, dynamicOffsets) {
+      const bgid = getHandleId(s, bindGroup as object, 'bindGroup');
+      const recordedDynamicOffsets =
+        dynamicOffsets === undefined ? undefined : Array.from(dynamicOffsets);
+      pushEvent(s, {
+        kind: 'setBindGroup',
+        passHandleId: passHId,
+        index,
+        bindGroupHandleId: bgid,
+        dynamicOffsets: recordedDynamicOffsets,
+      });
+      realPass.setBindGroup(index, bindGroup, dynamicOffsets);
+    },
+    dispatchWorkgroups(x, y, z) {
+      pushEvent(s, {
+        kind: 'dispatchWorkgroups',
+        passHandleId: passHId,
+        x,
+        y: y ?? 1,
+        z: z ?? 1,
+      });
+      realPass.dispatchWorkgroups(x, y, z);
+    },
+    dispatchWorkgroupsIndirect(indirectBuffer, indirectOffset) {
+      const bufferHandleId = getHandleId(s, indirectBuffer as object, 'buffer');
+      pushEvent(s, {
+        kind: 'dispatchWorkgroupsIndirect',
+        passHandleId: passHId,
+        indirectBufferHandleId: bufferHandleId,
+        indirectOffset,
+      });
+      realPass.dispatchWorkgroupsIndirect(indirectBuffer, indirectOffset);
+    },
+    end() {
+      pushEvent(s, { kind: 'endComputePass', passHandleId: passHId });
+      realPass.end();
+    },
+  };
+}

package/src/recorder/proxy.ts

@@ -0,0 +1,59 @@
+import type { RhiCanvasContext, RhiDevice, RhiError, RhiInstance } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { createRhiDebugError, type RhiDebugError } from '../errors';
+import {
+  type CreateShaderModuleFn,
+  type DebugRhiInstance,
+  wrap,
+  wrapCreateShaderModule,
+} from '../recorder';
+
+export interface RecordableBackend {
+  readonly rhi: RhiInstance & {
+    readonly acquireCanvasContext?: (
+      canvas: HTMLCanvasElement | OffscreenCanvas,
+    ) => Result<RhiCanvasContext, RhiError>;
+  };
+  readonly createShaderModule: CreateShaderModuleFn;
+}
+
+export interface RecorderBackend extends RecordableBackend {
+  readonly unwrapDeviceForSurface: (device: RhiDevice) => Result<RhiDevice, RhiDebugError>;
+}
+
+export interface RecorderProxy {
+  readonly backend: RecorderBackend;
+  readonly recorder: DebugRhiInstance;
+}
+
+export function createRecorderProxy(backend: RecordableBackend): RecorderProxy {
+  const recorder = wrap(backend.rhi);
+  const wrappedCreateShaderModule = wrapCreateShaderModule(backend.createShaderModule, recorder);
+  const acquireCanvasContext = backend.rhi.acquireCanvasContext;
+  // Runtime's explicit-RHI seam receives the wrapped singleton as one value.
+  // Keep the standalone shader factory enumerable on that value so the
+  // renderer can preserve the complete typed backend pack after capture
+  // attachment; the public RhiInstance contract remains unchanged.
+  const rhi: RecordableBackend['rhi'] & { readonly createShaderModule: CreateShaderModuleFn } = {
+    requestAdapter: recorder.requestAdapter.bind(recorder),
+    createShaderModule: wrappedCreateShaderModule,
+    ...(acquireCanvasContext === undefined
+      ? {}
+      : { acquireCanvasContext: acquireCanvasContext.bind(backend.rhi) }),
+  };
+  const wrappedBackend: RecorderBackend = {
+    rhi,
+    createShaderModule: wrappedCreateShaderModule,
+    unwrapDeviceForSurface(device) {
+      const raw = (device as RhiDevice & { readonly _realDevice?: RhiDevice })._realDevice;
+      if (raw !== undefined) return ok(raw);
+      return err(
+        createRhiDebugError('capture-unavailable', {
+          stage: 'capture',
+          cause: 'the recorder backend does not expose a surface device resolver',
+        }),
+      );
+    },
+  };
+  return { backend: wrappedBackend, recorder };
+}

package/src/recorder/queue.ts

@@ -0,0 +1,109 @@
+// @forgeax/engine-rhi-debug/src/recorder/queue -- queue proxy owner.
+
+import type { Buffer, CommandBuffer, RhiQueue } from '@forgeax/engine-rhi';
+import type { RhiCallEventWriteTexture } from '../types';
+import type { RecorderInternal } from './core';
+import { getHandleId, pushEvent, shouldRecord, storeBlob } from './core';
+
+export function createQueueProxy(s: RecorderInternal, realQueue: RhiQueue): RhiQueue {
+  return {
+    writeBuffer(
+      buffer: Buffer,
+      bufferOffset: number,
+      data: ArrayBufferView | ArrayBuffer,
+      dataOffset?: number,
+      size?: number,
+    ) {
+      // Idle fast-path: when not recording, skip getHandleId + slice + the
+      // storeBlob hash-and-double-copy entirely (they would only feed a
+      // pushEvent that the state gate drops, and blobPool is reset on arm()).
+      // Same-condition-as-pushEvent, so a recording call still records.
+      if (!shouldRecord(s)) {
+        return realQueue.writeBuffer(buffer, bufferOffset, data, dataOffset, size);
+      }
+      const hId = getHandleId(s, buffer as object, 'buffer');
+      const raw = ArrayBuffer.isView(data)
+        ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+        : new Uint8Array(data as ArrayBuffer);
+      const sz = size ?? raw.byteLength - (dataOffset ?? 0);
+      const slice = raw.slice(dataOffset ?? 0, (dataOffset ?? 0) + sz);
+      const dataHash = storeBlob(s, slice.buffer as ArrayBuffer);
+
+      pushEvent(s, {
+        kind: 'writeBuffer',
+        handleId: hId,
+        bufferOffset,
+        dataHash,
+        size: sz,
+      });
+      return realQueue.writeBuffer(buffer, bufferOffset, data, dataOffset, size);
+    },
+
+    writeTexture(destination, data, dataLayout, copySize) {
+      // Idle fast-path (see writeBuffer): skip storeBlob hash+copy when the
+      // recorded event would be dropped anyway.
+      if (!shouldRecord(s)) {
+        return realQueue.writeTexture(destination, data, dataLayout, copySize);
+      }
+      const hId = getHandleId(s, destination.texture as object, 'texture');
+      const raw = ArrayBuffer.isView(data)
+        ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+        : new Uint8Array(data as ArrayBuffer);
+      const dataHash = storeBlob(s, raw.buffer as ArrayBuffer);
+
+      pushEvent(s, {
+        kind: 'writeTexture',
+        destination: {
+          textureHandleId: hId,
+          mipLevel: destination.mipLevel,
+          origin: destination.origin,
+          aspect: destination.aspect,
+        },
+        dataHash,
+        dataLayout: {
+          offset: dataLayout.offset,
+          bytesPerRow: dataLayout.bytesPerRow,
+          rowsPerImage: dataLayout.rowsPerImage,
+        },
+        size: copySize,
+      } as RhiCallEventWriteTexture);
+      return realQueue.writeTexture(destination, data, dataLayout, copySize);
+    },
+
+    copyExternalImageToTexture(source, destination, copySize) {
+      if (!shouldRecord(s)) {
+        return realQueue.copyExternalImageToTexture(source, destination, copySize);
+      }
+      const hId = getHandleId(s, destination.texture as object, 'texture');
+      pushEvent(s, {
+        kind: 'copyExternalImageToTexture',
+        source: { origin: source.origin, flipY: source.flipY },
+        destination: {
+          textureHandleId: hId,
+          mipLevel: destination.mipLevel,
+          origin: destination.origin,
+          aspect: destination.aspect,
+          colorSpace: destination.colorSpace,
+          premultipliedAlpha: destination.premultipliedAlpha,
+        },
+        copySize,
+      });
+      return realQueue.copyExternalImageToTexture(source, destination, copySize);
+    },
+
+    submit(commandBuffers: readonly CommandBuffer[]) {
+      if (!shouldRecord(s)) {
+        return realQueue.submit(commandBuffers);
+      }
+      const cmdHandleIds = commandBuffers.map((cb) =>
+        getHandleId(s, cb as object, 'commandBuffer'),
+      );
+      pushEvent(s, { kind: 'submit', cmdHandleIds });
+      return realQueue.submit(commandBuffers);
+    },
+
+    onSubmittedWorkDone() {
+      return realQueue.onSubmittedWorkDone();
+    },
+  };
+}

package/src/recorder/resource-registry.ts

@@ -0,0 +1,53 @@
+import type { DebugRhiInstance } from '../recorder';
+import type { HandleId } from '../types';
+
+export interface ResourceCandidate {
+  readonly handleId: HandleId;
+  readonly kind: 'buffer' | 'texture';
+  readonly estimatedBytes: number;
+}
+
+export class ResourceRegistry {
+  constructor(private readonly recorder: DebugRhiInstance) {}
+
+  candidates(): readonly ResourceCandidate[] {
+    return Array.from(this.recorder.descriptorTable(), ([handleId, descriptor]) => ({
+      handleId,
+      kind: descriptor.kind,
+      estimatedBytes: estimateBytes(descriptor),
+    }));
+  }
+
+  estimateSnapshotBytes(): number {
+    return this.candidates().reduce((total, candidate) => total + candidate.estimatedBytes, 0);
+  }
+
+  clearGeneration(): void {
+    this.recorder.transitionToError();
+    this.recorder.resetForDeviceLoss();
+  }
+}
+
+function estimateBytes(descriptor: {
+  readonly kind: 'buffer' | 'texture';
+  readonly size?: number | GPUExtent3DStrict;
+}): number {
+  if (descriptor.kind === 'buffer') {
+    return typeof descriptor.size === 'number' ? descriptor.size : 0;
+  }
+  if (descriptor.size === undefined || typeof descriptor.size === 'number') return 4;
+  if (Array.isArray(descriptor.size)) {
+    return Math.max(
+      1,
+      (descriptor.size[0] ?? 1) * (descriptor.size[1] ?? 1) * (descriptor.size[2] ?? 1) * 4,
+    );
+  }
+  if (!('width' in descriptor.size)) return 4;
+  return Math.max(
+    1,
+    descriptor.size.width *
+      (descriptor.size.height ?? 1) *
+      (descriptor.size.depthOrArrayLayers ?? 1) *
+      4,
+  );
+}

package/src/recorder/session.ts

@@ -0,0 +1,152 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { createRhiDebugError, type RhiDebugError } from '../errors';
+import { assembleTape, type EncodedTape } from './assemble';
+import { createRecorderProxy, type RecordableBackend, type RecorderBackend } from './proxy';
+import { ResourceRegistry } from './resource-registry';
+import { snapshotFrame } from './snapshot';
+
+export interface CaptureFrameOptions {
+  readonly snapshotTimeoutMs?: number;
+  readonly byteBudget?: number;
+  readonly signal?: AbortSignal;
+}
+
+export interface RecorderOptions {
+  readonly snapshotTimeoutMs?: number;
+  readonly byteBudget?: number;
+}
+
+export interface RecorderAttachment {
+  readonly backend: RecorderBackend;
+  captureFrame(options?: CaptureFrameOptions): Promise<Result<EncodedTape, RhiDebugError>>;
+  frameBoundary(): Promise<Result<void, RhiDebugError>>;
+  deviceLost(): void;
+  dispose(): Promise<Result<void, RhiDebugError>>;
+}
+
+type Phase = 'idle' | 'armed' | 'snapshotting' | 'recording' | 'disposed';
+
+export function attachRecorder(
+  backend: RecordableBackend,
+  options: RecorderOptions = {},
+): Result<RecorderAttachment, RhiDebugError> {
+  const proxy = createRecorderProxy(backend);
+  const registry = new ResourceRegistry(proxy.recorder);
+  let phase: Phase = 'idle';
+  let generation = 0;
+  let active:
+    | {
+        readonly generation: number;
+        readonly options: CaptureFrameOptions;
+        readonly resolve: (result: Result<EncodedTape, RhiDebugError>) => void;
+        readonly signal?: AbortSignal;
+        abortListener?: () => void;
+      }
+    | undefined;
+
+  const fail = <T>(
+    code: 'capture-unavailable' | 'capture-busy',
+    cause: string,
+  ): Result<T, RhiDebugError> => err(createRhiDebugError(code, { stage: 'capture', cause }));
+
+  const settle = (result: Result<EncodedTape, RhiDebugError>): void => {
+    const request = active;
+    if (request === undefined) return;
+    active = undefined;
+    request.signal?.removeEventListener('abort', request.abortListener ?? (() => {}));
+    if (!result.ok && proxy.recorder.getState() === 'error') proxy.recorder.disposeError();
+    phase = phase === 'disposed' ? 'disposed' : 'idle';
+    request.resolve(result);
+  };
+
+  const abort = (): void => {
+    if (active === undefined) return;
+    proxy.recorder.transitionToError();
+    settle(fail('capture-unavailable', 'capture request was aborted'));
+  };
+
+  const attachment: RecorderAttachment = {
+    backend: proxy.backend,
+    captureFrame(captureOptions = {}) {
+      if (phase === 'disposed')
+        return Promise.resolve(fail('capture-unavailable', 'recorder is disposed'));
+      if (active !== undefined)
+        return Promise.resolve(fail('capture-busy', 'another capture is active'));
+      const signal = captureOptions.signal;
+      if (signal?.aborted)
+        return Promise.resolve(fail('capture-unavailable', 'capture request was aborted'));
+      const arm = proxy.recorder.arm(1);
+      if (!arm.ok) return Promise.resolve(fail('capture-busy', arm.error.hint));
+      phase = 'armed';
+      generation += 1;
+      return new Promise<Result<EncodedTape, RhiDebugError>>((resolve) => {
+        const request = {
+          generation,
+          options: captureOptions,
+          resolve,
+          ...(signal === undefined ? {} : { signal }),
+        } as {
+          readonly generation: number;
+          readonly options: CaptureFrameOptions;
+          readonly resolve: (result: Result<EncodedTape, RhiDebugError>) => void;
+          readonly signal?: AbortSignal;
+          abortListener?: () => void;
+        };
+        request.abortListener = abort;
+        active = request;
+        signal?.addEventListener('abort', abort, { once: true });
+      });
+    },
+    async frameBoundary() {
+      if (phase === 'disposed' || active === undefined) return ok(undefined);
+      const request = active;
+      if (request.generation !== generation) return ok(undefined);
+      if (phase === 'armed') {
+        phase = 'snapshotting';
+        const result = await snapshotFrame(proxy.recorder, registry, {
+          snapshotTimeoutMs:
+            request.options.snapshotTimeoutMs ?? options.snapshotTimeoutMs ?? 30_000,
+          byteBudget: request.options.byteBudget ?? options.byteBudget ?? Number.MAX_SAFE_INTEGER,
+        });
+        if (!result.ok) {
+          proxy.recorder.transitionToError();
+          settle(err(result.error));
+          return err(result.error);
+        }
+        phase = 'recording';
+        return ok(undefined);
+      }
+      if (phase !== 'recording') return ok(undefined);
+      proxy.recorder.onFrameEnd();
+      if (proxy.recorder.getState() !== 'idle') return ok(undefined);
+      const result = assembleTape(proxy.recorder);
+      settle(result);
+      return result.ok ? ok(undefined) : err(result.error);
+    },
+    deviceLost() {
+      generation += 1;
+      registry.clearGeneration();
+      if (active !== undefined) {
+        phase = 'idle';
+        settle(fail('capture-unavailable', 'device loss invalidated the active generation'));
+      } else if (phase !== 'disposed') {
+        phase = 'idle';
+      }
+    },
+    async dispose() {
+      if (phase === 'disposed') return ok(undefined);
+      if (active !== undefined) {
+        proxy.recorder.transitionToError();
+        settle(fail('capture-unavailable', 'recorder was disposed during capture'));
+      }
+      proxy.recorder.disposeError();
+      phase = 'disposed';
+      return ok(undefined);
+    },
+  };
+  return ok(attachment);
+}
+
+export type { CreateShaderModuleFn } from '../recorder';
+export type { EncodedTape } from './assemble';
+export type { RecordableBackend, RecorderBackend } from './proxy';

package/src/recorder/shader.ts

@@ -0,0 +1,47 @@
+// @forgeax/engine-rhi-debug/src/recorder/shader -- standalone shader factory proxy.
+
+import type { Result, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
+import type { HandleId } from '../types';
+import type { CreateShaderModuleFn, DebugRhiInstance } from './core';
+
+export function wrapCreateShaderModule(
+  originalFn: CreateShaderModuleFn,
+  debugInst: DebugRhiInstance,
+): CreateShaderModuleFn {
+  return async function wrappedCreateShaderModule(
+    device: RhiDevice,
+    desc: { code: string; label?: string | undefined },
+  ): Promise<Result<ShaderModule, import('@forgeax/engine-rhi').RhiError>> {
+    // The renderer threads the proxied RhiDevice (from proxyDevice()) here, but
+    // engine-rhi-webgpu's createShaderModule reverse-looks-up the GPUDevice via
+    // a WeakMap keyed on the RhiDevice that makeRhiDevice registered. The proxy
+    // is a different JS object, so WeakMap.get(proxy) is undefined and the real
+    // fn returns shader-compile-failed ("unregistered RhiDevice"). Unwrap the
+    // proxy to the registered device via the _realDevice escape hatch that
+    // proxyDevice exposes for exactly this purpose.
+    const realDevice = (device as RhiDevice & { _realDevice?: RhiDevice })._realDevice ?? device;
+    const result = await originalFn(realDevice, desc);
+    if (!result.ok) return result;
+
+    // I-12 (round 1 implement-review) fix: route the createShaderModule
+    // event through the same `pushExternalEvent` helper that wraps the
+    // internal `pushEvent` (and therefore the `_skipRecord` + state-machine
+    // guard). The previous `(events as RhiCallEvent[]).push(...)` cast
+    // bypassed those guards — recorder-internal RHI calls during shader
+    // construction would have self-polluted the tape.
+    const hId = debugInst.pushExternalCreateEvent(result.value, 'shaderModule', {
+      kind: 'createShaderModule',
+      handleId: '' as HandleId,
+      wgslCode: desc.code,
+    });
+    // Register the shader module handle in the recorder's handleMap so
+    // downstream pipeline events (createRenderPipeline / createComputePipeline)
+    // can resolve the handleId via getHandleId. Required for cross-device
+    // replay: the tape's pipeline desc carries live GPU module objects which
+    // are device-bound, so the replayer must swap them with re-created shader
+    // modules from the handleMap using the handleId.
+    debugInst.registerShaderModule(result.value, hId);
+
+    return result;
+  };
+}