@vgpu/render 0.0.4 → 0.0.6

package/README.md

@@ -1,8 +1,8 @@
 # @vgpu/render
 
-> 0.0.1 — early preview
+> 0.0.6 — early preview
 
-`@vgpu/render` is the small rendering layer on top of `@vgpu/core`. It currently focuses on two public building blocks: creating a render pipeline from a vgpu shader wrapper, and issuing a render pass against a texture or texture view. The package is intentionally narrow in 0.0.1 and leaves higher-level scene helpers for later releases.
+`@vgpu/render` is the small rendering layer on top of `@vgpu/core`. It focuses on explicit WebGPU-style control: create pipelines, encode standalone render passes, or build one frame command encoder with multiple user-ordered passes.
 
 ## Install
 
@@ -13,15 +13,23 @@ pnpm add @vgpu/render
 ## Exports
 
 ### Runtime
-- `createRenderPipeline`
+- `createRenderPipeline` / `createRenderPipelineAsync`
 - `RenderPass`
+- `beginFrame` / `Frame`
+- `createRenderBundle` / `RenderBundleRecorder`
+- `RapidRenderer`
 
 ### Types
 - `RenderPipelineOptions`
 - `ColorAttachment`
+- `DepthStencilAttachment`
 - `RenderPassOptions`
+- `RenderPassDrawOptions`
+- `RenderPassDynamicOffsets`
+- `FrameOptions`
+- `RenderBundleOptions`
 
-## Usage
+## Standalone pass
 
 ```ts
 import { App } from "@vgpu/core";
@@ -47,9 +55,90 @@ const pass = new RenderPass(device, {
 });
 pass.setPipeline(pipeline);
 pass.draw(3);
-pass.end();
+pass.end(); // finishes and submits this one-shot pass
 ```
 
+## Rapid renderer
+
+`RapidRenderer` is available for examples and simple one-draw submissions:
+
+```ts
+import { RapidRenderer } from "@vgpu/render";
+
+const renderer = new RapidRenderer(device);
+material.writeUniforms({ viewProjection, model, cameraPosition, light });
+await renderer.draw({ material, mesh, target, depthTarget });
+```
+
+For homepage-grade hot paths, do not resolve shaders or rebuild pipelines inside
+the animation-frame path. If shader source truly changes dynamically, resolve 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.
+
+## Explicit multipass frame
+
+Render bundles are setup-time reusable draw packets, not hidden passes or a render graph:
+
+```ts
+import { beginFrame, createRenderBundle } from "@vgpu/render";
+
+const bundle = createRenderBundle(device, {
+  label: "hero.light-sources.bundle",
+  colorFormats: ["rgba8unorm"],
+  depthStencilFormat: "depth24plus",
+  sampleCount: 1,
+  record(bundle) {
+    bundle.setPipeline(lightPipeline);
+    bundle.setBindGroup(0, lightBindGroup);
+    bundle.draw(lightVertexCount);
+  },
+});
+```
+
+Native WebGPU multipass code uses one command encoder, explicit pass begin/end calls, then one finish/submit:
+
+```ts
+const encoder = device.gpu.createCommandEncoder({ label: "hero.frame" });
+
+const lightPass = encoder.beginRenderPass(lightPassDescriptor);
+lightPass.executeBundles([bundle]);
+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`, the lifecycle is the same but pass end and final submission are harder to get wrong:
+
+```ts
+const frame = beginFrame(device, { label: "hero.frame" });
+frame.renderPass(lightPassDescriptor, (pass) => {
+  pass.executeBundles([bundle]);
+});
+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(); // finishes once and submits once
+```
+
+`Frame` preserves authored ordering and exposes its raw `GPUCommandEncoder` as `frame.gpu` for advanced commands. Direct raw encoder calls follow WebGPU behavior; VGPU helper methods guard use after `submit()` with `VGPU-FRAME-SUBMITTED`.
+
+For homepage-grade hot paths, create pipelines (sync or async), buffers, bind groups, and render bundles during setup/warmup or resize, then keep per-frame code to command encoding and one queue submit. `createRenderPipelineAsync()` defaults to `fallback: "sync"` with a once-only diagnostic when native async creation is unavailable; use `fallback: "throw"` if warmup must fail rather than block. Avoid runtime `resolveShader()`/shader creation in frame loops; dynamically changing shader source should be resolved and pipelined off the frame path, with staged or double-buffered swaps at frame boundaries.
+
+Raw `.gpu` properties such as `device.gpu`, `queue.gpu`, `buffer.gpu`, `texture.gpu`, `shader.gpu`, `frame.gpu`, and `RenderBundleRecorder.gpu` are intentional advanced escape hatches to native WebGPU objects and are treated as semver-protected public API. Native WebGPU validation and lifecycle rules still apply when using them directly.
+
 ## License
 
 MIT.

