Revision 4. Pure API-design document: migration, versioning and rollout planning are intentionally out of scope — this issue describes the target API and its contracts, nothing else. This revision simplifies: exactly one options type per factory (the *Descriptor / *Options split is gone), real multithreading is OffscreenCanvas + one agent that owns the whole GPU stack (nothing device-side crosses threads, so there is no clonability contract to design around), and every factory takes exactly one positional input after gpu. Adjudication of the 12 follow-up review comments is in the companion comment; previous texts in the edit history.

vNext API: typed options, unified frames, and pipeline preparation

Motivation

0.3.0 has four verified design gaps (confirmed in packages/vgpu-api/src):

1. compute(...).dispatch() creates its own encoder and submits immediately. Queue order is preserved — consecutive submits to the same GPUQueue execute in submission order — but a dispatch issued inside a frame callback submits before the frame's own encoder, which is submitted when the callback returns. Program order and execution order diverge, and compute and render cannot be encoded, instrumented and submitted as one explicit frame.
2. bundle() compiles missing pipelines synchronously in the hot path. There is no async preparation path, and bundle readiness is not observable.
3. uniforms() is values-first / order-dependent, and the real unmet need — one shared buffer reused across pipelines — has no good public path. Resource ownership is latched by call order (VGPU-R1-OWNERSHIP-FLIP), an error class that should be unrepresentable.
4. Reusable modules must accept gpu as a parameter even when everything they describe is static data: today a module cannot export "the bloom effect" as a value. After a device loss everything device-local dies — the only naturally surviving unit is plain data. The API should have a first-class name for it: one exported options type per factory, plain enough that a module with no gpu in scope can hold it in a const, and re-instantiable as-is against a new device.

Design principles: pay-for-what-you-import (tree-shakeable free functions; no method facades — see Rejected); one word per concept, no second spellings; costs are visible in the API (byte updates vs identity updates, sync vs async compilation); WebGPU platform vocabulary wherever it exists.

Design summary

1. One typed options object per factory — no new runtime primitive. draw, effect, compute and bundle each export exactly one input type (DrawOptions, EffectOptions, ComputeOptions, BundleOptions), taken in one positional slot after gpu. That single type carries the module story by itself: a module with no gpu in scope cannot put a device-local resource into export const bloom = { … } satisfies EffectOptions, because it has nothing device-local to put there. Composition is plain object spread — effect(gpu, { ...bloom, bindings: { globals } }) — never a second options argument with implicit merge precedence.
2. Unified frame — f.compute() / f.copyBuffer() / f.raw() join f.pass() in one encoder, one ordered command list, exactly one queue.submit().
3. prepare() — async pipeline preparation over combinations (a render pipeline cannot exist without the target signature). One compilation policy for draws, effects, computes and bundles: pendingPipelines: "sync" | "skip" | "throw", resolved call site → frame → gpu default. The default is "throw": encountering an unprepared pipeline during synchronous encoding fails immediately and does not start compilation. Async compilation happens only when the application enters an async path: explicit prepare(), the standalone renderOnce() / dispatchOnce() helpers, or background preparation selected by "skip". "sync" is the explicit exception: it creates pending pipelines inline and may stall. The policy is normally set once (at init() or per frame); the per-call form exists only for exceptions.
4. Explicit resource ownership — fixed at construction via { values, bindings }: .set() writes bytes on instance-owned values (never rebuilds bind groups), .bind() swaps resource identity (rebuilds exactly the affected group). The order-dependent ownership latch becomes unrepresentable.

The API by example

0. Hello mesh — the minimal happy path under the strict default

import { init, surface, geometry, draw, prepare, frameLoop, clock } from "vgpu";
import { box } from "vgpu/scene";

const gpu    = await init();
const screen = surface(gpu, canvas, { depth: true, sampleCount: 4 });
//             depth/sampleCount on surface() are NEW in this design (0.3.0 has them on target() only)
const mesh   = geometry(gpu, box());
const cube   = draw(gpu, { shader: litWgsl, geometry: mesh });

await prepare(gpu, [{ draw: cube, target: screen }]);   // the one async line the strict default asks for

frameLoop(gpu, (f) => {
  cube.set("camera", { viewProjection: mvpFor(clock(gpu).time) });  // binding-scoped: names the owned WGSL binding
  f.pass(screen, (p) => p.draw(cube));                  // prepared → draws; unprepared → VGPU-PIPELINE-PENDING
});

This is the canonical chain of the corpus (init → surface → clock → frameLoop, 10/21 projects) with exactly one addition: the prepare() line.

