@solidrt/flux-types 0.0.40 → 0.0.41

package/gui/camera.d.ts

@@ -3,6 +3,8 @@
 // to a bound session object, so the raw handle never leaves the runtime.
 
 declare module "flux:camera" {
+  import type { TextureId } from "flux:gpu"
+
   /** A camera device from {@link listCameras}. */
   type CameraDevice = {
     /** Device id to pass as `open({ camera })`. */
@@ -38,7 +40,7 @@ declare module "flux:camera" {
   /** An opened camera session: the frame texture plus controls bound to it. */
   type CameraSession = {
     /** GPU texture id the latest frame is uploaded into (use as a texture source). */
-    texture: number
+    texture: TextureId
     /** Frame width in pixels. */
     width: number
     /** Frame height in pixels. */
@@ -52,11 +54,20 @@ declare module "flux:camera" {
     close(): void
   }
 
-  /** List the available camera devices. */
+  /**
+   * List the available camera devices. The first call also starts the camera
+   * subsystem, which comes up asynchronously: expect an empty list until the
+   * initial cameraDeviceChange events arrive.
+   */
   export function listCameras(): CameraDevice[]
   /**
    * Open a camera. Opening is also the permission request: the promise rejects
-   * if permission is denied, and resolves once the first frame is ready.
+   * 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.
    */
   export function open(options?: CameraOpenOptions): Promise<CameraSession>
   /**

package/gui/gpu.d.ts

@@ -1,12 +1,17 @@
 // Low-level GPU textures and shaders (gui-enabled runtime only). The
 // imperative primitive; @solidrt/core's gpu helpers add reactive auto-cleanup
-// on top. Three id spaces, each destroyed by its own destroyer: texture ids
-// (the public token used as `<texture src>` and sampler inputs ->
-// destroyTexture), buffer ids (-> destroyBuffer), and the raw shading layer's
-// shader-stage ids (-> destroyShader) and program ids (-> destroyProgram).
+// on top. Each id space has its own destroyer: texture ids (the public token
+// used as `<texture src>` and sampler inputs -> destroyTexture), buffer ids
+// (-> destroyBuffer), and the raw shading layer's shader-stage ids
+// (-> destroyShader), program ids (-> destroyProgram), and render-pipeline
+// ids (-> destroyRenderPipeline).
 // Layering: compileShader/linkProgram are the raw GL primitives (complete
-// sources, explicit header opt-in); createShader/createPipeline are fused
-// conveniences (compile + link + target in one call, curated preamble).
+// sources, explicit header opt-in); createRenderPipeline pairs a program with
+// draw state (topology, blend, 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.
 //
 // Sampling is a per-texture property declared at creation: every create path
 // accepts `{ filter?, wrap? }` ("linear"/"nearest", "clamp"/"repeat";
@@ -21,15 +26,73 @@
 // samples both. WITHIN one pipeline draw, `blend: "add"` accumulates
 // overlapping geometry additively; anything else (a fragment target, or a
 // pipeline without the option) draws with GL blending disabled and overwrites.
+//
+// The render contract. A target's contents are a pure function of its inputs
+// (params, bound textures, geometry): the runtime renders it whenever inputs
+// change - zero, one, or many times per frame, at its discretion - so a pass
+// must not depend on its own previous output or on how often it runs. When a
+// pass IS state (accumulation, feedback, simulation), create the target with
+// `render: "manual"`: the runtime then never renders it, only an explicit
+// renderTarget(id) does, in call order - the app owns the stepping. Targets
+// sampling a manual target update after each explicit render; a manual
+// target's own params/geometry writes take effect at its next render.
+// `loadOp: "load"` (manual-only) keeps the previous contents under each
+// draw - single-target accumulation - and copyTexture(src, dst) seeds or
+// snapshots a manual target GPU-side. Both compose with renderTarget in
+// call order.
+//
+// The pixel contract. Three facts hold for every texture and target:
+//
+// - Clip space is y-down. `gl_Position` y = -1 is the top of the target, +1
+//   the bottom (GL's row 0 is clip y = -1, and Impeller samples row 0 as the
+//   top). A vertex stage carrying camera-up geometry must negate y, or fold
+//   the flip into its projection, or it draws upside down: Vulkan's
+//   convention, not desktop GL's. The fragment path absorbs the same flip
+//   already, so `vUV` is 0..1 with top-left origin and a fragment-only shader
+//   never sees it.
+// - Color is premultiplied alpha. A target's RGB is expected already
+//   multiplied by its A - `vec4(rgb * a, a)`, not `vec4(rgb, a)`, which
+//   composites as opaque. That is what Impeller composites and what
+//   `<texture blendMode>` blends; `clearColor` is premultiplied too, so the
+//   default transparent black needs no thought.
+// - Values are non-linear RGBA8, with no color-space concept. Every texture
+//   and target holds 8-bit RGBA UNORM exactly as written; nothing converts to
+//   or from linear light. `filter: "linear"` averages and `blend: "add"`
+//   accumulates non-linear values - the usual approximation, stated so
+//   shaders written today stay correct if a format vocabulary arrives.
 
 declare module "flux:gpu" {
+  /**
+   * A GPU texture handle: what every texture-producing call returns and every
+   * texture-consuming site takes (`<texture src>`, sampler bindings, the
+   * texture mutators and destroyTexture). At runtime it is a plain number;
+   * the brand exists so each id space is its own type and a cross-space slip
+   * - `destroyBuffer(textureId)`, `createShaderTarget(programId, ...)` - is a
+   * type error instead of an operation on an unrelated live resource (every
+   * space counts from 1, so a wrong id is usually a valid id in the wrong
+   * space). Ids widen to number freely; only number -> id is blocked.
+   */
+  export type TextureId = number & { readonly __texture: unique symbol }
+  /** The vertex-buffer id space ({@link createBuffer}); see {@link TextureId} for the brand model. */
+  export type BufferId = number & { readonly __buffer: unique symbol }
+  /** The compiled-stage id space ({@link compileShader}); see {@link TextureId} for the brand model. */
+  export type ShaderStageId = number & { readonly __shaderStage: unique symbol }
+  /** The linked-program id space ({@link linkProgram}); see {@link TextureId} for the brand model. */
+  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 }
   /**
    * Shader uniform values by name. A number drives a scalar uniform (`float`,
    * or `int`/`bool`, truncated); a flat number array drives a typed uniform
    * whose declared GLSL type sets the expected length: 2/3/4 for
    * `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`. Dispatch follows the
-   * shader's own declaration; a value whose length does not fit it is skipped
-   * with a runtime warning, as is a name with no active uniform.
+   * shader's own declaration, and every write is validated against it at the
+   * 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).
+   * An `undefined` value is skipped, so conditional spreads stay usable.
    */
   export type ShaderParams = Record<string, number | number[]>
   /** Magnification/minification filter; "linear" (default) or hard-pixel "nearest". */
@@ -44,22 +107,52 @@ declare module "flux:gpu" {
    * matters to shaders sampling outside 0..1; the display draw never tiles.
    */
   export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode }
+  /**
+   * 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
+   * 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}).
+   */
+  export type LabelOption = { label?: string }
+  /**
+   * This device's hard ceilings, queried once at startup: process constants.
+   * Every create and bind validates against them at the call site, so an
+   * oversize target throws naming the limit instead of failing later as a
+   * driver error, and a binding list past the unit cap throws instead of
+   * silently sampling garbage. Values at or below these are safe on this
+   * device; the GLES 3.0 floors (2048 / 16 / 16) are the portable baseline
+   * every device guarantees.
+   */
+  export let limits: {
+    /** Largest width/height of any texture or render target, in pixels (>= 2048). */
+    maxTextureSize: number
+    /**
+     * Sampler inputs one pass may bind (>= 16): a target's `textures`
+     * entries; on a window shader the runtime-filled `uSource` (and
+     * `uPrevious` when declared) count toward it too.
+     */
+    maxTextureUnits: number
+    /** Vertex attributes one pipeline may declare (>= 16). */
+    maxVertexAttribs: number
+  }
   /**
    * Create an immutable texture from an RGBA8 pixel buffer (exactly
    * width*height*4 bytes). Returns the texture id.
    */
-  export function createTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions): number
+  export function createTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & LabelOption): TextureId
   /**
    * Create a texture intended to be updated later via {@link uploadTexture}. The
    * seed buffer must hold at least one frame (width*height*4 bytes) and may hold
    * more (uploadTexture selects a frame by offset).
    */
-  export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions): number
+  export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & LabelOption): TextureId
   /**
    * Replace a mutable texture's pixels. `data` may hold several frames; `offset`
    * (default 0) selects which frame to upload.
    */
