@driftengine/core 3.61.0

package/dist/render/particlePool.d.ts

@@ -0,0 +1,124 @@
+import type { InstanceData } from './instancedMesh.ts';
+import type { Vec3 } from '../math/color.ts';
+/**
+ * A pool's per-particle stream, as a particle material reads it.
+ *
+ * Separate from `InstanceData` — which is a *scatter* stream, built for placing
+ * thousands of static plants — because the two want different things and sharing
+ * one of them cost this engine its whole particle look. A blade of grass needs a
+ * yaw and a wind response and is opaque; a puff of smoke needs an **age**, a
+ * **seed** and an **opacity**, and has no wind of its own because its velocity
+ * already carries it.
+ *
+ * Lacking those three, the scatter path had to fake the one that matters: a
+ * particle "faded" by having its colour multiplied toward black, which is a real
+ * fade only if the material is additive. Drawn through the opaque foliage shader
+ * it is not a fade at all — it is a grain turning into a black cube — and that,
+ * rather than any tuning, is why every effect built on this read as raw.
+ */
+export interface ParticleInstances {
+    /** World position, three floats each. */
+    positions: Float32Array;
+    /** Metres across, and radians of roll about the particle's own axis. */
+    sizes: Float32Array;
+    spins: Float32Array;
+    /** Linear colour, three floats each. */
+    colors: Float32Array;
+    /** Opacity, 0 to 1 — a real one, not a colour standing in for it. */
+    alphas: Float32Array;
+    /** Age as a share of this particle's own life, for anything that evolves. */
+    ages: Float32Array;
+    /** Per-particle randomness, so neighbours never animate together. */
+    seeds: Float32Array;
+    /** Current velocity, three floats each: what a streak is stretched along. */
+    velocities: Float32Array;
+    count: number;
+    capacity: number;
+}
+/**
+ * A pool of short-lived particles, simulated on the CPU and drawn as instances.
+ *
+ * Deliberately not a new GPU path: `InstancedMesh` already uploads instance
+ * data per frame and already knows how to draw thousands of copies of one mesh
+ * in a single call, so a particle system is *only* the simulation. That keeps
+ * the whole thing testable — none of what follows needs a GL context — and
+ * keeps WebGL where the standing rule says it lives.
+ *
+ * A ring buffer, not a free list. Emission is continuous and the oldest
+ * particle is always the right one to reuse, so the bookkeeping a free list
+ * exists for is bookkeeping nobody needs; and overrunning it degrades by
+ * dropping the oldest, which is invisible, rather than by refusing to emit,
+ * which is visible exactly when the effect matters most.
+ */
+export interface ParticlePoolOptions {
+    capacity: number;
+    /** Seconds a particle lives. */
+    lifeSec: number;
+    /** Size at birth and at death, metres. */
+    sizeStart: number;
+    sizeEnd: number;
+    /** Colour at birth and at death. */
+    colorStart: Vec3;
+    colorEnd: Vec3;
+    /** Downward acceleration. Smoke wants a little; grit wants a lot. */
+    gravity: number;
+    /** How fast motion decays, per second. */
+    drag: number;
+    /** Constant upward push, for anything that behaves like smoke. */
+    rise: number;
+    /**
+     * Opacity at birth and at death. Omitted means the old behaviour exactly —
+     * fully opaque, fading by colour — so no existing pool changes by a bit.
+     */
+    alphaStart?: number;
+    alphaEnd?: number;
+}
+export declare class ParticlePool {
+    private readonly options;
+    readonly instances: InstanceData;
+    /** The same particles, as a particle material wants them. See `ParticleInstances`. */
+    readonly particles: ParticleInstances;
+    private readonly x;
+    private readonly y;
+    private readonly z;
+    private readonly vx;
+    private readonly vy;
+    private readonly vz;
+    private readonly age;
+    private readonly life;
+    private readonly spin;
+    private readonly scale;
+    /**
+     * The seed the caller emitted with, kept as well as hashed into `spin`.
+     *
+     * A material that animates — noise-eroded smoke, a stuttering spark — needs a
+     * per-particle constant to offset its own animation by, and a rotation is the
+     * wrong number for it: two particles a radian apart are visually unrelated but
+     * arithmetically adjacent, so noise sampled at the spin makes neighbours ripple
+     * together.
+     */
+    private readonly seedOf;
+    private next;
+    constructor(options: ParticlePoolOptions);
+    /** How many particles are alive. */
+    get live(): number;
+    /**
+     * Add one particle.
+     *
+     * `seed` drives the per-particle variation instead of `Math.random`, so a
+     * caller inside a deterministic system can pass a tick count and get the same
+     * plume twice — which a replay needs, since the same run has to look the same
+     * on the way to being a clip.
+     */
+    emit(x: number, y: number, z: number, vx: number, vy: number, vz: number, seed: number, sizeScale?: number, lifeScale?: number): void;
+    /**
+     * Advance every particle and rebuild the instance buffer.
+     *
+     * Compacting as it goes: live particles are written to the front of the
+     * instance data, so the draw call submits exactly the live count and dead
+     * particles cost nothing but the loop iteration.
+     */
+    update(dt: number): void;
+    /** Drop everything, for a respawn or a scene change. */
+    clear(): void;
+}

