@solidrt/flux-types 0.0.51 → 0.0.53

package/README.md

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

package/gui/camera.d.ts

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

package/gui/gpu.d.ts

@@ -17,11 +17,12 @@
 // they return.
 //
 // Sampling is a per-texture property declared at creation: every create path
-// accepts `{ filter?, wrap? }` ("linear"/"nearest", "clamp"/"repeat";
-// defaults linear + clamp for every origin). The state follows the id
-// everywhere it is sampled - shader passes and `<texture>` display alike -
-// and survives id-stable resizes. It cannot be changed after creation. No
-// mipmaps exist.
+// accepts `{ filter?, wrap?, mipmap? }` ("linear"/"nearest", "clamp"/"repeat",
+// boolean; defaults linear + clamp + no mips for every origin). The state
+// follows the id everywhere it is sampled - shader passes and `<texture>`
+// display alike - and survives id-stable resizes. It cannot be changed after
+// creation. `mipmap: true` keeps a mip chain on the id, regenerated after
+// every upload or render, so shader sampling minifies without aliasing.
 //
 // Compositing several targets is a render-tree job, not a shader one: stack
 // `<texture>` elements and set their `blendMode` (the full Skia set, e.g.
@@ -103,8 +104,9 @@ declare module "flux:gpu" {
    * call site: a name with no active uniform, a value whose length does not
    * fit the declared type, a `sampler2D` named here (samplers bind via
    * `textures`), or a value that is not a number / number array throws.
-   * Reflection only sees active uniforms, so a uniform that is declared but
-   * optimized out counts as unknown - remove the write (or use the uniform).
+   * A uniform that is declared but optimized out by the compiler is accepted
+   * with a warning and the write is skipped, so one param object can drive
+   * shader variants that do not all use every uniform.
    * An `undefined` value is skipped, so conditional spreads stay usable.
    */
   export type ShaderParams = Record<string, number | number[]>
@@ -118,8 +120,29 @@ declare module "flux:gpu" {
    * sampler2D inputs AND `<texture src>` display (a "nearest" texture
    * upscales with hard pixels on screen - the pixel-art path). `wrap` only
    * matters to shaders sampling outside 0..1; the display draw never tiles.
-   */
-  export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode }
+   *
+   * `mipmap` (default false) keeps a mip chain on the id: rebuilt by the
+   * runtime after every upload (data textures) and every render (targets,
+   * automatically - nothing to schedule), and used by shader sampling when
+   * the texture is minified (trilinear for "linear", per-level nearest for
+   * "nearest"). Without it minification skips texels and aliases. Only
+   * shader sampling minifies through the chain; the `<texture>` display
+   * draw samples the full-size level. Regeneration is one GPU pass per
+   * upload or render, so a per-frame texture pays it per frame.
+   */
+  export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode; mipmap?: boolean }
+  /**
+   * One `textures` binding value: a texture id, sampled with the texture's
+   * own declared state, or `{ id, filter?, wrap? }` to sample that id with a
+   * different filter and/or wrap in this binding only (blur a "nearest"
+   * atlas linearly; tile a clamped target in one consumer). The override is
+   * a per-pass deviation: the texture's own state stays what `<texture>`
+   * paints and what every binding without an override uses. `mipmap` is
+   * not overridable - the chain either exists on the id or it does not.
+   */
+  export type TextureBinding = TextureId | { id: TextureId; filter?: FilterMode; wrap?: WrapMode }
+  /** Sampler2D inputs by uniform name; see {@link TextureBinding}. */
+  export type TextureBindings = Record<string, TextureBinding>
   /**
    * A free-form debug name every create accepts (WebGPU's label): surfaced by
    * the dev server's GPU inventory (get_gpu_resources) and in engine log
@@ -243,7 +266,7 @@ declare module "flux:gpu" {
     width: number,
     height: number,
     params?: ShaderParams | null,
-    opts?: { textures?: Record<string, TextureId> } & SamplerOptions & LabelOption,
+    opts?: { textures?: TextureBindings } & SamplerOptions & LabelOption,
   ): TextureId
   /**
    * Compile a single shader stage from raw GLSL ES: the primitive under
@@ -314,9 +337,12 @@ declare module "flux:gpu" {
        * entry's buffer, from record 0 (ES 3.0 has no base instance), so
        * several independently culled groups cannot share one buffer as
        * sub-ranges: give each group its own `instanceBuffer` and entry, and
-       * cull it by `instanceCount`.
+       * cull it by `instanceCount`. Each attribute's `slot` (default 0)
+       * picks a buffer of the entry's `instanceBuffers` list (see
+       * {@link InstanceAttribute}); a pipeline using only slot 0 binds via
+       * the plain `instanceBuffer` key.
        */
-      instanceAttributes?: VertexAttribute[]
+      instanceAttributes?: InstanceAttribute[]
       topology?: Topology
       blend?: BlendMode
       cull?: CullMode
