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

package/dist/protocol/codec.d.ts

@@ -0,0 +1,6 @@
+import { type Result } from '@forgeax/engine-types';
+import { createRhiDebugError } from '../errors';
+import { type Tape, type TapeEncodeOptions } from './types';
+export declare function encodeTape(tape: Tape, options?: TapeEncodeOptions): Result<Uint8Array, ReturnType<typeof createRhiDebugError<'tape-invalid'>>>;
+export declare function decodeTape(bytes: Uint8Array): Result<Tape, ReturnType<typeof createRhiDebugError<'tape-invalid'>> | ReturnType<typeof createRhiDebugError<'tape-version-unsupported'>>>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/protocol/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/protocol/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAI7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAIL,KAAK,IAAI,EAET,KAAK,iBAAiB,EACvB,MAAM,SAAS,CAAC;AAqBjB,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,cAAc,CAAC,CAAC,CAAC,CAyC5E;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,GAChB,MAAM,CACP,IAAI,EACF,UAAU,CAAC,OAAO,mBAAmB,CAAC,cAAc,CAAC,CAAC,GACtD,UAAU,CAAC,OAAO,mBAAmB,CAAC,0BAA0B,CAAC,CAAC,CACrE,CA4GA"}

package/dist/protocol/event-semantics.d.ts

@@ -0,0 +1,15 @@
+import type { EventKind, ResourceKind, RhiCallEvent } from './types';
+export type EventCategory = 'resource' | 'pass' | 'state' | 'work' | 'copy' | 'submit' | 'marker';
+export interface EventSemantics {
+    readonly category: EventCategory;
+    readonly created: (event: RhiCallEvent) => readonly string[];
+    readonly read: (event: RhiCallEvent) => readonly string[];
+    readonly written: (event: RhiCallEvent) => readonly string[];
+    readonly destroyed: (event: RhiCallEvent) => readonly string[];
+}
+export declare const eventKinds: readonly ["frameMark", "createBuffer", "createTexture", "destroyBuffer", "destroyTexture", "createTextureView", "createSampler", "createBindGroupLayout", "createBindGroup", "createPipelineLayout", "createRenderPipeline", "createComputePipeline", "createShaderModule", "createCommandEncoder", "writeBuffer", "writeTexture", "copyExternalImageToTexture", "submit", "beginRenderPass", "beginComputePass", "copyBufferToBuffer", "copyBufferToTexture", "copyTextureToBuffer", "copyTextureToTexture", "clearBuffer", "pushDebugGroup", "popDebugGroup", "insertDebugMarker", "finish", "setPipeline", "setVertexBuffer", "setIndexBuffer", "setBindGroup", "draw", "drawIndexed", "setViewport", "setScissorRect", "setStencilReference", "endRenderPass", "setBlendConstant", "drawIndirect", "drawIndexedIndirect", "passPushDebugGroup", "passPopDebugGroup", "passInsertDebugMarker", "setComputePipeline", "dispatchWorkgroups", "dispatchWorkgroupsIndirect", "endComputePass", "initialData"];
+export declare const workEventKinds: readonly ["draw", "drawIndexed", "drawIndirect", "drawIndexedIndirect", "dispatchWorkgroups", "dispatchWorkgroupsIndirect"];
+export declare function isWorkEvent(kind: EventKind): boolean;
+export declare const EVENT_SEMANTICS: Readonly<Record<EventKind, EventSemantics>>;
+export declare function resourceKindForEvent(kind: EventKind): ResourceKind | undefined;
+//# sourceMappingURL=event-semantics.d.ts.map

package/dist/protocol/event-semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-semantics.d.ts","sourceRoot":"","sources":["../../src/protocol/event-semantics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAErE,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,SAAS,MAAM,EAAE,CAAC;IAC7D,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,SAAS,MAAM,EAAE,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,SAAS,MAAM,EAAE,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,SAAS,MAAM,EAAE,CAAC;CAChE;AAED,eAAO,MAAM,UAAU,88BAmDkB,CAAC;AAE1C,eAAO,MAAM,cAAc,6HAOc,CAAC;AAE1C,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEpD;AAED,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,cAAc,CAAC,CAElC,CAAC;AAEvC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAwB9E"}