package/dist/frame.d.ts

@@ -0,0 +1,19 @@
+import { Buffer, type Device } from "@vgpu/core";
+import { type RenderPass, type RenderPassOptions } from "./render-pass.ts";
+export interface FrameOptions {
+    readonly label?: string;
+}
+export type FrameRenderPassCallback = (pass: RenderPass) => void;
+export declare class Frame {
+    private readonly device;
+    readonly gpu: GPUCommandEncoder;
+    private submitted;
+    constructor(device: Device, opts?: FrameOptions);
+    renderPass(opts: RenderPassOptions, record: FrameRenderPassCallback): void;
+    copyBufferToBuffer(source: Buffer | GPUBuffer, destination: Buffer | GPUBuffer, size: GPUSize64, sourceOffset?: number, destinationOffset?: number): void;
+    submit(): void;
+    dispose(): void;
+    private assertOpen;
+}
+export declare function beginFrame(device: Device, opts?: FrameOptions): Frame;
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAA6B,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AAEjE,qBAAa,KAAK;IAIJ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,OAAO,CAAC,SAAS,CAAS;gBAEG,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB;IAIpE,UAAU,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAU1E,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,SAAI,EAAE,iBAAiB,SAAI,GAAG,IAAI;IAK/I,MAAM,IAAI,IAAI;IAMd,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,UAAU;CAQnB;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,KAAK,CAEzE"}

package/dist/frame.js

@@ -0,0 +1,50 @@
+import { Buffer, VGPUError } from "@vgpu/core";
+import { createRenderPassOnEncoder } from "./render-pass.js";
+export class Frame {
+    device;
+    gpu;
+    submitted = false;
+    constructor(device, opts = {}) {
+        this.device = device;
+        this.gpu = device.gpu.createCommandEncoder({ label: opts.label });
+    }
+    renderPass(opts, record) {
+        this.assertOpen("Frame.renderPass");
+        const pass = createRenderPassOnEncoder(this.device, opts, this.gpu);
+        try {
+            record(pass);
+        }
+        finally {
+            pass.end();
+        }
+    }
+    copyBufferToBuffer(source, destination, size, sourceOffset = 0, destinationOffset = 0) {
+        this.assertOpen("Frame.copyBufferToBuffer");
+        this.gpu.copyBufferToBuffer(gpuBuffer(source), sourceOffset, gpuBuffer(destination), destinationOffset, size);
+    }
+    submit() {
+        this.assertOpen("Frame.submit");
+        this.submitted = true;
+        this.device.queue.gpu.submit([this.gpu.finish()]);
+    }
+    dispose() {
+        if (!this.submitted)
+            this.submit();
+    }
+    assertOpen(where) {
+        if (!this.submitted)
+            return;
+        throw new VGPUError({
+            code: "VGPU-FRAME-SUBMITTED",
+            message: "Frame cannot encode or submit after submit().",
+            where,
+        });
+    }
+}
+export function beginFrame(device, opts = {}) {
+    return new Frame(device, opts);
+}
+function gpuBuffer(buffer) {
+    return buffer instanceof Buffer ? buffer.gpu : buffer;
+}
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAA2C,MAAM,kBAAkB,CAAC;AAQtG,MAAM,OAAO,KAAK;IAIa;IAHpB,GAAG,CAAoB;IACxB,SAAS,GAAG,KAAK,CAAC;IAE1B,YAA6B,MAAc,EAAE,OAAqB,EAAE;QAAvC,WAAM,GAAN,MAAM,CAAQ;QACzC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,UAAU,CAAC,IAAuB,EAAE,MAA+B;QACjE,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,CAAC;QACf,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IAED,kBAAkB,CAAC,MAA0B,EAAE,WAA+B,EAAE,IAAe,EAAE,YAAY,GAAG,CAAC,EAAE,iBAAiB,GAAG,CAAC;QACtI,IAAI,CAAC,UAAU,CAAC,0BAA0B,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,WAAW,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;IAChH,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACrC,CAAC;IAEO,UAAU,CAAC,KAAa;QAC9B,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,MAAM,IAAI,SAAS,CAAC;YAClB,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,+CAA+C;YACxD,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,OAAqB,EAAE;IAChE,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,SAAS,CAAC,MAA0B;IAC3C,OAAO,MAAM,YAAY,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -1,11 +1,15 @@
-export { createRenderPipeline } from "./pipeline.ts";
+export { beginFrame, Frame } from "./frame.ts";
+export { createRenderBundle, RenderBundleRecorder } from "./render-bundle.ts";
+export { createRenderPipeline, createRenderPipelineAsync } from "./pipeline.ts";
 export { RenderPass } from "./render-pass.ts";
 export { RapidRenderer } from "./rapid-renderer.ts";
 export { UniformPool } from "./uniform-pool.ts";