Normative — a Surface has a frame-independent pipeline signature. prepare() and every other target-signature consumer derive { colors: [surface.format], depth: depthFormatFor(opts.depth), sampleCount } from the surface's configuration, not from getCurrentTexture(). Preparing against a surface outside frame() is legal and is exactly this example's path; only encoding needs the current texture. (0.3.0 derives a surface's signature from the current texture and therefore rejects this call with VGPU-SURFACE-NOT-IN-FRAME — this clause is the design change that makes the canonical happy path implementable.) Frame-independent does not mean lifetime-independent: a disposed surface's signature is not derivable — reading it (and compiling against it) throws, matching every other operation on a disposed object.

1. Reusable modules: options objects are plain typed data

// bloom.ts — a reusable module. No gpu, no wiring, no runtime constructor.
import type { EffectOptions } from "vgpu";

export const bloom = {
  shader: bloomWgsl,
  blend: "additive",
} satisfies EffectOptions;

// app.ts — instantiation happens at the app edge, where gpu lives:
import { init, surface, effect, frameLoop } from "vgpu";
import { bloom } from "./bloom";

const gpu = await init();
const s   = surface(gpu, canvas, { depth: true, sampleCount: 4 });
const fx  = effect(gpu, bloom);                       // one positional input
const hdr = effect(gpu, { ...bloom, bindings: { globals } });  // composition is object spread

The type is the whole mechanism. There is one EffectOptions, not a data-only twin: a module that never receives a gpu has no device-local resource to smuggle into its exported constant, and the fields that can hold one (values, bindings) are only ever filled at the app edge. Validation happens at instantiation. Nothing here promises that an options object can be cloned or transferred across agents — see §8.

2. Unified frame: compute + copy + render, one submit

const sim = compute(gpu, simWgsl);                    // string | ShaderSource shorthand for { shader }

frameLoop(gpu, (f) => {
  f.compute(sim, Math.ceil(particleCount / 64));      // same encoder as the pass below
  f.copyBuffer({ source: staging, destination: uniformBuf }); // size defaults to source.size − sourceOffset
  f.pass(s, (p) => {
    p.draw(particles);   // p.draw() accepts Draw | Effect
    p.draw(fx);
  });
});   // exactly ONE queue.submit() — program order IS execution order

f.copyBuffer({ source, destination, size?, sourceOffset?, destinationOffset? }) mirrors copyBufferToBuffer: offsets default to 0, and an omitted size defaults to source.size − sourceOffset (the source remainder), exactly as WebGPU defines it. WebGPU's validation is preserved verbatim, not softened: size, sourceOffset and destinationOffset must be multiples of 4, sourceOffset + size ≤ source.size, destinationOffset + size ≤ destination.size, and source and destination must be different buffers. A destination too small for the source remainder is an error, never a truncated copy. Texture copies (texture↔texture, texture↔buffer) go through f.raw().

f.raw((encoder) => …) is the escape hatch for anything else that must land in this command buffer and submission: texture copies, clearBuffer(), resolveQuerySet(), debug markers, external encoders, and future WebGPU commands vgpu does not wrap yet. It operates between managed passes, so there is no managed render-pass state cache to reconcile. Normative clause — encoder ownership, lifetime and legal boundary:

type BorrowedCommandEncoder = Omit<GPUCommandEncoder, "finish">;

f.raw((encoder: BorrowedCommandEncoder) => { … });

• it encodes into the frame's existing GPUCommandEncoder, preserving program order and the frame's single submit;
• it is legal only while the frame's command encoder is open and no managed render/compute pass and no other f.raw() callback is active. Calling it from inside f.pass(…) / f.compute(…), or reentrantly from another f.raw() callback, throws VGPU-FRAME-ENCODER-LOCKED before the callback is invoked — no borrowed encoder is handed out and nothing is encoded;
• the callback is synchronous: it must not return a promise, and it must not retain the encoder past its own return — the borrow ends when it returns;
• finish() is unrepresentable, not merely forbidden: the parameter type is Omit<GPUCommandEncoder, "finish">, so submission stays the frame's job;
• any native render or compute pass begun inside the callback must also be ended inside it, before returning;
• no render-state cache invalidation or "state re-establishment" is implied. Render state belongs to a GPURenderPassEncoder, not to the top-level GPUCommandEncoder, so a raw block cannot perturb the state of vgpu's managed passes.

const stats    = gpu.gpu.createQuerySet({ type: "timestamp", count: 2 });   // gpu.gpu is the GPUDevice
const resolved = gpu.gpu.createBuffer({ size: 16, usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC });

frameLoop(gpu, (f) => {
  f.raw((encoder) => {                                   // between passes: what only f.raw() can express
    encoder.pushDebugGroup("simulation");
    encoder.clearBuffer(resolved, 0, 16);                 // no f.clearBuffer() exists — this is the path
    encoder.resolveQuerySet(stats, 0, 2, resolved, 0);    // app-owned query set: vgpu wraps none
    encoder.popDebugGroup();
  });
  f.compute(sim, Math.ceil(particleCount / 64));          // same encoder, same submit
  f.pass(s, (p) => p.draw(particles));
});

frameLoop(gpu, (f) => {
  f.pass(s, (p) => {
    p.draw(particles);
    f.raw(() => {});   // VGPU-FRAME-ENCODER-LOCKED — thrown before the callback runs
  });
});

Raw handles are reached through the .gpu accessor vgpu objects already ship — gpu.gpu is the GPUDevice, Texture.gpu a GPUTexture, Buffer.gpu a GPUBuffer, prepared.gpu the pipeline or bundle — and there is no second .raw spelling anywhere in the API. Buffer-to-buffer copies stay on f.copyBuffer(); f.raw() is for what vgpu does not wrap. f.raw() does not reach a Surface's current texture: that texture is frame-scoped and deliberately not exposed (there is no withSurface() — §4c), so surface readback remains surface.read() / surface.readFloats(). Persistent, user-visible Texture / Target handles are copyable through f.raw().

There is deliberately no interleavable p.raw() and no target-aware f.rawPass() in this design: handing out the real GPURenderPassEncoder inside a cache-managed pass makes vgpu's state unknowable (WebGPU has no state introspection or push/pop), and the alternatives — conservative invalidation, preservation flags, or a permanent wrapper over an evolving API — are all worse than waiting for a concrete need. The target-aware variant is tracked in #322 for a future version and must not block this design.

compute.dispatchOnce(n) remains for standalone use (own submit, explicit — see §7).

2a. Frame callbacks are synchronous

A Frame borrows one command encoder for exactly the dynamic extent of its callback. frame() and frameLoop() therefore accept synchronous functions only: the callback must finish recording before it returns, and a borrowed Frame is closed immediately afterwards.

A plain (frame) => void type is deliberately insufficient because TypeScript permits an async function returning Promise<void> wherever a void return is expected. The public callback type rejects every PromiseLike return while preserving ordinary block-bodied and expression-bodied synchronous callbacks:

type SyncReturn<R> =
  R extends PromiseLike<unknown> ? never : unknown;

type FrameCallback<R> =
  (frame: Frame) => R & SyncReturn<R>;

function frame<R>(gpu: Gpu, callback: FrameCallback<R>): void;
// frameLoop() uses the same FrameCallback<R> constraint.

frame(gpu, (f) => f.pass(screen, (p) => p.draw(cube))); // OK

frame(gpu, async (f) => {                                // Type error
  await loadAssets();                                    // Promise<void> is rejected
  f.pass(screen, (p) => p.draw(cube));
});

Async work happens before entering the frame:

const assets = await loadAssets();
await prepare(gpu, [{ draw: cube, target: screen }]);

frame(gpu, (f) => {
  f.pass(screen, (p) => p.draw(cube));
});

Runtime contract for JavaScript / any: if the callback returns a thenable, vgpu closes the borrowed Frame, discards that frame’s command encoder without submitting it, and throws VGPU-ASYNC-FRAME-CALLBACK. Any later call through an escaped Frame reference throws VGPU-FRAME-CLOSED. No partial frame is submitted.

This discard is the one explicit exception to the rule that a managed frame submits itself when its callback returns (§2): an async callback aborts the frame instead of submitting what it recorded — the frame is closed and its command buffer discarded, so the "one frame, one ordered command list, exactly one queue.submit()" guarantee is kept by submitting nothing at all rather than a prefix of the intended work.

2b. Most apps do not own the loop: external tickers are first-class

Real applications usually delegate the loop to an animation engine (GSAP, Motion, an XR session, a host framework). frame(gpu, cb) per tick is the primitive; frameLoop is convenience sugar for self-contained demos — the corpus already reflects this (8/21 examples run their own rAF loop).

// The animation engine owns the loop; vgpu renders one explicit frame per tick:
gsap.ticker.add((_time, deltaMs) => {
  clock(gpu).advance(deltaMs / 1000);   // manual clock: one tick per frame (existing contract)
  frame(gpu, (f) => f.pass(s, (p) => p.draw(fx)));
});

The strict compilation default matters most here: a hidden synchronous pipeline compile inside a third-party tick is a dropped animation frame in an engine the app does not control. Under the default policy that stall is impossible — an unprepared pipeline fails fast instead.

2c. Compute → render: the full data flow through a storage buffer

const particles = storage(gpu, N * 8, "read-write");   // shared storage buffer
const sim  = compute(gpu, { shader: simWgsl, values: { sim: { dt: 0.016 } }, bindings: { particles } });
const dots = draw(gpu, { shader: particleWgsl, instances: N, vertices: 6, bindings: { particles } });
// storage-driven instanced draw: no geometry — vertices come from the buffer the kernel writes

await prepare(gpu, [{ compute: sim }, { draw: dots, target: screen }]);

frameLoop(gpu, (f) => {
  f.compute(sim, Math.ceil(N / 64));       // writes `particles` — same encoder
  f.pass(screen, (p) => p.draw(dots));     // reads `particles` — guaranteed to run after
});                                        // one submit; program order IS execution order

Today this exact flow requires two independent submits (dispatch() owns its encoder) — motivation #1 is this example, mechanically. Note vgpu deliberately does no cross-encoder hazard tracking beyond WebGPU's own usage scopes (it is not a render graph); the only aliasing guard is compute-side writable double-bind rejection, unchanged.

3. prepare() + pendingPipelines: readiness is explicit, policy is named

const particles = draw(gpu, { shader: particleWgsl, geometry: quads });

// Warm every pipeline before the first frame — combinations, because a
// GPURenderPipeline requires the target signature (platform fact):
await prepare(gpu, [
  { draw: particles, target: s },
  { draw: fx,        target: s },   // `draw:` takes Draw | Effect — the same union p.draw() takes
  { compute: sim },
]);

// The policy is set ONCE — at init() or per frame. Per-call is for exceptions only:
frameLoop(gpu, (f) => {
  f.pass(s, (p) => p.draw(particles));   // prepared above → draws.
});                                       // unprepared → VGPU-PIPELINE-PENDING (default policy)

// Exception, per call site — a streaming asset that should appear when ready:
p.draw(streamedMesh, { pendingPipelines: "skip" });

// Prototyping / porting escape hatch — opt in to inline compilation app-wide:
// const gpu = await init({ pendingPipelines: "sync" });

Compilation paths (normative):

An already-prepared combination always reuses its cached pipeline; none of these paths creates another one.

Policy semantics (one chain for draws, effects, computes and bundles — call site → frame → gpu default):

• "throw" (the default — uniform across browser, mock and node; no dev/prod divergence): does not start compilation and throws VGPU-PIPELINE-PENDING with an actionable message ("await prepare(gpu, [{draw, target}]) before drawing, or opt in to inline compilation with pendingPipelines: 'sync'"). Synchronous encode contexts never compile pipelines implicitly — a compilation stall is a choice, never an accident. Tests simply call prepare(), which is instant on the mock device.
• "skip": the object is skipped this frame; async compilation is started/continued. A compilation failure moves the object to failed, is reported once via gpu.onError with a stable code, and the object keeps being skipped — it never throws per frame. A skipped compute producer does not cascade: consumers read the resource's previous contents (or its zero-initialized state). vgpu is not a render graph and does not pretend to have the dependency graph to do otherwise.
• "sync" (explicit opt-in): do the pending work inline — immediate WebGPU pipeline creation, and for a stale bundle a re-encode; may stall.

3b. What prepare() returns: one handle per requested combination

const [cube, sim] = await prepare(gpu, [
  { draw: cubeDraw, target: screen },
  { compute: simulation },
]);

cube.draw;       // the renderable, echoed back — the handle identifies the combination
cube.signature;  // resolved TargetSignature { colors, depth, sampleCount }
cube.gpu;        // GPURenderPipeline — the same-agent low-level escape hatch
sim.gpu;         // GPUComputePipeline (a compute request has no target signature)

const prepared = await prepare(gpu, { bundle: forest });  // single request → single handle
prepared.gpu;    // GPURenderBundle

type PrepareRequest =
  | { draw: Draw | Effect; target: CompileTarget }
  | { compute: Compute }
  | { bundle: Bundle };

type PreparedDraw    = { readonly draw: Draw | Effect; readonly signature: TargetSignature; readonly gpu: GPURenderPipeline };
type PreparedCompute = { readonly compute: Compute;                                         readonly gpu: GPUComputePipeline };
type PreparedBundle  = { readonly bundle: Bundle;      readonly signature: TargetSignature; readonly gpu: GPURenderBundle };

type PreparedFor<R> =
  R extends { compute: Compute } ? PreparedCompute :
  R extends { bundle: Bundle }   ? PreparedBundle  : PreparedDraw;

function prepare<const R extends PrepareRequest>(gpu: Gpu, request: R): Promise<PreparedFor<R>>;
function prepare<const R extends readonly PrepareRequest[]>(gpu: Gpu, requests: R): Promise<{ [K in keyof R]: PreparedFor<R[K]> }>;

Rules:

• Handles are data, not state. There is no prepared.status: prepare() rejects if any requested combination fails, with VGPU-PREPARE-FAILED enumerating every failure (renderable label + resolved signature + cause). Combinations that did compile stay cached, so re-preparing the good subset is free. Ignoring the result stays valid — the happy path is unchanged.
• The array form preserves request order and tuple inference; the single-request form returns one handle.
• prepared.gpu is the only low-level pipeline escape hatch (see the readiness rule: no per-object compile() / pipelineFor() spellings, and no compute.pipeline field), and it is same-agent only — like every device-local object.

4. Render bundles: record once, replay cheap, readiness observable

const forest = bundle(gpu, { target: s }, (p) => {
  for (const tree of trees) p.draw(tree);        // hundreds of draws, recorded once
});

forest.status;   // "pending-pipelines" | "ready" | "stale" | "failed" | "disposed"  (frozen union)
forest.error;    // the retained VGPUError while status === "failed"
await prepare(gpu, [{ bundle: forest }]);         // materializes the native GPURenderBundle

frameLoop(gpu, (f) => f.pass(s, (p) => p.bundles(forest)));

fx.set("params", { intensity });                  // byte update: bundle stays "ready"

fx.bind("input", nextTexture);                    // identity update: bundle goes "stale"
await prepare(gpu, [{ bundle: forest }]);         // re-encodes the retained logical recording; no rebuild()

forest.rebuild((p) => { for (const t of trees) p.draw(t); }); // only when the command list itself changes
// rebuild() is SYNCHRONOUS (it is called at the edge of a synchronous frame callback); it replaces the
// logical recording, clears any retained error from the previous recording, and leaves the bundle
// "stale", or "pending-pipelines" if the new recording introduces an uncompiled combination.
await prepare(gpu, [{ bundle: forest }]);         // the ONE spelling for awaiting bundle readiness

Rules: bundle() captures a logical command list — the native bundle is materialized by prepare() (or by a "sync" replay, which may compile inline and is exactly the stall this feature exists to avoid; the supported path is prepare()). An identity change only makes the native bundle stale: prepare() re-encodes the retained logical recording with current resources. rebuild() is reserved for replacing the logical command list itself. Replaying a non-ready bundle follows the pendingPipelines chain — never a silent hot-path compile. The full transition table is in API contracts. Recording a bundle needs only formats — never getCurrentTexture() — so bundle(gpu, { target: surface }, …) outside frame() is legal, exactly like prepare(). Under the "throw" default, construction records the logical command list without compiling: the bundle is born "pending-pipelines" and prepare() materializes it. Construction never throws for pending pipelines.

4b. Render-to-target: multi-pass chains, and why you bind the Target

const scene = target(gpu, { size: [512, 512], format: "rgba16float", depth: true });
const post  = effect(gpu, {
  shader:   postWgsl,
  values:   { params: { texel: scene.texelSize } },
  bindings: { src: scene },        // ← bind the TARGET, not scene.color (rule below)
});

await prepare(gpu, [{ draw: sceneDraw, target: scene }, { draw: post, target: screen }]);

frameLoop(gpu, (f) => {
  f.pass({ target: scene, clear: [0, 0, 0, 1] }, (p) => p.draw(sceneDraw));
  f.pass(screen, (p) => p.draw(post));
});

// Resize: the binding needs nothing — a Target binding auto-heals:
scene.resize(newSize);
// the binding re-normalizes to the new texture identity. A bundle recorded over `post` moves to "stale"
// through the same identity-change event. Its logical recording is still valid: `prepare(gpu, { bundle })`
// re-encodes it with the new texture before the next replay; no `rebuild()` is needed.
// Bindings auto-heal; native bundles require explicit preparation.

Bind the Target, not its texture snapshot. Binding the Target object wires resource-recreation events: resizes re-bind transparently and dependent bundles are marked stale. Binding .color (a Texture snapshot) has no recreation hook — it goes silently stale on resize. This formalizes behavior 0.3.0 already implements but its own example corpus gets wrong; under this design .bind("src", scene) is the canonical spelling.

4c. Surface is a presentation destination; Target is a bindable resource

const screen = surface(gpu, canvas, { depth: true, sampleCount: 4 });
const scene  = target(gpu, { size: screen.size, format: "rgba16float", depth: true });

const tonemap = effect(gpu, { shader: tonemapWgsl, bindings: { source: scene } });  // ✅ Target: persistent identity
const wrong   = effect(gpu, { shader: tonemapWgsl, bindings: { source: screen } }); // ❌ VGPU-SURFACE-NOT-BINDABLE

frameLoop(gpu, (f) => {
  f.pass(scene,  (p) => p.draw(world));
  f.pass(screen, (p) => p.draw(tonemap));
});

Normative distinction.

• Both are render destinations: accepted by f.pass() and by prepare() as a target signature. RenderDestination is the shared supertype (size, formats, sample count, clear color, resize, render-pass descriptor).
• Target additionally has persistent resource identity: it exposes .color/.colors/.depth, may be used as a texture binding, and auto-heals bindings across resize/recreation.
• Surface is presentation-only and is NOT a texture binding. Surface does not extend Target; passing one as a binding fails with VGPU-SURFACE-NOT-BINDABLE. Its presentation texture is frame-scoped: it may change every frame, so a bind group built over it would retain a view of a texture that is already invalid, and any bundle recorded over it would be continuously stale. There is no withSurface() / current-texture borrowing API.
• Readback from a surface stays an explicit copy, not a binding: surface.read() / surface.readFloats() (the canvas is configured COPY_SRC). f.raw() is not a second path to it — the current texture is never handed out, so a borrowed encoder cannot copy it; raw texture copies apply to persistent, user-visible Texture / Target handles.
• Resize invalidation is by signature, not by identity. A resize that preserves color format, depth format and sample count does not invalidate a prepared pipeline or a render bundle — only a change to that render-pass signature invalidates the corresponding prepared combinations.

5. uniform(): one shared resource across pipelines

const globals = uniform(gpu, { time: "f32", resolution: "vec2f" }); // schema shape = OQ2

const scenePass = draw(gpu, { shader: sceneWgsl, geometry: mesh, bindings: { globals } });
const post      = effect(gpu, { shader: postWgsl, bindings: { globals } });

globals.set({ time: t });   // ONE write — every pipeline bound to it sees the update

uniform() storage is zero-initialized (the WebGPU guarantee; corpus code already relies on it). No mandatory initial values. uniform() keeps its one-argument .set() because the receiver is the binding — that is not a second spelling of the instance-scoped form below.

6. Ownership fixed at construction: .set() is bytes, .bind() is identity

const fx = effect(gpu, {
  ...bloom,
  values:   { params: { intensity: 1 } },   // instance-owned uniform storage → .set()
  bindings: { globals, input: sourceTexture, inputSampler: linearSampler }, // external → .bind()
});

fx.set("params", { intensity: 0.8 });  // bytes only. Never rebuilds a bind group; bundles stay valid.
fx.bind("input", nextTexture);         // identity. Rebuilds exactly that group; bundles go stale.
globals.set({ time });                 // externally bound: update the resource, not the instance.

fx.set("input", otherTexture);         // ❌ VGPU-R1-EXTERNAL-BINDING — actionable error that
                                       // names the resource to update instead.

.set() has exactly one form: binding-scoped. The first argument names a WGSL binding owned by the instance; the second is its value:

set<K extends OwnedValueBinding>(binding: K, value: ValueUpdate<ValueFor<K>>): this;
// ValueUpdate<T> = T extends struct ? Partial<T> : T

• For a struct-typed binding the value is a partial: absent fields keep the last value written (merged on the CPU, then one rewrite of the complete struct).
• For a binding whose WGSL type is not a struct (mat4x4f, vec4f, array<f32,N>), the value is the binding's complete value — there is no partial.
• There is no object-wide form (cube.set({ camera: … })), no member-name shortcut (post.set({ time: 0.5 }) without naming params), no batch alias and no single-binding overload. One spelling keeps updates intentional, removes the binding-vs-member ambiguity (a runtime error today) and collapses N member writes into a single struct rewrite.
• Externally shared resources are updated on the resource (globals.set({ time })); identity changes are exclusively instance.bind(binding, resource).

Rules:

• Ownership is declared once, at construction. The order-dependent latch (VGPU-R1-OWNERSHIP-FLIP) is unrepresentable in this model.
• A binding declared in the WGSL that does not appear in bindings is instance-owned (value-owned) by default; its storage is created at construction and zero-initialized. values supplies initial values and pins the type; it is not what creates ownership. That is why Example 0 can call cube.set("camera", …) without declaring values. Ownership is determined by construction in both cases — never by call order.
• .bind() dedupes by identity — re-binding the same resource is free.
• Owned→external transitions are not supported: recreate the instance (a plain options object makes that cheap).
• Multiple .set() calls before a submit do not snapshot: passes sharing an instance within a frame see the last value written (the writes land in the same buffer and all of them land before the single queue.submit()). For per-pass or per-draw values there is uniformArray + dynamic offsets, where the buffer identity is bound once and each draw selects a slot:

const jumps = uniformArray(gpu, { dist: "f32" }, cascadeCount);   // persistent slots, aligned stride
for (let i = 0; i < cascadeCount; i++) jumps.at(i).set({ dist: dists[i] });

const fx = effect(gpu, { shader: cascadeWgsl, bindings: { jump: jumps } });  // identity bound ONCE

f.pass(screen, (p) => {
  for (let i = 0; i < cascadeCount; i++) p.draw(fx, { slots: { jump: jumps.at(i) } });
});

slots is a per-draw encoding parameter, never .bind(): neither the buffer nor the bind group changes identity, so the instance rebuilds nothing and bundles do not go stale.

uniformArray contract:

uniformArray(gpu, schema, count): UniformArray   // one buffer, `count` persistent slots
array.at(i): UniformSlot                         // stable, memoized handle: at(i) === at(i)
slot.set(value)                                  // same semantics as the binding-scoped .set() (partial on structs)

• Slot stride = align(sizeof(schema), gpu.limits.minUniformBufferOffsetAlignment) (256 on most adapters): an f32 occupies a whole slot. The padding cost is visible and documented; for many small values, group fields into one struct per slot.
• at(i) out of range → error with a stable code, not a clamp.
• at(i) returns a stable handle (one per slot): using it in the encode loop preserves handle identity. TypeScript validates the binding name and slot schema, but two uniformArray instances with the same schema are structurally compatible. At draw/dispatch encoding or bundle-recording time, vgpu therefore verifies that slot.owner is the exact array bound to that binding; a mismatch throws VGPU-UNIFORM-SLOT-OWNER before encoding the affected operation, including through JavaScript/unknown paths.
• A draw whose binding is a uniformArray and that receives no entry in slots fails with a stable code (it does not silently fall back to slot 0). Consistent with the "throw" default: choices are explicit.
• More than gpu.limits.maxDynamicUniformBuffersPerPipelineLayout (8 by default) dynamic bindings on one instance → error with a stable code at construction, not at the first draw.
• Storage is zero-initialized, like uniform().
• slots is the same parameter in both encoding contexts: p.draw(inst, { slots }) and f.compute(inst, count, { slots }). Dynamic offsets work the same way in a compute pass; a draw-only parameter would leave "N dispatches with different parameters in one submit" without an answer and grow a second spelling later.
• Slots recorded in a bundle are part of the recorded command list. bundle() records setBindGroup(group, bg, offsets) with the slots current at recording time; changing slots afterwards produces no identity event and therefore does not move the bundle to stale — the bundle cannot observe it. Writing bytes into any slot is reflected on replay (same buffer). Rule: inside a bundle the per-draw slot is a recording constant; to vary the selection per frame, record each variant or do not use a bundle. BundleStatus gains no states.
• Slot writes update CPU-side state and are visible before the next submission that consumes the array; repeated writes to the same value observe the last write. vgpu may coalesce adjacent or repeated writes, but the number and shape of native upload operations are implementation details, not public API.

7. One-shot paths: renderOnce / dispatchOnce

await renderOnce(gpu, s, (p) => p.draw(quad));   // standalone render, own encoder + one submit
await sim.dispatchOnce(1024);                    // standalone compute, own encoder + one submit

dispatchOnce() is convenience for a compute operation that is independent of a frame loop: initialization, preprocessing, tests and headless work. If the compute pipeline is not ready, it awaits createComputePipelineAsync(), then creates its own command encoder and compute pass, records one dispatch and submits exactly once. An already-prepared pipeline is reused without compilation.

// Standalone work:
await sim.dispatchOnce(workgroups);

// Work that must share ordering and one submission with other commands:
frame(gpu, (f) => {
  f.compute(sim, workgroups);
  f.pass(screen, (p) => p.draw(result));
});

dispatchOnce() is not the API for work that belongs inside frame(): its encoder and submit are independent. Use f.compute() for that case. Both one-shot helpers resolve after pipeline readiness and submission — never after GPU completion. Waiting for completion is explicit and separate: await gpu.settled(). The pendingPipelines policy controls synchronous encode contexts; one-shot helpers always use their async readiness path.

8. Workers: one agent owns the whole GPU stack

Multithreading is canvas.transferControlToOffscreen() plus a worker that runs all of vgpu — init(), surface(gpu, offscreenCanvas), factories, frames (OffscreenCanvas is already a SurfaceCanvas). Nothing device-side crosses agents: no device, pipeline, resource, encoder, command buffer or render bundle, and the API deliberately carries no clonability contract that would suggest otherwise. initFromDevice(device) adopts a device owned by another library in the same agent (ORT, WebLLM, a host engine) — it is not a cross-thread mechanism.

9. Device loss is terminal: the app rebuilds, vgpu restores nothing

async function createGpuState(canvas: HTMLCanvasElement) {
  const gpu    = await init();
  const screen = surface(gpu, canvas, { depth: true, sampleCount: 4 }); // same canvas, new device
  const fx     = effect(gpu, bloom);                                    // GPU-independent module options: reused as-is
  await prepare(gpu, [{ draw: fx, target: screen }]);
  return { gpu, screen, fx };
}

let state = await createGpuState(canvas);
await state.gpu.lost;                    // proactive: resolves even if the app is idle
state = await createGpuState(canvas);    // rebuild everything device-local

Device-loss contract. Device loss is terminal for the Gpu and for every object created from it. vgpu never restores, reattaches or re-points an existing Surface, Target, texture, buffer, uniform/storage resource, geometry, instance, bind group, prepared pipeline or bundle onto a replacement device. On loss vgpu stops every frame loop it owns, marks the whole device-local object graph terminal, releases the CPU bookkeeping it can, and from then on every operation on that graph throws VGPU-DEVICE-LOST — fx.set() / fx.bind(), frame(gpu, cb) / frameLoop(), prepare(), a bundle replay, target.read(). The application must recreate: Gpu; surfaces/targets; textures, buffers, uniform/storage resources; Draw/Effect/Compute instances and their bind groups; prepared pipelines and render bundles. What is reusable is application data, not vgpu objects: GPU-independent configuration values and retained CPU-side state may be reused when constructing the new GPU subsystem, while any options value that holds a device-local object must be reconstructed — { ...bloom, bindings: { globals, input: oldTexture } } is not reusable against a new device, and neither is a values entry carrying a Target or a geometry buffer. That is ordinary application data reuse, not a vgpu restoration mechanism. The canvas itself is reused — the new device reconfigures its context. gpu.lost is a promise that resolves only on real device loss, with the platform's GPUDeviceLostInfo (delivered independently of gpu.onError, which reports operation failures); it is the terminal signal, and it never implies that individual vgpu objects are recoverable. An intentional gpu.dispose() is not a loss: gpu.lost never resolves after it — even though GPUDevice.destroy() resolves the native GPUDevice.lost with reason "destroyed", vgpu deliberately suppresses that (the behavior packages/core already implements via its observeLoss guard, core/src/device.ts:136-143). This keeps the canonical recovery pattern (await gpu.lost → rebuild) from firing a rebuild during teardown. Intentional disposal is observed synchronously through gpu.disposed. There is deliberately no onLost() callback — one spelling per semantic.

Design rules

• No second spellings. No new method may duplicate an existing one's semantics (p.draw() covers effects — no p.effect(); p.bundles() is canonical; gpu.lost has no callback twin).

• One call shape for the shader factories. Exactly one positional input after gpu, and one options type per factory:

  function effect(gpu: Gpu, input: string | ShaderSource | EffectOptions): Effect;
  function compute(gpu: Gpu, input: string | ShaderSource | ComputeOptions): Compute;
  function draw(gpu: Gpu, input: DrawOptions): Draw;   // no bare-string shorthand: a draw needs more than a shader

  A bare string | ShaderSource is shorthand for { shader }. Composing a module-exported options object with app-side resources is plain object spread — effect(gpu, { ...bloom, bindings: { input } }) — never a second options argument with implicit merge precedence. This retires the two shapes that coexist today (draw(gpu, opts) with the shader inside the bag vs. effect(gpu, source, opts) / compute(gpu, source, opts)) and follows the pattern already shipped for geometry (geometry(gpu, GeometryOptions | GeometryRecipe)).

• The shader field is spelled shader (readonly shader: string | ShaderSource) in all three factories — the spelling already shipped in DrawOptions. wgsl is a second spelling of one concept and additionally lies when the value is a loader ShaderSource artifact rather than WGSL text; code would be a string-only platform word, and source collides with copyBuffer({ source }).

• A binding bound to a uniformArray is a dynamic-offset binding, and that is part of the pipeline signature. hasDynamicOffset is decided at construction, from the kind of resource present in bindings, with per-binding granularity (not per group). Consequences: (1) bind-group-layout derivation stops being a pure function of the WGSL — it is a function of (reflection, set of dynamic-offset bindings), so the layout cache and the pipeline key must include that signature, and two instances of the same shader, one with a uniformArray and one without, are two different pipeline layouts; (2) prepare() prepares combinations of real instances, so the signature travels with the instance — its shape does not change, its cache key does; (3) the offset array passed to setBindGroup carries one offset per dynamic entry of the group, in binding order, and mixing a plain uniform() with a uniformArray in one group is valid, with only the latter dynamic.

• slots is the only typed spelling for dynamic offsets. slots: { binding: array.at(i) } covers every vgpu-managed binding. The raw offsets knob (numbers per group) is exclusively for raw groups adopted through claimGroup() / draw.group(), where vgpu knows neither the layout nor the sizes. Disjoint domains, not two spellings: passing offsets for a vgpu-managed group is an error with a stable code.

• Readiness is a property of a combination, never of an object. The unit of preparation is (renderable, target signature): a Draw can be ready for the screen, uncompiled for an HDR target and failed for a depth24plus-stencil8 target at the same time. No Draw/Effect/Compute carries ready/pending/failed fields, and no per-target status map is exposed: prepare() is the query (idempotent, O(1) on an already-prepared combination, and it rejects with the failure). Every other pipeline-affecting input (geometry vertex layout, topology/strip format, cull/front face, depth/stencil/multisample/blend state, pipeline constants, entry points) is fixed at construction of the renderable, so (renderable, signature) is a complete key — that is why prepare() needs no geometry: or state axis. The internal pipeline cache key is not public API (it embeds process-local module/layout ids).

• prepare() request keys mirror the encode call they warm. p.draw(Draw | Effect) → { draw, target }; f.compute(c) → { compute }; p.bundles(b) → { bundle }. There is no { effect } branch (the draw: key takes Draw | Effect, exactly like p.draw()) and no render: spelling (no encode API is called render at object granularity). A { bundle } request carries no target — a bundle froze its target signature at construction.

• One spelling for readiness: prepare(). There is no per-bundle readiness promise, no draw.compile() / compileSync(), no pipelineFor() and no DrawOptions.targets precompile list. Each of those is a per-object spelling of a per-combination fact, and the synchronous ones compile pipelines outside an async API — the exact behavior the pendingPipelines default forbids.

• compute() does not compile at construction. prepare(gpu, [{ compute: sim }]) and dispatchOnce() create a missing pipeline with createComputePipelineAsync(). f.compute() on an unprepared kernel follows the pendingPipelines chain exactly like a draw: default "throw" fails without starting compilation; "skip" starts or continues async compilation and omits the dispatch; explicit "sync" uses immediate createComputePipeline() inline and may stall. The public compute.pipeline field is replaced by prepared.gpu — one spelling for the same-agent low-level escape hatch.

• A Surface has a frame-independent pipeline signature — derived from its configuration, not from getCurrentTexture() (normative clause in Example 0). Preparing against a surface outside frame() is legal; only encoding needs the current texture.

• surface({ depth: true }) resolves to depth24plus — the same rule target() uses (depthFormatFor). The depth format is part of the pipeline signature; changing it invalidates prepared pipelines.

• sampleCount is the one spelling for multisampling on both surface() and target() (WebGPU platform vocabulary). 0.3.0's target({ msaa }) is renamed — msaa is not a second spelling.

• Depth and MSAA on surface() are new surface area, not a passthrough of target(): 0.3.0's Surface hardcodes depth: undefined / sampleCount: 1 and emits color-only render passes (surface.ts:146-147,181-188). The design requires Surface to own its internal depth/multisample attachments, recreate them on resize/auto-resize, and resolve MSAA into the presentation texture; depth: true resolves through the shared depthFormatFor (target-utils.ts:35-36).

• Transient attachments are automatic, not a flag. No public transient option: a transient attachment cannot be sampled or copied, and a public flag invites exactly that misuse. surface()/target() may allocate an internally-managed attachment with TRANSIENT_ATTACHMENT (feature-detected) only when the attachment satisfies all four conditions at allocation time: (1) vgpu allocated it and it is unreachable through every public accessor (.color, .colors, .depth, read(), readFloats(), and any binding path); (2) it is used exclusively as a render attachment — never sampled, copied, or bound; (3) every pass that can write it uses storeOp: "discard" / depthStoreOp: "discard"; (4) no public option can cause it to be loaded (preserve / loadOp: "load" / depthReadOnly). The predicate must be decidable when the texture is created — usage flags are immutable, so "nobody will preserve it later" is not something the implementation may assume. Under 0.3.0's shape this leaves only the intermediate multisample attachments of an MSAA target (already storeOp: "discard" / depthStoreOp: "discard", target-utils.ts:72,88). Explicitly not transient: a single-sample depth: true attachment (target.depth is public and bindable, target.ts:49; preserve loads it, target-utils.ts:88; depthReadOnly reads it across passes, target-utils.ts:79-87), and the canvas color texture (configured TEXTURE_BINDING | COPY_SRC, surface.ts:279). Whether the optimization is applied at all is an implementation detail; the normative part is the predicate that forbids it everywhere else.

• gpu.settled() is a snapshot, and it is the only place GPU completion is observable. At the moment of the call it snapshots everything vgpu has already started and resolves when all of it has finished:

  1. queue completion — GPUQueue.onSubmittedWorkDone() for every submission made before the call (unconditionally, not only when other bookkeeping happens to be in flight);
  2. pipeline compilation already started (prepare(), "skip" background compiles);
  3. readback mapping already started by vgpu (target.read(), timer/occlusion query rings);
  4. asynchronously reported errors — pending gpu.onError deliveries are flushed before it resolves, so a caller may await gpu.settled() and then read the errors it collected.

  Deliberately excluded: work submitted, compiled or requested after the call (the snapshot does not extend), and any readback the application did not start. settled() never rejects — failures are reported through gpu.onError; it is a completion/timing signal, not an error channel. Calling it twice is meaningful: each call takes a new snapshot.

• Feature-gated platform wins (subgroups, immediates) are internal: no public option, options field or capability flag exposes them, and none is ever assumed available.

• Indirect draw arguments are not public API. How the implementation batches them (aggregation in shared buffers, where it uses them at all) is free to change; no user-visible type refers to an indirect buffer.

• Resource indirection keeps a future bindless migration non-breaking — user code refers to resources by binding name, never by table index. Bindless and multi-draw-indirect are not promised (not in standard WebGPU).

Rejected alternatives (design rationale)

API contracts

These are normative invariants of the public API, stated so they can be falsified. How they are verified — fixtures, instrumentation, bundle-size measurement — is not part of this document.

1. A compute dispatch and a render pass recorded in the same frame() produce exactly one queue.submit(), in program order.

2. After a completed prepare() on a {draw, target} combination, encoding that combination in a frame() creates no pipelines: no createRenderPipeline/createComputePipeline is issued on the user-provided GPUDevice during encode.

3. pendingPipelines: default "throw" everywhere including mock/node (uniform — no dev/prod divergence) and it does not start compilation; "skip" starts/continues async compilation, never blocks the encode path and never throws per frame; "sync" performs immediate pipeline creation inline and is the only synchronous-compilation opt-in; resolution chain is call site → frame → gpu.

4. compute() performs no pipeline creation at construction. A missing compute pipeline is created through createComputePipelineAsync() by prepare() / dispatchOnce() and by background "skip" preparation; explicit "sync" instead uses immediate createComputePipeline() during encoding. Compute exposes no pipeline field.

5. Every factory exports exactly one input options type (DrawOptions, EffectOptions, ComputeOptions, BundleOptions) and no data-only twin of it; type-only imports (import type) contribute zero runtime bytes to the consumer bundle.

6. Combination-scoped readiness: preparing { draw: d, target: a } does not make { draw: d, target: b } ready, and a failure on b neither throws for a nor mutates any state observable through d.

7. prepare() returns handles: the array form preserves order and tuple types; prepared.gpu is the same object the encode path uses; prepare() rejects with VGPU-PREPARE-FAILED listing every failed combination, and a subsequent prepare() of the succeeding subset performs no new createRenderPipeline call.

8. prepare() against a Surface outside frame() resolves (never VGPU-SURFACE-NOT-IN-FRAME), and the resolved signature equals the one used when encoding the same surface inside a frame.

9. .set() on a value-owned binding never rebuilds a bind group; .bind() rebuilds exactly the affected group; .bind() dedupes by identity; .set() of an externally-bound name fails with VGPU-R1-EXTERNAL-BINDING.

10. .set() exists only in binding-scoped form: a non-struct binding accepts its complete value, naming a member without naming the binding is rejected — today a runtime error with an actionable message naming the owning binding; making it a type error requires typed shader reflection, which is exactly open question 2 (a ShaderSource is { version, wgsl } and carries no binding info by design until a loader version bump) — and one call carrying N fields of a struct produces exactly one buffer write.

11. uniform() shared across two pipelines updates both with one write; storage is zero-initialized.

12. A binding bound to a uniformArray produces a bind group layout entry with hasDynamicOffset: true only on that binding; two instances of the same shader, one with and one without a uniformArray, produce different pipeline layouts.

13. p.draw(inst, { slots }) changes no identity: no createBindGroup is issued and an associated bundle stays ready; omitting slots for a dynamic binding throws a stable code; at(i) is identity-stable (Object.is(a.at(2), a.at(2))); slots is accepted identically by f.compute(inst, count, { slots }). TypeScript validates binding/schema compatibility, while an exact-owner mismatch (slot.owner !== boundUniformArray) throws VGPU-UNIFORM-SLOT-OWNER before the affected draw, dispatch or bundle command is recorded.

14. Slot stride is align(size, minUniformBufferOffsetAlignment); exceeding maxDynamicUniformBuffersPerPipelineLayout throws at construction. A slot write is visible before the next submission that consumes the array and repeated writes observe the last value; implementations may coalesce uploads, but native upload count and range selection are not API contracts.

15. Bundle state machine. BundleStatus = "pending-pipelines" | "ready" | "stale" | "failed" | "disposed" — frozen union. Semantics: pending-pipelines = pipelines still to compile (and the native bundle to encode); stale = pipelines compiled, the native bundle must be re-encoded from the retained logical recording — that re-encode is prepare(gpu, [{ bundle }]) (or an explicit "sync" replay); rebuild() is never required to leave stale. Every public transition:

    From	Event	To
    —	bundle(gpu, { target }, rec)	pending-pipelines (always: the native bundle is not materialized at construction)
    pending-pipelines | stale | failed	prepare(gpu, [{ bundle }]) succeeds	ready (compiles missing pipelines, then encodes the native bundle)
    any non-disposed	prepare() fails	failed, retaining the error in bundle.error
    ready	.set() byte update on a captured resource	ready (no transition)
    ready	.bind() identity update, or a captured Target recreating its texture (resize)	stale
    pending-pipelines | stale | failed	identity update	unchanged
    any non-disposed	rebuild(cb) (synchronous)	Clear bundle.error, then move to stale, or pending-pipelines if the new recording introduces an uncompiled combination. rebuild() replaces the logical command list; it never compiles and never throws for readiness reasons
    any	dispose()	disposed (terminal; releases the native bundle and the retained recording; a second dispose() is a no-op)

    prepare() on a ready bundle is a no-op. prepare() always retries a failed bundle — there is no "retryable failure" classification; during that retry bundle.error remains available and the status stays failed, then success clears the error and moves to ready. rebuild() clears the retained error immediately because it replaces the logical recording to which that failure belonged. bundle.error?: VGPUError is defined only while status is failed.

    Replay of a non-ready bundle follows the one pendingPipelines chain (call site → frame → gpu):

    • "throw": pending-pipelines → VGPU-PIPELINE-PENDING; stale → VGPU-R3-BUNDLE-STALE (message names prepare(gpu, { bundle }); no rebuild() is required); failed → the retained error is rethrown (cause preserved).
    • "skip": the bundle is skipped this frame; pending-pipelines starts/continues async compilation; failed is reported once via gpu.onError and keeps being skipped; stale is skipped — never silently re-encoded.
    • "sync": do the pending work inline — pending-pipelines: compile + encode (the stall this feature exists to avoid); stale: re-encode from the retained recording (bounded: no compilation — this is the opt-in auto-heal); failed: does not retry, the retained error is thrown (retry is only through prepare()).
    • disposed always throws VGPU-BUNDLE-DISPOSED, under every policy.

16. A bundle recorded with slots: at(0) replays with slot 0's offset even if it is later encoded with at(1); writing bytes into slot 0 is visible on replay.

17. dispatchOnce() / f.compute() validate integer workgroup counts ≥ 0 with a stable error code.

18. f.copyBuffer() with size omitted copies source.size − sourceOffset bytes; a range or 4-byte-alignment violation, or source === destination, fails with a stable error code and encodes nothing.

19. gpu.lost resolves without any intervening operation after a real device loss, and loss is terminal: every frame loop vgpu owns stops, and every subsequent operation on that Gpu's object graph — .set() / .bind(), frame() / frameLoop(), prepare(), a bundle replay, read() / readFloats() — throws VGPU-DEVICE-LOST; no vgpu object is ever re-pointed at a replacement device, and no API exists to ask for that. gpu.lost does not resolve after an intentional gpu.dispose() — it stays pending while gpu.disposed === true.

20. renderOnce() / dispatchOnce() use async pipeline readiness, own their encoder and submit exactly once; they resolve after readiness + submit and never await onSubmittedWorkDone. dispatchOnce() is for standalone compute; compute that belongs to a frame() uses f.compute() so it participates in that frame’s ordering and single submit.

21. gpu.settled() awaits onSubmittedWorkDone for submissions made before the call even when no validation, compilation or readback is pending; it does not await work submitted after the call; it flushes pending onError deliveries before resolving; it never rejects on a failed submission.

22. Transient-attachment safety predicate (negative contract). No attachment reachable through a public accessor is ever allocated with TRANSIENT_ATTACHMENT: a single-sample depth: true target's depth attachment, a target's .color/.colors, and a surface's canvas texture never carry the flag. Where the implementation does apply it to a private discard-only multisample attachment, it is feature-detected and its absence changes nothing observable. Applying the flag is not a required behavior — the required behavior is that it never appears on an observable attachment.

23. Surface is not a texture binding: effect(gpu, { shader, bindings: { src: surfaceInstance } }) and instance.bind("src", surfaceInstance) both fail with VGPU-SURFACE-NOT-BINDABLE, including through the JS/unknown path — structural typing is not the enforcement mechanism. A resize that preserves color format, depth format and sample count triggers no createRenderPipeline and leaves bundles ready; changing any of the three invalidates the corresponding prepared combinations.

24. frame() / frameLoop() reject callbacks whose inferred return type extends PromiseLike<unknown> while accepting synchronous block- and expression-bodied callbacks. Through JavaScript or any, returning a thenable throws VGPU-ASYNC-FRAME-CALLBACK, closes the borrowed frame and produces no submit — the single explicit exception to "a managed frame submits itself when its callback returns", and never a partial submit; use of a frame after its callback returns throws VGPU-FRAME-CLOSED.

25. f.raw() borrows the frame's open command encoder typed as Omit<GPUCommandEncoder, "finish">, so finish() is not callable at the type level and the frame keeps exactly one queue.submit(). It is legal only between managed passes — and so is every encoder-level command: f.compute() and f.copyBuffer() invoked inside an open f.pass() throw the same error. Invoked inside f.pass() / f.compute(), or reentrantly from another f.raw() callback, it throws VGPU-FRAME-ENCODER-LOCKED before invoking the callback, encoding nothing. This mirrors the platform: WebGPU §13.1 puts the command encoder in the "locked" state while a pass encoder is active, and any command issued in that state invalidates the whole encoder silently. The borrow ends when the callback returns synchronously: a native pass begun inside it must be ended inside it, and the callback must not retain the encoder (a thenable return is the VGPU-ASYNC-FRAME-CALLBACK case of contract 24). No Surface current texture is reachable through the borrowed encoder.

Out of scope

• Scene orchestration (#219 / #206 — this design only provides the shared prepare / pendingPipelines chokepoint).
• Build-time WGSL reflection in loaders (today's loader emits {version: 1, wgsl} only; docs must not promise typed uniforms from the loader).
• Interleavable p.raw() / target-aware f.rawPass() — tracked in #322.
• Bindless / multi-draw-indirect (not in standard WebGPU; the resource-indirection rule keeps the door open).
• The 0.3.0 behavior bug where preserve: true on an MSAA target loads an attachment whose storeOp was "discard" (target-utils.ts:69-72) — a bug of the shipped release, tracked separately in #323; this design only prevents the class going forward, through the transient predicate's four decidable conditions.
• Migration, versioning and rollout planning — deliberately not part of this document.
• Test strategy and verification tooling — the contracts above are stated as observable invariants; which fixtures, instrumentation or bundle-size measurements demonstrate them belongs to the implementation issue.

Open questions

1. Exact shape of the frameLoop ownership hook (8/21 examples avoid frameLoop today because it owns the present pass). The external-ticker positioning (§2b: frame() per tick is the primitive, frameLoop is sugar) may resolve this by demotion rather than by a new hook.
2. uniform() / values schema shape: { time: "f32" } literals vs reflection-derived (examples 5–6 are illustrative on this point).