@solidrt/flux-types 0.0.46 → 0.0.48

package/gui/gpu.d.ts

@@ -95,7 +95,10 @@ declare module "flux:gpu" {
    * 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
+   * `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`. An array uniform
+   * (`vec3 uLight[4]`) goes by its bare name and takes one flat array of
+   * element length times array size (12 here; a light list or palette is one
+   * write). Dispatch follows the
    * 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
@@ -676,12 +679,14 @@ declare module "flux:gpu" {
    * 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.
+   * 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
   /**
@@ -702,12 +707,12 @@ declare module "flux:gpu" {
    * 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.
+   * 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
   /**
@@ -773,7 +778,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-*`
@@ -781,34 +787,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "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
 }