-export type { RenderPipelineOptions } from "./pipeline.ts";
+export type { FrameOptions, FrameRenderPassCallback } from "./frame.ts";
+export type { RenderBundleOptions } from "./render-bundle.ts";
+export type { RenderPipelineAsyncFallback, RenderPipelineFragmentOptions, RenderPipelineOptions, RenderPipelineShaderInput, RenderPipelineStageOptions, RenderPipelineVertexOptions, } from "./pipeline.ts";
 export type { DrawSpec } from "./rapid-renderer.ts";
 export type { UniformLayout, UniformPoolOptions, UniformSlot } from "./uniform-pool-types.ts";
-export type { ColorAttachment, RenderPassDrawOptions, RenderPassDynamicOffsets, RenderPassOptions, } from "./render-pass.ts";
+export type { ColorAttachment, DepthStencilAttachment, RenderPassDrawOptions, RenderPassDynamicOffsets, RenderPassOptions, } from "./render-pass.ts";
 export { box, capsule, cone, cylinder, degToRad, disk, dodecahedron, fullscreenQuad, getMaterialDeclarations, icosahedron, icosphere, material, Mesh, octahedron, orthographicCamera, perspectiveCamera, plane, ring, sampler, sphere, srgb, tetrahedron, torus, wgslDeclarations } from "./domain/index.ts";
 export type { BoxSpec, Camera, CapsuleSpec, ConeSpec, CylinderSpec, DiskSpec, FullscreenQuadSpec, IcosphereSpec, Material, MaterialSamplerSpec, MaterialSpec, MaterialTextureSpec, MaterialUniformValue, Mat4, MeshGpu, MeshPrimitive, PlaneSpec, PolyhedronSpec, RingSpec, Sampler, SamplerSpec, SphereSpec, TextureKind, TextureSpec, TextureValue, TorusSpec, Vec3, VertexAttributes, VertexLayoutKind, WgslUniformType, WriteTextureValues } from "./domain/index.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9F,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7S,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,aAAa,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9F,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7S,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,aAAa,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,4 +1,6 @@
-export { createRenderPipeline } from "./pipeline.js";
+export { beginFrame, Frame } from "./frame.js";
+export { createRenderBundle, RenderBundleRecorder } from "./render-bundle.js";
+export { createRenderPipeline, createRenderPipelineAsync } from "./pipeline.js";
 export { RenderPass } from "./render-pass.js";
 export { RapidRenderer } from "./rapid-renderer.js";
 export { UniformPool } from "./uniform-pool.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAUhD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoBhD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/pipeline.d.ts

@@ -1,16 +1,37 @@
-import type { Device, Shader } from "@vgpu/core";
+import { Shader, type Device } from "@vgpu/core";
+export type RenderPipelineShaderInput = Shader | GPUShaderModule;
+export type RenderPipelineAsyncFallback = "sync" | "throw";
+export interface RenderPipelineStageOptions {
+    /** VGPU Shader or raw GPUShaderModule for this stage. Defaults to RenderPipelineOptions.shader. */
+    readonly shader?: RenderPipelineShaderInput;
+    /** Descriptor-like alias for shader. */
+    readonly module?: RenderPipelineShaderInput;
+    /** Entry-point name. Kept for backwards compatibility with the first render helper API. */
+    readonly entry?: string;
+    /** Descriptor-like entry-point name. */
+    readonly entryPoint?: string;
+    readonly constants?: Record<string, GPUPipelineConstantValue>;
+}
+export interface RenderPipelineVertexOptions extends RenderPipelineStageOptions {
+    readonly buffers?: readonly (GPUVertexBufferLayout | null)[];
+}
+export interface RenderPipelineFragmentOptions extends RenderPipelineStageOptions {
+    readonly targets: readonly (GPUColorTargetState | null)[];
+}
 export interface RenderPipelineOptions {
-    readonly shader: Shader;
-    readonly vertex: {
-        readonly entry: string;
-    };
-    readonly fragment: {
-        readonly entry: string;
-        readonly targets: readonly GPUColorTargetState[];
-    };
+    /** Optional shared shader module used by vertex/fragment stages that do not provide their own module. */
+    readonly shader?: RenderPipelineShaderInput;
+    readonly vertex: RenderPipelineVertexOptions;
+    readonly fragment?: RenderPipelineFragmentOptions;
     readonly primitive?: GPUPrimitiveState;
+    readonly depthStencil?: GPUDepthStencilState;
+    readonly multisample?: GPUMultisampleState;
     readonly layout?: GPUPipelineLayout | "auto";
     readonly label?: string;
+    /** createRenderPipelineAsync fallback when GPUDevice.createRenderPipelineAsync is unavailable. Defaults to "sync". */
+    readonly fallback?: RenderPipelineAsyncFallback;
 }
 export declare function createRenderPipeline(device: Device, opts: RenderPipelineOptions): GPURenderPipeline;
