@solidrt/flux-types 0.0.45 → 0.0.47

package/gui/gpu.d.ts

@@ -123,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 }
   /**
@@ -186,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
   /**
@@ -205,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
@@ -328,8 +328,8 @@ 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), and
@@ -385,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:
@@ -526,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(
@@ -605,6 +575,15 @@ declare module "flux:gpu" {
    * 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
@@ -618,8 +597,10 @@ declare module "flux:gpu" {
   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"
@@ -646,6 +627,14 @@ declare module "flux:gpu" {
    * `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,
@@ -665,15 +654,75 @@ declare module "flux:gpu" {
    */
   export function removeDraw(target: TextureId, draw: DrawId): void
   /**
-   * Update one draw entry's uniforms by name: {@link setShaderParams}
+   * 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 - down
+   * to zero coverage: a name no current entry declares is stored and skips
+   * everywhere until a declaring entry arrives, so shared state does not
+   * depend on write order (a seed before entries and a write after are the
+   * same state). Validation is arity where declared: a name must match the
+   * declared component count in every entry program that declares it; 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, down to zero coverage
+   * (an undeclared name is stored, joins the sampler graph, and binds when
+   * a declaring entry arrives); shared bindings are target state that entry
+   * add/remove/rebuild cannot lose. Each name must be a sampler2D
+   * 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
+  /**
+   * 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 setShaderTextures} addressed to a single entry, same merge,
+   * {@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.
    */