-  export function uploadTexture(id: number, data: Uint8Array, offset?: number): void
+  export function uploadTexture(id: TextureId, data: Uint8Array, offset?: number): void
   /**
    * Replace a texture's storage with a new size at the same id (an id-stable
    * resize): `<texture src>` references and shader sampler bindings keep
@@ -68,7 +161,7 @@ declare module "flux:gpu" {
    * width*height*4 frame. Shader/pipeline target ids are rejected - resize
    * those with {@link setShaderSize}.
    */
-  export function resizeTexture(id: number, data: Uint8Array, width: number, height: number): void
+  export function resizeTexture(id: TextureId, data: Uint8Array, width: number, height: number): void
   /**
    * Destroy a texture (immutable, mutable, or shader). Frame-safe: the id is
    * reclaimed by the runtime once the render tree no longer references it, so
@@ -77,57 +170,70 @@ declare module "flux:gpu" {
    * in. A destroyed id that stays mounted keeps drawing (and stays allocated)
    * until it is unmounted or repointed.
    */
-  export function destroyTexture(id: number): void
+  export function destroyTexture(id: TextureId): void
   /**
    * Compile a GLSL ES fragment shader into an offscreen texture of the given
-   * size. `params` sets uniforms by name (see {@link ShaderParams} for the
-   * value shapes); `textures` binds sampler2D uniforms to texture ids - any
-   * texture id, including another shader/pipeline target's output. Bound
-   * targets are live dependencies: when a source re-renders (its params,
-   * geometry, or data change), every target sampling it re-renders too,
-   * transitively through chains, before the next frame or readback - no
-   * per-frame uniform write is needed to keep a chain current. Returns the resulting texture id. The fused
-   * convenience: one call compiles a program and creates a target over it,
-   * and the program lives and dies with the target. To share one compile
-   * across targets (or hold a program with no target yet), use the raw layer:
-   * {@link compileShader} + {@link linkProgram} + {@link createShaderTarget}.
+   * size. `params` sets initial uniforms by name (see {@link ShaderParams}
+   * 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
+   * 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
+   * `sampler2D` uniform. Bound targets are live dependencies: when a source
+   * re-renders (its params, geometry, or data change), every target sampling
+   * it re-renders too, transitively through chains, before the next frame or
+   * readback - no per-frame uniform write is needed to keep a chain current.
+   * Returns the resulting texture id. The fused convenience: one call
+   * compiles a program and creates a target over it, and the program lives
+   * and dies with the target. To share one compile across targets (or hold a
+   * program with no target yet), use the raw layer: {@link compileShader} +
+   * {@link linkProgram} + {@link createRenderPipeline} +
+   * {@link createShaderTarget}.
    *
-   * The preamble (`#version 300 es`, precision, `vUV`, `iResolution`, `iTime`,
+   * The preamble (`#version 300 es`, precision, `vUV`, `iResolution`,
    * `fragColor`) is injected only into sources that do not declare their own
-   * `#version` line. A source that starts with `#version 300 es` is compiled
-   * exactly as written, so a shader with its own uniform names (a port from
-   * elsewhere) needs no rewriting and no drop to the raw layer. The built-in
-   * vertex stage still supplies `vUV` to a complete source; declare
-   * `in vec2 vUV;` yourself to read it. Same rule on {@link createPipeline}.
-   * A complete source may also declare `iResolution` as vec3 (the Shadertoy
-   * shape); it is then filled as `(w, h, 1.0)`.
-   */
-  export function createShader(
+   * `#version` line, and declares exactly what the runtime provides - an
+   * app-driven uniform (a time value, say) is the source's own declaration,
+   * driven through params like any other. A source that starts with
+   * `#version 300 es` is compiled exactly as written, so a shader with its
+   * own uniform names (a port from elsewhere) needs no rewriting and no drop
+   * to the raw layer. The built-in vertex stage still supplies `vUV` to a
+   * complete source; declare `in vec2 vUV;` yourself to read it. Same rule on
+   * {@link createPipelineTexture}. A complete source may also declare
+   * `iResolution` as vec3 (the Shadertoy shape); it is then filled as
+   * `(w, h, 1.0)`.
+   */
+  export function createShaderTexture(
     fragmentSrc: string,
     width: number,
     height: number,
-    params?: ShaderParams,
-    textures?: Record<string, number>,
-    opts?: SamplerOptions,
-  ): number
+    params?: ShaderParams | null,
+    opts?: { textures?: Record<string, TextureId> } & SamplerOptions & LabelOption,
+  ): TextureId
   /**
    * Compile a single shader stage from raw GLSL ES: the primitive under
    * {@link linkProgram}, GL's own model (a "shader" is one stage; linking
    * stages yields a program). The source is complete - it declares its own
    * `#version 300 es`, precision, varyings and uniforms; nothing is injected.
    * With `header: true` the standard header is prepended explicitly: `#version
-   * 300 es`, `precision highp float;`, `uniform vec2 iResolution;`, `uniform
-   * float iTime;`, plus `out vec4 fragColor;` for a fragment stage (the same
-   * text {@link createPipeline} injects). Do not combine `header` with your
+   * 300 es`, `precision highp float;`, `uniform vec2 iResolution;`, plus
+   * `out vec4 fragColor;` for a fragment stage (the same text
+   * {@link createPipelineTexture} injects). Do not combine `header` with your
    * own `#version` line. Returns a shader (stage) id in its own id space;
    * compile errors throw here, synchronously, at a call site the app chose.
    * Free with {@link destroyShader}.
+   *
+   * A vertex stage writes into a y-down clip space: `gl_Position` y = -1 is
+   * the top 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.
    */
   export function compileShader(
     stage: "vertex" | "fragment",
     source: string,
     opts?: { header?: boolean },
-  ): number
+  ): ShaderStageId
   /**
    * Link a compiled vertex and fragment stage into a program, returning a
    * program id (its own id space, like buffers - not a texture id). Link
@@ -137,70 +243,127 @@ declare module "flux:gpu" {
    * Creating targets from the returned handle compiles nothing. Free with
    * {@link destroyProgram}.
    */