+export declare function createRenderPipelineAsync(device: Device, opts: RenderPipelineOptions): Promise<GPURenderPipeline>;
+export declare function __resetCreateRenderPipelineAsyncFallbackWarningForTests(): void;
 //# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAA;KAAE,CAAC;IAChG,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAQnG"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,eAAe,CAAC;AACjE,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,0BAA0B;IACzC,mGAAmG;IACnG,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,EAAE,CAAC;CAC9D;AAED,MAAM,WAAW,6BAA8B,SAAQ,0BAA0B;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,mBAAmB,GAAG,IAAI,CAAC,EAAE,CAAC;CAC3D;AAED,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,6BAA6B,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sHAAsH;IACtH,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC;CACjD;AAOD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAEnG;AAED,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAkBvH;AAkDD,wBAAgB,uDAAuD,IAAI,IAAI,CAE9E"}

package/dist/pipeline.js

@@ -1,10 +1,77 @@
+import { Shader, VGPUError } from "@vgpu/core";
+// Warn once per JS process. This keeps compatibility fallback visible without spamming
+// apps that intentionally warm up multiple pipelines on implementations without
+// GPUDevice.createRenderPipelineAsync().
+let didWarnAboutAsyncFallback = false;
 export function createRenderPipeline(device, opts) {
-    return device.gpu.createRenderPipeline({
+    return device.gpu.createRenderPipeline(toRenderPipelineDescriptor(opts));
+}
+export async function createRenderPipelineAsync(device, opts) {
+    const descriptor = toRenderPipelineDescriptor(opts);
+    const createAsync = device.gpu.createRenderPipelineAsync;
+    if (typeof createAsync === "function") {
+        return createAsync.call(device.gpu, descriptor);
+    }
+    if ((opts.fallback ?? "sync") === "throw") {
+        throw new VGPUError({
+            code: "VGPU-RENDER-PIPELINE-ASYNC-UNAVAILABLE",
+            message: "GPUDevice.createRenderPipelineAsync is unavailable on this WebGPU implementation.",
+            fix: "Use fallback: 'sync' for compatibility or call createRenderPipeline() explicitly during setup/warmup.",
+            where: "createRenderPipelineAsync",
+        });
+    }
+    warnAsyncFallbackOnce();
+    return device.gpu.createRenderPipeline(descriptor);
+}
+function toRenderPipelineDescriptor(opts) {
+    const descriptor = {
         label: opts.label,
         layout: opts.layout ?? "auto",
-        vertex: { module: opts.shader.gpu, entryPoint: opts.vertex.entry },
-        fragment: { module: opts.shader.gpu, entryPoint: opts.fragment.entry, targets: [...opts.fragment.targets] },
+        vertex: {
+            module: stageModule(opts.vertex, opts.shader, "vertex"),
+            entryPoint: stageEntryPoint(opts.vertex),
+            constants: opts.vertex.constants,
+            buffers: opts.vertex.buffers ? [...opts.vertex.buffers] : undefined,
+        },
         primitive: opts.primitive,
-    });
+        depthStencil: opts.depthStencil,
+        multisample: opts.multisample,
+    };
+    if (opts.fragment) {
+        descriptor.fragment = {
+            module: stageModule(opts.fragment, opts.shader, "fragment"),
+            entryPoint: stageEntryPoint(opts.fragment),
+            constants: opts.fragment.constants,
+            targets: [...opts.fragment.targets],
+        };
+    }
+    return descriptor;
+}
+function stageModule(stage, fallback, stageName) {
+    const module = stage.module ?? stage.shader ?? fallback;
+    if (!module) {
+        throw new VGPUError({
+            code: "VGPU-RENDER-PIPELINE-MISSING-SHADER",
+            message: `Missing shader module for ${stageName} stage.`,
+            fix: "Pass options.shader for a shared module or pass vertex/fragment module or shader.",
+            where: `createRenderPipeline.${stageName}`,
+        });
+    }
+    return isShader(module) ? module.gpu : module;
+}
+function stageEntryPoint(stage) {
+    return stage.entryPoint ?? stage.entry;
+}
+function isShader(input) {
+    return input instanceof Shader;
+}
+export function __resetCreateRenderPipelineAsyncFallbackWarningForTests() {
+    didWarnAboutAsyncFallback = false;
+}
+function warnAsyncFallbackOnce() {
+    if (didWarnAboutAsyncFallback)
+        return;
+    didWarnAboutAsyncFallback = true;
+    globalThis.console?.warn?.("[vgpu/render] createRenderPipelineAsync is unavailable; falling back to synchronous createRenderPipeline(). Pass fallback: 'throw' to make this a structured VGPUError.");
 }
 //# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,IAA2B;IAC9E,OAAO,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACrC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM;QAC7B,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;QAClE,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAC3G,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/render-bundle.d.ts