@@ -698,7 +747,7 @@ declare module "flux:gpu" {
   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.
@@ -726,7 +775,8 @@ declare module "flux:gpu" {
    */
   export function copyTexture(src: TextureId, dst: TextureId): void
   /**
-   * Capture a render-tree node's subtree into a new GPU texture, resolving once
+   * Capture a render-tree node's subtree as RGBA8 pixels (tightly packed,
+   * top-to-bottom rows - the {@link readTexture} result shape), resolving once
    * it has been rendered on the next paint pass. The node must be attached to
    * the live tree (an unmounted node is never painted, so its capture rejects)
    * and paint a non-zero box. A laid-out node captures its layout box. A `d-*`
@@ -734,34 +784,32 @@ declare module "flux:gpu" {
    * painted box instead: its own `w`/`h` when set, else the nearest laid-out
    * ancestor's box (the same box the render tree reports for it), with its
    * `x`/`y` paint offset mapped to the texture origin.
-   * Rendered at the current display scale, so `width`/`height` are the texture's
-   * actual pixel dimensions (ceil(logicalSize * displayScale)), not logical
-   * points. Each call returns an independent id you must {@link destroyTexture}
-   * when done. Use the returned id anywhere a texture id is accepted
-   * (`<texture src>`, a shader sampler input, {@link readTexture}).
+   * Rendered at the current display scale, so `width`/`height` are actual
+   * pixel dimensions (ceil(logicalSize * displayScale)), not logical points.
+   * No texture is created and there is nothing to free; to display or sample
+   * the result, upload it with {@link createTexture}.
    *
    * Intended for one-shot bakes and inspection: turning something the engine
    * can draw but the app cannot compute - shaped text, an SVG, a themed view -
-   * into pixels, usually to hand to {@link readTexture} and process on the CPU.
-   * Baking a glyph atlas by laying out cells, capturing them and keeping the
-   * coverage channel is the worked example. Tests and freeze-frames are the
-   * same shape.
+   * into pixels the app processes on the CPU. Baking a glyph atlas by laying
+   * out cells, capturing them and keeping the coverage channel is the worked
+   * example. Tests and freeze-frames are the same shape.
    *
    * Not a rendering primitive. Every call rasterizes the subtree into a fresh
-   * offscreen MSAA target, reads the pixels back to the CPU and uploads them
-   * again as a new texture: a full GPU -> CPU -> GPU round trip plus a paint
-   * pass of latency, per call, with nothing incremental about it. Batch what
-   * you capture (many nodes captured together are serviced by one paint pass),
-   * and do not drive it per frame or reach for it to feed live content into a
-   * shader - an effect over what is beneath it, a backdrop filter. Content that
-   * must stay current has to come from a source that updates in place: another
-   * pipeline's render target, a camera texture, a mutable texture.
+   * offscreen MSAA target and reads the pixels back to the CPU: a GPU -> CPU
+   * readback stall plus a paint pass of latency, per call, with nothing
+   * incremental about it. Batch what you capture (many nodes captured together
+   * are serviced by one paint pass), and do not drive it per frame or reach
+   * for it to feed live content into a shader - an effect over what is beneath
+   * it, a backdrop filter. Content that 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: TextureId; width: number; height: number }>
+  export function captureSnapshot(nodeId: number): Promise<{ width: number; height: number; data: Uint8Array }>
   /**
    * Read back a registered texture's current pixels as RGBA8 (tightly packed,
    * top-to-bottom rows), for any texture id whatever created it (createTexture,
-   * createShaderTexture, captureSnapshot). Synchronous. Throws if the id is
+   * createShaderTexture, a render target). Synchronous. Throws if the id is
    * unknown.
    */
   export function readTexture(id: TextureId): { width: number; height: number; data: Uint8Array }

package/gui/rendertree.d.ts

@@ -28,7 +28,13 @@ declare module "flux:rendertree" {
   export function detachNode(parentId: number, nodeId: number): void
   /** Free `nodeId` and its whole subtree. Call after {@link detachNode}. */
   export function destroyNode(nodeId: number): void
-  /** Write a single property on a node; `value` is marshalled per property. */
+  /**
+   * Write a single property on a node; `value` is marshalled per property.
+   * Throws an `Error` for an unknown property name (message starts with
+   * "Unknown property") or a value that does not decode; it never aborts the
+   * runtime. Core's renderer warns-and-continues on the name-level rejections
+   * and rethrows value errors.
+   */
   export function setProperty(nodeId: number, name: string, value: unknown): void
   /**
    * Declare which pointer deliveries the node's handlers want, as a bitmask

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.45",
+  "version": "0.0.47",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",

package/standards/base64.d.ts

@@ -10,7 +10,8 @@
 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.
+ * (read the bytes back with `charCodeAt`). Forgiving per WHATWG: ASCII
+ * whitespace is ignored and missing `=` padding is tolerated; anything else
+ * that is not valid base64 throws.
  */
 declare function atob(data: string): string

package/standards/fetch.d.ts

@@ -4,12 +4,16 @@
 // Grouped in one file because the four share BodyInit/HeadersInit and reference
 // each other.
 
-/** Header initializer: a plain name -> value object, or another Headers. */
+/**
+ * Header initializer: a plain name -> value object, or another Headers.
+ * Values must be strings: a non-string value throws (the web stringifies it).
+ */
 type HeadersInit = Record<string, string> | Headers
 
 /**
  * A message body: a string, raw bytes, or an async-iterable of string/byte
- * chunks (e.g. an `async function*`), which is sent as a stream.
+ * chunks (e.g. an `async function*`), which is sent as a stream. Any other
+ * value throws (the web stringifies it).
  */
 type BodyInit = string | Uint8Array | AsyncIterable<string | Uint8Array>
 

package/standards/time.d.ts

@@ -1,6 +1,15 @@
 // Timers, microtask scheduling, and the monotonic clock. flux's timers differ
 // from the browser in two ways: the delay is required, and no extra callback
 // arguments are forwarded.
+//
+// In a GUI runtime the whole time surface here is FRAME-STEPPED: timers and
+// performance.now() march on the same paced timeline as onFrame and
+// requestAnimationFrame, quantized to frames. So timer resolution is one
+// frame (~16 ms at 60 Hz; a setTimeout of 0 runs on the next frame), an
+// interval fires at most once per frame, and pausing the runtime clock (the
+// dev tools' set_time_scale 0) freezes all of it together deterministically.
+// Date.now() is the wall-clock escape hatch: it always reports real calendar
+// time. Headless flux (scripts, servers) keeps ordinary wall-clock timers.
 
 /**
  * Run `callback` after at least `ms` milliseconds. Returns a timer id for
@@ -25,7 +34,16 @@ declare function queueMicrotask(callback: () => void): void
 declare let performance: {
   /**
    * Milliseconds since a monotonic origin (high-resolution, not wall-clock). Use
-   * for measuring durations, not for calendar time.
+   * for measuring durations, not for calendar time. In a GUI runtime this is
+   * the paced frame timeline (same clock as the onFrame/requestAnimationFrame
+   * timestamps, frozen while the runtime clock is paused); for real elapsed
+   * wall time use Date.now().
    */
   now(): number
+  /**
+   * Wall-clock time (ms since the Unix epoch) when the runtime started. Unlike
+   * the browser, timeOrigin + now() is not the current wall-clock time: now()
+   * runs on the paced runtime timeline, which can be frozen or scaled.
+   */
+  readonly timeOrigin: number
 }