package/dist/render/particlePool.js

@@ -0,0 +1,182 @@
+import { createInstanceData, writeInstance } from './instancedMesh.js';
+function createParticleInstances(capacity) {
+    return {
+        positions: new Float32Array(capacity * 3),
+        sizes: new Float32Array(capacity),
+        spins: new Float32Array(capacity),
+        colors: new Float32Array(capacity * 3),
+        alphas: new Float32Array(capacity),
+        ages: new Float32Array(capacity),
+        seeds: new Float32Array(capacity),
+        velocities: new Float32Array(capacity * 3),
+        count: 0,
+        capacity,
+    };
+}
+export class ParticlePool {
+    options;
+    instances;
+    /** The same particles, as a particle material wants them. See `ParticleInstances`. */
+    particles;
+    x;
+    y;
+    z;
+    vx;
+    vy;
+    vz;
+    age;
+    life;
+    spin;
+    scale;
+    /**
+     * The seed the caller emitted with, kept as well as hashed into `spin`.
+     *
+     * A material that animates — noise-eroded smoke, a stuttering spark — needs a
+     * per-particle constant to offset its own animation by, and a rotation is the
+     * wrong number for it: two particles a radian apart are visually unrelated but
+     * arithmetically adjacent, so noise sampled at the spin makes neighbours ripple
+     * together.
+     */
+    seedOf;
+    next = 0;
+    constructor(options) {
+        this.options = options;
+        const { capacity } = options;
+        if (!Number.isInteger(capacity) || capacity <= 0) {
+            throw new Error('A particle pool needs a positive integer capacity.');
+        }
+        if (options.lifeSec <= 0)
+            throw new Error('Particles need a positive lifetime.');
+        this.instances = createInstanceData(capacity);
+        this.particles = createParticleInstances(capacity);
+        this.x = new Float32Array(capacity);
+        this.y = new Float32Array(capacity);
+        this.z = new Float32Array(capacity);
+        this.vx = new Float32Array(capacity);
+        this.vy = new Float32Array(capacity);
+        this.vz = new Float32Array(capacity);
+        this.age = new Float32Array(capacity).fill(Infinity);
+        this.life = new Float32Array(capacity);
+        this.spin = new Float32Array(capacity);
+        this.scale = new Float32Array(capacity).fill(1);
+        this.seedOf = new Float32Array(capacity);
+    }
+    /** How many particles are alive. */
+    get live() {
+        let count = 0;
+        for (let i = 0; i < this.age.length; i++) {
+            if (this.age[i] !== Infinity && this.age[i] < this.life[i])
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Add one particle.
+     *
+     * `seed` drives the per-particle variation instead of `Math.random`, so a
+     * caller inside a deterministic system can pass a tick count and get the same
+     * plume twice — which a replay needs, since the same run has to look the same
+     * on the way to being a clip.
+     */
+    emit(x, y, z, vx, vy, vz, seed, sizeScale = 1, lifeScale = 1) {
+        const i = this.next;
+        this.next = (this.next + 1) % this.instances.capacity;
+        this.x[i] = x;
+        this.y[i] = y;
+        this.z[i] = z;
+        this.vx[i] = vx;
+        this.vy[i] = vy;
+        this.vz[i] = vz;
+        this.age[i] = 0;
+        this.life[i] = this.options.lifeSec * lifeScale;
+        // Hashed rather than sequential: neighbouring particles must not share a
+        // rotation, or a plume reads as a single object turning.
+        const hash = Math.sin(seed * 12.9898 + i * 78.233) * 43758.5453;
+        this.spin[i] = (hash - Math.floor(hash)) * Math.PI * 2;
+        this.scale[i] = sizeScale;
+        this.seedOf[i] = seed;
+    }
+    /**
+     * Advance every particle and rebuild the instance buffer.
+     *
+     * Compacting as it goes: live particles are written to the front of the
+     * instance data, so the draw call submits exactly the live count and dead
+     * particles cost nothing but the loop iteration.
+     */
+    update(dt) {
+        const o = this.options;
+        let count = 0;
+        for (let i = 0; i < this.age.length; i++) {
+            const age = this.age[i];
+            if (age === Infinity)
+                continue;
+            const life = this.life[i];
+            const next = age + dt;
+            if (next >= life) {
+                this.age[i] = Infinity;
+                continue;
+            }
+            this.age[i] = next;
+            const decay = Math.max(0, 1 - o.drag * dt);
+            let vx = this.vx[i] * decay;
+            let vy = this.vy[i] * decay;
+            let vz = this.vz[i] * decay;
+            vy += (o.rise - o.gravity) * dt;
+            this.vx[i] = vx;
+            this.vy[i] = vy;
+            this.vz[i] = vz;
+            const px = this.x[i] + vx * dt;
+            const py = this.y[i] + vy * dt;
+            const pz = this.z[i] + vz * dt;
+            this.x[i] = px;
+            this.y[i] = py;
+            this.z[i] = pz;
+            const t = next / life;
+            const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * this.scale[i];
+            const r = o.colorStart[0] + (o.colorEnd[0] - o.colorStart[0]) * t;
+            const g = o.colorStart[1] + (o.colorEnd[1] - o.colorStart[1]) * t;
+            const b = o.colorStart[2] + (o.colorEnd[2] - o.colorStart[2]) * t;
+            /*
+             * Colour carries the fade rather than an alpha channel: the instanced
+             * path multiplies a tint into the base mesh and has no per-instance
+             * opacity, and for an additive puff darkening to nothing *is* fading out.
+             * It also means the effect needs no blend-state change.
+             */
+            const fade = 1 - t * t;
+            writeInstance(this.instances, count, px, py, pz, size, this.spin[i], r * fade, g * fade, b * fade, 0, 0, 0);
+            /*
+             * The same particle for a material that has a real opacity channel. Colour
+             * is written *unfaded* here, because dimming it is the scatter path's
+             * workaround and doing both would fade twice — a puff that vanished at half
+             * its life while still occluding what was behind it.
+             */
+            const p = this.particles;
+            const alphaStart = o.alphaStart ?? 1;
+            const alphaEnd = o.alphaEnd ?? 0;
+            p.positions[count * 3] = px;
+            p.positions[count * 3 + 1] = py;
+            p.positions[count * 3 + 2] = pz;
+            p.sizes[count] = size;
+            p.spins[count] = this.spin[i];
+            p.colors[count * 3] = r;
+            p.colors[count * 3 + 1] = g;
+            p.colors[count * 3 + 2] = b;
+            p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
+            p.ages[count] = t;
+            p.seeds[count] = this.seedOf[i];
+            p.velocities[count * 3] = vx;
+            p.velocities[count * 3 + 1] = vy;
+            p.velocities[count * 3 + 2] = vz;
+            count++;
+        }
+        this.instances.count = count;
+        this.particles.count = count;
+    }
+    /** Drop everything, for a respawn or a scene change. */
+    clear() {
+        this.age.fill(Infinity);
+        this.instances.count = 0;
+        this.particles.count = 0;
+        this.next = 0;
+    }
+}

package/dist/render/pass.d.ts

@@ -0,0 +1,195 @@
+import { type HandleRegistry } from './handleRegistry.ts';
+import type { FrameResource } from './frame/index.ts';
+/**
+ * A pass a package contributes, and the two contexts it is handed.
+ *
+ * **This is the one thing that makes a rendering package possible.** The renderer's verb surface
+ * is fixed and nothing outside `render/` can add to it, so `@driftengine/splats`, `ui2d` and `xr`
+ * had nowhere at all to put a draw call. `RENDERING.md` and the render graph design both name
+ * that as the thing blocking the package architecture rather than any shortage of machinery.
+ */
+/**
+ * What a registered pass is handed once, at registration, to build its resources.
+ *
+ * **Backend-specific on purpose.** A neutral device abstraction would be a second renderer API
+ * and an enormous one, and it would buy nothing: a package drawing Gaussian splats has a
+ * different shader, a different buffer layout and a different sort on each backend, so it
+ * branches whatever this looks like. A union makes the branch explicit and typed instead of
+ * hidden behind a lowest common denominator.
+ *
+ * `format` and `samples` ride along on the WebGPU side because a render pipeline cannot be built
+ * without them and a package has no other way to learn what the frame is.
+ *
+ * **`depthFormat` rides along for the same reason, and was missing for the same length of time
+ * nobody depth-tested through this seam (2026-08-25).** A pipeline that reads the depth buffer
+ * cannot be built without it either, and the only contributed pass in the tree hard-coded
+ * `depth24plus` with `depthCompare: 'always'` — invisible while a pass does not depth-test, and
+ * wrong the first time one does. Splats are that first one: a Gaussian is composed *into* the
+ * scene and has to be occluded by the geometry standing in front of it, which is a depth test
+ * against the frame's own attachment.
+ *
+ * What it costs: one more field every backend must answer honestly, which is the 2026-08-13 rule
+ * and not an accident. What would make it wrong: a frame with no depth attachment at all, which
+ * this renderer does not have and which would want the field to be nullable rather than absent.
+ */
+export type PassDevice = {
+    /**
+     * Pre-multiply a projection by this before uploading it. Identity on WebGL2.
+     *
+     * **The two APIs do not agree about which way clip space points, and the engine settles it in
+     * the matrix rather than in the shaders** — see `CLIP_CORRECTION`, whose own comment gives the
+     * reason: the shaders are generated from the GLSL the WebGL2 path uses, and a Y flip written
+     * into them would be a difference no generator could keep honest. WebGPU's framebuffer origin
+     * is the top-left and OpenGL's is the bottom-left, and depth clips to [0, 1] rather than
+     * [-1, 1].
+     *
+     * A contributed pass takes its camera from its caller, so it never sees the corrected matrix the
+     * renderer built for its own verbs. Without this it would have to copy four numbers — and a
+     * copied convention is one that silently disagrees the day the original changes. The splat pass
+     * drew the world upside down on WebGPU until this existed, which is the same first frame this
+     * backend ever produced: a colonnade hanging from the ceiling.
+     */
+    readonly clipCorrection: Float32Array;
+} & ({
+    readonly backend: 'webgl2';
+    readonly gl: WebGL2RenderingContext;
+} | {
+    readonly backend: 'webgpu';
+    readonly device: GPUDevice;
+    readonly format: GPUTextureFormat;
+    readonly depthFormat: GPUTextureFormat;
+    readonly samples: number;
+});
+/**
+ * What it is handed each frame, at the point the caller asked for it.
+ *
+ * On WebGL2 the framebuffer the frame is going into is already bound, so the context is the
+ * whole of it. On WebGPU the encoder is the pass, and it is the frame's own or the mirror's
+ * depending on where the caller invoked it — which is the caller's business and not this
+ * object's.
+ */
+export type PassContext = {
+    /**
+     * The grade this frame wants, and whether it wants one at all.
+     *
+     * **A contributed pass is a forward pass, so the 2026-08-17 rule binds it too**: with a
+     * composite the resolve grades and a pass that also graded would apply the curve twice; without
+     * one, each pass is the last thing to touch the frame and each must grade itself. The renderer
+     * decides which by whether it has a scene target, and that decision was private — so until this
+     * field a package could only guess, and both guesses are wrong half the time.
+     *
+     * 0 is none, and is what a frame with a composite reports. `OUTPUT_TRANSFORM_GLSL` is exported
+     * from the barrel so the pass applies the same curve rather than a copy of it.
+     */
+    readonly outputTransform: number;
+    /** The exposure that goes with it. 1 where the composite will apply the real one. */
+    readonly outputExposure: number;
+} & ({
+    readonly backend: 'webgl2';
+    readonly gl: WebGL2RenderingContext;
+} | {
+    readonly backend: 'webgpu';
+    readonly pass: GPURenderPassEncoder;
+});
+/**
+ * What a pass is handed once a frame, before the frame's own target exists.
+ *
+ * **A sibling of `PassContext` rather than a widening of it**, because the two carry different
+ * things and one of them cannot be nested inside the other. `draw` is invoked *inside* an open
+ * render pass on WebGPU, and a render pass cannot contain another; so a pass that wants to render
+ * into a target of its own needs a `GPUCommandEncoder` instead, and that is what this is.
+ *
+ * **The window it runs in already existed.** `beginFrame` creates the frame's command encoder and
+ * then defers opening the frame's render pass until the first draw that wants one — which
+ * `ensurePass` does for a measured reason about mirrors and tile memory. So there is a point at
+ * which an encoder exists and no render pass is open, and commands recorded on one encoder execute
+ * in recording order. A pass-owned target filled there has completed before any frame pass could
+ * sample it, **with the graph learning nothing and nothing reordered**.
+ *
+ * **On WebGL2 the contract is a restore rather than an ordering.** There is no verb-level graph on
+ * that backend and it was withdrawn on purpose, so there is nothing to schedule against. `prepare`
+ * is called before the frame's target is bound, with the **default framebuffer bound**, and must
+ * leave it bound. That is the same promise `draw` already makes about the program, the vertex
+ * array, the blend and depth state and the viewport — one step stronger, because a framebuffer
+ * left bound takes the whole frame with it rather than one draw. The asymmetry with WebGPU is real
+ * and is not papered over: there the ordering is a property of the encoder, and here it is a
+ * property of the caller's politeness.
+ */
+export type PrepareContext = {
+    readonly backend: 'webgl2';
+    readonly gl: WebGL2RenderingContext;
+} | {
+    readonly backend: 'webgpu';
+    readonly encoder: GPUCommandEncoder;
+};
+export interface PassDefinition {
+    /** For diagnostics, and for the label a backend gives the work. */
+    readonly label: string;
+    /**
+     * Attachments this pass samples.
+     *
+     * **Reads only, and that asymmetry is deliberate.** What a pass *writes* is wherever the
+     * caller is drawing, and is not negotiable: every built-in verb writes the current target and
+     * the executor replays a flush's nodes into one open pass, so a node declaring some other
+     * write-set schedules as a separate pass that nothing opens. Letting a package name its writes
+     * would hand it the single declaration nothing can enforce, whose failure mode is a scene
+     * quietly losing draws.
+     *
+     * A read, by contrast, is exactly what the scheduler needs from outside: declare `mirrorColor`
+     * and the frame stops deriving a discard for an attachment this pass is about to sample.
+     */
+    readonly reads?: readonly FrameResource[];
+    /**
+     * Fill a target the pass **owns**, once a frame, before anything opens the frame's own.
+     *
+     * **Shipped 2026-08-27, to the design this comment used to carry as a plan.** A package's own
+     * shadow map, blur pyramid or picking buffer: rendered here, sampled from `draw`. What a pass
+     * writes into the *frame* stays refused for the reason `reads` gives above, and a pass-owned
+     * target is outside that set by construction, which is what makes this declarable when a write
+     * to the frame is not. `createPassAttachment` builds one from the `PassDevice` this pass was
+     * handed at `init`; the pass releases it in its own `dispose`.
+     *
+     * **Called at one fixed point, for every pass that declares it, in registration order** — which
+     * must not become dependency ordering. Gate 1.2 withdrew that with a reason on record and this
+     * does not reintroduce it: registration order is an order, not a dependency graph, and a pass
+     * that needs another's output has to be registered after it and know that it does.
+     *
+     * **It costs nothing for a pass that does not declare it.** Both renderers keep a count of the
+     * passes that do and skip the whole step at zero, rather than walking the registry every frame
+     * to find out that nobody wants it.
+     *
+     * Allocates nothing, like `draw`. On WebGL2, leaves the default framebuffer bound — see
+     * `PrepareContext`, which is where that contract is written out.
+     */
+    prepare?(ctx: PrepareContext): void;
+    /** Build pipelines, buffers and textures. Called once, when the pass is registered. */
+    init?(device: PassDevice): void;
+    /**
+     * Draw. Called once a frame, at the point the caller invoked `drawPass`.
+     *
+     * **Allocates nothing.** This is a per-frame hot path and the engine's own rule about them
+     * binds a contributor exactly as it binds the renderer.
+     *
+     * **Leaves the context as it found it.** On WebGL2 that means the program, the bound vertex
+     * array, the blend and depth state and the viewport; the renderer's own verbs assume what they
+     * left. On WebGPU the pass encoder's pipeline and bind groups are set by every verb before it
+     * draws, so only the viewport and the scissor persist and only those two matter.
+     */
+    draw(ctx: PassContext): void;
+    /** Release what `init` built. Called on `unregisterPass` and when the renderer is disposed. */
+    dispose?(device: PassDevice): void;
+}
+/**
+ * A registered pass, as the caller holds it.
+ *
+ * A slot and a generation packed into one number rather than a bare index, so a handle kept past
+ * `unregisterPass` answers nothing instead of answering to whoever took the slot next. A package
+ * that was torn down and goes on drawing reads as a leak and is a use-after-free.
+ */
+export type PassHandle = number;
+export { drainRegistry, registerIn, unregisterIn } from './handleRegistry.ts';
+/** The pass registry: the generic slot table with the definition type filled in. */
+export type PassRegistry = HandleRegistry<PassDefinition>;
+export declare function createPassRegistry(): PassRegistry;
+/** The pass a handle names, or `undefined` if it names one that has been released. */
+export declare function passAt(registry: PassRegistry, handle: PassHandle): PassDefinition | undefined;

package/dist/render/pass.js

@@ -0,0 +1,9 @@
+import { createHandleRegistry, definitionAt } from './handleRegistry.js';
+export { drainRegistry, registerIn, unregisterIn } from './handleRegistry.js';
+export function createPassRegistry() {
+    return createHandleRegistry();
+}
+/** The pass a handle names, or `undefined` if it names one that has been released. */
+export function passAt(registry, handle) {
+    return definitionAt(registry, handle);
+}

package/dist/render/passTarget.d.ts

@@ -0,0 +1,86 @@
+import type { PassDevice } from './pass.ts';
+/**
+ * A render target a contributed pass owns: it renders into this and samples it later.
+ *
+ * **The asymmetry with `PassDefinition.reads` is the whole design and is worth reading first.**
+ * What a pass *writes into the frame* is not negotiable and is refused: every built-in verb writes
+ * the current target, the executor replays a flush's nodes into one open pass, and a node
+ * declaring some other write-set would schedule as a pass nothing opens — so letting a package
+ * name its writes hands it the one declaration nothing can enforce. A target the pass *owns* is
+ * outside that set by construction, which is exactly what makes it declarable when a write to the
+ * frame is not.
+ *
+ * What it is for: a package's own shadow map, blur pyramid, picking buffer or intermediate. A
+ * `@driftengine/splats` pass wanting a depth prepass of its own, a UI package wanting a cached
+ * layer, an XR package wanting a per-eye scratch.
+ *
+ * **Two implementations behind one call**, the same split `PassDevice` itself takes, and for the
+ * same reason: a neutral device abstraction would be a second renderer API and would buy nothing,
+ * because a package's shader, buffer layout and pipeline differ per backend anyway. The union
+ * makes the branch explicit and typed.
+ *
+ * **Single-sampled, and that is a decision rather than an omission.** A multisampled pass-owned
+ * target needs a resolve target beside it and a decision about who allocates it, and no
+ * contributed pass has asked. *What that costs* is that a pass wanting antialiased geometry of its
+ * own supersamples instead. *What would reverse it* is a contributed pass that needs it, at which
+ * point `samples` joins the options and the resolve target is created with the colour one.
+ *
+ * **`dispose` is the pass's to call**, from its own `dispose`, and nothing calls it for you: the
+ * renderer knows what it created and this is not that. A target left undisposed is a texture the
+ * driver holds until the context goes.
+ */
+export interface PassAttachmentOptions {
+    /** For the label a backend gives the texture, and for diagnostics. */
+    readonly label?: string;
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Eight bits a channel, or half floats.
+     *
+     * Two rather than the format zoo either API offers, because these are the two a pass drawing
+     * into its own target wants: a picking buffer or a cached layer is `rgba8`, and anything
+     * carrying light before a tone curve is `rgba16float`. A third would need a reason.
+     */
+    readonly format?: 'rgba8' | 'rgba16float';
+    /** Whether to attach a depth buffer. Default true, because a pass with geometry wants one. */
+    readonly depth?: boolean;
+}
+export type PassTarget = {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Free the GPU objects. Call it from the pass's own `dispose`, and call it before creating a
+     * replacement — **resizing is dispose-and-recreate** rather than a method, because a resize is
+     * not a per-frame path and a mutable target would be one more thing to keep consistent.
+     */
+    dispose(): void;
+} & ({
+    readonly backend: 'webgl2';
+    /** Bind this, draw, and bind `null` again. See `PassDefinition.prepare`. */
+    readonly framebuffer: WebGLFramebuffer;
+    readonly colour: WebGLTexture;
+    readonly depth: WebGLTexture | null;
+} | {
+    readonly backend: 'webgpu';
+    readonly colour: GPUTexture;
+    readonly colourView: GPUTextureView;
+    readonly depth: GPUTexture | null;
+    readonly depthView: GPUTextureView | null;
+    /** What a pipeline drawing into this must declare. */
+    readonly format: GPUTextureFormat;
+    readonly depthFormat: GPUTextureFormat | null;
+});
+/**
+ * Build one. Called from a pass's `init`, or from its `prepare` when the size has changed.
+ *
+ * **Restores the default framebuffer on WebGL2**, rather than whatever was bound before. Both
+ * points where a pass may call this — `init`, outside a frame, and `prepare`, whose contract is
+ * that the default framebuffer is bound on entry and on exit — have the default bound, so
+ * restoring to it is restoring what was there. Reading the binding back to restore it exactly
+ * would be a synchronous driver query in return for covering a case the contract forbids.
+ *
+ * Fails fast on a size that cannot work, which is the init-time rule: a zero-sized attachment is a
+ * framebuffer that is never complete, and a driver reports that as a black draw rather than an
+ * error.
+ */
+export declare function createPassAttachment(device: PassDevice, options: PassAttachmentOptions): PassTarget;