@forgeax/engine-rhi-debug 0.1.28 → 0.1.30

package/src/recorder/closure.ts

@@ -135,17 +135,22 @@ export function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]
           cmdHandleId: HandleId;
           colorAttachmentViewHandleIds: readonly (HandleId | undefined)[];
           depthStencilViewHandleId?: HandleId;
+          occlusionQuerySetHandleId?: HandleId;
+          timestampQuerySetHandleId?: HandleId;
         };
         refs.add(we.cmdHandleId);
         for (const vhId of we.colorAttachmentViewHandleIds) {
           if (vhId !== undefined) refs.add(vhId);
         }
         if (we.depthStencilViewHandleId !== undefined) refs.add(we.depthStencilViewHandleId);
+        if (we.occlusionQuerySetHandleId !== undefined) refs.add(we.occlusionQuerySetHandleId);
+        if (we.timestampQuerySetHandleId !== undefined) refs.add(we.timestampQuerySetHandleId);
         break;
       }
       case 'beginComputePass': {
-        const we = e as { cmdHandleId: HandleId };
+        const we = e as { cmdHandleId: HandleId; timestampQuerySetHandleId?: HandleId };
         refs.add(we.cmdHandleId);
+        if (we.timestampQuerySetHandleId !== undefined) refs.add(we.timestampQuerySetHandleId);
         break;
       }
       case 'finish': {
@@ -204,6 +209,7 @@ export function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]
         break;
       }
       case 'createBindGroup':
+      case 'getBindGroupLayout':
       case 'createPipelineLayout':
       case 'createRenderPipeline':
       case 'createComputePipeline':
@@ -223,17 +229,28 @@ export function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]
       }
       case 'destroyBuffer':
       case 'destroyTexture':
+      case 'destroyQuerySet':
         refs.add(e.handleId);
         break;
       case 'frameMark':
       case 'createBuffer':
       case 'createTexture':
+      case 'createQuerySet':
       case 'createSampler':
       case 'createBindGroupLayout':
       case 'createShaderModule':
       case 'createCommandEncoder':
         // Leaf declaration events — no backward references to collect.
         break;
+      case 'resolveQuerySet':
+        refs.add(e.cmdHandleId);
+        refs.add(e.querySetHandleId);
+        refs.add(e.destinationHandleId);
+        break;
+      case 'beginOcclusionQuery':
+      case 'endOcclusionQuery':
+        refs.add(e.passHandleId);
+        break;
       default: {
         // Exhaustiveness guard: if a new RhiCallEvent member is added to the
         // union without a corresponding handle-collection case, tsc fails here.
@@ -292,8 +309,11 @@ export function _getCreateEventReferencedHandleIds(event: RhiCallEvent): HandleI
       const e = event as { sourceHandleId: HandleId };
       return [e.sourceHandleId];
     }
+    case 'getBindGroupLayout':
+      return [(event as { pipelineHandleId: HandleId }).pipelineHandleId];
     case 'createBuffer':
     case 'createTexture':
+    case 'createQuerySet':
     case 'createSampler':
     case 'createBindGroupLayout':
     case 'createShaderModule':

package/src/recorder/core.ts

@@ -5,6 +5,7 @@
 import type {
   Result,
   RhiDevice,
+  RhiError,
   RhiInstance,
   ShaderModule,
   TextureView,
@@ -557,6 +558,16 @@ export type CreateShaderModuleFn = (
   desc: { code: string; label?: string | undefined },
 ) => Promise<Result<ShaderModule, import('@forgeax/engine-rhi').RhiError>>;
 
+/**
+ * Synchronous shader-module factory used by the render path's immediate
+ * adapter. Keep it in the recordable backend contract so attaching RHI-debug
+ * does not silently remove the renderer's first-use fast path.
+ */
+export type CreateShaderModuleImmediateFn = (
+  device: RhiDevice,
+  desc: { code: string; label?: string | undefined },
+) => Result<ShaderModule, RhiError>;
+
 export type { RecorderInternal, SnapshotProgress };
 export {
   addSwapchainViewFormat,

package/src/recorder/device.ts

@@ -40,6 +40,7 @@ import {
   TEXTURE_USAGE_COPY_SRC,
 } from './core';
 import { createCommandEncoderProxy } from './encoder';
+import { wrapPipeline } from './pipeline';
 import { createQueueProxy } from './queue';
 
 export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): RhiDevice {
@@ -338,9 +339,9 @@ export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): R
         vertexShaderModuleHandleId,
         fragmentShaderModuleHandleId,
       };