-  export function linkProgram(vertexShader: number, fragmentShader: number): number
+  export function linkProgram(vertexShader: ShaderStageId, fragmentShader: ShaderStageId, opts?: LabelOption): ProgramId
   /**
    * Destroy a compiled stage by id. Programs linked from it are unaffected.
    */
-  export function destroyShader(id: number): void
+  export function destroyShader(id: ShaderStageId): void
   /**
-   * Create a render target over a linked program and render it once: the
-   * target half of {@link createPipeline}. Returns a texture id exactly like
-   * createShader/createPipeline do (drive uniforms via the `params` prop or
-   * {@link setShaderParams}, resize with {@link setShaderSize}, destroy with
-   * {@link destroyTexture}). Many targets may share one program. A raw-linked
-   * program carries its own vertex stage, so the mesh options apply:
-   * `attributes`/`buffer` for vertex input (omit for attributeless rendering
-   * via gl_VertexID - a fullscreen pass is `vertexCount: 3` with a
-   * covering-triangle vertex stage), `topology`, `vertexCount`, `depth`,
-   * `clearColor`, all as in {@link createPipeline}.
+   * Pair a linked program with draw state, returning a render pipeline id
+   * (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
+   * {@link destroyRenderPipeline}; the program is yours and outlives it.
    */
