@solidrt/flux-types 0.0.44 → 0.0.46

package/gui/gpu.d.ts

@@ -7,11 +7,14 @@
 // ids (-> destroyRenderPipeline).
 // Layering: compileShader/linkProgram are the raw GL primitives (complete
 // sources, explicit header opt-in); createRenderPipeline pairs a program with
-// draw state (topology, blend, depth, vertex layout - how it draws);
+// draw state (topology, blend, cull, depth, vertex layout - how it draws);
 // createShaderTarget builds a texture-backed target over a pipeline (size,
-// buffer, uniforms, clear - where it draws). createShaderTexture/
-// createPipelineTexture are fused conveniences (compile + link + pipeline +
-// target in one call, curated preamble) - named for what they return.
+// buffer, uniforms, clear - where it draws); createDrawTarget holds an
+// ordered, mutable LIST of such draws in one target (addDraw/removeDraw +
+// per-entry setters, sharing one depth buffer) - the multi-pass render pass.
+// createShaderTexture/createPipelineTexture are fused conveniences (compile +
+// link + pipeline + target in one call, curated preamble) - named for what
+// they return.
 //
 // Sampling is a per-texture property declared at creation: every create path
 // accepts `{ filter?, wrap? }` ("linear"/"nearest", "clamp"/"repeat";