-      registerHandle(s, res.value as object, 'renderPipeline', event);
+      const pipelineId = registerHandle(s, res.value as object, 'renderPipeline', event);
       pushEvent(s, event);
-      return res;
+      return makeOk(wrapPipeline(s, res.value, pipelineId));
     },
 
     createComputePipeline(desc: ComputePipelineDescriptor) {
@@ -364,13 +365,26 @@ export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): R
         layoutHandleId: layoutId,
         computeShaderModuleHandleId,
       };
-      registerHandle(s, res.value as object, 'computePipeline', event);
+      const pipelineId = registerHandle(s, res.value as object, 'computePipeline', event);
       pushEvent(s, event);
-      return res;
+      return makeOk(wrapPipeline(s, res.value, pipelineId));
     },
 
     createQuerySet(desc: QuerySetDescriptor) {
-      return realDevice.createQuerySet(desc);
+      const res = realDevice.createQuerySet(desc);
+      if (!res.ok) return res;
+      const event: RhiCallEvent = {
+        kind: 'createQuerySet',
+        handleId: '' as HandleId,
+        desc: {
+          ...(desc.label === undefined ? {} : { label: desc.label }),
+          type: desc.type ?? 'occlusion',
+          count: desc.count ?? 0,
+        },
+      };
+      registerHandle(s, res.value as object, 'querySet', event);
+      pushEvent(s, event);
+      return res;
     },
 
     destroyBuffer(buf: Buffer) {
@@ -419,7 +433,20 @@ export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): R
     },
 
     destroyQuerySet(querySet: QuerySet) {
-      return realDevice.destroyQuerySet(querySet);
+      const hId = s.handleMap.get(querySet as object);
+      const res = realDevice.destroyQuerySet(querySet);
+      if (!res.ok) return res;
+      if (hId !== undefined) {
+        if (
+          !retainsCaptureBootstrap(s) &&
+          !s.snapshotSeededHandles.has(hId) &&
+          !hasBootstrapDependency(s, hId)
+        ) {
+          s.bootstrapCreates.delete(hId);
+        }
+        pushEvent(s, { kind: 'destroyQuerySet', handleId: hId });
+      }
+      return res;
     },
 
     destroyTexture(tex: Texture) {

package/src/recorder/encoder.ts

@@ -54,6 +54,10 @@ export function createCommandEncoderProxy(
         kind: 'beginRenderPass',
         cmdHandleId: cmdHId,
         passHandleId: passHId,
+        timestampQuerySetHandleId:
+          desc?.timestampWrites === undefined
+            ? undefined
+            : getHandleId(s, desc.timestampWrites.querySet as object, 'querySet'),
         desc: {
           colorAttachments: Array.from(desc.colorAttachments).map((attachment) =>
             attachment === null || attachment === undefined ? attachment : { ...attachment },
@@ -61,15 +65,23 @@ export function createCommandEncoderProxy(
           ...(desc.depthStencilAttachment === undefined
             ? {}
             : { depthStencilAttachment: { ...desc.depthStencilAttachment } }),
-          ...(desc.occlusionQuerySet === undefined
+          ...(desc.timestampWrites === undefined
             ? {}
-            : { occlusionQuerySet: desc.occlusionQuerySet }),
-          ...(desc.timestampWrites === undefined ? {} : { timestampWrites: desc.timestampWrites }),
+            : { timestampWrites: recordTimestampWrites(desc.timestampWrites) }),
           ...(desc.maxDrawCount === undefined ? {} : { maxDrawCount: desc.maxDrawCount }),
         },
         colorAttachmentViewHandleIds,
         colorAttachmentResolveTargetHandleIds,
         depthStencilViewHandleId,
+        ...(desc.occlusionQuerySet === undefined
+          ? {}
+          : {
+              occlusionQuerySetHandleId: getHandleId(
+                s,
+                desc.occlusionQuerySet as object,
+                'querySet',
+              ),
+            }),
       });
       const realPass = realEnc.beginRenderPass(desc);
       return createRenderPassProxy(s, realPass, passHId);
@@ -80,7 +92,17 @@ export function createCommandEncoderProxy(
         kind: 'beginComputePass',
         cmdHandleId: cmdHId,
         passHandleId: passHId,
-        desc: desc as Partial<GPUComputePassDescriptor> | undefined,
+        timestampQuerySetHandleId:
+          desc?.timestampWrites === undefined
+            ? undefined
+            : getHandleId(s, desc.timestampWrites.querySet as object, 'querySet'),
+        desc:
+          desc === undefined
+            ? undefined
+            : {
+                ...(desc.label === undefined ? {} : { label: desc.label }),
+                timestampWrites: recordTimestampWrites(desc.timestampWrites),
+              },
       });
       const realPass = realEnc.beginComputePass(desc);
       return createComputePassProxy(s, realPass, passHId);
@@ -91,7 +113,14 @@ export function createCommandEncoderProxy(
         kind: 'beginComputePass',
         cmdHandleId: cmdHId,
         passHandleId: passHId,
-        desc: desc as unknown as Partial<GPUComputePassDescriptor>,
+        timestampQuerySetHandleId:
+          desc?.timestampWrites === undefined
+            ? undefined
+            : getHandleId(s, desc.timestampWrites.querySet as object, 'querySet'),
+        desc: {
+          ...(desc.label === undefined ? {} : { label: desc.label }),
+          timestampWrites: recordTimestampWrites(desc.timestampWrites),
+        },
       });
       realEnc.encodeEmptyComputePass(desc);
       pushEvent(s, { kind: 'endComputePass', passHandleId: passHId });