-  export function createShaderTarget(
-    program: number,
-    width: number,
-    height: number,
+  export function createRenderPipeline(
+    program: ProgramId,
     opts?: {
-      params?: ShaderParams
-      textures?: Record<string, number>
       attributes?: VertexAttribute[]
-      buffer?: number
       topology?: Topology
-      vertexCount?: number
+      blend?: BlendMode
       depth?: boolean
       depthWrite?: boolean
-      blend?: BlendMode
+    } & LabelOption,
+  ): RenderPipelineId
+  /**
+   * Destroy a render pipeline by id. Targets created from it are unaffected:
+   * each holds the pipeline until it is itself destroyed, so either
+   * destruction order is safe. The id stops being usable for new targets
+   * immediately.
+   */
+  export function destroyRenderPipeline(id: RenderPipelineId): void
+  /**
+   * 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
+   * 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`
+   * 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
+   * (`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}).
+   *
+   * `render: "manual"` opts the target out of runtime-driven rendering (see
+   * the render contract above): it starts cleared to `clearColor` and its
+   * pass runs only when {@link renderTarget} is called.
+   *
+   * `loadOp` chooses what each render finds in the target: `"clear"` (the
+   * default) clears to `clearColor` first, `"load"` keeps the previous
+   * contents and draws over them - single-target accumulation (with the
+   * pipeline's `blend: "add"`, an additive trail; without blending, draws
+   * simply land over old pixels). `"load"` requires `render: "manual"` and
+   * throws otherwise: on a runtime-rendered target the output would depend
+   * on how often the runtime happened to render. Depth (when the pipeline
+   * has it) is per-render scratch and always clears; creation, resize, and
+   * nothing else reset the color to `clearColor`. State that needs a
+   * 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.
+   */
+  export function createShaderTarget(
+    pipeline: RenderPipelineId,
+    width: number,
+    height: number,
+    params?: ShaderParams | null,
+    opts?: {
+      textures?: Record<string, TextureId>
+      buffer?: BufferId
       clearColor?: [number, number, number, number]
-    } & SamplerOptions,
-  ): number
+      render?: "auto" | "manual"
+      loadOp?: "clear" | "load"
+    } & DrawRange &
+      SamplerOptions &
+      LabelOption,
+  ): TextureId
   /**
-   * Destroy a linked program by id. Targets created from it are unaffected:
+   * Destroy a linked program by id. Pipelines created from it are unaffected:
    * each holds the program until it is itself destroyed, so either
-   * destruction order is safe. The id stops being usable for new targets
+   * destruction order is safe. The id stops being usable for new pipelines
    * immediately.
    */