@@ -0,0 +1,24 @@
+import { Buffer } from "@vgpu/core";
+import type { RenderPassDrawOptions, RenderPassDynamicOffsets } from "./render-pass.ts";
+export interface RenderBundleOptions {
+    readonly label?: string;
+    readonly colorFormats: readonly (GPUTextureFormat | null)[];
+    readonly depthStencilFormat?: GPUTextureFormat;
+    readonly sampleCount?: number;
+    readonly depthReadOnly?: boolean;
+    readonly stencilReadOnly?: boolean;
+    readonly record: (bundle: RenderBundleRecorder) => void;
+}
+export declare class RenderBundleRecorder {
+    readonly gpu: GPURenderBundleEncoder;
+    constructor(gpu: GPURenderBundleEncoder);
+    setPipeline(pipeline: GPURenderPipeline): void;
+    setBindGroup(index: number, group: GPUBindGroup | null, dynamicOffsets?: RenderPassDynamicOffsets): void;
+    setVertexBuffer(slot: number, buffer: Buffer | GPUBuffer | null, offset?: number, size?: GPUSize64): void;
+    draw(options: RenderPassDrawOptions): void;
+    draw(vertexCount: number, instanceCount?: number, firstVertex?: number, firstInstance?: number): void;
+}
+export declare function createRenderBundle(device: {
+    readonly gpu: GPUDevice;
+}, opts: RenderBundleOptions): GPURenderBundle;
+//# sourceMappingURL=render-bundle.d.ts.map

package/dist/render-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-bundle.d.ts","sourceRoot":"","sources":["../src/render-bundle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAExF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,EAAE,CAAC;IAC5D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;CACzD;AAED,qBAAa,oBAAoB;IACnB,QAAQ,CAAC,GAAG,EAAE,sBAAsB;gBAA3B,GAAG,EAAE,sBAAsB;IAEhD,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAI9C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,cAAc,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAIxG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,SAAI,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAIpG,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAC1C,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;CAatG;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EAAE,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAWlH"}

package/dist/render-bundle.js

@@ -0,0 +1,39 @@
+import { Buffer } from "@vgpu/core";
+export class RenderBundleRecorder {
+    gpu;
+    constructor(gpu) {
+        this.gpu = gpu;
+    }
+    setPipeline(pipeline) {
+        this.gpu.setPipeline(pipeline);
+    }
+    setBindGroup(index, group, dynamicOffsets) {
+        this.gpu.setBindGroup(index, group, dynamicOffsets);
+    }
+    setVertexBuffer(slot, buffer, offset = 0, size) {
+        this.gpu.setVertexBuffer(slot, gpuBuffer(buffer), offset, size);
+    }
+    draw(optionsOrVertexCount, instanceCount = 1, firstVertex = 0, firstInstance = 0) {
+        if (typeof optionsOrVertexCount === "number") {
+            this.gpu.draw(optionsOrVertexCount, instanceCount, firstVertex, firstInstance);
+            return;
+        }
+        this.gpu.draw(optionsOrVertexCount.vertexCount, optionsOrVertexCount.instanceCount ?? 1, optionsOrVertexCount.firstVertex ?? 0, optionsOrVertexCount.firstInstance ?? 0);
+    }
+}
+export function createRenderBundle(device, opts) {
+    const encoder = device.gpu.createRenderBundleEncoder({
+        label: opts.label,
+        colorFormats: opts.colorFormats,
+        depthStencilFormat: opts.depthStencilFormat,
+        sampleCount: opts.sampleCount,
+        depthReadOnly: opts.depthReadOnly,
+        stencilReadOnly: opts.stencilReadOnly,
+    });
+    opts.record(new RenderBundleRecorder(encoder));
+    return encoder.finish({ label: opts.label });
+}
+function gpuBuffer(buffer) {
+    return buffer instanceof Buffer ? buffer.gpu : buffer;
+}
+//# sourceMappingURL=render-bundle.js.map