package/dist/protocol/tape-index.d.ts

@@ -0,0 +1,30 @@
+import type { EventKind, ResourceKind, Tape } from './types';
+export interface TapePassEntry {
+    readonly passIndex: number;
+    readonly kind: 'render' | 'compute';
+    readonly beginEventIndex: number;
+    readonly endEventIndex: number | undefined;
+    readonly workIndices: readonly number[];
+}
+export interface TapeWorkEntry {
+    readonly workIndex: number;
+    readonly eventIndex: number;
+    readonly passIndex: number;
+    readonly kind: Extract<EventKind, 'draw' | 'drawIndexed' | 'drawIndirect' | 'drawIndexedIndirect' | 'dispatchWorkgroups' | 'dispatchWorkgroupsIndirect'>;
+}
+export interface TapeResourceEntry {
+    readonly resourceId: string;
+    readonly kind: ResourceKind;
+    readonly origin: 'bootstrap' | 'frame';
+    readonly createEventIndex: number | undefined;
+    readonly destroyEventIndex: number | undefined;
+}
+export interface TapeIndex {
+    readonly passes: readonly TapePassEntry[];
+    readonly works: readonly TapeWorkEntry[];
+    readonly resources: readonly TapeResourceEntry[];
+    readonly eventKinds: readonly EventKind[];
+    readonly passIndexByEvent: readonly number[];
+}
+export declare function buildTapeIndex(tape: Tape): TapeIndex;
+//# sourceMappingURL=tape-index.d.ts.map

package/dist/protocol/tape-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tape-index.d.ts","sourceRoot":"","sources":["../../src/protocol/tape-index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CACpB,SAAS,EACP,MAAM,GACN,aAAa,GACb,cAAc,GACd,qBAAqB,GACrB,oBAAoB,GACpB,4BAA4B,CAC/B,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CA6EpD"}

package/dist/protocol/types.d.ts