@@ -220,13 +249,25 @@ export function createCommandEncoderProxy(
       realEnc.clearBuffer(buffer, offset, size);
     },
     resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset) {
-      return realEnc.resolveQuerySet(
+      const result = realEnc.resolveQuerySet(
         querySet,
         firstQuery,
         queryCount,
         destination,
         destinationOffset,
       );
+      if (result.ok) {
+        pushEvent(s, {
+          kind: 'resolveQuerySet',
+          cmdHandleId: cmdHId,
+          querySetHandleId: getHandleId(s, querySet as object, 'querySet'),
+          firstQuery,
+          queryCount,
+          destinationHandleId: getHandleId(s, destination as object, 'buffer'),
+          destinationOffset,
+        });
+      }
+      return result;
     },
     pushDebugGroup(groupLabel) {
       pushEvent(s, { kind: 'pushDebugGroup', cmdHandleId: cmdHId, groupLabel });
@@ -257,3 +298,16 @@ export function createCommandEncoderProxy(
     },
   };
 }
+
+function recordTimestampWrites(writes: RenderPassDescriptor['timestampWrites']) {
+  return writes === undefined
+    ? undefined
+    : {
+        ...(writes.beginningOfPassWriteIndex === undefined
+          ? {}
+          : { beginningOfPassWriteIndex: writes.beginningOfPassWriteIndex }),
+        ...(writes.endOfPassWriteIndex === undefined
+          ? {}
+          : { endOfPassWriteIndex: writes.endOfPassWriteIndex }),
+      };
+}

package/src/recorder/pass.ts