-  export function destroyProgram(id: number): void
+  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).
+   * {@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: number, params: ShaderParams): void
+  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, or a binding would create a
-   * sampling cycle among targets (binding a shader's own target is the
-   * shortest case).
+   * 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: number, textures: Record<string, number>): void
+  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 setDrawCount analog for output
+   * over; only the output size changes. The setDraw analog for output
    * size.
    */
-  export function setShaderSize(id: number, width: number, height: number): void
+  export function setShaderSize(id: TextureId, width: number, height: number): void
 
   export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
   /**
@@ -220,64 +383,131 @@ declare module "flux:gpu" {
    * 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.
+   */
+  export type DrawRange = { firstVertex?: number; vertexCount?: number; instanceCount?: number }
 
   /**
    * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
    * the given size and render it once. Sources without a `#version` line get
-   * a 300 es preamble declaring `iResolution`/`iTime` (no vUV: varyings are
-   * the pipeline's own). `attributes` describes one interleaved vertex in
-   * `buffer` (a {@link createBuffer} id); omit both for attributeless
-   * rendering via gl_VertexID. `vertexCount` defaults to the whole buffer
-   * (buffer size / vertex stride). 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
+   * a 300 es preamble declaring `iResolution` (no vUV: varyings are the
+   * pipeline's own; app-driven uniforms are the source's own declarations).
+   * Clip space is y-down: `gl_Position` y = -1 is the top
+   * 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
+   * `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
    * {@link BlendMode}); an additive pass over a depth buffer is
    * `{ depth: true, blend: "add", depthWrite: false }`, stated explicitly.
    * The target is cleared to `clearColor` (default transparent black) before
-   * each draw.
+   * each draw. `render: "manual"` and `loadOp` behave exactly as on
+   * {@link createShaderTarget}: no runtime-driven renders, step with
+   * {@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
    * {@link destroyTexture}.
    */
-  export function createPipeline(
+  export function createPipelineTexture(
     vertexSrc: string,
     fragmentSrc: string,
     width: number,
     height: number,
+    params?: ShaderParams | null,
     opts?: {
-      params?: ShaderParams
-      textures?: Record<string, number>
+      textures?: Record<string, TextureId>
       attributes?: VertexAttribute[]
-      buffer?: number
+      buffer?: BufferId
       topology?: Topology
-      vertexCount?: number
       depth?: boolean
       depthWrite?: boolean
       blend?: BlendMode
       clearColor?: [number, number, number, number]
-    } & SamplerOptions,
-  ): number
+      render?: "auto" | "manual"
+      loadOp?: "clear" | "load"
+    } & DrawRange &
+      SamplerOptions &
+      LabelOption,
+  ): TextureId
 
   /**
    * 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.
    */
