@solidrt/flux-types 0.0.50 → 0.0.52

package/README.md

@@ -46,12 +46,12 @@ rely on must be named.
 
 - `Flux` global (`version`, `capabilities`).
 - `flux:*` modules: `flux:http`, `flux:fs`, `flux:sqlite`, `flux:subprocess`,
-  `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:path`, `flux:wasm`, `flux:ffi`,
+  `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:tty`, `flux:path`, `flux:wasm`, `flux:ffi`,
   and (on a gui-enabled runtime)
-  `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`.
+  `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`, `flux:spatial`.
 - Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,
   `setTimeout`/`setInterval`/`queueMicrotask`, `performance`, `WebSocket`,
-  `TextEncoder`/`TextDecoder`. These are deliberate subsets matching exactly what
+  `TextEncoder`/`TextDecoder`, `crypto.subtle.digest`. These are deliberate subsets matching exactly what
   the runtime implements.
 - GUI globals (gui-enabled runtime only): `requestAnimationFrame` /
   `cancelAnimationFrame` (web-standard names, so kept global).

package/gui/audio.d.ts

@@ -1,7 +1,10 @@
-// Sound playback (gui-enabled runtime only). The imperative primitive; `play`
-// decodes and starts a clip in one call, while `load`/`loadPcm`/`stream` yield
-// a Clip that starts cheap overlapping Playbacks. Handles carry controls bound
-// to just that clip or playback, so raw ids never leave the runtime.
+// Sound playback (gui-enabled runtime only: feature-detect with
+// `Flux.capabilities.includes("audio")` before importing on a runtime that may
+// lack it - a static import fails at module load there). The imperative
+// primitive; `play` decodes and starts a clip in one call, while
+// `load`/`loadPcm`/`stream` yield a Clip that starts cheap overlapping
+// Playbacks. Handles carry controls bound to just that clip or playback, so
+// raw ids never leave the runtime.
 
 declare module "flux:audio" {
   /** Options for {@link play} and {@link Clip.play}. */
@@ -16,31 +19,97 @@ declare module "flux:audio" {
      * all, which for a mono clip is about 3 dB louder than `pan: 0`.
      */
     pan?: number
+    /**
+     * Playback rate: 1.0 plays as loaded, higher is faster and higher-pitched,
+     * lower slower and deeper (a plain resample, no formant correction).
+     * Clamped to [0.01, 100]. Defaults to 1.0.
+     */
+    rate?: number
+    /**
+     * Fade in from silence over this many milliseconds (sample-accurate).
+     * Defaults to 0 (start at full level).
+     */
+    fadeInMs?: number
+    /**
+     * Name of the bus this playback belongs to, so `stop({ bus })` can stop
+     * the whole group at once. Buses are plain names created by use - no
+     * setup call, and (for now) no per-bus gain.
+     */
+    bus?: string
+  }
+
+  /** Options for the live setters ({@link Playback.setGain} and friends). */
+  type RampOptions = {
+    /**
+     * Reach the new value by ramping over this many milliseconds instead of
+     * jumping. Linear, stepped by the engine at control rate (about every
+     * 10 ms), so a fade stays smooth regardless of the app's frame rate. A
+     * later set on the same parameter takes over from the ramp's current
+     * value; omitted (or 0) sets immediately and cancels any ramp in flight.
+     */
+    rampMs?: number
+  }
+
+  /** Options for {@link Playback.stop} and the module-level {@link stop}. */
+  type StopOptions = {
+    /**
+     * Fade to silence over this many milliseconds before stopping
+     * (sample-accurate) instead of cutting immediately. The playback keeps
+     * playing while it fades; ended() turns true once the fade completes.
+     */
+    fadeOutMs?: number
+  }
+
+  /** Options for the module-level {@link stop}. */
+  type StopAllOptions = StopOptions & {
+    /**
+     * Stop only the playbacks on this bus (see {@link PlayOptions.bus})
+     * instead of everything.
+     */
+    bus?: string
   }
 
   /** One playing instance of a clip, with live controls bound to it. */
   type Playback = {
-    /** Stop this playback. A no-op if it already finished. */
-    stop(): void
+    /**
+     * Stop this playback. A no-op if it already finished. Stopping is not
+     * pausing: a stopped playback is gone for good, including a looping one -
+     * to silence it temporarily, ramp its gain to 0 instead.
+     */
+    stop(options?: StopOptions): void
     /**
      * Change the volume while playing. A finite number >= 0; 1.0 is the clip's
      * own level. A no-op after the playback finished.
      */
-    setGain(gain: number): void
+    setGain(gain: number, options?: RampOptions): void
     /**
      * Move the stereo position while playing (see {@link PlayOptions.pan}).
+     * A ramped set on a never-panned playback sweeps from center. A no-op
+     * after the playback finished.
+     */
+    setPan(pan: number, options?: RampOptions): void
+    /**
+     * Change the playback rate while playing (see {@link PlayOptions.rate}) -
+     * a live rate sweep is how an engine revs or a doppler pass falls.
      * A no-op after the playback finished.
      */
-    setPan(pan: number): void
+    setRate(rate: number, options?: RampOptions): void
     /** Whether playback finished, naturally or via {@link stop}. */
     ended(): boolean
   }
 
   /** A loaded clip that can be played without re-decoding. */
   type Clip = {
-    /** Start a fresh overlapping playback of this clip. */
+    /**
+     * Start a fresh overlapping playback of this clip. Throws once 256
+     * playbacks are live at once - a guard that turns a runaway play() loop
+     * into an error instead of a saturated mixer.
+     */
     play(options?: PlayOptions): Playback
-    /** Release the clip. Playbacks already running keep going. */
+    /**
+     * Release the clip. Playbacks already running keep going; `play()` after
+     * unloading throws.
+     */
     unload(): void
   }
 
@@ -80,6 +149,41 @@ declare module "flux:audio" {
    * playback; do not overlap a stream with itself. Call `unload()` when done.
    */
   export function stream(source: ReturnType<typeof import("flux:fs").file>): Clip
-  /** Stop every playing sound. */
-  export function stop(): void
+  /**
+   * Stop every playing sound - or just one bus with `{ bus }` - fading it
+   * out first if asked. Stopping is not pausing: stopped playbacks (looping
+   * ones included) cannot be restarted - to silence a group temporarily,
+   * ramp gains to 0 instead.
+   */
+  export function stop(options?: StopAllOptions): void
+  /**
+   * Scale the whole mix: every playing and future flux:audio playback, on top
+   * of per-playback gains (1.0 = unchanged, 0 = silence). A finite number
+   * >= 0; ramps like the per-playback setters. Resets to 1.0 when the app
+   * reloads.
+   */
+  export function setMasterGain(gain: number, options?: RampOptions): void
+  /**
+   * Scale one bus (see {@link PlayOptions.bus}): a playback's audible level
+   * is its own gain x its bus's gain x the master gain, each layer set
+   * independently - none overwrites another. Applies to live and future
+   * playbacks on the bus, defaults to 1.0, resets to 1.0 when the app
+   * reloads, and ramps like the other gain setters.
+   *
+   * NOT IMPLEMENTED YET: calling this throws. Until it lands, keep the bus
+   * gain in the app and fold it into each voice's setGain - one ramped
+   * write per change:
+   *
+   * ```ts
+   * let musicGain = 0.3
+   * for (let v of musicVoices) v.setGain(voiceGain * musicGain, { rampMs: 200 })
+   * ```
+   */
+  export function setBusGain(bus: string, gain: number, options?: RampOptions): void
+  /**
+   * The mixer's output sample rate in Hz. Synthesize PCM at this rate and
+   * {@link loadPcm} feeds it to the mixer without a resample. Opens the audio
+   * device on first use, like the load and play calls.
+   */
+  export function outputSampleRate(): number
 }

package/gui/camera.d.ts

@@ -65,9 +65,10 @@ declare module "flux:camera" {
    * if permission is denied, and resolves once the first frame is ready. On
    * Linux a session that delivers neither within 10 seconds rejects with a
    * timeout error and releases the device (a wedged capture backend would
-   * otherwise hold it and never settle). Rejects with "camera subsystem is
-   * starting" while the subsystem is still coming up - wait for listCameras
-   * to report a device before opening.
+   * otherwise hold it and never settle). The first open also starts the
+   * camera subsystem and waits for it (on every platform, up to 10 seconds,
+   * then rejects with a timeout), so there is no need to poll listCameras
+   * before opening.
    */
   export function open(options?: CameraOpenOptions): Promise<CameraSession>
   /**

package/gui/gpu.d.ts

@@ -17,11 +17,12 @@
 // they return.
 //
 // Sampling is a per-texture property declared at creation: every create path
-// accepts `{ filter?, wrap? }` ("linear"/"nearest", "clamp"/"repeat";
-// defaults linear + clamp for every origin). The state follows the id
-// everywhere it is sampled - shader passes and `<texture>` display alike -
-// and survives id-stable resizes. It cannot be changed after creation. No
-// mipmaps exist.
+// accepts `{ filter?, wrap?, mipmap? }` ("linear"/"nearest", "clamp"/"repeat",
+// boolean; defaults linear + clamp + no mips for every origin). The state
+// follows the id everywhere it is sampled - shader passes and `<texture>`
+// display alike - and survives id-stable resizes. It cannot be changed after
+// creation. `mipmap: true` keeps a mip chain on the id, regenerated after
+// every upload or render, so shader sampling minifies without aliasing.
 //
 // Compositing several targets is a render-tree job, not a shader one: stack
 // `<texture>` elements and set their `blendMode` (the full Skia set, e.g.
@@ -103,8 +104,9 @@ declare module "flux:gpu" {
    * call site: a name with no active uniform, a value whose length does not
    * fit the declared type, a `sampler2D` named here (samplers bind via
    * `textures`), or a value that is not a number / number array throws.
-   * Reflection only sees active uniforms, so a uniform that is declared but
-   * optimized out counts as unknown - remove the write (or use the uniform).
+   * A uniform that is declared but optimized out by the compiler is accepted
+   * with a warning and the write is skipped, so one param object can drive
+   * shader variants that do not all use every uniform.
    * An `undefined` value is skipped, so conditional spreads stay usable.
    */
   export type ShaderParams = Record<string, number | number[]>
@@ -118,8 +120,29 @@ declare module "flux:gpu" {
    * sampler2D inputs AND `<texture src>` display (a "nearest" texture
    * upscales with hard pixels on screen - the pixel-art path). `wrap` only
    * matters to shaders sampling outside 0..1; the display draw never tiles.
-   */
-  export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode }
+   *
+   * `mipmap` (default false) keeps a mip chain on the id: rebuilt by the
+   * runtime after every upload (data textures) and every render (targets,
+   * automatically - nothing to schedule), and used by shader sampling when
+   * the texture is minified (trilinear for "linear", per-level nearest for
+   * "nearest"). Without it minification skips texels and aliases. Only
+   * shader sampling minifies through the chain; the `<texture>` display
+   * draw samples the full-size level. Regeneration is one GPU pass per
+   * upload or render, so a per-frame texture pays it per frame.
+   */
+  export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode; mipmap?: boolean }
+  /**
+   * One `textures` binding value: a texture id, sampled with the texture's
+   * own declared state, or `{ id, filter?, wrap? }` to sample that id with a
+   * different filter and/or wrap in this binding only (blur a "nearest"
+   * atlas linearly; tile a clamped target in one consumer). The override is
+   * a per-pass deviation: the texture's own state stays what `<texture>`
+   * paints and what every binding without an override uses. `mipmap` is
+   * not overridable - the chain either exists on the id or it does not.
+   */
+  export type TextureBinding = TextureId | { id: TextureId; filter?: FilterMode; wrap?: WrapMode }
+  /** Sampler2D inputs by uniform name; see {@link TextureBinding}. */
+  export type TextureBindings = Record<string, TextureBinding>
   /**
    * A free-form debug name every create accepts (WebGPU's label): surfaced by
    * the dev server's GPU inventory (get_gpu_resources) and in engine log
@@ -243,7 +266,7 @@ declare module "flux:gpu" {
     width: number,
     height: number,
     params?: ShaderParams | null,
-    opts?: { textures?: Record<string, TextureId> } & SamplerOptions & LabelOption,
+    opts?: { textures?: TextureBindings } & SamplerOptions & LabelOption,
   ): TextureId
   /**
    * Compile a single shader stage from raw GLSL ES: the primitive under
@@ -310,9 +333,16 @@ declare module "flux:gpu" {
        * arithmetic. Declaring any makes `instanceBuffer` required on every
        * entry drawn with this pipeline. A mat4 per instance is its four
        * vec4 columns, reassembled in the shader (attributes have no matrix
-       * formats, as in WebGPU).
+       * formats, as in WebGPU). Instance N always reads record N of the
+       * entry's buffer, from record 0 (ES 3.0 has no base instance), so
+       * several independently culled groups cannot share one buffer as
+       * sub-ranges: give each group its own `instanceBuffer` and entry, and
+       * cull it by `instanceCount`. Each attribute's `slot` (default 0)
+       * picks a buffer of the entry's `instanceBuffers` list (see
+       * {@link InstanceAttribute}); a pipeline using only slot 0 binds via
+       * the plain `instanceBuffer` key.
        */