package/dist/render-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-bundle.js","sourceRoot":"","sources":["../src/render-bundle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAapC,MAAM,OAAO,oBAAoB;IACV;IAArB,YAAqB,GAA2B;QAA3B,QAAG,GAAH,GAAG,CAAwB;IAAG,CAAC;IAEpD,WAAW,CAAC,QAA2B;QACrC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,YAAY,CAAC,KAAa,EAAE,KAA0B,EAAE,cAAyC;QAC/F,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IACtD,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,MAAiC,EAAE,MAAM,GAAG,CAAC,EAAE,IAAgB;QAC3F,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAClE,CAAC;IAID,IAAI,CAAC,oBAAoD,EAAE,aAAa,GAAG,CAAC,EAAE,WAAW,GAAG,CAAC,EAAE,aAAa,GAAG,CAAC;QAC9G,IAAI,OAAO,oBAAoB,KAAK,QAAQ,EAAE,CAAC;YAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;YAC/E,OAAO;QACT,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CACX,oBAAoB,CAAC,WAAW,EAChC,oBAAoB,CAAC,aAAa,IAAI,CAAC,EACvC,oBAAoB,CAAC,WAAW,IAAI,CAAC,EACrC,oBAAoB,CAAC,aAAa,IAAI,CAAC,CACxC,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAmC,EAAE,IAAyB;IAC/F,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC;QACnD,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;QAC3C,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,eAAe,EAAE,IAAI,CAAC,eAAe;KACtC,CAAC,CAAC;IACH,IAAI,CAAC,MAAM,CAAC,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,SAAS,CAAC,MAAiC;IAClD,OAAO,MAAM,YAAY,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC"}

package/dist/render-pass.d.ts

@@ -1,13 +1,25 @@
 import { Buffer, type Device, type Texture } from "@vgpu/core";
 export interface RenderPassOptions {
     readonly colorAttachments: readonly ColorAttachment[];
+    readonly depthStencilAttachment?: DepthStencilAttachment;
     readonly label?: string;
 }
 export interface ColorAttachment {
     readonly view: Texture | GPUTextureView;
     readonly loadOp: GPULoadOp;
     readonly storeOp: GPUStoreOp;
-    readonly clearValue?: readonly [number, number, number, number];
+    readonly clearValue?: GPUColor;
+}
+export interface DepthStencilAttachment {
+    readonly view: Texture | GPUTextureView;
+    readonly depthClearValue?: number;
+    readonly depthLoadOp?: GPULoadOp;
+    readonly depthStoreOp?: GPUStoreOp;
+    readonly depthReadOnly?: boolean;
+    readonly stencilClearValue?: GPUStencilValue;
+    readonly stencilLoadOp?: GPULoadOp;
+    readonly stencilStoreOp?: GPUStoreOp;
+    readonly stencilReadOnly?: boolean;
 }
 export interface RenderPassDrawOptions {
     readonly vertexCount: number;
@@ -19,15 +31,18 @@ export type RenderPassDynamicOffsets = readonly GPUBufferDynamicOffset[] | Uint3
 export declare class RenderPass {
     private readonly device;
     private readonly encoder;
+    private readonly submitOnEnd;
     private passEncoder;
     constructor(device: Device, opts: RenderPassOptions);
     get gpu(): GPURenderPassEncoder;
     setPipeline(pipeline: GPURenderPipeline): void;
     setBindGroup(index: number, group: GPUBindGroup | null, dynamicOffsets?: RenderPassDynamicOffsets): void;
     setVertexBuffer(slot: number, buffer: Buffer | GPUBuffer | null, offset?: number, size?: GPUSize64): void;
+    executeBundles(bundles: Iterable<GPURenderBundle>): void;
     draw(options: RenderPassDrawOptions): void;
     draw(vertexCount: number, instanceCount?: number, firstVertex?: number, firstInstance?: number): void;
     end(): void;
     dispose(): void;
 }
+export declare function createRenderPassOnEncoder(device: Device, opts: RenderPassOptions, encoder: GPUCommandEncoder): RenderPass;
 //# sourceMappingURL=render-pass.d.ts.map

package/dist/render-pass.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-pass.d.ts","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,wBAAwB,GAAG,SAAS,sBAAsB,EAAE,GAAG,WAAW,CAAC;AAEvF,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,WAAW,CAA8B;gBAEpB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB;IAQpE,IAAI,GAAG,IAAI,oBAAoB,CAS9B;IAED,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAI9C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,cAAc,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAIxG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,SAAI,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAIpG,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAC1C,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAcrG,GAAG,IAAI,IAAI;IAQX,OAAO,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"render-pass.d.ts","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,eAAe,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,wBAAwB,GAAG,SAAS,sBAAsB,EAAE,GAAG,WAAW,CAAC;AASvF,qBAAa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,WAAW,CAA8B;gBAEpB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB;IAQpE,IAAI,GAAG,IAAI,oBAAoB,CAS9B;IAED,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAI9C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,cAAc,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAIxG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,SAAI,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAIpG,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,IAAI;IAIxD,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAC1C,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAcrG,GAAG,IAAI,IAAI;IAQX,OAAO,IAAI,IAAI;CAGhB;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAGzH"}

