@vgpu/render 0.0.5 → 0.0.7

package/dist/uniform.d.ts

@@ -0,0 +1,55 @@
+import { Buffer, type Device } from "@vgpu/core";
+export interface UniformOptions {
+    /** Byte size of the uniform buffer. Must be a positive number. */
+    readonly size: number;
+    /** Optional debug label forwarded to the buffer, bind group layout, and bind group. */
+    readonly label?: string;
+    /**
+     * Shader stages that read binding 0. Defaults to `VERTEX | FRAGMENT`.
+     * Ignored when {@link UniformOptions.bindGroupLayout} is provided.
+     */
+    readonly visibility?: GPUShaderStageFlags;
+    /**
+     * Reuse a pipeline-owned bind group layout instead of creating one.
+     * The layout's binding 0 must be a uniform buffer compatible with `size`.
+     */
+    readonly bindGroupLayout?: GPUBindGroupLayout;
+}
+/**
+ * A single stable uniform buffer for one render pass, rewritten per frame.
+ *
+ * @remarks
+ * Unlike {@link UniformPool} (a dynamic-offset ring allocator built for many
+ * per-draw uniforms), `Uniform` owns exactly one uniform buffer at binding 0 with
+ * a fixed (non-dynamic) offset. The caller decides when to {@link Uniform.write}
+ * — typically gating on real changes — and the bind group never moves. This fits
+ * the "one camera/globals buffer per pass" case where a dynamic-offset binding
+ * would needlessly mark the layout `hasDynamicOffset` and re-upload every frame.
+ *
+ * @example
+ * ```ts
+ * const uniform = new Uniform(device, { size: 64, label: "globals" });
+ * // per frame, only when inputs changed:
+ * uniform.write(globalsBytes);
+ * pass.setBindGroup(0, uniform.bindGroup);
+ * ```
+ */
+export declare class Uniform {
+    readonly device: Device;
+    readonly size: number;
+    readonly buffer: Buffer;
+    readonly bindGroupLayout: GPUBindGroupLayout;
+    readonly bindGroup: GPUBindGroup;
+    private destroyed;
+    constructor(device: Device, opts: UniformOptions);
+    /** The underlying uniform `GPUBuffer`. */
+    get gpu(): GPUBuffer;
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the uniform contents actually change.
+     */
+    write(data: BufferSource, offset?: number): void;
+    destroy(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=uniform.d.ts.map

package/dist/uniform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform.d.ts","sourceRoot":"","sources":["../src/uniform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAA0C,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAE/F,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC;CAC/C;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,OAAO;IAON,QAAQ,CAAC,MAAM,EAAE,MAAM;IANnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,OAAO,CAAC,SAAS,CAAS;gBAEL,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc;IAczD,0CAA0C;IAC1C,IAAI,GAAG,IAAI,SAAS,CAEnB;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,SAAI,GAAG,IAAI;IAI3C,OAAO,IAAI,IAAI;IAMf,OAAO,IAAI,IAAI;CAGhB"}

package/dist/uniform.js

@@ -0,0 +1,64 @@
+import { bind, createBindGroup, createBindGroupLayout } from "@vgpu/core";
+const defaultVisibility = ((globalThis.GPUShaderStage?.VERTEX ?? 1) | (globalThis.GPUShaderStage?.FRAGMENT ?? 2));
+/**
+ * A single stable uniform buffer for one render pass, rewritten per frame.
+ *
+ * @remarks
+ * Unlike {@link UniformPool} (a dynamic-offset ring allocator built for many
+ * per-draw uniforms), `Uniform` owns exactly one uniform buffer at binding 0 with
+ * a fixed (non-dynamic) offset. The caller decides when to {@link Uniform.write}
+ * — typically gating on real changes — and the bind group never moves. This fits
+ * the "one camera/globals buffer per pass" case where a dynamic-offset binding
+ * would needlessly mark the layout `hasDynamicOffset` and re-upload every frame.
+ *
+ * @example
+ * ```ts
+ * const uniform = new Uniform(device, { size: 64, label: "globals" });
+ * // per frame, only when inputs changed:
+ * uniform.write(globalsBytes);
+ * pass.setBindGroup(0, uniform.bindGroup);
+ * ```
+ */
+export class Uniform {
+    device;
+    size;
+    buffer;
+    bindGroupLayout;
+    bindGroup;
+    destroyed = false;
+    constructor(device, opts) {
+        this.device = device;
+        this.size = opts.size;
+        this.buffer = device.createBuffer({ size: opts.size, usage: ["uniform", "copy_dst"], label: opts.label });
+        this.bindGroupLayout = opts.bindGroupLayout ?? createBindGroupLayout(device, {
+            label: opts.label ? `${opts.label}.bgl` : undefined,
+            entries: [bind.uniform(0, opts.visibility ?? defaultVisibility, { minBindingSize: opts.size })],
+        });
+        this.bindGroup = createBindGroup(device, {
+            label: opts.label ? `${opts.label}.bg` : undefined,
+            layout: this.bindGroupLayout,
+            entries: [bind.resource(0, this.buffer)],
+        });
+    }
+    /** The underlying uniform `GPUBuffer`. */
+    get gpu() {
+        return this.buffer.gpu;
+    }
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the uniform contents actually change.
+     */
+    write(data, offset = 0) {
+        this.buffer.write(data, offset);
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.buffer.destroy();
+    }
+    dispose() {
+        this.destroy();
+    }
+}
+//# sourceMappingURL=uniform.js.map

package/dist/uniform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform.js","sourceRoot":"","sources":["../src/uniform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAU,eAAe,EAAE,qBAAqB,EAAe,MAAM,YAAY,CAAC;AAmB/F,MAAM,iBAAiB,GAAG,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAwB,CAAC;AAEzI;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,OAAO;IAOG;IANZ,IAAI,CAAS;IACb,MAAM,CAAS;IACf,eAAe,CAAqB;IACpC,SAAS,CAAe;IACzB,SAAS,GAAG,KAAK,CAAC;IAE1B,YAAqB,MAAc,EAAE,IAAoB;QAApC,WAAM,GAAN,MAAM,CAAQ;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC1G,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,qBAAqB,CAAC,MAAM,EAAE;YAC3E,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS;YACnD,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,IAAI,iBAAiB,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;SAChG,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE;YACvC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS;YAClD,MAAM,EAAE,IAAI,CAAC,eAAe;YAC5B,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAC1C,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAkB,EAAE,MAAM,GAAG,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vgpu/render",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Render pipeline + render pass abstractions for vgpu.",
   "keywords": [
     "webgpu",
@@ -47,6 +47,10 @@
     "./passes": {
       "types": "./dist/passes/index.d.ts",
       "import": "./dist/passes/index.js"
+    },
+    "./perf": {
+      "types": "./dist/perf/index.d.ts",
+      "import": "./dist/perf/index.js"
     }
   },
   "files": [
@@ -58,14 +62,15 @@
   ],
   "dependencies": {
     "wgpu-matrix": "^3.4.2",
-    "@vgpu/core": "0.0.5"
+    "@vgpu/core": "0.0.7"
   },
   "vgpuExportBundleBudgetsGzipBytes": {
     ".": 49152,
     "./inspect": 4096,
     "./utils": 2048,
     "./edit": 25600,
-    "./passes": 3584
+    "./passes": 3584,
+    "./perf": 3072
   },
   "scripts": {
     "build": "tsc -b",

package/src/Frame.docs.md

@@ -0,0 +1,79 @@
+# Frame
+
+`Frame` owns one `GPUCommandEncoder` for an explicit sequence of commands. Use
+`beginFrame(device)` when one render frame needs multiple render passes, query
+commands, or copies in a user-authored order, then call `submit()` once.
+
+VGPU does not infer pass order, bind group layouts, or pipeline layouts. The
+helpers keep the native WebGPU lifecycle visible while removing repeated
+boilerplate around pass begin/end and final submission.
+
+## Native WebGPU baseline
+
+Without `Frame`, a multipass render frame is one command encoder, multiple
+passes ended in order, then one finish/submit:
+
+```ts
+const encoder = device.gpu.createCommandEncoder({ label: "hero.frame" });
+
+const lightPass = encoder.beginRenderPass(lightPassDescriptor);
+lightPass.executeBundles([lightBundle]);
+lightPass.end();
+
+encoder.writeTimestamp(querySet, 0);
+encoder.copyBufferToBuffer(srcBuffer, 0, dstBuffer, 0, byteLength);
+
+const compositePass = encoder.beginRenderPass(compositePassDescriptor);
+compositePass.setPipeline(compositePipeline);
+compositePass.setBindGroup(0, compositeBindGroup);
+compositePass.draw(3);
+compositePass.end();
+
+device.queue.gpu.submit([encoder.finish()]);
+```
+
+## With VGPU Frame
+
+`Frame` keeps that same lifecycle: one encoder, explicit pass order, finish once,
+submit once. This one-encoder/one-submit contract is intentional for homepage-style
+multipass renderers: setup and warmup should create pipelines, buffers, bind
+groups, and bundles up front; the per-frame path should only encode commands and
+submit the finished command buffer.
+
+```ts
+const frame = beginFrame(device, { label: "hero.frame" });
+
+frame.renderPass(lightPassDescriptor, (pass) => {
+  pass.executeBundles([lightBundle]);
+});
+
+frame.gpu.writeTimestamp(querySet, 0);
+frame.copyBufferToBuffer(srcBuffer, dstBuffer, byteLength);
+
+frame.renderPass(compositePassDescriptor, (pass) => {
+  pass.setPipeline(compositePipeline);
+  pass.setBindGroup(0, compositeBindGroup);
+  pass.draw(3);
+});
+
+frame.submit();
+```
+
+`frame.renderPass(options, callback)` begins a `RenderPass` wrapper on the
+frame-owned encoder, runs the callback, and ends that pass in a `finally` block.
+Unlike constructing a standalone `RenderPass`, a pass created by `Frame` does
+**not** finish or submit the command encoder when it ends. `frame.submit()` is
+the only submission point.
+
+The raw command encoder is available as `frame.gpu` for WebGPU operations that
+are intentionally not wrapped, such as `writeTimestamp()` or `resolveQuerySet()`.
+This is an advanced, semver-protected public escape hatch. Direct raw encoder
+calls follow native WebGPU behavior; VGPU only guards its own helper methods
+after `submit()`.
+
+`copyBufferToBuffer(source, destination, size, sourceOffset?, destinationOffset?)`
+is a small typed helper that accepts either core `Buffer` instances or raw
+`GPUBuffer`s. For all other encoder commands, use `frame.gpu` directly.
+
+A `Frame` is single-use. Calling VGPU helper methods after `submit()` throws
+`VGPUError` with code `VGPU-FRAME-SUBMITTED`.

package/src/RenderPass.docs.md

@@ -5,9 +5,11 @@ attachments. Construct it with a core `Device` and `RenderPassOptions`, encode
 render commands, then call `end()` to finish the pass and submit the command
 buffer through `Device.queue`.
 
-`RenderPassOptions` contains `colorAttachments` and an optional `label`.
-`ColorAttachment.view` accepts either a core `Texture` or a raw
-`GPUTextureView`; `loadOp`, `storeOp`, and `clearValue` are forwarded to WebGPU.
+`RenderPassOptions` contains `colorAttachments`, optional
+`depthStencilAttachment`, and an optional `label`. `ColorAttachment.view` and
+`DepthStencilAttachment.view` accept either a core `Texture` or a raw
+`GPUTextureView`; load/store operations and clear values are forwarded to
+WebGPU.
 
 Commands mirror the WebGPU render pass encoder:
 
@@ -15,6 +17,7 @@ Commands mirror the WebGPU render pass encoder:
 - `setBindGroup(index, group, dynamicOffsets?)` binds a raw `GPUBindGroup`.
 - `setVertexBuffer(slot, buffer, offset?, size?)` binds a core `Buffer` or raw
   `GPUBuffer` for vertex input.
+- `executeBundles(bundles)` executes setup-time `GPURenderBundle`s in the pass.
 - `draw({ vertexCount, instanceCount?, firstVertex?, firstInstance? })` issues a
   non-indexed draw. The numeric WebGPU-style `draw(vertexCount, ...)` call is
   also accepted.

package/src/createRenderPipeline.docs.md

@@ -1,34 +1,128 @@
-# createRenderPipeline
+# createRenderPipeline / createRenderPipelineAsync
 
-Creates a GPU render pipeline from a vgpu `Shader` plus vertex and fragment
-entry points. Returns a raw `GPURenderPipeline` with no wrapper.
+Creates a GPU render pipeline from descriptor-like VGPU options. Both helpers
+return a raw `GPURenderPipeline` with no wrapper so the result can be passed
+directly to native WebGPU, `RenderPass.setPipeline()`, or render-bundle recording.
 
-## Signature
+## Signatures
 
-`createRenderPipeline(device: Device, opts: RenderPipelineOptions): GPURenderPipeline`
+```ts
+createRenderPipeline(device: Device, opts: RenderPipelineOptions): GPURenderPipeline
+createRenderPipelineAsync(device: Device, opts: RenderPipelineOptions): Promise<GPURenderPipeline>
+createRenderPipelineFromDescriptor(device: Device, descriptor: GPURenderPipelineDescriptor): GPURenderPipeline
+createRenderPipelineFromDescriptorAsync(device: Device, descriptor: GPURenderPipelineDescriptor, fallback?: RenderPipelineAsyncFallback): Promise<GPURenderPipeline>
+```
+
+`createRenderPipelineAsync` calls `GPUDevice.createRenderPipelineAsync()` when it
+exists. If the implementation does not expose the async API, the default
+compatibility policy is `fallback: "sync"`, which emits a once-only diagnostic and
+calls `createRenderPipeline()` instead. Performance-critical warmup can pass
+`fallback: "throw"` to receive a structured `VGPUError` with code
+`VGPU-RENDER-PIPELINE-ASYNC-UNAVAILABLE` instead of accidentally blocking.
+
+## Raw descriptor entrypoints
+
+If you already have a hand-built `GPURenderPipelineDescriptor`, pass it straight
+through — do not reshape it into `RenderPipelineOptions` just to get the
+async→sync fallback:
+
+- `createRenderPipelineFromDescriptor(device, descriptor)` forwards the descriptor
+  to `GPUDevice.createRenderPipeline()` unchanged.
+- `createRenderPipelineFromDescriptorAsync(device, descriptor, fallback?)` forwards
+  it to `GPUDevice.createRenderPipelineAsync()` with the exact same compatibility
+  fallback as `createRenderPipelineAsync` (default `"sync"`, or `"throw"` for a
+  structured `VGPUError`).
+
+The descriptor is forwarded verbatim, so native WebGPU validation and lifecycle
+rules remain the caller's responsibility. These are explicit, separately named
+exports rather than an overload so a `RenderPipelineOptions` caller can never be
+misread as passing a raw descriptor.
+
+VGPU does not cache pipelines: one helper call equals one WebGPU device call.
+Keep pipeline caches explicit and owned by the caller.
 
 ## Options
 
-- `shader`: the `Shader` whose compiled GPU module will back both stages.
-- `vertex.entry`: the vertex shader entry-point name.
-- `fragment.entry`: the fragment shader entry-point name.
-- `fragment.targets`: the color target formats and blend/write settings.
-- `primitive`: optional WebGPU primitive state such as topology or culling.
-- `layout`: optional pipeline layout, or `"auto"` to let WebGPU derive one.
+- `shader`: optional shared `Shader` or raw `GPUShaderModule` used by stages that
+  do not provide their own module.
+- `vertex`: vertex stage options.
+  - `shader` / `module`: optional per-stage `Shader` or raw `GPUShaderModule`.
+  - `entry` / `entryPoint`: vertex entry-point name.
+  - `buffers`: optional vertex buffer layouts and attributes.
+  - `constants`: optional pipeline constants.
+- `fragment`: optional fragment stage options.
+  - `shader` / `module`: optional per-stage `Shader` or raw `GPUShaderModule`.
+  - `entry` / `entryPoint`: fragment entry-point name.
+  - `targets`: color target formats plus blend and write-mask state.
+  - `constants`: optional pipeline constants.
+- `primitive`: optional WebGPU primitive state.
+- `depthStencil`: optional depth/stencil state.
+- `multisample`: optional multisample state.
+- `layout`: explicit `GPUPipelineLayout`, or `"auto"`. Defaults to `"auto"`.
 - `label`: optional debug label forwarded to WebGPU.
+- `fallback`: async-only fallback policy, `"sync"` or `"throw"`.
+
+## Examples
 
-## Example
+Shared VGPU `Shader` module:
 
 ```ts
-const pipeline = createRenderPipeline(device, {
+const pipeline = await createRenderPipelineAsync(device, {
+  label: "hero.pipeline",
+  fallback: "throw",
   shader,
-  vertex: { entry: "vs_main" },
-  fragment: { entry: "fs_main", targets: [{ format: "rgba8unorm" }] },
-  primitive: { topology: "triangle-list" },
+  layout: explicitPipelineLayout,
+  vertex: {
+    entry: "vs_main",
+    buffers: [{
+      arrayStride: 16,
+      attributes: [{ shaderLocation: 0, offset: 0, format: "float32x4" }],
+    }],
+  },
+  fragment: {
+    entry: "fs_main",
+    targets: [{
+      format,
+      blend: {
+        color: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+        alpha: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+      },
+      writeMask: 0xf,
+    }],
+  },
+  primitive: { topology: "triangle-list", cullMode: "back" },
+  depthStencil: { format: "depth24plus", depthWriteEnabled: true, depthCompare: "less" },
+  multisample: { count: 4 },
 });
 ```
 
-## Notes
+Raw shader modules and per-stage constants:
+
+```ts
+const pipeline = createRenderPipeline(device, {
+  layout: "auto",
+  vertex: { module: vertexModule, entryPoint: "vs", constants: { scale: 2 } },
+  fragment: { module: fragmentModule, entryPoint: "fs", targets: [{ format }] },
+});
+```
+
+Existing raw `GPURenderPipelineDescriptor`, only wanting the async fallback:
+
+```ts
+const descriptor: GPURenderPipelineDescriptor = {
+  label: "hero.pipeline",
+  layout: pipelineLayout,
+  vertex: { module: shaderModule, entryPoint: "vs_main", buffers },
+  fragment: { module: shaderModule, entryPoint: "fs_main", targets: [{ format }] },
+  primitive: { topology: "triangle-list" },
+};
+
+const pipeline = await createRenderPipelineFromDescriptorAsync(device, descriptor, "throw");
+```
+
+## Raw escape hatch
 
-The returned `GPURenderPipeline` can be used directly with WebGPU APIs or
-passed to `RenderPass.setPipeline`.
+`Shader.gpu` is an intentional advanced escape hatch to the underlying
+`GPUShaderModule`. It is part of VGPU's public API surface and should be treated
+as semver-protected, but direct native WebGPU usage remains responsible for
+native WebGPU validation and lifecycle rules.

package/src/perf/perf.docs.md

@@ -0,0 +1,45 @@
+# @vgpu/render/perf
+
+Measurement utilities for the optimize loop: confirm a shader change is still correct and actually
+faster. **Tooling only — never call these on a live animation-frame path.** See the `measuring`
+guide (`vgpu docs cat /guides/measuring.docs.md`) for the workflow.
+
+## gpuFrameTime
+
+`gpuFrameTime(device, encode, options?)` measures median GPU time per frame for a render routine.
+
+The `encode(frame, index)` callback records the frame's passes onto a vgpu `Frame` — the same body
+you run in production. The harness owns warmup, the loop, submit, and timing. It uses GPU timestamp
+queries when the device exposes `timestamp-query`, otherwise wall-clock timing via
+`device.queue.flush()`.
+
+```ts
+import { gpuFrameTime } from "@vgpu/render/perf";
+
+const { medianMs, method } = await gpuFrameTime(device, (frame, i) => {
+  frame.renderPass(scenePass, (pass) => drawScene(pass, i));
+  frame.renderPass(floorPass, (pass) => drawFloor(pass, i));
+});
+```
+
+- `options.frames` (default 120), `options.warmup` (default 30), `options.batch` (wall-clock batch
+  size, default 8), `options.forceWallClock`, `options.label`.
+- Returns `GpuFrameTimeResult`: `{ medianMs, meanMs, minMs, p95Ms, samples, method }` where `method`
+  is `"timestamp-query"` or `"wall-clock"`.
+- Compare medians before vs after. For absolute numbers use a real-GPU device (`@vgpu/adapter-node`
+  Dawn or a browser); software backends give relative signal only.
+
+## pixelDiff
+
+`pixelDiff(a, b)` compares two renders byte-for-byte. Pass two `Texture`s (read back via
+`Texture.read()`) or two `Uint8Array`s.
+
+```ts
+import { pixelDiff } from "@vgpu/render/perf";
+
+const { maxByte } = await pixelDiff(before, after); // before/after are Texture or Uint8Array
+```
+
+Returns `PixelDiffResult`: `{ maxByte, meanByte, changedBytes, totalBytes, changedFraction }`.
+Interpret `maxByte` (max per-channel delta, 0–255): `0` bit-exact, `1–2` imperceptible
+(driver-rounding floor), more is a real visual change. A length mismatch surfaces as `maxByte = 255`.

package/src/rapid-renderer.docs.md

@@ -15,4 +15,18 @@ material has uniforms. The renderer does not write camera, transform, light, or
 material parameters.
 
 `clearValue` defaults to opaque black. `depthTarget` is optional. `renderer.gpu`
-returns the raw `GPUDevice`. `draw()` resolves after command submission.
+returns the raw `GPUDevice`. Like other `.gpu` fields, this is an advanced,
+semver-protected public escape hatch. `draw()` resolves after command submission.
+
+## Hot-path caveats
+
+`RapidRenderer` is optimized for examples and simple draws, not for hiding all
+homepage hot-path work. For performance-critical renderers, keep pipeline,
+buffer, bind-group, and render-bundle creation in setup/warmup code. Similarly,
+`material().writeUniforms()` writes CPU-side uniform data for later upload and
+should be scheduled deliberately.
+
+Do not resolve shaders, compile shaders, or rebuild pipelines inside the animation
+frame path. If shader source truly changes dynamically, resolve the shader and
+create the replacement pipeline outside the frame loop, then stage or
+double-buffer the swap so a completed pipeline is installed at a frame boundary.

package/src/render-bundle.docs.md

@@ -0,0 +1,46 @@
+# createRenderBundle
+
+`createRenderBundle(device, options)` records a WebGPU render bundle once during
+setup and returns the finished `GPURenderBundle`.
+
+Render bundles are reusable draw packets, not mini-passes. They do not own color
+or depth attachments and they do not decide ordering. Execute them from an
+explicit render pass with `pass.executeBundles([bundle])`, alongside the normal
+WebGPU state constraints for bundles and render passes.
+
+```ts
+const lightBundle = createRenderBundle(device, {
+  label: "hero.light-sources.bundle",
+  colorFormats: [format],
+  depthStencilFormat: "depth24plus",
+  sampleCount: 1,
+  record(bundle) {
+    bundle.setPipeline(lightPipeline);
+    bundle.setBindGroup(0, lightBindGroup);
+    bundle.draw(lightVertexCount);
+  },
+});
+
+const frame = beginFrame(device);
+frame.renderPass(lightPassDescriptor, (pass) => {
+  pass.executeBundles([lightBundle]);
+});
+frame.submit();
+```
+
+Options mirror the required parts of `GPURenderBundleEncoderDescriptor`:
+`colorFormats`, optional `depthStencilFormat`, optional `sampleCount`, and the
+optional depth/stencil read-only flags. The `record` callback receives a
+`RenderBundleRecorder` wrapper with `gpu` escape-hatch access plus convenience
+methods for `setPipeline`, `setBindGroup`, `setVertexBuffer`, and `draw`. The raw
+`bundle.gpu` recorder is an advanced, semver-protected public escape hatch to the
+underlying `GPURenderBundleEncoder`.
+
+Create bundles during setup or resize, not in the per-frame hot path. A bundle is
+compatible with the `colorFormats`, `depthStencilFormat`, `sampleCount`,
+`depthReadOnly`, and `stencilReadOnly` values it was recorded with. If resize or
+render-target reconfiguration changes any of those bundle-compatible fields,
+re-record the affected bundles before the next frame.
+
+VGPU preserves explicit pipeline, layout, and bind-group control. Bundle helpers
+never infer layouts and do not switch to `layout: "auto"` for performance.

package/src/render-target/render-target-canvas.docs.md

@@ -0,0 +1,15 @@
+# renderTargetForCanvas
+
+`renderTargetForCanvas(context, options?)` adapts the current texture from a
+`GPUCanvasContext` into a render target that can be passed to `pass()` and other
+`@vgpu/render/passes` helpers.
+
+The returned target resolves its `color` view lazily each time it is read, so it
+tracks `context.getCurrentTexture()` across frames. Use `label` and `clearColor`
+in the options object to configure the generated attachment metadata and default
+clear color.
+
+```ts
+const target = renderTargetForCanvas(canvasContext, { label: "screen" });
+pass({ mesh, material, target });
+```

package/src/storage-buffer.docs.md

@@ -0,0 +1,102 @@
+# StorageBuffer
+
+`StorageBuffer` is one stable storage buffer for a single render (or compute)
+pass, rewritten as needed and change-gated by the caller. It is the
+storage-buffer counterpart to `Uniform`: it creates a `storage | copy_dst`
+buffer, a bind group layout with a single storage binding at binding 0, and a
+bind group wired to that buffer. `write()` uploads bytes with
+`queue.writeBuffer` at a fixed offset — there is no dynamic offset and the bind
+group never changes.
+
+## When to use `StorageBuffer` vs `Uniform` vs `UniformPool`
+
+Use `StorageBuffer` when the data is too large or too dynamic for a uniform:
+arrays, runtime-sized data, particle/instance state, lookup tables. Storage
+buffers can be much larger than uniforms — up to the adapter's
+`maxStorageBufferBindingSize` (typically 128 MiB) versus a uniform's 64 KiB —
+and the shader can write them with `access: "read-write"`.
+
+Use `Uniform` for the common "globals/camera per pass" case: a small, fixed,
+read-only buffer (`var<uniform>`).
+
+Use `UniformPool` only when you have **many** small per-draw uniforms. It is a
+dynamic-offset ring allocator: every slot binding is marked
+`hasDynamicOffset: true` and the whole CPU mirror is re-uploaded each frame.
+
+## `access`: read vs read-write
+
+`access` controls the bind group layout entry type. Both modes default to
+`FRAGMENT | COMPUTE` visibility:
+
+- `"read"` (default) → WGSL `var<storage, read>`, layout type
+  `"read-only-storage"`.
+- `"read-write"` → WGSL `var<storage, read_write>`, layout type `"storage"`.
+
+> Neither default includes `VERTEX`. Read-write storage is forbidden in the
+> vertex stage outright. Read-only storage is _allowed_ in the vertex stage, but
+> `maxStorageBuffersInVertexStage` is **0** on many adapters (software/CI Vulkan,
+> some mobile GPUs) — a `VERTEX`-visible default silently invalidates the layout
+> there and the draw no-ops. For vertex-stage read-only storage, pass
+> `visibility: VERTEX | …` explicitly **and** raise `maxStorageBuffersInVertexStage`
+> via `requiredLimits` when requesting the device.
+
+## Constructor
+
+```ts
+new StorageBuffer(device, {
+  size,            // byte size of the storage buffer (required)
+  label,           // optional debug label for buffer, layout, and bind group
+  access,          // "read" (default) | "read-write"
+  visibility,      // GPUShaderStageFlags; defaults by access (see above)
+  bindGroupLayout, // optional pipeline-owned layout to reuse instead of creating one
+});
+```
+
+- `size`: byte size of the storage buffer. May be far larger than a uniform.
+- `label`: optional debug label; suffixed `.bgl` / `.bg` for the layout and bind
+  group.
+- `access`: `"read"` (default, read-only storage) or `"read-write"` (writable
+  storage). Selects the layout entry type and the default visibility.
+- `visibility`: shader stages that access binding 0. Defaults to
+  `FRAGMENT | COMPUTE` for both access modes (no `VERTEX` — see the note above).
+  Ignored when `bindGroupLayout` is provided.
+- `bindGroupLayout`: reuse a pipeline-owned bind group layout instead of creating
+  one. Its binding 0 must be a storage buffer compatible with `size` and
+  `access`.
+
+## Members
+
+- `storageBuffer.gpu`: the underlying storage `GPUBuffer`.
+- `storageBuffer.buffer`: the VGPU `Buffer` wrapper around `gpu`.
+- `storageBuffer.bindGroup`: the `GPUBindGroup` to bind for the pass.
+- `storageBuffer.bindGroupLayout`: the `GPUBindGroupLayout` (created or reused).
+- `storageBuffer.size`: the buffer byte size.
+- `storageBuffer.access`: the resolved access mode (`"read"` or `"read-write"`).
+- `storageBuffer.write(data, offset = 0)`: uploads `data` via
+  `device.queue.writeBuffer(gpu, offset, data)`. No dynamic offset; the bind
+  group is unchanged. Call only when the contents actually change.
+- `storageBuffer.destroy()` / `storageBuffer.dispose()`: releases the backing
+  buffer once; idempotent.
+
+## Example
+
+```ts
+// A read-only array the fragment shader samples:
+//   @group(0) @binding(0) var<storage, read> values: array<f32>;
+const storage = new StorageBuffer(device, { size: 4 * count, label: "values" });
+storage.write(new Float32Array(values));
+
+const pipeline = createRenderPipelineFromDescriptor(device, {
+  layout: device.gpu.createPipelineLayout({ bindGroupLayouts: [storage.bindGroupLayout] }),
+  vertex: { module, entryPoint: "vs_main" },
+  fragment: { module, entryPoint: "fs_main", targets: [{ format }] },
+});
+
+pass.setPipeline(pipeline);
+pass.setBindGroup(0, storage.bindGroup);
+pass.draw(3);
+
+// A compute-written scratch buffer:
+//   @group(0) @binding(0) var<storage, read_write> out: array<u32>;
+const scratch = new StorageBuffer(device, { size: 4 * count, access: "read-write" });
+```