-      instanceAttributes?: VertexAttribute[]
+      instanceAttributes?: InstanceAttribute[]
       topology?: Topology
       blend?: BlendMode
       cull?: CullMode
@@ -364,6 +394,18 @@ declare module "flux:gpu" {
    * read-modify-write of its own pixels (decay, blur, simulation) still
    * ping-pongs across two manual targets - a pass can never sample the
    * texture it writes.
+   *
+   * `samples` (1, 2, 4 or 8; default 1) multisamples the target's storage:
+   * edges of filled geometry get coverage-weighted AA instead of binary
+   * jaggies. Storage only - the texture id still names a single-sample
+   * image, so display, sampling, `readTexture` and `copyTexture` are
+   * unaffected. The count is clamped to the device maximum and a
+   * configuration the driver refuses falls back to single-sample with a
+   * warning (read the effective value off the resource inventory). Cannot
+   * combine with `loadOp: "load"` (throws): multisampled storage cannot
+   * load the previous contents. Tiled mobile GPUs resolve in-tile
+   * (EXT_multisampled_render_to_texture); everywhere else a resolve blit
+   * follows each pass.
    */
   export function createShaderTarget(
     pipeline: RenderPipelineId,
@@ -371,12 +413,16 @@ declare module "flux:gpu" {
     height: number,
     params?: ShaderParams | null,
     opts?: {
-      textures?: Record<string, TextureId>
+      textures?: TextureBindings
       buffer?: BufferId
       instanceBuffer?: BufferId
+      /** One buffer per instance slot of the pipeline (index = the
+       * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
+      instanceBuffers?: BufferId[]
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
+      samples?: 1 | 2 | 4 | 8
     } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
@@ -388,6 +434,16 @@ declare module "flux:gpu" {
    * immediately.
    */
   export function destroyProgram(id: ProgramId): void
+  /**
+   * The vertex attributes a linked program actually reads (name and format),
+   * as the compiler left them: an `in` the vertex stage never uses is not
+   * listed, and a type no layout can feed (a matrix, an integer vector) is
+   * rejected at linkProgram. This is the list a pipeline over the program
+   * must cover between `attributes` and `instanceAttributes` - an uncovered
+   * or mis-formatted one throws at createRenderPipeline. Answered locally,
+   * no GPU round trip.
+   */
+  export function programAttributes(program: ProgramId): VertexAttribute[]
   export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
   /**
    * Blending for a pipeline's own draw. "none" (default) overwrites:
@@ -439,6 +495,17 @@ declare module "flux:gpu" {
    * shader's `in` declarations.
    */
   export type VertexAttribute = { name: string; format: "f32" | "vec2" | "vec3" | "vec4" }
+  /**
+   * One float attribute of a per-instance record. `slot` (default 0) picks
+   * which buffer of the entry's `instanceBuffers` list the attribute
+   * fetches from: attributes sharing a slot interleave into one record in
+   * list order, distinct slots are distinct buffers with their own strides
+   * - which is what lets two writers own instance data independently (a
+   * core-written pose buffer beside an app-written style buffer). Slots
+   * must be dense from 0, at most 4; a single-slot pipeline (every `slot`
+   * omitted) binds via the plain `instanceBuffer` key.
+   */
+  export type InstanceAttribute = VertexAttribute & { slot?: number }
   /**
    * A pipeline target's draw as data, WebGPU-style: `firstVertex` +
    * `vertexCount` pick the vertex range `[firstVertex, firstVertex +
@@ -453,7 +520,9 @@ declare module "flux:gpu" {
    * buffer bound, `instanceCount` is bounds-checked against it like every
    * fetch (instances 0..N-1 each read one record). Two GL facts worth
    * knowing: `gl_VertexID` includes `firstVertex` (as in WebGPU), and
-   * `gl_InstanceID` always counts from 0 - ES 3.0 has no base instance.
+   * `gl_InstanceID` always counts from 0 - ES 3.0 has no base instance, so
+   * instance N reads record N of the entry's `instanceBuffer` and a group
+   * that is culled independently needs its own buffer and entry.
    */
   export type DrawRange = { firstVertex?: number; vertexCount?: number; instanceCount?: number }
   /**
@@ -486,6 +555,28 @@ declare module "flux:gpu" {
    * there is no base vertex (ES 3.0, like ES 3.0's missing base instance).
    */
   export type IndexRange = { firstIndex?: number; indexCount?: number; instanceCount?: number }
+  /**
+   * A draw entry's buffer swap: each key present re-points that role of the
+   * entry at another {@link createBuffer} buffer, absent keys keep their
+   * current buffer. Replace-only - the roles an entry fills are pipeline
+   * layout state (`attributes` needs a `buffer`, `instanceAttributes` an
+   * `instanceBuffer`) and indexing is its draw vocabulary, so naming a role
+   * the entry does not fill throws; `indexBuffer` travels with
+   * `indexFormat` as at create. The entry's current range is kept and
+   * rechecked against the new buffers' sizes: a swap to a buffer too small
+   * for the live range throws (shrink the range first); a larger buffer
+   * never does. This is the growth primitive: a population outgrowing its
+   * instance buffer creates a larger one, writes it, swaps, and destroys
+   * the old (the entry holds the old buffer alive until the swap lands, so
+   * either order is safe). `instanceBuffer` swaps slot 0;
+   * `instanceBuffers` swaps every slot at once and must fill exactly the
+   * slots the entry fills (pass one spelling or the other).
+   */
+  export type BufferUpdate = {
+    buffer?: BufferId
+    instanceBuffer?: BufferId
+    instanceBuffers?: BufferId[]
+  } & ({} | IndexBinding)
 
   /**
    * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
@@ -525,12 +616,15 @@ declare module "flux:gpu" {
     height: number,
     params?: ShaderParams | null,
     opts?: {
-      textures?: Record<string, TextureId>
+      textures?: TextureBindings
       attributes?: VertexAttribute[]
       buffer?: BufferId
       /** See {@link createRenderPipeline}'s `instanceAttributes`. */
-      instanceAttributes?: VertexAttribute[]
+      instanceAttributes?: InstanceAttribute[]
       instanceBuffer?: BufferId
+      /** One buffer per instance slot (index = the attributes' `slot`);
+       * pass this OR `instanceBuffer`, not both. */
+      instanceBuffers?: BufferId[]
       topology?: Topology
       depth?: boolean
       depthWrite?: boolean
@@ -539,6 +633,7 @@ declare module "flux:gpu" {
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
+      samples?: 1 | 2 | 4 | 8
     } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
@@ -546,10 +641,34 @@ declare module "flux:gpu" {
 
   /**
    * Create a vertex buffer from raw bytes (interleave attribute data to match
-   * the pipeline's attribute list). Buffer ids are their own space, separate
-   * from texture ids.
+   * the pipeline's attribute list), or from a byte length alone - a zeroed
+   * buffer, the natural create when the contents arrive through the write
+   * lease ({@link beginBufferWrite}). Buffer ids are their own space,
+   * separate from texture ids. Size is fixed for the id's lifetime: reserve
+   * the maximum up front and publish a prefix.
+   */
+  export function createBuffer(data: Uint8Array | number, opts?: LabelOption): BufferId
+  /**
+   * Open a zero-copy write into a vertex buffer: returns an ArrayBuffer over
+   * runtime-owned memory exactly the buffer's size. Write into it in place
+   * (wrap it in a Float32Array or any view), then publish with
+   * {@link endBufferWrite} - no copy happens anywhere on the CPU path.
+   *
+   * Contents are UNSPECIFIED at begin: a recycled block holds what was
+   * published the time before last, so fill everything you publish. One open
+   * write per buffer id at a time (a second begin throws). The view is
+   * detached at end/destroy - a retained reference becomes zero-length, and
+   * writes through it are inert, never a race.
+   */
+  export function beginBufferWrite(id: BufferId): ArrayBuffer
+  /**
+   * Publish the open write's first `byteLength` bytes at offset 0 (default:
+   * the whole buffer) and close the lease. `byteLength` 0 cancels: the lease
+   * closes and nothing is published. Always closes the lease, error or not;
+   * throws when no write is open or `byteLength` exceeds the buffer size.
+   * Pipelines drawing from the buffer re-render, like {@link writeBuffer}.
    */
-  export function createBuffer(data: Uint8Array, opts?: LabelOption): BufferId
+  export function endBufferWrite(id: BufferId, byteLength?: number): void
   /**
    * Overwrite part of a vertex buffer at `byteOffset` (default 0), within the
    * size it was created with. Pipelines drawing from the buffer re-render
@@ -575,9 +694,13 @@ declare module "flux:gpu" {
    * (On a manual target nothing renders here; the range applies at its next
    * {@link renderTarget}.) An indexed target takes the {@link IndexRange}
    * spelling instead, bounds-checked against its index buffer; the pair
-   * that does not match the target's mode throws.
+   * that does not match the target's mode throws. Buffer keys
+   * ({@link BufferUpdate}) swap the target's buffers in the same call: the
+   * merged range is checked against the swapped buffers, so one call grows a
+   * buffer and extends the range into it, and a call that throws changes
+   * nothing (range and buffers commit together or not at all).
    */
-  export function setDraw(id: TextureId, draw: DrawRange | IndexRange): void
+  export function setDraw(id: TextureId, draw: (DrawRange | IndexRange) & BufferUpdate): void
   /**
    * Create a draw target: a render target whose contents are an ordered,
    * mutable LIST of draws - one render clears once, then executes every
@@ -593,6 +716,10 @@ declare module "flux:gpu" {
    * occlusion work. It is the storage half of the depth story; whether an
    * entry tests/writes depth is its pipeline's `depth`/`depthWrite` state,
    * and adding a depth-testing pipeline to a target without storage throws.
+   * `depth: "texture"` is the same storage as a SAMPLEABLE depth texture
+   * with an id of its own - {@link depthTexture} - for shadow maps,
+   * depth-of-field, SSAO; it cannot combine with `samples` (a multisampled
+   * depth texture is not sampleable; the create throws).
    *
    * `params` seeds the target's SHARED params - the target-level values
    * every entry reads, the same live channel {@link setTargetParams} drives
@@ -608,8 +735,9 @@ declare module "flux:gpu" {
    * "auto"` target re-renders exactly when its entries or their inputs
    * change - a static scene costs zero passes, however many entries it
    * holds, and one render is ONE pass however many entries it draws.
-   * `render: "manual"` and `loadOp: "load"` compose exactly as on
-   * {@link createShaderTarget}. With no entries a render is the clear alone.
+   * `render: "manual"`, `loadOp: "load"` and `samples` compose exactly as
+   * on {@link createShaderTarget}. With no entries a render is the clear
+   * alone.
    * Returns a texture id (display, resize, destroy like any target; entries
    * die with it).
    */
@@ -618,14 +746,34 @@ declare module "flux:gpu" {
     height: number,
     params?: ShaderParams | null,
     opts?: {
-      depth?: boolean
-      textures?: Record<string, TextureId>
+      depth?: boolean | "texture"
+      textures?: TextureBindings
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
+      samples?: 1 | 2 | 4 | 8
     } & SamplerOptions &
       LabelOption,
   ): TextureId
+  /**
+   * The depth texture of a draw target created with `depth: "texture"`: a
+   * texture id of its own, stable for the target's life (a
+   * {@link setTargetSize} follows the color), holding the target's depth
+   * after every render - 24-bit window depth in 0..1, read as `.r` from a
+   * `sampler2D`. Bind it anywhere a texture binds ({@link setTargetTextures}
+   * for a whole scene target, an entry's `textures`, a fragment target's
+   * inputs); the dependency graph treats a binding to it as a binding to its
+   * target, so the depth pass renders first and a target sampling its own
+   * depth throws. SAMPLER-ONLY: it is not an upload texture and not a
+   * readback source (`readTexture`/`copyTexture` throw - render it through a
+   * pass to read it), its sampling is fixed at `nearest`/`clamp` (a depth
+   * texture is only complete at nearest without a comparison mode - filter
+   * in the shader, e.g. a PCF loop), and it dies with its target
+   * (`destroyTexture` on it throws). Displaying it via `<texture src>`
+   * shows the depth in the red channel. Throws for a target without texture
+   * depth.
+   */
+  export function depthTexture(target: TextureId): TextureId
   /**
    * Append a draw entry to a draw target: `pipeline` draws `opts.buffer`
    * (required when the pipeline declares attributes) with its own `params`
@@ -660,9 +808,12 @@ declare module "flux:gpu" {
     pipeline: RenderPipelineId,
     params?: ShaderParams | null,
     opts?: {
-      textures?: Record<string, TextureId>
+      textures?: TextureBindings
       buffer?: BufferId
       instanceBuffer?: BufferId
+      /** One buffer per instance slot of the pipeline (index = the
+       * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
+      instanceBuffers?: BufferId[]
       before?: DrawId
     } & (DrawRange | (IndexBinding & IndexRange)),
   ): DrawId
@@ -730,7 +881,7 @@ declare module "flux:gpu" {
    * everywhere it is declared, and each entry's effective inputs (its own
    * plus the applicable shared ones) must fit the device's texture units.
    */
-  export function setTargetTextures(target: TextureId, textures: Record<string, TextureId>): void
+  export function setTargetTextures(target: TextureId, textures: TextureBindings): void
   /**
    * Resize a render target of any kind in place and re-render it: the id,
    * compiled programs, last-applied params, sampler bindings, and draw
@@ -745,13 +896,19 @@ declare module "flux:gpu" {
    * validation, and cycle rules. Entries bind independently - two entries
    * may bind the same uniform name to different sources.
    */
-  export function setDrawTextures(target: TextureId, draw: DrawId, textures: Record<string, TextureId>): void
+  export function setDrawTextures(target: TextureId, draw: DrawId, textures: TextureBindings): void
   /**
    * Update one draw entry's draw range: {@link setDraw} addressed to a
    * single entry, same partial merge, bounds validation, and vocabulary
    * rule (an indexed entry speaks {@link IndexRange}).
    */
   export function setDrawRange(target: TextureId, draw: DrawId, update: DrawRange | IndexRange): void
+  /**
+   * Swap one draw entry's buffers: the {@link BufferUpdate} half of
+   * {@link setDraw} addressed to a single entry, same replace-only rule and
+   * range recheck.
+   */
+  export function setDrawBuffers(target: TextureId, draw: DrawId, update: BufferUpdate): void
   /**
    * Reorder a draw target's list. `order` must name every current entry
    * exactly once - a full permutation of the live {@link DrawId}s; a