package/dist/render-pass.js

@@ -1,16 +1,18 @@
 import { Buffer, VGPUError } from "@vgpu/core";
 const textureBrand = Symbol.for("vgpu/Texture");
+const renderPassEncoderSources = new WeakMap();
 export class RenderPass {
     device;
     encoder;
+    submitOnEnd;
     passEncoder;
     constructor(device, opts) {
         this.device = device;
-        this.encoder = device.gpu.createCommandEncoder({ label: opts.label });
-        this.passEncoder = this.encoder.beginRenderPass({
-            label: opts.label,
-            colorAttachments: opts.colorAttachments.map(colorAttachment),
-        });
+        const source = renderPassEncoderSources.get(opts);
+        renderPassEncoderSources.delete(opts);
+        this.encoder = source?.encoder ?? device.gpu.createCommandEncoder({ label: opts.label });
+        this.submitOnEnd = source?.submitOnEnd ?? true;
+        this.passEncoder = this.encoder.beginRenderPass(renderPassDescriptor(opts));
     }
     get gpu() {
         if (!this.passEncoder) {
@@ -31,6 +33,9 @@ export class RenderPass {
     setVertexBuffer(slot, buffer, offset = 0, size) {
         this.gpu.setVertexBuffer(slot, gpuBuffer(buffer), offset, size);
     }
+    executeBundles(bundles) {
+        this.gpu.executeBundles(bundles);
+    }
     draw(optionsOrVertexCount, instanceCount = 1, firstVertex = 0, firstInstance = 0) {
         if (typeof optionsOrVertexCount === "number") {
             this.gpu.draw(optionsOrVertexCount, instanceCount, firstVertex, firstInstance);
@@ -44,20 +49,48 @@ export class RenderPass {
         const pass = this.passEncoder;
         this.passEncoder = null;
         pass.end();
-        this.device.queue.gpu.submit([this.encoder.finish()]);
+        if (this.submitOnEnd)
+            this.device.queue.gpu.submit([this.encoder.finish()]);
     }
     dispose() {
         this.end();
     }
 }
+export function createRenderPassOnEncoder(device, opts, encoder) {
+    renderPassEncoderSources.set(opts, { encoder, submitOnEnd: false });
+    return new RenderPass(device, opts);
+}
+function renderPassDescriptor(opts) {
+    return {
+        label: opts.label,
+        colorAttachments: opts.colorAttachments.map(colorAttachment),
+        depthStencilAttachment: opts.depthStencilAttachment ? depthStencilAttachment(opts.depthStencilAttachment) : undefined,
+    };
+}
 function colorAttachment(attachment) {
     return {
-        view: isVGPUTexture(attachment.view) ? attachment.view.createView() : attachment.view,
+        view: textureView(attachment.view),
         loadOp: attachment.loadOp,
         storeOp: attachment.storeOp,
         clearValue: attachment.clearValue,
     };
 }
+function depthStencilAttachment(attachment) {
+    return {
+        view: textureView(attachment.view),
+        depthClearValue: attachment.depthClearValue,
+        depthLoadOp: attachment.depthLoadOp,
+        depthStoreOp: attachment.depthStoreOp,
+        depthReadOnly: attachment.depthReadOnly,
+        stencilClearValue: attachment.stencilClearValue,
+        stencilLoadOp: attachment.stencilLoadOp,
+        stencilStoreOp: attachment.stencilStoreOp,
+        stencilReadOnly: attachment.stencilReadOnly,
+    };
+}
+function textureView(view) {
+    return isVGPUTexture(view) ? view.createView() : view;
+}
 function gpuBuffer(buffer) {
     return buffer instanceof Buffer ? buffer.gpu : buffer;
 }

package/dist/render-pass.js.map

@@ -1 +1 @@
-{"version":3,"file":"render-pass.js","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-pass.js","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAA6B,MAAM,YAAY,CAAC;AAE1E,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAyChD,MAAM,wBAAwB,GAAG,IAAI,OAAO,EAA8C,CAAC;AAE3F,MAAM,OAAO,UAAU;IAKQ;IAJZ,OAAO,CAAoB;IAC3B,WAAW,CAAU;IAC9B,WAAW,CAA8B;IAEjD,YAA6B,MAAc,EAAE,IAAuB;QAAvC,WAAM,GAAN,MAAM,CAAQ;QACzC,MAAM,MAAM,GAAG,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClD,wBAAwB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACzF,IAAI,CAAC,WAAW,GAAG,MAAM,EAAE,WAAW,IAAI,IAAI,CAAC;QAC/C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,GAAG;QACL,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,SAAS,CAAC;gBAClB,IAAI,EAAE,wBAAwB;gBAC9B,OAAO,EAAE,gDAAgD;gBACzD,KAAK,EAAE,gBAAgB;aACxB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,WAAW,CAAC,QAA2B;QACrC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,YAAY,CAAC,KAAa,EAAE,KAA0B,EAAE,cAAyC;QAC/F,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IACtD,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,MAAiC,EAAE,MAAM,GAAG,CAAC,EAAE,IAAgB;QAC3F,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,cAAc,CAAC,OAAkC;QAC/C,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAID,IAAI,CAAC,oBAAoD,EAAE,aAAa,GAAG,CAAC,EAAE,WAAW,GAAG,CAAC,EAAE,aAAa,GAAG,CAAC;QAC9G,IAAI,OAAO,oBAAoB,KAAK,QAAQ,EAAE,CAAC;YAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;YAC/E,OAAO;QACT,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CACX,oBAAoB,CAAC,WAAW,EAChC,oBAAoB,CAAC,aAAa,IAAI,CAAC,EACvC,oBAAoB,CAAC,WAAW,IAAI,CAAC,EACrC,oBAAoB,CAAC,aAAa,IAAI,CAAC,CACxC,CAAC;IACJ,CAAC;IAED,GAAG;QACD,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,IAAI,IAAI,CAAC,WAAW;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,IAAI,CAAC,GAAG,EAAE,CAAC;IACb,CAAC;CACF;AAED,MAAM,UAAU,yBAAyB,CAAC,MAAc,EAAE,IAAuB,EAAE,OAA0B;IAC3G,wBAAwB,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IACpE,OAAO,IAAI,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAuB;IACnD,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,eAAe,CAAC;QAC5D,sBAAsB,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,sBAAsB,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,SAAS;KACtH,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,UAA2B;IAClD,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC;QAClC,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,UAAU,EAAE,UAAU,CAAC,UAAU;KAClC,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,UAAkC;IAChE,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC;QAClC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,YAAY,EAAE,UAAU,CAAC,YAAY;QACrC,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,iBAAiB,EAAE,UAAU,CAAC,iBAAiB;QAC/C,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,cAAc,EAAE,UAAU,CAAC,cAAc;QACzC,eAAe,EAAE,UAAU,CAAC,eAAe;KAC5C,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAA8B;IACjD,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC;AAED,SAAS,SAAS,CAAC,MAAiC;IAClD,OAAO,MAAM,YAAY,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC;AAED,SAAS,aAAa,CAAC,IAA8B;IACnD,OAAO,OAAO,CAAE,IAA2C,CAAC,YAAY,CAAC,CAAC,CAAC;AAC7E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vgpu/render",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Render pipeline + render pass abstractions for vgpu.",
   "keywords": [
     "webgpu",
@@ -58,7 +58,7 @@
   ],
   "dependencies": {
     "wgpu-matrix": "^3.4.2",
-    "@vgpu/core": "0.0.4"
+    "@vgpu/core": "0.0.6"
   },
   "vgpuExportBundleBudgetsGzipBytes": {
     ".": 49152,

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,94 @@
-# 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>
+```
+
+`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.
+
+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 },
+});
+```
+
+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 }] },
 });
 ```
 
-## Notes
+## 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/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 });
+```