@@ -81,6 +84,13 @@ declare module "flux:gpu" {
   export type ProgramId = number & { readonly __program: unique symbol }
   /** The render-pipeline id space ({@link createRenderPipeline}); see {@link TextureId} for the brand model. */
   export type RenderPipelineId = number & { readonly __renderPipeline: unique symbol }
+  /**
+   * A draw-entry handle on a draw target ({@link addDraw}); see
+   * {@link TextureId} for the brand model. Target-scoped and stable: an id
+   * keeps naming its entry across other adds and removes (never an index),
+   * and a removed entry's id errors from then on rather than aliasing.
+   */
+  export type DrawId = number & { readonly __draw: unique symbol }
   /**
    * Shader uniform values by name. A number drives a scalar uniform (`float`,
    * or `int`/`bool`, truncated); a flat number array drives a typed uniform
@@ -113,7 +123,7 @@ declare module "flux:gpu" {
    * messages, so a chain of targets reads as "bloom-h samples particle-verts"
    * instead of anonymous ids. Not unique, never interpreted; set at create,
    * kept across id-stable resizes ({@link resizeTexture},
-   * {@link setShaderSize}).
+   * {@link setTargetSize}).
    */
   export type LabelOption = { label?: string }
   /**
@@ -176,8 +186,8 @@ declare module "flux:gpu" {
    * working, and shaders sampling the texture re-render. `data` seeds the new
    * contents and, like {@link createMutableTexture}, must hold at least one
    * frame at the id's format (which survives the resize, like the sampler
-   * state). Shader/pipeline target ids are rejected - resize those with
-   * {@link setShaderSize}.
+   * state). Render target ids are rejected - resize those with
+   * {@link setTargetSize}.
    */
   export function resizeTexture(id: TextureId, data: Uint8Array, width: number, height: number): void
   /**
@@ -195,7 +205,7 @@ declare module "flux:gpu" {
    * for the value shapes and the validation contract - a typo'd name throws
    * here, at the create). It is its own argument, not an option, because it
    * is the initial value of a live channel - the same values the `<texture
-   * params>` prop and {@link setShaderParams} drive later; pass `null` (or
+   * params>` prop and {@link setTargetParams} drive later; pass `null` (or
    * omit it) for a shader with none. `opts.textures` binds sampler2D
    * uniforms to texture ids - any texture id, including another
    * shader/pipeline target's output, under a name that must be an active
@@ -273,19 +283,36 @@ declare module "flux:gpu" {
    * (its own id space, like programs and buffers - not a texture id): the
    * pipeline state object of every modern GPU API. The pipeline owns HOW its
    * targets draw - `attributes` (the interleaved vertex layout; omit for
-   * attributeless rendering via gl_VertexID), `topology`, `blend`, `depth`,
-   * `depthWrite` (`false` requires `depth: true`) - while each target brings
-   * its own size, buffer, uniforms, and clear. Creating a pipeline compiles
-   * nothing, and many pipelines may share one program. The vocabulary is
-   * validated here, so a bad word throws at this call site. Free with
+   * attributeless rendering via gl_VertexID), `instanceAttributes` (the
+   * per-instance layout, fetched from each entry's `instanceBuffer` - see
+   * the option's doc), `topology`, `blend`, `cull`, `depth`, `depthWrite`
+   * (`false` requires `depth: true`) - while each target brings its own
+   * size, buffers, uniforms, and clear. Both layouts share one attribute
+   * namespace (each name is one `in` of the vertex stage), so a name in
+   * both lists throws. Creating a pipeline compiles nothing, and many
+   * pipelines may share one program. The vocabulary is validated here, so a
+   * bad word throws at this call site. Free with
    * {@link destroyRenderPipeline}; the program is yours and outlives it.
    */
   export function createRenderPipeline(
     program: ProgramId,
     opts?: {
       attributes?: VertexAttribute[]
+      /**
+       * One interleaved record per INSTANCE (WebGPU's `stepMode:
+       * "instance"`): these attributes read from the entry's
+       * `instanceBuffer` and advance per instance instead of per vertex, so
+       * every vertex of instance N sees record N - real per-instance state
+       * (offsets, colors, a packed transform) with no `gl_InstanceID`
+       * 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).
+       */
+      instanceAttributes?: VertexAttribute[]
       topology?: Topology
       blend?: BlendMode
+      cull?: CullMode
       depth?: boolean
       depthWrite?: boolean
     } & LabelOption,
@@ -301,17 +328,19 @@ declare module "flux:gpu" {
    * Create a render target over a {@link createRenderPipeline} pipeline and
    * render it once: the target half of {@link createPipelineTexture}. Returns
    * a texture id exactly like the fused creates do (drive uniforms
-   * via the `params` prop or {@link setShaderParams}, resize with
-   * {@link setShaderSize}, destroy with {@link destroyTexture}). Many targets
+   * via the `params` prop or {@link setTargetParams}, resize with
+   * {@link setTargetSize}, destroy with {@link destroyTexture}). Many targets
    * may share one pipeline, and creating a target compiles nothing. `buffer`
    * supplies the concrete vertex buffer the pipeline's attribute layout
-   * describes (required when the pipeline declares attributes); the
-   * {@link DrawRange} keys pick what is drawn from it - `vertexCount`
+   * describes (required when the pipeline declares attributes), and
+   * `instanceBuffer` the per-instance records its `instanceAttributes`
+   * describe (required exactly when it declares any); the
+   * {@link DrawRange} keys pick what is drawn from them - `vertexCount`
    * defaults to the rest of the buffer from `firstVertex` on,
-   * `instanceCount` repeats the range - and a vertex fetch past the
-   * buffer's end throws here. A fullscreen pass over an attributeless
-   * pipeline is `vertexCount: 3` with a covering-triangle vertex stage.
-   * Draw-state keys
+   * `instanceCount` to one instance per instance-buffer record (1 without
+   * one) - and a fetch past either buffer's end throws here. A fullscreen
+   * pass over an attributeless pipeline is `vertexCount: 3` with a
+   * covering-triangle vertex stage. Draw-state keys
    * (`attributes`, `topology`, `blend`, `depth`, `depthWrite`) belong to the
    * pipeline and throw here. `params` and `textures` are validated against
    * the pipeline's program (see {@link ShaderParams}).
@@ -341,10 +370,11 @@ declare module "flux:gpu" {
     opts?: {
       textures?: Record<string, TextureId>
       buffer?: BufferId
+      instanceBuffer?: BufferId
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
-    } & DrawRange &
+    } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
   ): TextureId
@@ -355,36 +385,6 @@ declare module "flux:gpu" {
    * immediately.
    */
   export function destroyProgram(id: ProgramId): void
-  /**
-   * Update a shader texture's uniforms by name and re-render it (see
-   * {@link ShaderParams} for the value shapes and the validation contract -
-   * an unknown name or a mismatched length throws here, on the line that
-   * wrote it). On a manual target nothing renders here; the values apply at
-   * its next {@link renderTarget}.
-   */
-  export function setShaderParams(id: TextureId, params: ShaderParams): void
-  /**
-   * Rebind a shader texture's sampler2D inputs by uniform name and re-render
-   * it with its last-applied params - the sampler analog of
-   * {@link setShaderParams}. Bindings not named keep their current source, so
-   * a single input can be retargeted (post-process source swap, ping-pong
-   * between two data textures) without recompiling the shader. Throws if the
-   * shader or a source texture id is unknown, if a binding names anything
-   * but an active `sampler2D` uniform, if it names the shader's own target
-   * (same-pass feedback), or if it would close a sampling cycle among
-   * runtime-rendered targets. A cycle through a
-   * `render: "manual"` target is legal - the runtime never renders one, so
-   * the loop only steps when the app calls {@link renderTarget}.
-   */
-  export function setShaderTextures(id: TextureId, textures: Record<string, TextureId>): void
-  /**
-   * Resize a shader or pipeline target texture in place and re-render it: the
-   * id, compiled program, last-applied params, and sampler bindings all carry
-   * over; only the output size changes. The setDraw analog for output
-   * size.
-   */
-  export function setShaderSize(id: TextureId, width: number, height: number): void
-
   export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
   /**
    * Blending for a pipeline's own draw. "none" (default) overwrites:
@@ -398,24 +398,75 @@ declare module "flux:gpu" {
    */
   export type BlendMode = "none" | "add"
   /**
-   * One float attribute of an interleaved vertex. The attribute list's order
-   * defines the byte layout; locations are resolved by name against the
-   * vertex shader's `in` declarations.
+   * Face culling for a pipeline's draws. "none" (default) rasters both faces
+   * - the two-sided fallback open surfaces need. "back" discards faces wound
+   * away from the camera, halving a closed mesh's fragment work; "front"
+   * discards the other set (shadow and inside-out tricks). The winding rule
+   * is WebGPU's, fixed: counter-clockwise AS DISPLAYED (screen coordinates,
+   * y down) = front. Measured after every flip, so it just works: a mesh
+   * exported counter-clockwise-front for a y-up world, drawn through a
+   * standard right-handed camera (looking down -z) with the usual y
+   * negation for display, culls correctly with "back". If "back" shows you
+   * the mesh's inside anyway, the winding reaching the screen is mirrored -
+   * either the exporter winds clockwise, or the hand-rolled projection is
+   * left-handed (the classic: camera looking toward +z without mirroring
+   * x). Fix the rig, flip the exporter, or use "front".
+   */
+  export type CullMode = "none" | "back" | "front"
+  /**
+   * One float attribute of an interleaved record - a vertex of `attributes`
+   * or an instance record of `instanceAttributes`. The list's order defines
+   * the byte layout; locations are resolved by name against the vertex
+   * shader's `in` declarations.
    */
   export type VertexAttribute = { name: string; format: "f32" | "vec2" | "vec3" | "vec4" }
   /**
    * A pipeline target's draw as data, WebGPU-style: `firstVertex` +
    * `vertexCount` pick the vertex range `[firstVertex, firstVertex +
    * vertexCount)` of the buffer, `instanceCount` draws that range as N
-   * instances (`glDrawArraysInstanced`) told apart by `gl_InstanceID`. All
-   * keys optional: at create, `firstVertex` defaults to 0, `vertexCount` to
-   * the rest of the buffer and `instanceCount` to 1 (the plain draw); in
-   * {@link setDraw}, absent keys keep their current value. `instanceCount: 0`
-   * draws nothing - a cheap off switch. 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.
+   * instances (`glDrawArraysInstanced`) told apart by `gl_InstanceID` (and
+   * by their `instanceAttributes` records, when the pipeline declares any).
+   * All keys optional: at create, `firstVertex` defaults to 0, `vertexCount`
+   * to the rest of the buffer, and `instanceCount` to one instance per
+   * record of the entry's `instanceBuffer` - 1 without one, the plain draw;
+   * in {@link setDraw}, absent keys keep their current value.
+   * `instanceCount: 0` draws nothing - a cheap off switch. With an instance
+   * 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.
    */
   export type DrawRange = { firstVertex?: number; vertexCount?: number; instanceCount?: number }
+  /**
+   * The element type of an index buffer: "uint16" halves index bandwidth and
+   * addresses meshes up to 65535 vertices, "uint32" covers the rest -
+   * WebGPU's two formats exactly.
+   */
+  export type IndexFormat = "uint16" | "uint32"
+  /**
+   * An entry's index binding: any {@link createBuffer} buffer plus its
+   * element type (the buffer is typeless bytes, so the format must be
+   * declared - as WebGPU does at setIndexBuffer). One buffer kind serves
+   * both roles; there is no separate index-buffer create. With a binding
+   * present the draw is `glDrawElements`: vertices are fetched through the
+   * index VALUES, so shared vertices are stored (and shaded) once, and the
+   * range speaks {@link IndexRange} instead of {@link DrawRange}. The
+   * index-buffer fetch is bounds-checked like every range; the index values
+   * themselves are not checked against the vertex buffer (that would mean
+   * reading them back) - an out-of-range index is the same undefined fetch
+   * raw GL gives you.
+   */
+  export type IndexBinding = { indexBuffer: BufferId; indexFormat: IndexFormat }
+  /**
+   * The index-counted spelling of a draw range, for indexed entries
+   * (WebGPU's drawIndexed vocabulary): `firstIndex` + `indexCount` pick the
+   * range of the INDEX buffer, `instanceCount` as in {@link DrawRange}.
+   * Same defaults and merge rules; the vertex-named keys throw on an
+   * indexed entry (and these throw on a plain one), so a range never
+   * silently counts the wrong thing. `gl_VertexID` reads the index value;
+   * 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 }
 
   /**
    * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
@@ -426,11 +477,14 @@ declare module "flux:gpu" {
    * row of the target and +1 the bottom, so camera-up geometry must negate y
    * (or fold the flip into its projection) to display up. `attributes`
    * describes one interleaved vertex in `buffer` (a {@link createBuffer} id);
-   * omit both for attributeless rendering via gl_VertexID. The
-   * {@link DrawRange} keys pick what is drawn: `vertexCount` defaults to the
-   * rest of the buffer from `firstVertex` on, `instanceCount` draws the
-   * range as N instances told apart by `gl_InstanceID`; a vertex fetch past
-   * the buffer's end throws. With
+   * omit both for attributeless rendering via gl_VertexID.
+   * `instanceAttributes` describes one per-instance record in
+   * `instanceBuffer` (see {@link createRenderPipeline}; declare both or
+   * neither). The {@link DrawRange} keys pick what is drawn: `vertexCount`
+   * defaults to the rest of the buffer from `firstVertex` on,
+   * `instanceCount` draws the range as N instances told apart by
+   * `gl_InstanceID` and defaults to one per instance-buffer record; a fetch
+   * past either buffer's end throws. With
    * `depth: true` the pipeline gets a private depth buffer, cleared and tested
    * on every render; `depthWrite: false` (requires `depth: true`) keeps the
    * test but stops the draw from writing depth. `blend` sets the draw's own blending (see
@@ -442,7 +496,7 @@ declare module "flux:gpu" {
    * {@link renderTarget}, and `loadOp: "load"` (manual-only) keeps the
    * previous contents under each draw.
    * Returns a texture id: display it with `<texture src>`, drive uniforms via
-   * the `params` prop or {@link setShaderParams}, destroy with
+   * the `params` prop or {@link setTargetParams}, destroy with
    * {@link destroyTexture}.
    */
   export function createPipelineTexture(
@@ -455,14 +509,18 @@ declare module "flux:gpu" {
       textures?: Record<string, TextureId>
       attributes?: VertexAttribute[]
       buffer?: BufferId
+      /** See {@link createRenderPipeline}'s `instanceAttributes`. */
+      instanceAttributes?: VertexAttribute[]
+      instanceBuffer?: BufferId
       topology?: Topology
       depth?: boolean
       depthWrite?: boolean
       blend?: BlendMode
+      cull?: CullMode
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
-    } & DrawRange &
+    } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
   ): TextureId
@@ -496,12 +554,198 @@ declare module "flux:gpu" {
    * buffer size) - the out-of-bounds draw GL itself never checks; a target
    * without vertex fetch (attributeless) accepts any non-negative range.
    * (On a manual target nothing renders here; the range applies at its next
-   * {@link renderTarget}.)
-   */
-  export function setDraw(id: TextureId, draw: DrawRange): void
+   * {@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.
+   */
+  export function setDraw(id: TextureId, draw: DrawRange | IndexRange): void
+  /**
+   * Create a draw target: a render target whose contents are an ordered,
+   * mutable LIST of draws - one render clears once, then executes every
+   * entry in list order into the same storage. The multi-pass shape of every
+   * 3D API (N meshes, N pipelines, one shared depth buffer), retained: where
+   * WebGPU re-encodes a render pass every frame, this target holds the pass
+   * as state and re-renders on demand. Entries are added and removed at any
+   * time ({@link addDraw}/{@link removeDraw}) and updated per entry
+   * ({@link setDrawParams}, {@link setDrawTextures}, {@link setDrawRange}).
+   *
+   * `depth: true` gives the target its own depth storage, shared by every
+   * entry and cleared once per render - this is what makes cross-entry
+   * 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.
+   *
+   * `params` seeds the target's SHARED params - the target-level values
+   * every entry reads, the same live channel {@link setTargetParams} drives
+   * later (positional like every create's params; see there for the
+   * precedence and validation contract). `opts.textures` seeds the shared
+   * sampler bindings the same way, the channel {@link setTargetTextures}
+   * drives (in opts like every create's textures). At creation there are no
+   * entries to validate against, so names are accepted as-is and simply
+   * apply to whichever later entries' programs declare them.
+   *
+   * The render contract is unchanged: the list is input data like params, so
+   * "render twice = render once" still holds and the default `render:
+   * "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.
+   * Returns a texture id (display, resize, destroy like any target; entries
+   * die with it).
+   */
+  export function createDrawTarget(
+    width: number,
+    height: number,
+    params?: ShaderParams | null,
+    opts?: {
+      depth?: boolean
+      textures?: Record<string, TextureId>
+      clearColor?: [number, number, number, number]
+      render?: "auto" | "manual"
+      loadOp?: "clear" | "load"
+    } & SamplerOptions &
+      LabelOption,
+  ): TextureId
+  /**
+   * Append a draw entry to a draw target: `pipeline` draws `opts.buffer`
+   * (required when the pipeline declares attributes) with its own `params`
+   * and `textures`, last in list order - the same per-entry shape
+   * {@link createShaderTarget} takes, addressed to one entry of the list.
+   * Returns the entry's {@link DrawId}, the handle every per-entry update
+   * takes. Everything validates here at the call site: unknown ids, depth
+   * compatibility (see {@link createDrawTarget}), uniform names and arities,
+   * the vertex-fetch bound, per-entry texture-unit count, and sampling
+   * cycles. List order is draw order - later entries land over earlier ones
+   * where depth does not decide - so painter-style layering is append order,
+   * and per-entry `params` is where per-object state (a model matrix) lives.
+   * `before` inserts the entry immediately before an existing one instead
+   * of appending (it must name a live entry); for wholesale reordering use
+   * {@link setDrawOrder}. An {@link IndexBinding} makes the entry draw
+   * indexed - real meshes share most vertices, and indexing stores and
+   * shades each one once - with the range in {@link IndexRange} spelling.
+   * `instanceBuffer` supplies the per-instance records the pipeline's
+   * `instanceAttributes` describe (required exactly when it declares any);
+   * `instanceCount` then defaults to one instance per record.
+   *
+   * Seed every uniform the entry's program declares - here, via the
+   * target's shared params, or with a later write. GL uniform state lives
+   * on the program object, so a declared name nothing writes holds
+   * whatever the last draw through that program applied, from any entry
+   * or target sharing it - not zero (only a freshly linked program reads
+   * the link-time zero). Coverage is deliberately not validated here:
+   * adding entries first and setting shared values after is legal.
+   */
+  export function addDraw(
+    target: TextureId,
+    pipeline: RenderPipelineId,
+    params?: ShaderParams | null,
+    opts?: {
+      textures?: Record<string, TextureId>
+      buffer?: BufferId
+      instanceBuffer?: BufferId
+      before?: DrawId
+    } & (DrawRange | (IndexBinding & IndexRange)),
+  ): DrawId
+  /**
+   * Remove a draw entry from a draw target. Remaining entries keep their
+   * order and ids; the removed id errors from then on (ids are never
+   * reused). The entry's pipeline and buffer are yours and unaffected.
+   */
+  export function removeDraw(target: TextureId, draw: DrawId): void
+  /**
+   * Update one draw entry's uniforms by name: {@link setTargetParams}
+   * addressed to a single entry, same merge and validation contract. The
+   * per-object hot path - a moved mesh is one setDrawParams with its new
+   * model matrix.
+   */
+  export function setDrawParams(target: TextureId, draw: DrawId, params: ShaderParams): void
+  /**
+   * Update a target's target-level uniforms by name, on any target kind,
+   * with the usual merge-by-name (see {@link ShaderParams} for value shapes;
+   * a bad name or a mismatched length throws here, on the line that wrote
+   * it). On a single-program target (a fragment texture or a pipeline
+   * target) the target level IS its one pass: every name validates against
+   * that program and the target re-renders. On a manual target nothing
+   * renders here; the values apply at its next {@link renderTarget}.
+   *
+   * On a draw target these are the SHARED params: values every entry reads
+   * - a camera's view-projection above all - written once per target
+   * instead of once per entry. Shared values apply at render before each
+   * entry's own params, so an entry naming the same uniform overrides the
+   * shared value (specific beats general), and they are target state: entry
+   * add/remove/rebuild cannot lose them. A draw target legitimately mixes
+   * material classes, so coverage may be partial: a name only some entries'
+   * programs declare is applied where declared and skipped elsewhere.
+   * Validation follows: each name must be an active settable uniform of at
+   * least ONE current entry's program (with the matching arity everywhere it
+   * is declared) - a name no entry declares throws. With no entries yet,
+   * names are accepted as-is; an entry added later whose program lacks an
+   * already-set name is never a retroactive error, the value just skips it.
+   */
+  export function setTargetParams(target: TextureId, params: ShaderParams): void
+  /**
+   * Rebind a target's target-level sampler2D inputs by uniform name, on any
+   * target kind - {@link setTargetParams}'s sampler analog. Bindings not
+   * named keep their current source, so a single input can be retargeted
+   * (post-process source swap, ping-pong between two data textures) without
+   * recompiling anything. Bound sources are live dependencies: the target
+   * re-renders when one changes. Every path throws if the target or a
+   * source texture id is unknown, if a binding names the target's own
+   * texture (same-pass feedback), or if it would close a sampling cycle
+   * among runtime-rendered targets; a cycle through a `render: "manual"`
+   * target is legal - the runtime never renders one, so the loop only steps
+   * when the app calls {@link renderTarget}. On a single-program target each
+   * name must be an active `sampler2D` of its one program.
+   *
+   * On a draw target these are the SHARED bindings: sources every entry
+   * reads - an environment map, a shadow map, a LUT - bound once per
+   * target, with the shared-params rules throughout: an entry's own binding
+   * for the same name wins; a name only some entries' programs declare
+   * binds where declared and is skipped elsewhere; shared bindings are
+   * target state that entry add/remove/rebuild cannot lose. Each name must
+   * be an active sampler2D of at least ONE current entry's program (with no
+   * entries yet names are accepted as-is, and a later entry never
+   * retroactively errors), 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
+  /**
+   * Resize a render target of any kind in place and re-render it: the id,
+   * compiled programs, last-applied params, sampler bindings, and draw
+   * state all carry over; only the output size changes. The setDraw analog
+   * for output size. (Pixel textures resize with {@link resizeTexture},
+   * which carries seed pixels instead.)
+   */
+  export function setTargetSize(id: TextureId, width: number, height: number): void
+  /**
+   * Rebind one draw entry's sampler2D inputs by uniform name:
+   * {@link setTargetTextures} addressed to a single entry, same merge,
+   * 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
+  /**
+   * 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
+  /**
+   * Reorder a draw target's list. `order` must name every current entry
+   * exactly once - a full permutation of the live {@link DrawId}s; a
+   * missing, duplicate, or unknown id throws, naming the problem. List
+   * order is draw order, which makes this the sorting verb: sort opaque
+   * entries front-to-back (early depth rejection) and transparent ones
+   * back-to-front, and re-issue the order when the camera moves. Entry
+   * state (params, textures, ranges) rides along untouched; ids are
+   * unaffected. Like every draw-list write it re-renders an auto target
+   * once at the next flush, and folds silently on a manual one.
+   */
+  export function setDrawOrder(target: TextureId, order: DrawId[]): void
   /**
    * Render a `render: "manual"` target once, now. Renders land in call order
-   * relative to every other GPU call: a `setShaderParams`/`writeBuffer`
+   * relative to every other GPU call: a `setTargetParams`/`writeBuffer`
    * issued before is visible to the pass, a {@link readTexture} issued after
    * observes it, and two renders run the pass twice in order. Inputs are
    * fresh: pending runtime-driven renders of sampled targets resolve first.

package/index.d.ts

@@ -5,6 +5,7 @@
 /// <reference path="./modules/sqlite.d.ts" />
 /// <reference path="./modules/subprocess.d.ts" />
 /// <reference path="./modules/svg.d.ts" />
+/// <reference path="./modules/image.d.ts" />
 /// <reference path="./modules/p2p.d.ts" />
 /// <reference path="./modules/net.d.ts" />
 /// <reference path="./modules/mdns.d.ts" />

package/modules/image.d.ts

@@ -0,0 +1,24 @@
+declare module "flux:image" {
+  /** Decoded pixels: tightly-packed RGBA8 plus the pixel dimensions. */
+  export type DecodedImage = {
+    data: Uint8Array
+    width: number
+    height: number
+  }
+
+  /**
+   * Decodes encoded image bytes (png, jpeg, webp, gif, bmp, ico) into raw
+   * RGBA8 pixels plus the decoded dimensions. Synchronous, pure CPU. Throws
+   * when the bytes are not a decodable image.
+   */
+  export function decodeImage(bytes: Uint8Array): DecodedImage
+
+  /**
+   * Encodes raw RGBA8 pixels into an image file, the reverse of `decodeImage`
+   * (`encodeImage(decodeImage(bytes))` round-trips). `format` defaults to
+   * `"png"` (lossless, keeps alpha); `"jpeg"` drops the alpha channel and
+   * takes `quality` in 0..1 (default 0.9, ignored for png). Throws when
+   * `data.length` does not match `width * height * 4`.
+   */
+  export function encodeImage(img: DecodedImage, options?: { format?: "png" | "jpeg"; quality?: number }): Uint8Array
+}

package/modules/process.d.ts

@@ -1,7 +1,9 @@
 declare module "flux:process" {
   /**
-   * The program's command-line arguments. `argv[0]` is the script path;
-   * `argv[1]` onward are the user-supplied arguments.
+   * The arguments the app was started with; empty when there are none.
+   * App arguments only: no executable path, no script path (deliberately
+   * simpler than Node/Bun's two leading entries), so `argv[0]` is the first
+   * argument.
    */
   export let argv: string[]
   /** The host OS: "darwin", "win32", "linux", "android", ... */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",