@@ -177,10 +177,15 @@ export function createRenderPassProxy(
       return realPass.executeBundles(bundles);
     },
     beginOcclusionQuery(queryIndex) {
-      return realPass.beginOcclusionQuery(queryIndex);
+      const result = realPass.beginOcclusionQuery(queryIndex);
+      if (result.ok)
+        pushEvent(s, { kind: 'beginOcclusionQuery', passHandleId: passHId, queryIndex });
+      return result;
     },
     endOcclusionQuery() {
-      return realPass.endOcclusionQuery();
+      const result = realPass.endOcclusionQuery();
+      if (result.ok) pushEvent(s, { kind: 'endOcclusionQuery', passHandleId: passHId });
+      return result;
     },
     end() {
       pushEvent(s, { kind: 'endRenderPass', passHandleId: passHId });

package/src/recorder/pipeline.ts

@@ -0,0 +1,31 @@
+import type { ComputePipeline, RenderPipeline, RhiRenderPipelineOps } from '@forgeax/engine-rhi';
+import type { HandleId } from '../types';
+import { pushEvent, type RecorderInternal, registerHandle } from './core';
+
+export function wrapPipeline<T extends RenderPipeline | ComputePipeline>(
+  state: RecorderInternal,
+  pipeline: T,
+  pipelineHandleId: HandleId,
+): T {
+  // Preserve native pipeline identity: renderer-owned command paths may pass
+  // the opaque handle directly to WebGPU, which rejects a JavaScript Proxy.
+  const operation = (pipeline as T & Partial<RhiRenderPipelineOps>).getBindGroupLayout;
+  if (operation === undefined) return pipeline;
+  const getLayout = operation.bind(pipeline);
+  Object.defineProperty(pipeline, 'getBindGroupLayout', {
+    configurable: true,
+    value: (index: number) => {
+      const layout = getLayout(index);
+      const event = {
+        kind: 'getBindGroupLayout' as const,
+        handleId: '' as HandleId,
+        pipelineHandleId,
+        index,
+      };
+      registerHandle(state, layout, 'bindGroupLayout', event);
+      pushEvent(state, event);
+      return layout;
+    },
+  });
+  return pipeline;
+}

package/src/recorder/proxy.ts

@@ -3,6 +3,7 @@ import { err, ok, type Result } from '@forgeax/engine-types';
 import { createRhiDebugError, type RhiDebugError } from '../errors';
 import {
   type CreateShaderModuleFn,
+  type CreateShaderModuleImmediateFn,
   type DebugRhiInstance,
   wrap,
   wrapCreateShaderModule,
@@ -15,6 +16,8 @@ export interface RecordableBackend {
     ) => Result<RhiCanvasContext, RhiError>;
   };
   readonly createShaderModule: CreateShaderModuleFn;
+  /** Optional synchronous factory retained for render's first-use path. */
+  readonly createShaderModuleImmediate?: CreateShaderModuleImmediateFn;
 }
 
 export interface RecorderBackend extends RecordableBackend {
@@ -29,21 +32,74 @@ export interface RecorderProxy {
 export function createRecorderProxy(backend: RecordableBackend): RecorderProxy {
   const recorder = wrap(backend.rhi);
   const wrappedCreateShaderModule = wrapCreateShaderModule(backend.createShaderModule, recorder);
+  const originalCreateShaderModuleImmediate = backend.createShaderModuleImmediate;
+  const wrappedCreateShaderModuleImmediate =
+    originalCreateShaderModuleImmediate === undefined
+      ? undefined
+      : (device: RhiDevice, desc: { code: string; label?: string | undefined }) => {
+          const realDevice =
+            (device as RhiDevice & { readonly _realDevice?: RhiDevice })._realDevice ?? device;
+          const result = originalCreateShaderModuleImmediate(realDevice, desc);
+          if (!result.ok) return result;
+          const hId = recorder.pushExternalCreateEvent(result.value, 'shaderModule', {
+            kind: 'createShaderModule',
+            handleId: '' as import('../types').HandleId,
+            wgslCode: desc.code,
+          });
+          recorder.registerShaderModule(result.value, hId);
+          return result;
+        };
   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 } = {
+  const rhi: RecordableBackend['rhi'] & {
+    readonly createShaderModule: CreateShaderModuleFn;
+    readonly createShaderModuleImmediate?: CreateShaderModuleImmediateFn;
+  } = {
     requestAdapter: recorder.requestAdapter.bind(recorder),
     createShaderModule: wrappedCreateShaderModule,
+    ...(wrappedCreateShaderModuleImmediate === undefined
+      ? {}
+      : { createShaderModuleImmediate: wrappedCreateShaderModuleImmediate }),
     ...(acquireCanvasContext === undefined
       ? {}
-      : { acquireCanvasContext: acquireCanvasContext.bind(backend.rhi) }),
+      : {
+          acquireCanvasContext(canvas) {
+            const result = acquireCanvasContext.call(backend.rhi, canvas);
+            if (!result.ok) return result;
+            const context = result.value;
+            // rhi-webgpu's canvas shim translates the forgeax RhiDevice to the
+            // native GPUDevice through its own WeakMap. The recorder device is
+            // an intentional proxy, so passing it directly makes configure()
+            // reject with a foreign-device error before the first frame. Keep
+            // the context owned by the selected backend, but unwrap only the
+            // device argument at this boundary; all resource calls continue to
+            // flow through the recorder device and remain capturable.
+            return ok({
+              ...context,
+              configure(configuration) {
+                const device = (
+                  configuration.device as RhiDevice & {
+                    readonly _realDevice?: RhiDevice;
+                  }
+                )._realDevice;
+                return context.configure({
+                  ...configuration,
+                  ...(device === undefined ? {} : { device }),
+                });
+              },
+            });
+          },
+        }),
   };
   const wrappedBackend: RecorderBackend = {
     rhi,
     createShaderModule: wrappedCreateShaderModule,
+    ...(wrappedCreateShaderModuleImmediate === undefined
+      ? {}
+      : { createShaderModuleImmediate: wrappedCreateShaderModuleImmediate }),
     unwrapDeviceForSurface(device) {
       const raw = (device as RhiDevice & { readonly _realDevice?: RhiDevice })._realDevice;
       if (raw !== undefined) return ok(raw);

package/src/recorder/session.ts

@@ -147,6 +147,6 @@ export function attachRecorder(
   return ok(attachment);
 }
 
-export type { CreateShaderModuleFn } from '../recorder';
+export type { CreateShaderModuleFn, CreateShaderModuleImmediateFn } from '../recorder';
 export type { EncodedTape } from './assemble';
 export type { RecordableBackend, RecorderBackend } from './proxy';

package/src/recorder/shader.ts

@@ -2,7 +2,24 @@
 
 import type { Result, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
 import type { HandleId } from '../types';
-import type { CreateShaderModuleFn, DebugRhiInstance } from './core';
+import type { CreateShaderModuleFn, CreateShaderModuleImmediateFn, DebugRhiInstance } from './core';
+
+function recordShaderModule(
+  debugInst: DebugRhiInstance,
+  result: Result<ShaderModule, import('@forgeax/engine-rhi').RhiError>,
+  desc: { code: string; label?: string | undefined },
+): Result<ShaderModule, import('@forgeax/engine-rhi').RhiError> {
+  if (!result.ok) return result;
+  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 can resolve the handleId during replay.
+  debugInst.registerShaderModule(result.value, hId);
+  return result;
+}
 
 export function wrapCreateShaderModule(
   originalFn: CreateShaderModuleFn,
@@ -21,27 +38,17 @@ export function wrapCreateShaderModule(
     // 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 recordShaderModule(debugInst, result, desc);
+  };
+}
 
-    return result;
+/** Wrap the synchronous render-path factory while preserving tape ownership. */
+export function wrapCreateShaderModuleImmediate(
+  originalFn: CreateShaderModuleImmediateFn,
+  debugInst: DebugRhiInstance,
+): CreateShaderModuleImmediateFn {
+  return (device, desc) => {
+    const realDevice = (device as RhiDevice & { _realDevice?: RhiDevice })._realDevice ?? device;
+    return recordShaderModule(debugInst, originalFn(realDevice, desc), desc);
   };
 }

package/src/recorder.ts

@@ -1,6 +1,10 @@
 // @forgeax/engine-rhi-debug/src/recorder -- split recorder public seam.
 
-export type { CreateShaderModuleFn, DebugRhiInstance } from './recorder/core';
+export type {
+  CreateShaderModuleFn,
+  CreateShaderModuleImmediateFn,
+  DebugRhiInstance,
+} from './recorder/core';
 export { PER_EVENT_OVERHEAD, TAPE_FORMAT_VERSION } from './recorder/core';
 export type {
   CaptureFrameOptions,
@@ -11,5 +15,5 @@ export type {
   RecorderOptions,
 } from './recorder/session';
 export { attachRecorder } from './recorder/session';
-export { wrapCreateShaderModule } from './recorder/shader';
+export { wrapCreateShaderModule, wrapCreateShaderModuleImmediate } from './recorder/shader';
 export { wrap } from './recorder/wrap';