@@ -0,0 +1,44 @@
+import type { Result } from '@forgeax/engine-types';
+import type { RhiDebugError } from '../errors';
+import type { RhiCallEvent as LegacyRhiCallEvent } from '../types';
+export declare const TAPE_FORMAT_VERSION: 7;
+export declare const TAPE_MAGIC: "RHITAPE";
+export type RhiCallEvent = LegacyRhiCallEvent;
+export type EventKind = RhiCallEvent['kind'];
+export type TapeBlobCompression = 'none' | 'gzip';
+export type ResourceKind = 'buffer' | 'texture' | 'texture-view' | 'sampler' | 'shader-module' | 'pipeline' | 'binding' | 'encoder';
+export interface RhiCapsRecorded {
+    readonly [key: string]: boolean | number | string | null;
+}
+export interface InitialDataSlice {
+    readonly hash: string;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+export interface BootstrapResource {
+    readonly handleId: string;
+    readonly kind: ResourceKind;
+    readonly create: Record<string, unknown>;
+    readonly initialData: readonly InitialDataSlice[];
+}
+export interface TapeBlob {
+    readonly hash: string;
+    readonly bytes: Uint8Array;
+    readonly compression: TapeBlobCompression;
+}
+export interface Tape {
+    readonly header: {
+        readonly formatVersion: typeof TAPE_FORMAT_VERSION;
+        readonly rhiCaps: RhiCapsRecorded;
+        readonly eventCount: number;
+        readonly blobCount: number;
+    };
+    readonly bootstrap: readonly BootstrapResource[];
+    readonly events: readonly RhiCallEvent[];
+    readonly blobs: readonly TapeBlob[];
+}
+export interface TapeEncodeOptions {
+    readonly compression?: TapeBlobCompression;
+}
+export type RhiDebugResult<T> = Result<T, RhiDebugError>;
+//# sourceMappingURL=types.d.ts.map

package/dist/protocol/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/protocol/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnE,eAAO,MAAM,mBAAmB,EAAG,CAAU,CAAC;AAC9C,eAAO,MAAM,UAAU,EAAG,SAAkB,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAC7C,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAClD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,SAAS,GACT,cAAc,GACd,SAAS,GACT,eAAe,GACf,UAAU,GACV,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;CAC3C;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,aAAa,EAAE,OAAO,mBAAmB,CAAC;QACnD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;QAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC"}

package/dist/protocol/validation.d.ts

@@ -0,0 +1,7 @@
+import { type Result } from '@forgeax/engine-types';
+import { createRhiDebugError } from '../errors';
+import { type Tape } from './types';
+type TapeValidation = ReturnType<typeof createRhiDebugError<'tape-invalid'>>;
+export declare function validateTape(tape: Tape): Result<Tape, TapeValidation>;
+export {};
+//# sourceMappingURL=validation.d.ts.map

package/dist/protocol/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/protocol/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAA6D,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/F,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,cAAc,CAAC,CAAC,CAAC;AAE7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAkFrE"}

package/dist/readback.d.ts

@@ -0,0 +1,156 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import type { Result } from '@forgeax/engine-types';
+import { type RhiDebugError } from './errors';
+import type { RhiCallEvent } from './types';
+/** Resolved descriptor for a texture (or texture-view) handle from the tape. */
+export interface ResolvedTextureDescriptor {
+    /** The source GPUTexture handleId (copyTextureToBuffer needs a texture, not a view). */
+    readonly handleId: string;
+    readonly width: number;
+    readonly height: number;
+    readonly format: string;
+    /** The view's dimension ('2d' | 'cube' | '2d-array' | '3d' | ...); '2d' when no view event. */
+    readonly dimension: string;
+    /** The source texture's depthOrArrayLayers (slice count); 1 for a plain 2D texture. */
+    readonly arrayLayers: number;
+}
+/**
+ * Walk the tape events to resolve a view-or-texture handleId to its source
+ * GPUTexture descriptor (handleId, real dimensions, format, view dimension).
+ *
+ * The single source of truth for "tape handle -> texture descriptor": both the
+ * color-attachment RT path (resolveAttachmentSize / readbackDrawRt) and the
+ * viewer's depth + bound-texture preview paths resolve handles this way —
+ * createTextureView.resultHandleId -> sourceHandleId -> createTexture, falling
+ * back to the id itself when it is a direct texture handle (no view event).
+ *
+ * Size is read from the raw createTexture event. Returns null when no
+ * createTexture event declares the resolved handle.
+ */
+export declare function resolveTextureDescriptor(events: readonly RhiCallEvent[], viewOrTextureHandleId: string): ResolvedTextureDescriptor | null;
+/**
+ * Walk the tape events to find the real texture dimensions for a given
+ * color attachment view/target handleId. Avoids hard-coding 512×512.
+ *
+ * Thin wrapper over {@link resolveTextureDescriptor}; returns
+ * { width: 512, height: 512 } as a conservative fallback when no createTexture
+ * event is found (should not happen for a real frame).
+ */
+export declare function resolveAttachmentSize(events: readonly RhiCallEvent[], attachmentViewHandleId: string): {
+    readonly width: number;
+    readonly height: number;
+};
+/**
+ * Read back raw RGBA8 pixels from a GPU texture into a host-side Uint8Array.
+ *
+ * Steps:
+ * 1. Create a staging buffer (COPY_DST | MAP_READ) sized to aligned rows.
+ * 2. Create a command encoder + copyTextureToBuffer.
+ * 3. Finish + submit + await onSubmittedWorkDone.
+ * 4. mapAsync(READ) + getMappedRange() → new Uint8Array(slice).
+ * 5. Unmap + destroy staging buffer.
+ *
+ * The returned Uint8Array has length = texWidth * texHeight * 4 (tight;
+ * alignment padding is stripped). The buffer alignment is WebGPU 256-byte
+ * row requirement.
+ *
+ * @param device - The RHI device that owns the texture.
+ * @param texture - The texture to read back (opaque branded handle at the boundary).
+ * @param texWidth - Texture width in pixels.
+ * @param texHeight - Texture height in pixels.
+ */
+export declare function readbackTexturePixels(device: RhiDevice, texture: unknown, texWidth: number, texHeight: number, opts?: {
+    /** Bytes in one uncompressed texel; retained for depth/color callers. */
+    bytesPerTexel?: number;
+    /** Compressed-format footprint; defaults to bytesPerTexel with a 1x1 block. */
+    bytesPerBlock?: number;
+    blockWidth?: number;
+    blockHeight?: number;
+    mipLevel?: number;
+    baseArrayLayer?: number;
+    aspect?: 'all' | 'depth-only' | 'stencil-only';
+}): Promise<Uint8Array>;
+/**
+ * Read back the raw bytes of a GPU buffer into a host-side ArrayBuffer.
+ *
+ * Sibling of readbackTexturePixels under the single "GPU byte readback"
+ * responsibility unit (plan-strategy D-7) — snapshotResource calls this to
+ * capture a buffer's initial GPU bytes at frame-header time.
+ *
+ * Steps:
+ * 1. Create a staging buffer (COPY_DST | MAP_READ) sized to `size`.
+ * 2. Create a command encoder + copyBufferToBuffer(src, 0, staging, 0, size).
+ * 3. Finish + submit + await onSubmittedWorkDone.
+ * 4. mapAsync(READ=0x1) + getMappedRange() -> sliced ArrayBuffer copy.
+ * 5. Unmap + destroy staging buffer.
+ *
+ * Returns Ok(ArrayBuffer) (a detached copy independent of the mapped range)
+ * or Err(readback-failed) with `.detail.phase` narrowing
+ * the failure point (copy / map). The buffer is passed opaque (`unknown`)
+ * because RHI handles are branded; the caller resolved it from the descriptor
+ * registry. The caller (snapshotResource) holds the handleId and maps this
+ * readback error to the capture-snapshot-failed boundary.
+ *
+ * Reuses the M0-fixed mapAsync(0x1) + Result-unwrap pattern from
+ * readbackTexturePixels (never the all-zero mode=2 bug).
+ *
+ * @param device - The RHI device that owns the buffer.
+ * @param buffer - The source buffer (opaque branded handle) to read back.
+ * @param size - Number of bytes to read back (the buffer's recorded size).
+ */
+export declare function readbackBufferBytes(device: RhiDevice, buffer: unknown, size: number): Promise<Result<ArrayBuffer, RhiDebugError>>;
+/** A load-time buffer that can be read back as part of one GPU submission. */
+export interface BufferReadbackBatchRequest {
+    readonly handleId: string;
+    readonly buffer: unknown;
+    readonly size: number;
+}
+export interface BufferReadbackBatchCallbacks {
+    readonly onResourceStart?: (handleId: string) => void;
+    readonly onResourceComplete?: (handleId: string) => void;
+    /** Return true when the owning snapshot generation has been invalidated. */
+    readonly isCancelled?: () => boolean;
+}
+/**
+ * Read back multiple buffers with one command submission and one queue drain.
+ *
+ * Prism City exposed the cost of the old one-buffer helper: every resource
+ * submitted and awaited independently, so thousands of small buffers spent
+ * most of capture time in synchronization rather than byte transfer. The
+ * batch keeps each staging buffer isolated but submits all copies together;
+ * mapping remains per-resource so a timeout can still identify the current
+ * handle and the caller can preserve the original initialData event order.
+ */
+export declare function readbackBufferBytesBatch(device: RhiDevice, requests: readonly BufferReadbackBatchRequest[], callbacks?: BufferReadbackBatchCallbacks): Promise<Result<ReadonlyMap<string, ArrayBuffer>, RhiDebugError>>;
+/** One (layer, mip) copy contributing to a complete texture snapshot blob. */
+export interface TextureReadbackBatchSlice {
+    readonly layer: number;
+    readonly mip: number;
+    readonly width: number;
+    readonly height: number;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+/** A complete texture whose subresources are copied in one bounded batch. */
+export interface TextureReadbackBatchRequest {
+    readonly handleId: string;
+    readonly texture: unknown;
+    readonly bytesPerBlock: number;
+    readonly blockWidth: number;
+    readonly blockHeight: number;
+    readonly totalBytes: number;
+    readonly slices: readonly TextureReadbackBatchSlice[];
+}
+export interface TextureReadbackBatchCallbacks {
+    readonly onResourceStart?: (handleId: string) => void;
+    readonly onResourceComplete?: (handleId: string) => void;
+    /** Return true when the owning snapshot generation has been invalidated. */
+    readonly isCancelled?: () => boolean;
+}
+/**
+ * Read complete texture snapshots with one submission and drain per bounded
+ * resource batch. Each subresource retains its own staging buffer, so mip and
+ * array-layer bytes are copied without padding or ordering loss.
+ */
+export declare function readbackTexturePixelsBatch(device: RhiDevice, requests: readonly TextureReadbackBatchRequest[], callbacks?: TextureReadbackBatchCallbacks): Promise<Result<ReadonlyMap<string, ArrayBuffer>, RhiDebugError>>;
+//# sourceMappingURL=readback.d.ts.map

package/dist/readback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readback.d.ts","sourceRoot":"","sources":["../src/readback.ts"],"names":[],"mappings":"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"}

package/dist/recorder/assemble.d.ts

@@ -0,0 +1,11 @@
+import { type Result } from '@forgeax/engine-types';
+import { type RhiDebugError } from '../errors';
+import type { Tape as V7Tape } from '../protocol/types';
+import type { DebugRhiInstance } from '../recorder';
+export interface EncodedTape {
+    readonly bytes: Uint8Array;
+    readonly digest: string;
+    readonly tape: V7Tape;
+}
+export declare function assembleTape(recorder: DebugRhiInstance): Result<EncodedTape, RhiDebugError>;
+//# sourceMappingURL=assemble.d.ts.map

package/dist/recorder/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/recorder/assemble.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAEpE,OAAO,KAAK,EAAqB,IAAI,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC,WAAW,EAAE,aAAa,CAAC,CAqB3F"}

package/dist/recorder/closure.d.ts

@@ -0,0 +1,39 @@
+import type { HandleId, RhiCallEvent } from '../types';
+export declare function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]): Set<HandleId>;
+/**
+ * @internal
+ * Return handleIds referenced by a create* event for transitive closure traversal.
+ *
+ * The edge set follows D-3 (plan-strategy 2):
+ *   - createBindGroup → layoutHandleId + resourceHandleIds
+ *   - createPipelineLayout → bglHandleIds
+ *   - createRenderPipeline → layoutHandleId (if != 'layout:auto') + vertex/fragmentShaderModuleHandleId (R-1)
+ *   - createComputePipeline → layoutHandleId (if != 'layout:auto') + computeShaderModuleHandleId (R-1)
+ *   - createTextureView → sourceHandleId
+ * Leaf resources (buffer / texture / sampler / BGL / shaderModule) return empty.
+ */
+export declare function _getCreateEventReferencedHandleIds(event: RhiCallEvent): HandleId[];
+/**
+ * @internal
+ * Compute the transitive closure of handleIds from bootstrapCreates.
+ *
+ * Starting from the given seed set, recursively walks all referenced handleIds
+ * via _getCreateEventReferencedHandleIds. Returns the set of all handleIds
+ * whose create events must be included in the tape prefix for self-containment.
+ *
+ * If a referenced handleId is not found in bootstrapCreates, returns
+ * `null` for that id — the caller should produce a structured tape error.
+ */
+export declare function _computeClosure(seedHandleIds: Set<HandleId>, bootstrapCreates: Map<HandleId, RhiCallEvent>, inFrameHandleIds: Set<HandleId>): {
+    closure: Set<HandleId>;
+    missing: HandleId | null;
+};
+/**
+ * @internal
+ * Topologically sort the closure set so that dependencies appear before dependents.
+ *
+ * Builds a dep-graph: if event A references handleId of event B, then B must
+ * appear before A. Uses Kahn's algorithm.
+ */
+export declare function _topoSortClosure(closure: Set<HandleId>, bootstrapCreates: Map<HandleId, RhiCallEvent>): RhiCallEvent[];
+//# sourceMappingURL=closure.d.ts.map

package/dist/recorder/closure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closure.d.ts","sourceRoot":"","sources":["../../src/recorder/closure.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvD,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,GAAG,CAAC,QAAQ,CAAC,CAmP/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,YAAY,GAAG,QAAQ,EAAE,CA2ClF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,GAAG,CAAC,QAAQ,CAAC,EAC5B,gBAAgB,EAAE,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,EAC7C,gBAAgB,EAAE,GAAG,CAAC,QAAQ,CAAC,GAC9B;IAAE,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAE,CAwBtD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,EACtB,gBAAgB,EAAE,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,GAC5C,YAAY,EAAE,CA8ChB"}