@@ -368,6 +394,18 @@ declare module "flux:gpu" {
    * read-modify-write of its own pixels (decay, blur, simulation) still
    * ping-pongs across two manual targets - a pass can never sample the
    * texture it writes.
+   *
+   * `samples` (1, 2, 4 or 8; default 1) multisamples the target's storage:
+   * edges of filled geometry get coverage-weighted AA instead of binary
+   * jaggies. Storage only - the texture id still names a single-sample
+   * image, so display, sampling, `readTexture` and `copyTexture` are
+   * unaffected. The count is clamped to the device maximum and a
+   * configuration the driver refuses falls back to single-sample with a
+   * warning (read the effective value off the resource inventory). Cannot
+   * combine with `loadOp: "load"` (throws): multisampled storage cannot
+   * load the previous contents. Tiled mobile GPUs resolve in-tile
+   * (EXT_multisampled_render_to_texture); everywhere else a resolve blit
+   * follows each pass.
    */
   export function createShaderTarget(
     pipeline: RenderPipelineId,
@@ -375,12 +413,16 @@ declare module "flux:gpu" {
     height: number,
     params?: ShaderParams | null,
     opts?: {
-      textures?: Record<string, TextureId>
+      textures?: TextureBindings
       buffer?: BufferId
       instanceBuffer?: BufferId
+      /** One buffer per instance slot of the pipeline (index = the
+       * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
+      instanceBuffers?: BufferId[]
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
+      samples?: 1 | 2 | 4 | 8
     } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
@@ -392,6 +434,16 @@ declare module "flux:gpu" {
    * immediately.
    */
   export function destroyProgram(id: ProgramId): void
+  /**
+   * The vertex attributes a linked program actually reads (name and format),
+   * as the compiler left them: an `in` the vertex stage never uses is not
+   * listed, and a type no layout can feed (a matrix, an integer vector) is
+   * rejected at linkProgram. This is the list a pipeline over the program
+   * must cover between `attributes` and `instanceAttributes` - an uncovered
+   * or mis-formatted one throws at createRenderPipeline. Answered locally,
+   * no GPU round trip.
+   */
+  export function programAttributes(program: ProgramId): VertexAttribute[]
   export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
   /**
    * Blending for a pipeline's own draw. "none" (default) overwrites:
@@ -443,6 +495,17 @@ declare module "flux:gpu" {
    * shader's `in` declarations.
    */
   export type VertexAttribute = { name: string; format: "f32" | "vec2" | "vec3" | "vec4" }
+  /**
+   * One float attribute of a per-instance record. `slot` (default 0) picks
+   * which buffer of the entry's `instanceBuffers` list the attribute
+   * fetches from: attributes sharing a slot interleave into one record in
+   * list order, distinct slots are distinct buffers with their own strides
+   * - which is what lets two writers own instance data independently (a
+   * core-written pose buffer beside an app-written style buffer). Slots
+   * must be dense from 0, at most 4; a single-slot pipeline (every `slot`
+   * omitted) binds via the plain `instanceBuffer` key.
+   */
+  export type InstanceAttribute = VertexAttribute & { slot?: number }
   /**
    * A pipeline target's draw as data, WebGPU-style: `firstVertex` +
    * `vertexCount` pick the vertex range `[firstVertex, firstVertex +
@@ -492,6 +555,28 @@ declare module "flux:gpu" {
    * there is no base vertex (ES 3.0, like ES 3.0's missing base instance).
    */
   export type IndexRange = { firstIndex?: number; indexCount?: number; instanceCount?: number }
+  /**
+   * A draw entry's buffer swap: each key present re-points that role of the
+   * entry at another {@link createBuffer} buffer, absent keys keep their
+   * current buffer. Replace-only - the roles an entry fills are pipeline
+   * layout state (`attributes` needs a `buffer`, `instanceAttributes` an
+   * `instanceBuffer`) and indexing is its draw vocabulary, so naming a role
+   * the entry does not fill throws; `indexBuffer` travels with
+   * `indexFormat` as at create. The entry's current range is kept and
+   * rechecked against the new buffers' sizes: a swap to a buffer too small
+   * for the live range throws (shrink the range first); a larger buffer
+   * never does. This is the growth primitive: a population outgrowing its
+   * instance buffer creates a larger one, writes it, swaps, and destroys
+   * the old (the entry holds the old buffer alive until the swap lands, so
+   * either order is safe). `instanceBuffer` swaps slot 0;
+   * `instanceBuffers` swaps every slot at once and must fill exactly the
+   * slots the entry fills (pass one spelling or the other).
+   */
+  export type BufferUpdate = {
+    buffer?: BufferId
+    instanceBuffer?: BufferId
+    instanceBuffers?: BufferId[]
+  } & ({} | IndexBinding)
 
   /**
    * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
@@ -531,12 +616,15 @@ declare module "flux:gpu" {
     height: number,
     params?: ShaderParams | null,
     opts?: {
-      textures?: Record<string, TextureId>
+      textures?: TextureBindings
       attributes?: VertexAttribute[]
       buffer?: BufferId
       /** See {@link createRenderPipeline}'s `instanceAttributes`. */
-      instanceAttributes?: VertexAttribute[]
+      instanceAttributes?: InstanceAttribute[]
       instanceBuffer?: BufferId
+      /** One buffer per instance slot (index = the attributes' `slot`);
+       * pass this OR `instanceBuffer`, not both. */
+      instanceBuffers?: BufferId[]
       topology?: Topology
       depth?: boolean
       depthWrite?: boolean
@@ -545,6 +633,7 @@ declare module "flux:gpu" {
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
+      samples?: 1 | 2 | 4 | 8
     } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
@@ -605,9 +694,13 @@ declare module "flux:gpu" {
    * (On a manual target nothing renders here; the range applies at its next
    * {@link renderTarget}.) An indexed target takes the {@link IndexRange}
    * spelling instead, bounds-checked against its index buffer; the pair
-   * that does not match the target's mode throws.
+   * that does not match the target's mode throws. Buffer keys
+   * ({@link BufferUpdate}) swap the target's buffers in the same call: the
+   * merged range is checked against the swapped buffers, so one call grows a
+   * buffer and extends the range into it, and a call that throws changes
+   * nothing (range and buffers commit together or not at all).
    */
-  export function setDraw(id: TextureId, draw: DrawRange | IndexRange): void
+  export function setDraw(id: TextureId, draw: (DrawRange | IndexRange) & BufferUpdate): void
   /**
    * Create a draw target: a render target whose contents are an ordered,
    * mutable LIST of draws - one render clears once, then executes every
@@ -623,6 +716,10 @@ declare module "flux:gpu" {
    * occlusion work. It is the storage half of the depth story; whether an
    * entry tests/writes depth is its pipeline's `depth`/`depthWrite` state,
    * and adding a depth-testing pipeline to a target without storage throws.
+   * `depth: "texture"` is the same storage as a SAMPLEABLE depth texture
+   * with an id of its own - {@link depthTexture} - for shadow maps,
+   * depth-of-field, SSAO; it cannot combine with `samples` (a multisampled
+   * depth texture is not sampleable; the create throws).
    *
    * `params` seeds the target's SHARED params - the target-level values
    * every entry reads, the same live channel {@link setTargetParams} drives
@@ -638,24 +735,64 @@ declare module "flux:gpu" {
    * "auto"` target re-renders exactly when its entries or their inputs
    * change - a static scene costs zero passes, however many entries it
    * holds, and one render is ONE pass however many entries it draws.
-   * `render: "manual"` and `loadOp: "load"` compose exactly as on
-   * {@link createShaderTarget}. With no entries a render is the clear alone.
+   * `render: "manual"`, `loadOp: "load"` and `samples` compose exactly as
+   * on {@link createShaderTarget}. With no entries a render is the clear
+   * alone.
    * Returns a texture id (display, resize, destroy like any target; entries
    * die with it).
+   *
+   * `into` makes a SUB-TARGET: a draw target that renders into the `width`
+   * x `height` rectangle at `x`/`y` (top-left origin, the texture leaf's
+   * `srcX`/`srcY` space; default 0) of draw target `into`'s storage instead
+   * of owning any. It is a draw target to every verb - entries, shared
+   * params and bindings, order, `setTargetSize` - with dirty state of its
+   * own, and the parent renders ALL its tiles in ONE pass: a changed tile
+   * redraws over its own rectangle (the rest keeps its pixels), a changed
+   * parent redraws everything. That is what makes N views or N shadow maps
+   * cost one pass instead of N. The returned id is not a texture: sample,
+   * display (`<d-texture src={parent} srcX srcY srcW srcH>`), read back and
+   * copy the PARENT; `depthTexture(parent)` is the tile's depth too. Depth,
+   * `samples`, `render` and `loadOp` are the parent's (passing them
+   * throws), `clearColor` is the tile's own. A rectangle partly outside the
+   * parent is clipped; {@link setTargetRect} moves it. Tiles do not nest.
+   * Destroying the parent destroys its tiles.
    */
   export function createDrawTarget(
     width: number,
     height: number,
     params?: ShaderParams | null,
     opts?: {
-      depth?: boolean
-      textures?: Record<string, TextureId>
+      depth?: boolean | "texture"
+      textures?: TextureBindings
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
+      samples?: 1 | 2 | 4 | 8
+      into?: TextureId
+      x?: number
+      y?: number
     } & SamplerOptions &
       LabelOption,
   ): TextureId
+  /**
+   * The depth texture of a draw target created with `depth: "texture"`: a
+   * texture id of its own, stable for the target's life (a
+   * {@link setTargetSize} follows the color), holding the target's depth
+   * after every render - 24-bit window depth in 0..1, read as `.r` from a
+   * `sampler2D`. Bind it anywhere a texture binds ({@link setTargetTextures}
+   * for a whole scene target, an entry's `textures`, a fragment target's
+   * inputs); the dependency graph treats a binding to it as a binding to its
+   * target, so the depth pass renders first and a target sampling its own
+   * depth throws. SAMPLER-ONLY: it is not an upload texture and not a
+   * readback source (`readTexture`/`copyTexture` throw - render it through a
+   * pass to read it), its sampling is fixed at `nearest`/`clamp` (a depth
+   * texture is only complete at nearest without a comparison mode - filter
+   * in the shader, e.g. a PCF loop), and it dies with its target
+   * (`destroyTexture` on it throws). Displaying it via `<texture src>`
+   * shows the depth in the red channel. Throws for a target without texture
+   * depth.
+   */
+  export function depthTexture(target: TextureId): TextureId
   /**
    * Append a draw entry to a draw target: `pipeline` draws `opts.buffer`
    * (required when the pipeline declares attributes) with its own `params`
@@ -690,9 +827,12 @@ declare module "flux:gpu" {
     pipeline: RenderPipelineId,
     params?: ShaderParams | null,
     opts?: {
-      textures?: Record<string, TextureId>
+      textures?: TextureBindings
       buffer?: BufferId
       instanceBuffer?: BufferId
+      /** One buffer per instance slot of the pipeline (index = the
+       * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
+      instanceBuffers?: BufferId[]
       before?: DrawId
     } & (DrawRange | (IndexBinding & IndexRange)),
   ): DrawId
@@ -760,7 +900,7 @@ declare module "flux:gpu" {
    * everywhere it is declared, and each entry's effective inputs (its own
    * plus the applicable shared ones) must fit the device's texture units.
    */
-  export function setTargetTextures(target: TextureId, textures: Record<string, TextureId>): void
+  export function setTargetTextures(target: TextureId, textures: TextureBindings): void
   /**
    * Resize a render target of any kind in place and re-render it: the id,
    * compiled programs, last-applied params, sampler bindings, and draw
@@ -769,19 +909,33 @@ declare module "flux:gpu" {
    * which carries seed pixels instead.)
    */
   export function setTargetSize(id: TextureId, width: number, height: number): void
+  /**
+   * Move and resize a sub-target's rectangle in its parent (top-left
+   * origin; every key required). The parent re-renders in full at the next
+   * flush. Throws for anything but a sub-target (see `into` on
+   * {@link createDrawTarget}); `setTargetSize` on a tile is this with the
+   * origin kept.
+   */
+  export function setTargetRect(id: TextureId, rect: { x: number; y: number; 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
+  export function setDrawTextures(target: TextureId, draw: DrawId, textures: TextureBindings): void
   /**
    * Update one draw entry's draw range: {@link setDraw} addressed to a
    * single entry, same partial merge, bounds validation, and vocabulary
    * rule (an indexed entry speaks {@link IndexRange}).
    */
   export function setDrawRange(target: TextureId, draw: DrawId, update: DrawRange | IndexRange): void
+  /**
+   * Swap one draw entry's buffers: the {@link BufferUpdate} half of
+   * {@link setDraw} addressed to a single entry, same replace-only rule and
+   * range recheck.
+   */
+  export function setDrawBuffers(target: TextureId, draw: DrawId, update: BufferUpdate): void
   /**
    * Reorder a draw target's list. `order` must name every current entry
    * exactly once - a full permutation of the live {@link DrawId}s; a

package/gui/rendertree.d.ts

@@ -5,6 +5,7 @@
 // module; requestFrame here only schedules a future frame.
 
 declare module "flux:rendertree" {
+  import type { TextureId } from "flux:gpu"
   /** Font options for {@link measureText} and {@link prepareText}. */
   export interface MeasureTextOptions {
     fontFamily?: "sans" | "serif" | "mono" | (string & {})
@@ -77,9 +78,20 @@ declare module "flux:rendertree" {
 
   /** Create the window root node with the given id. */
   export function createRoot(id: number): void
+  /**
+   * Make `id`, an existing window node, the root again. Creating a window
+   * takes the root over, so this is the way back to an earlier window without
+   * recreating it (render()'s error boundary swapping the app's window back
+   * in on reset). No-op for the current root or an unknown id.
+   */
+  export function setRoot(id: number): void
   /** Create a node of `kind` (the primitive element name) with the given id. Throws an `Error` for a name that is not an element. */
   export function createNode(id: number, kind: string): void
-  /** Insert `nodeId` under `parentId`, before `anchorId` if given (else appended). */
+  /**
+   * Insert `nodeId` under `parentId`, before `anchorId` if given (else appended).
+   * Throws an `Error` when a laid-out node would land under a detached (d-*)
+   * parent: a detached subtree is entirely detached. The tree is left untouched.
+   */
   export function insertNode(parentId: number, nodeId: number, anchorId?: number): void
   /**
    * Unlink `nodeId` from `parentId` but keep its subtree alive, so it can be
@@ -170,6 +182,18 @@ declare module "flux:rendertree" {
    * semantics), for comparing against pointer event coordinates.
    */
   export function getBoundingBoxViewport(id: number): { x: number, y: number, width: number, height: number } | null
+  /**
+   * The texture id of a snapshot repaint boundary's retained rasterization
+   * (its subtree's pixels at display scale, premultiplied, top-left origin,
+   * cropped to the layout box). Allocated on the first call and stable for
+   * the node's lifetime; it is re-pointed at the current pixels after every
+   * rasterization, so consumers never rebind. Before the first paint the id
+   * has no pixels yet (a `<texture>` measures 0x0, a shader pass skips the
+   * binding). Owned by the boundary: `destroyTexture` on it throws, and an
+   * unmounted boundary releases it through the deferred-destroy path. Throws
+   * if the node is not a snapshot boundary.
+   */
+  export function snapshotTexture(id: number): TextureId
   /**
    * Parses a CSS color string (hex, rgb()/rgba(), hsl()/hsla(), hwb(),
    * named colors) into packed 0xRRGGBBAA form (which the color property

package/gui/spatial.d.ts

@@ -0,0 +1,188 @@
+// The spatial core (gui-enabled runtime only): a native transform hierarchy
+// whose flush recomputes only the subtrees that changed and writes the
+// results to draw sinks - a draw entry's `uModel` (+ `uNormal`) params and
+// its instance count as the visibility switch. Generic on purpose: no camera,
+// mesh or light concept. @solidrt/3d is the first consumer; any draw-list
+// user with a tree of transforms (a 2D sprite scene, a skeleton) is the same
+// shape. Node ids are plain numbers, generation-tagged and never reused, so
+// a destroyed node's id throws everywhere.
+//
+// A transform argument is one Float32Array of 10: position xyz, unit
+// quaternion xyzw, scale xyz. Writes queue the node; nothing reaches the
+// GPU until flush(). worldMatrix() reads through pending writes.
+
+declare module "flux:spatial" {
+  import type { BufferId, DrawId, TextureId } from "flux:gpu"
+
+  export type NodeId = number & { readonly __spatialNode: unique symbol }
+
+  /** A new root node. `visible: false` hides the node's whole subtree. */
+  export function createNode(transform: Float32Array, visible: boolean): NodeId
+  /** Free a node; its children become roots. A bound sink is dropped
+   * without a write (removing the entry is the caller's job). */
+  export function destroyNode(node: NodeId): void
+  /** Re-parent (null = make a root). Throws on a cycle. */
+  export function setParent(node: NodeId, parent: NodeId | null): void
+  /** Replace the local transform (compare before calling; an unchanged
+   * write still queues the node). Never consults or cancels transition
+   * tracks: a running track overwrites a raw write at the next frame
+   * (last write wins - the producer rule). */
+  export function setTransform(node: NodeId, transform: Float32Array): void
+  /**
+   * One node-transition spec, the element `transition` vocabulary minus
+   * the lifecycle conveniences: `{ duration }` / `{ duration, bounce }`
+   * is a spring (the default kind; retargets keep position and velocity,
+   * rotation springs keep angular velocity along the geodesic),
+   * `{ duration, curve }` a tween (rotation tweens slerp the geodesic;
+   * retargets restart from the current value), or the shorthand string
+   * `"<duration>ms [curve]"`. Durations in ms; no delay, from or exit.
+   */
+  export type NodeTransitionSpec =
+    | { duration: number; bounce?: number }
+    | { duration: number; curve: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number] }
+    | string
+  /** The declaration setTransition takes: a spec per transform component
+   * plus `all` as a catch-all (per-component entries win). */
+  export interface NodeTransition {
+    position?: NodeTransitionSpec
+    rotation?: NodeTransitionSpec
+    scale?: NodeTransitionSpec
+    all?: NodeTransitionSpec
+  }
+  /**
+   * Declare (or with null clear) the node's transitions: with a config
+   * set, writeTransform animates instead of snapping. A bare string is
+   * the `all` catch-all. Clearing cancels the node's running tracks in
+   * place - it keeps its mid-flight transform, no settled events fire,
+   * and later writes snap. Replacing a config affects future writes only.
+   */
+  export function setTransition(node: NodeId, transition: NodeTransition | string | null): void
+  /**
+   * Replace the local transform THROUGH the transition declaration: a
+   * declared component animates toward the written value (the write is a
+   * target), an undeclared one snaps. Without a declaration this is
+   * setTransform. A component matching its running track's target is
+   * left alone, so rewriting the whole array to move one component never
+   * restarts the others. Each settled component fires one
+   * "spatialTransitionEnd" engine event (srt:events), payload
+   * `{ node, component: "position" | "rotation" | "scale" }`.
+   */
+  export function writeTransform(node: NodeId, transform: Float32Array): void
+  export function setVisible(node: NodeId, visible: boolean): void
+  /**
+   * Route the node's world matrix to one draw entry's `uModel` (and
+   * `uNormal`, the inverse-transpose, when `normal`). Validated like
+   * setDrawParams: the entry must exist and declare those uniforms. The
+   * entry is assumed switched off (instanceCount 0); the next flush turns it
+   * on with `count` when the node is shown, and off again when hidden.
+   * One draw sink PER TARGET: binding on a target the node already draws
+   * into replaces that sink, binding on another target adds one - a mesh
+   * drawn by a scene and by each of its views is one node with one flush.
+   */
+  export function bindDraw(node: NodeId, target: TextureId, draw: DrawId, normal: boolean, count: number): void
+  /** Remove the node's draw sink on `target`, or every draw sink without
+   * one. Issues no write: the entries are the caller's to remove. */
+  export function unbindDraw(node: NodeId, target?: TextureId): void
+  /** Change every bound entry's "on" count (an instanced mesh's record
+   * count); written at once to the entries currently on. */
+  export function setDrawCount(node: NodeId, count: number): void
+  /** Fill `out` (a Float32Array of 16, column-major) with the node's world
+   * matrix as the tree stands now, pending writes included. */
+  export function worldMatrix(node: NodeId, out: Float32Array): void
+  /** Effective visibility (every ancestor visible too) as of the last flush. */
+  export function shown(node: NodeId): boolean
+  /** Recompute every changed subtree and write the sinks; requests a frame
+   * when anything was written. */
+  export function flush(): void
+
+  export type ShapeId = number & { readonly __spatialShape: unique symbol }
+
+  /** One hit of raycast(), nearest first. `face`/`uv`/`normal` are present
+   * for nodes with a shape (uv only when the shape has UVs); a node with
+   * bounds but no shape reports its local box, distance and point only. */
+  export type Hit = {
+    node: NodeId
+    /** World units along the normalized ray. */
+    distance: number
+    point: [number, number, number]
+    /** World-space geometric normal, facing the ray. */
+    normal?: [number, number, number]
+    /** Triangle index into the shape's index list. */
+    face?: number
+    uv?: [number, number]
+  }
+
+  /** Set (null clears) the node's LOCAL tight box [minX, minY, minZ, maxX,
+   * maxY, maxZ]. With one the node is in the picking index: its world box
+   * follows the flush; hidden nodes stay in and are skipped at query time. */
+  export function setBounds(node: NodeId, bounds: Float32Array | null): void
+  /**
+   * Triangle data for the picking narrowphase, one copy shared by every
+   * node that references it: positions read from an interleaved vertex
+   * array (`stride` floats per vertex, xyz at `posOffset`, uv at
+   * `uvOffset`, -1 for none) and a Uint16Array/Uint32Array triangle list.
+   * Throws on out-of-range indices.
+   */
+  export function createShape(vertices: Float32Array, stride: number, posOffset: number, uvOffset: number, indices: Uint16Array | Uint32Array): ShapeId
+  /** Free a shape; nodes still referencing it fall back to their box. */
+  export function destroyShape(shape: ShapeId): void
+  export function setShape(node: NodeId, shape: ShapeId | null): void
+  /** Every shown node with bounds the ray strikes, nearest first. The
+   * direction need not be normalized; distances are world units. Reads
+   * the index as of the last flush. */
+  export function raycast(origin: Float32Array, direction: Float32Array): Hit[]
+  /**
+   * Every shown node with bounds whose local box, carried through its
+   * world transform, overlaps the world-axis box `bounds` (a Float32Array
+   * of 6: [minX, minY, minZ, maxX, maxY, maxZ]; touching counts, a point
+   * is min == max). Tested by separating axes, so a rotated flat rect -
+   * the 2d marquee case - tests exactly, never by its world AABB.
+   * Unordered; reads the index as of the last flush, like raycast.
+   */
+  export function overlap(bounds: Float32Array): NodeId[]
+
+  /**
+   * Route the world DIRECTION of the node's local `vector` (a
+   * Float32Array of 3) into
+   * vec3 slot `index` of the `len`-float shared array param `name` on a
+   * draw target: the flush writes `normalize(worldRotation * v)` there
+   * and re-sends the whole array when any slot changes; unbound slots are
+   * zeros. Every sink naming the same param shares one array (`len` must
+   * agree); what the slots mean - light directions, an emitter axis - is
+   * the caller's business, packed alongside its own non-spatial params.
+   * One slot sink per target, like bindDraw: rebinding on the same target
+   * replaces that sink (the abandoned slot zeroes), another target adds one.
+   */
+  export function bindDirectionSlot(node: NodeId, target: TextureId, name: string, len: number, index: number, vector: Float32Array): void
+  /** Remove the node's slot sink on `target`, or every slot sink without
+   * one (the abandoned slots zero at the next flush). */
+  export function unbindSlot(node: NodeId, target?: TextureId): void
+
+  /**
+   * Route the node's world pose to record slot `index` of vertex buffer
+   * `buffer` used as an instance buffer: the flush writes the 5 floats
+   * [x, y, angle, sx, sy] (world xy translation, rotation of the local x
+   * axis in the world xy plane, xy scale with sy negated when the matrix
+   * mirrors) at float offset index * 5. Writes batch: however many bound
+   * nodes moved, each flush issues at most one coalesced write per
+   * buffer, so producer-driven populations cost one buffer write per
+   * frame. A hidden node's slot zeroes (zero scale collapses the
+   * instance); so does an unbound or destroyed node's. Validated at bind
+   * time: the buffer must exist and the slot must fit its byte size.
+   * Rebinding replaces the node's record sink; the abandoned slot zeroes.
+   */
+  export function bindPoseRecord(node: NodeId, buffer: BufferId, index: number): void
+  /** Remove the node's record sink (its slot zeroes at the next flush). */
+  export function unbindRecord(node: NodeId): void
+  /**
+   * Move every record sink on buffer `old` to buffer `new`, slot indices
+   * untouched: the growth swap. The whole used range republishes into
+   * `new` at the next flush, so a population outgrowing its buffer swaps
+   * in a larger one with one call and one bulk write instead of a
+   * bindPoseRecord per node (pair it with the draw entry's own buffer
+   * swap, setDraw's `instanceBuffers`). Throws when nothing is bound to
+   * `old`, when `new` does not exist or cannot hold every bound slot, or
+   * when `new` already carries record sinks.
+   */
+  export function retargetRecords(old: BufferId, next: BufferId): void
+}

package/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference path="./modules/process.d.ts" />
+/// <reference path="./modules/tty.d.ts" />
 /// <reference path="./modules/path.d.ts" />
 /// <reference path="./modules/http.d.ts" />
 /// <reference path="./modules/fs.d.ts" />
@@ -15,7 +16,7 @@
 
 // Web-standard globals. The runtime is QuickJS, not a browser or Node, so it
 // ships no lib.dom / @types/bun: these declarations are the sole source for
-// console, fetch, the Fetch types, timers, WebSocket, and the encoders.
+// console, fetch, the Fetch types, timers, WebSocket, the encoders, and crypto.
 /// <reference path="./standards/console.d.ts" />
 /// <reference path="./standards/time.d.ts" />
 /// <reference path="./standards/text.d.ts" />
@@ -23,6 +24,7 @@
 /// <reference path="./standards/fetch.d.ts" />
 /// <reference path="./standards/websocket.d.ts" />
 /// <reference path="./standards/abort.d.ts" />
+/// <reference path="./standards/crypto.d.ts" />
 
 // GUI capabilities (present only on a gui-enabled runtime). rendertree/camera/
 // microphone/gpu are flux:* modules like the rest; requestAnimationFrame stays a
@@ -34,6 +36,7 @@
 /// <reference path="./gui/microphone.d.ts" />
 /// <reference path="./gui/audio.d.ts" />
 /// <reference path="./gui/gpu.d.ts" />
+/// <reference path="./gui/spatial.d.ts" />
 /// <reference path="./gui/video.d.ts" />
 /// <reference path="./gui/raf.d.ts" />
 

package/modules/fs.d.ts

@@ -34,6 +34,24 @@ declare module "flux:fs" {
     write(data: string | Uint8Array): Promise<void>
     /** Append `data` to the end of the file, creating it if missing. */
     append(data: string | Uint8Array): Promise<void>
+    /** Remove the file. A missing file is not an error. */
+    remove(): Promise<void>
+  }
+
+  /**
+   * One change under a watched directory. `path` is the absolute path of the
+   * entry. `rename` names the path a file now has (the target of a rename:
+   * an editor's atomic save shows up as one); the old name of a rename
+   * arrives as `remove`.
+   */
+  type WatchEvent = {
+    kind: "create" | "modify" | "remove" | "rename"
+    path: string
+  }
+
+  type WatchOptions = {
+    /** Watch the whole tree below the directory too. Default false. */
+    recursive?: boolean
   }
 
   type FluxDir = {
@@ -47,6 +65,13 @@ declare module "flux:fs" {
      * already exists.
      */
     create(): Promise<void>
+    /**
+     * Watch the directory for changes, calling `callback` for each one.
+     * Events are raw and undebounced: one save usually arrives as several,
+     * so coalesce them yourself. The watch keeps the process alive until the
+     * returned function is called. Throws if the directory does not exist.
+     */
+    watch(callback: (event: WatchEvent) => void, options?: WatchOptions): () => void
   }
 
   /**
@@ -66,4 +91,12 @@ declare module "flux:fs" {
    * @param path  Path to the directory.
    */
   export function dir(path: string): FluxDir
+  /**
+   * The canonical absolute path: symlinks resolved, `.`/`..` collapsed, the
+   * spelling the OS reports (no `\\?\` prefix on Windows). Rejects if the
+   * path does not exist.
+   *
+   * @param path  Path to a file or directory.
+   */
+  export function realpath(path: string): Promise<string>
 }

package/modules/http.d.ts

@@ -149,7 +149,7 @@ declare module "flux:http" {
   }
 
   type Server = {
-    /** The bound port. */
+    /** The bound port (the OS-assigned one when `port` was 0 or omitted). */
     readonly port: number
     /** The bound host/interface. */
     readonly host: string
@@ -191,8 +191,8 @@ declare module "flux:http" {
   }
 
   type ServeOptions = {
-    /** Port to listen on. */
-    port: number
+    /** Port to listen on. 0 or omitted picks a free port; read it back from `server.port`. */
+    port?: number
     /** Hostname/interface to bind. Defaults to "0.0.0.0" (all interfaces). */
     host?: string
     /**

package/modules/image.d.ts

@@ -1,24 +1,47 @@
 declare module "flux:image" {
-  /** Decoded pixels: tightly-packed RGBA8 plus the pixel dimensions. */
+  /**
+   * Decoded pixels: tightly-packed RGBA8 plus the pixel dimensions. Alpha is
+   * premultiplied unless the call that produced them said otherwise.
+   */
   export type DecodedImage = {
     data: Uint8Array
     width: number
     height: number
   }
 
+  /**
+   * Which alpha convention a pixel buffer follows. Image files store
+   * `"straight"` alpha; every texture and target on the GPU is
+   * `"premultiplied"` (color already multiplied by alpha), and so is what
+   * `readTexture` / `captureSnapshot` hand back.
+   */
+  export type AlphaMode = "premultiplied" | "straight"
+
   /**
    * 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.
+   *
+   * `alpha` selects what comes out: `"premultiplied"` (default) is ready for
+   * `createTexture` as-is; `"straight"` is the file's pixels verbatim, for CPU
+   * processing that wants color under transparent pixels preserved. Opaque
+   * pixels are identical either way.
    */
-  export function decodeImage(bytes: Uint8Array): DecodedImage
+  export function decodeImage(bytes: Uint8Array, options?: { alpha?: AlphaMode }): 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`.
+   * (`encodeImage(decodeImage(bytes))` round-trips: exactly for opaque and
+   * fully transparent pixels, within rounding for translucent ones). `format`
+   * defaults to `"png"` (lossless, keeps alpha); `"jpeg"` drops the alpha
+   * channel and takes `quality` in 0..1 (default 0.9, ignored for png).
+   * `alpha` names what `img.data` holds: `"premultiplied"` (default, a decode
+   * or a readback) is converted to the straight alpha PNG stores;
+   * `"straight"` is written verbatim. Throws when `data.length` does not
+   * match `width * height * 4`.
    */
-  export function encodeImage(img: DecodedImage, options?: { format?: "png" | "jpeg"; quality?: number }): Uint8Array
+  export function encodeImage(
+    img: DecodedImage,
+    options?: { format?: "png" | "jpeg"; quality?: number; alpha?: AlphaMode },
+  ): Uint8Array
 }

package/modules/net.d.ts

@@ -22,6 +22,10 @@ declare module "flux:net" {
   /**
    * Outcome of a {@link probe}. `closed` (a refusal) still means the host is up —
    * something answered; only `filtered` (a timeout/unreachable) is no evidence.
+   *
+   * Windows reports a refusal only after ~2 s of SYN retries, so a `timeoutMs`
+   * under that reads a refused port as `filtered` there; `open` is instant
+   * everywhere.
    */
   type Liveness = "open" | "closed" | "filtered"
 
@@ -43,6 +47,8 @@ declare module "flux:net" {
     mac: string | null
     /** Whether the interface is up. */
     up: boolean
+    /** Whether it holds the default route (the interface other hosts reach). */
+    default: boolean
     /** Whether it is a loopback interface. */
     loopback: boolean
     /** Whether it supports multicast. */

package/modules/process.d.ts

@@ -6,6 +6,8 @@ declare module "flux:process" {
    * argument.
    */
   export let argv: string[]
+  /** The OS process id of this process (what a registry record or a `kill` names). */
+  export let pid: number
   /** The host OS: "darwin", "win32", "linux", "android", ... */
   export let platform: string
   /** The CPU architecture: "x64", "arm64", ... */
@@ -16,6 +18,40 @@ declare module "flux:process" {
    * provided for now.)
    */
   export function memoryUsage(): { rss: number }
+  /**
+   * The current user's home directory, or `null` when the environment does
+   * not name one (HOME on unix, USERPROFILE on Windows).
+   */
+  export function homedir(): string | null
+  /**
+   * The path of the running executable, or `null` when the OS cannot name it
+   * (Node's is always a string). What a dev tool spawns through
+   * `flux:subprocess` to start another instance of the runtime it runs in.
+   * In a packed app this is the app itself: spawning it launches that app,
+   * not a bare runtime.
+   */
+  export let execPath: string | null
+  /**
+   * Terminate another process. Portable (SIGKILL / TerminateProcess), so
+   * there is no signal argument, unlike Node's `process.kill(pid, signal)`.
+   *
+   * @param pid  The OS process id.
+   * @returns `true` when the process was terminated; `false` when it does not
+   *          exist or the OS refused.
+   */
+  export function kill(pid: number): boolean
+  /**
+   * Whether a process with `pid` exists. The `process.kill(pid, 0)` idiom
+   * under its own name. A zombie (exited, not yet reaped) counts as gone.
+   *
+   * @param pid  The OS process id.
+   */
+  export function alive(pid: number): boolean
+  /**
+   * The process environment, snapshotted when the module is evaluated: a
+   * plain object, not Node's live and writable `process.env`.
+   */
+  export let env: Record<string, string | undefined>
   /**
    * Listen for an OS signal. The callback receives the signal name. Returns an
    * unsubscribe function. Unix only; a no-op elsewhere.

package/modules/subprocess.d.ts

@@ -14,6 +14,15 @@ declare module "flux:subprocess" {
      * as UTF-8 strings.
      */
     encoding?: "buffer" | "utf8"
+    /**
+     * `spawn()` only: the child outlives this engine and this process. It is
+     * never killed on drop or reload, has no stdin/stdout/stderr pipes (all
+     * null: `stdout`/`stderr` iterate to nothing, `write` fails) and runs in
+     * its own process group, so a Ctrl+C to the parent does not reach it.
+     * `pid`, `kill()` and `status()` still work. Cannot combine with `stdin`.
+     * What a dev tool uses to launch another runtime instance.
+     */
+    detached?: boolean
   }
 
   /** The buffered result of a child run to completion via {@link Command.output}. */

package/modules/tty.d.ts

@@ -0,0 +1,69 @@
+declare module "flux:tty" {
+  /**
+   * Whether stdin is a terminal this process can use. False for a pipe, a
+   * file, or no stdin at all (a GUI launch), the cases where nobody is there
+   * to prompt; on unix also false for a job backgrounded from an interactive
+   * shell (`cmd &`), which still has the terminal as stdin but would be
+   * stopped by job control the moment it touched it.
+   */
+  export let isTTY: boolean
+  /** One key press in raw mode (see {@link setRawMode}). */
+  export interface Key {
+    /**
+     * Node's keypress names: "return", "backspace", "tab", "escape",
+     * "delete", "insert", "up", "down", "left", "right", "home", "end",
+     * "pageup", "pagedown", "space", "f1".."f12", or the lowercase letter
+     * or symbol typed.
+     */
+    name: string
+    /** The character typed, with its case, for a printable key; else undefined. */
+    char: string | undefined
+    ctrl: boolean
+    /** Alt (Option) held. */
+    meta: boolean
+    shift: boolean
+  }
+  /**
+   * Listen for input on stdin. `"line"` delivers one line per call as the
+   * terminal's own line discipline hands it over (cooked mode: the terminal
+   * does the editing), with the newline stripped; `"key"` delivers one key
+   * press per call while raw mode is on (and nothing arrives as a line
+   * then); `"close"` fires once when stdin reaches end of file (Ctrl-D in
+   * cooked mode, or the pipe closing). A listener holds the process alive
+   * until it unsubscribes; after `"close"` nothing can come, so every tty
+   * listener is dropped then, and a later `on` registers nothing. stdin is
+   * read once per process: a second engine in the same process (an isolate)
+   * gets no input.
+   *
+   * @param event  `"line"`, `"key"` or `"close"`.
+   * @param callback  Receives the line text or the {@link Key}; nothing for
+   *                  `"close"`.
+   * @returns An unsubscribe function.
+   */
+  export function on(event: "line", callback: (line: string) => void): () => void
+  export function on(event: "key", callback: (key: Key) => void): () => void
+  export function on(event: "close", callback: () => void): () => void
+  /**
+   * Like {@link on}, but the listener fires at most once and then unsubscribes.
+   */
+  export function once(event: "line", callback: (line: string) => void): () => void
+  export function once(event: "key", callback: (key: Key) => void): () => void
+  export function once(event: "close", callback: () => void): () => void
+  /**
+   * Switch the terminal's raw mode: no echo, no line editing, no signal keys
+   * (Ctrl-C arrives as a key), and stdin delivers `"key"` events instead of
+   * `"line"`s. The change applies from the next read: a line the terminal
+   * is already collecting is delivered as a line. Turn it off before
+   * exiting; the runtime also restores the terminal on exit and on a panic,
+   * but not on a kill. Throws when stdin is not a terminal.
+   *
+   * While raw, `console.log` output still breaks lines correctly (the
+   * runtime writes "\r\n"); your own {@link write} calls must use "\r\n".
+   */
+  export function setRawMode(on: boolean): void
+  /**
+   * Write `text` to stdout as is and flush: no newline appended, unlike
+   * `console.log`. What a prompt needs.
+   */
+  export function write(text: string): void
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",

package/standards/crypto.d.ts

@@ -0,0 +1,18 @@
+// crypto. The Web Crypto surface flux provides: `subtle.digest` only. No key
+// material, no encryption, no random: an app hashes bytes (content
+// addressing, integrity checks) and the rest of the standard waits for a need.
+
+interface SubtleCrypto {
+  /**
+   * Hash `data` (a Uint8Array or ArrayBuffer) with `algorithm`, one of
+   * "SHA-256", "SHA-384", "SHA-512" (as a string or `{ name }`). Resolves to
+   * the digest as an ArrayBuffer. Other algorithms (SHA-1 included) reject.
+   */
+  digest(algorithm: string | { name: string }, data: Uint8Array | ArrayBuffer): Promise<ArrayBuffer>
+}
+
+interface Crypto {
+  readonly subtle: SubtleCrypto
+}
+
+declare var crypto: Crypto