-  export function createBuffer(data: Uint8Array): number
+  export function createBuffer(data: Uint8Array, opts?: LabelOption): BufferId
   /**
    * Overwrite part of a vertex buffer at `byteOffset` (default 0), within the
    * size it was created with. Pipelines drawing from the buffer re-render
    * with their last-applied params.
    */
-  export function writeBuffer(id: number, data: Uint8Array, byteOffset?: number): void
-  /** Destroy a vertex buffer. Destroy pipelines drawing from it first. */
-  export function destroyBuffer(id: number): void
+  export function writeBuffer(id: BufferId, data: Uint8Array, byteOffset?: number): void
+  /**
+   * Destroy a vertex buffer. Pipeline textures drawing from it hold their own
+   * reference, so destruction order does not matter; further writes to the id
+   * throw.
+   */
+  export function destroyBuffer(id: BufferId): void
+  /**
+   * Update a pipeline texture's draw range and re-render it: `vertexCount`
+   * after writing a variable amount of dynamic geometry into its buffer,
+   * `firstVertex` to draw a different window of a shared buffer,
+   * `instanceCount` to grow or shrink an instanced population. Keys absent
+   * from `draw` keep their current value, like params. Throws if a value is
+   * negative or the merged range's vertex fetch would run past the end of
+   * the target's buffer ((firstVertex + vertexCount) x vertex stride >
+   * 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
+  /**
+   * Render a `render: "manual"` target once, now. Renders land in call order
+   * relative to every other GPU call: a `setShaderParams`/`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.
+   * Targets sampling this one update after the render. Throws if the id is
+   * not a manual target - the runtime owns rendering the others, and a pass
+   * that depends on how often it runs is only well-defined when the app is
+   * the one counting. Ping-pong feedback is two manual targets sampling
+   * each other, stepped alternately from `onFrame`; binding a target to
+   * ITSELF still throws (same-pass GL feedback, undefined pixels regardless
+   * of who schedules it).
+   */
+  export function renderTarget(id: TextureId): void
   /**
-   * Set how many vertices a pipeline texture draws and re-render it, e.g.
-   * after writing a variable amount of dynamic geometry into its buffer.
+   * Overwrite a `render: "manual"` target with another texture's current
+   * pixels, GPU-side: the seed/history analog of {@link uploadTexture}
+   * (seed a `loadOp: "load"` accumulator, snapshot one ping-pong buffer
+   * into another, reset state to a known image). Exact and same-size only -
+   * content and row order are preserved, and a size mismatch throws (a
+   * scaling copy is an ordinary pass). Copies land in call order like
+   * renders: a copy after a render sees that render, a readback after a
+   * copy sees the copy, and targets sampling `dst` update afterwards.
+   * Throws if either id is unknown, `dst` is not a manual target (the
+   * runtime owns those contents), or `src === dst`. `src` may be any
+   * texture: uploaded, mutable, a camera frame, or another target's output.
    */
-  export function setDrawCount(id: number, count: number): void
+  export function copyTexture(src: TextureId, dst: TextureId): void
   /**
    * Capture a render-tree node's subtree into a new GPU texture, resolving once
    * it has been rendered on the next paint pass. The node must be attached to
@@ -310,11 +540,12 @@ declare module "flux:gpu" {
    * must stay current has to come from a source that updates in place: another
    * pipeline's render target, a camera texture, a mutable texture.
    */
-  export function captureSnapshot(nodeId: number): Promise<{ id: number; width: number; height: number }>
+  export function captureSnapshot(nodeId: number): Promise<{ id: TextureId; width: number; height: number }>
   /**
    * Read back a registered texture's current pixels as RGBA8 (tightly packed,
    * top-to-bottom rows), for any texture id whatever created it (createTexture,
-   * createShader, captureSnapshot). Synchronous. Throws if the id is unknown.
+   * createShaderTexture, captureSnapshot). Synchronous. Throws if the id is
+   * unknown.
    */
-  export function readTexture(id: number): { width: number; height: number; data: Uint8Array }
+  export function readTexture(id: TextureId): { width: number; height: number; data: Uint8Array }
 }

package/index.d.ts

@@ -4,6 +4,7 @@
 /// <reference path="./modules/fs.d.ts" />
 /// <reference path="./modules/sqlite.d.ts" />
 /// <reference path="./modules/subprocess.d.ts" />
+/// <reference path="./modules/svg.d.ts" />
 /// <reference path="./modules/p2p.d.ts" />
 /// <reference path="./modules/net.d.ts" />
 /// <reference path="./modules/mdns.d.ts" />
@@ -16,6 +17,7 @@
 /// <reference path="./standards/console.d.ts" />
 /// <reference path="./standards/time.d.ts" />
 /// <reference path="./standards/text.d.ts" />
+/// <reference path="./standards/base64.d.ts" />
 /// <reference path="./standards/fetch.d.ts" />
 /// <reference path="./standards/websocket.d.ts" />
 

package/modules/svg.d.ts

@@ -0,0 +1,73 @@
+declare module "flux:svg" {
+  /**
+   * A gradient paint from a parsed document, in the branded shape the render
+   * tree decodes: coordinates are absolute document-space values
+   * (`units: "absolute"`), `spread` is the SVG spreadMethod (absent = pad),
+   * and `transform` an SVG matrix(a b c d e f) sextet mapping the gradient's
+   * coordinates into the document space (absent = identity). Stop colors are
+   * packed `0xRRGGBBAA` numbers.
+   */
+  export type SvgGradient =
+    | {
+        __gradient: "linear"
+        units: "absolute"
+        x0: number
+        y0: number
+        x1: number
+        y1: number
+        stops: { offset: number; color: number }[]
+        spread?: "reflect" | "repeat"
+        transform?: [number, number, number, number, number, number]
+      }
+    | {
+        __gradient: "radial"
+        units: "absolute"
+        cx: number
+        cy: number
+        r: number
+        stops: { offset: number; color: number }[]
+        spread?: "reflect" | "repeat"
+        transform?: [number, number, number, number, number, number]
+      }
+
+  /**
+   * One resolved draw in document coordinates. The keys deliberately match
+   * the path element's props, so a draw spreads onto a `<d-path>` unchanged.
+   * A source path with both a fill and a stroke yields two draws (fill
+   * first). Solid colors are `#rrggbbaa` strings; stroke keys are only
+   * present on stroke draws, `fillRule` only on fills.
+   */
+  export type SvgDraw = {
+    d: string
+    color: string | SvgGradient
+    drawStyle: "fill" | "stroke"
+    fillRule?: "nonzero" | "evenodd"
+    strokeWidth?: number
+    strokeCap?: "butt" | "round" | "square"
+    strokeJoin?: "miter" | "round" | "bevel"
+  }
+
+  /** A parsed document: intrinsic size (viewBox/width-height) plus the flat draw list. */
+  export type SvgDocument = {
+    width: number
+    height: number
+    draws: SvgDraw[]
+  }
+
+  /**
+   * Parses an SVG document string into plain draw data: geometry is flattened
+   * to absolute path data (every group/element transform baked in) and paints
+   * are resolved to solid colors or gradients. Parsing is sandboxed: no
+   * network, file, or data-URI resource access. Throws on an invalid
+   * document.
+   *
+   * `opts.color` drives `currentColor` in the document, as a packed
+   * `0xRRGGBBAA` number (alpha ignored); explicit fills/strokes still win.
+   * The `@solidrt/core` re-export `parseSvg` accepts any CSS color string
+   * instead and is the surface applications normally use.
+   *
+   * Unsupported (skipped): clipPath, masks, filters, patterns, embedded
+   * images, and SVG text.
+   */
+  export function parseSvg(src: string, opts?: { color?: number }): SvgDocument
+}

package/package.json

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

package/standards/base64.d.ts

@@ -0,0 +1,16 @@
+// atob / btoa. Base64 over "binary strings" (WHATWG): the string is a byte
+// container, not text - each char code is one raw byte in 0..=255, with no
+// UTF-8 step in either direction.
+
+/**
+ * Base64-encode a binary string: each char code is taken as one raw byte.
+ * Throws if the string contains a code point above 255 (encode real text by
+ * taking its bytes first, e.g. via {@link TextEncoder}).
+ */
+declare function btoa(data: string): string
+/**
+ * Base64-decode to a binary string: each decoded byte becomes one char code
+ * (read the bytes back with `charCodeAt`). ASCII whitespace in the input is
+ * ignored; anything else that is not valid base64 throws.
+ */
+declare function atob(data: string): string