@solidrt/flux-types 0.0.50 → 0.0.52

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 & {})
@@ -14,6 +15,27 @@ declare module "flux:rendertree" {
     lineHeight?: number
     /** measureText only. */
     maxLines?: number
+    /** prepareText only: also report each unit's {@link TextUnit.carets}. */
+    carets?: boolean
+    /**
+     * prepareText only: styled ranges over the text, in JS string offsets,
+     * sorted and disjoint (text between them is in the base font). Each
+     * overrides the font options it names. A wrap unit crossing a range
+     * boundary comes back as one {@link TextUnit} per range, the pieces
+     * after the first `glue`d to it. Throws on an invalid range.
+     */
+    runs?: TextRunRange[]
+  }
+
+  /** One styled range for {@link MeasureTextOptions.runs}. */
+  export interface TextRunRange {
+    start: number
+    end: number
+    fontFamily?: "sans" | "serif" | "mono" | (string & {})
+    fontSize?: number
+    fontStyle?: "normal" | "italic"
+    fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    lineHeight?: number
   }
 
   /**
@@ -35,6 +57,17 @@ declare module "flux:rendertree" {
     descent: number
     /** The unit ends at a hard line break (newline). */
     hardBreak: boolean
+    /** A continuation piece of the previous unit (it crossed a `runs` boundary): a line never breaks before it. */
+    glue: boolean
+    /** Index into `runs` of the range this piece was shaped in; absent for the base font. */
+    run?: number
+    /**
+     * With `carets`: the caret positions inside the unit, one per grapheme
+     * cluster boundary from its start (`offset` = start, x 0) to the end of
+     * its shaped text (before any break characters), in order. `offset` is
+     * into the prepared text, `x` from the unit's pen position.
+     */
+    carets?: { offset: number, x: number }[]
   }
 
   /** The wrap units of a text in one font, shaped once. Plain data; layout is arithmetic over `units`. */
@@ -45,24 +78,41 @@ declare module "flux:rendertree" {
 
   /** Create the window root node with the given id. */
   export function createRoot(id: number): void
-  /** Create a node of `kind` (the primitive element name) with the given id. */
+  /**
+   * 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). */
   export function insertNode(parentId: number, nodeId: number, anchorId?: number): void
   /**
    * Unlink `nodeId` from `parentId` but keep its subtree alive, so it can be
    * re-inserted elsewhere (a move). Mirrors DOM removeChild. Pair with
-   * {@link destroyNode} once the node is confirmed dead.
+   * {@link destroyNode} once the node is confirmed dead. Divergence: a node
+   * whose `transition` declares `exit` values stays linked and animates them
+   * first; the unlink happens when the exit settles, and a re-insert before
+   * then abandons it (moves never play removal animations).
    */
   export function detachNode(parentId: number, nodeId: number): void
-  /** Free `nodeId` and its whole subtree. Call after {@link detachNode}. */
+  /**
+   * Free `nodeId` and its whole subtree. Call after {@link detachNode}. A
+   * node mid-exit is freed when its exit animation settles instead.
+   */
   export function destroyNode(nodeId: number): void
   /**
    * 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.
+   * `null`/`undefined` resets the property to its default (its value before
+   * anything was set, per element kind; on a span, back to inheriting from
+   * the paragraph). Content props (`text`, `d`) still require a value.
+   * 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
   /**
@@ -87,6 +137,13 @@ declare module "flux:rendertree" {
   }
   /** Enable or disable text-input capture / the on-screen keyboard. */
   export function setTextInputActive(active: boolean, hints?: TextInputHints): void
+  /**
+   * Enter or leave relative mouse mode (pointer lock): the cursor hides and
+   * confines to the window, absolute pointer positions freeze, and mouse
+   * motion keeps reporting through movementX/movementY. The applied state
+   * comes back on the sticky "pointerLock" bus event.
+   */
+  export function setPointerLock(locked: boolean): void
   /** Request that a frame be rendered soon (coalesced by the demand-driven loop). */
   export function requestFrame(): void
   /**
@@ -121,4 +178,30 @@ 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
+   * also accepts alongside plain CSS strings). Throws on an invalid string.
+   */
+  export function parseColor(color: string): number
+  /**
+   * Mixes two CSS colors in oklab; `t` is the fraction of `b` (0 = pure
+   * `a`, 1 = pure `b`). Returns a hex string, with an alpha byte only when
+   * the mix is translucent.
+   */
+  export function mixColors(a: string, b: string, t: number): string
+  /** Perceived brightness of a CSS color, 0 (black) to 1 (white), YIQ-weighted. */
+  export function brightness(color: string): number
 }

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,13 +16,15 @@
 
 // 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" />
 /// <reference path="./standards/base64.d.ts" />
 /// <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
@@ -33,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/isolate.d.ts

@@ -22,6 +22,14 @@ declare module "flux:isolate" {
   type IsolateOptions = {
     /** The child's `flux:process` `argv`. Default `[]`. */
     args?: string[]
+    /**
+     * Heap limit in bytes for the child runtime. Once reached, allocations in
+     * the child fail with an out-of-memory error where they happen instead of
+     * growing the process; an exit this causes is observable via `exited`.
+     * Applies to this child only (not to isolates it spawns itself). Default:
+     * unlimited.
+     */
+    memoryLimit?: number
   }
 
   /**
@@ -36,8 +44,10 @@ declare module "flux:isolate" {
       ? 0 extends 1 & R // an `any` result (untyped module) is a plain call, not a stream
         ? (...args: A) => Promise<any>
         : R extends AsyncIterable<infer Y>
-          ? (...args: A) => AsyncIterableIterator<Y>
-          : (...args: A) => Promise<Awaited<R>>
+          ? (...args: A | [...A, AbortSignal]) => AsyncIterableIterator<Y>
+          : R extends Generator<any, any, any> // sync generators do not stream: the call rejects
+            ? never
+            : (...args: A | [...A, AbortSignal]) => Promise<Awaited<R>>
       : never
   } & {
     /**
@@ -46,28 +56,58 @@ declare module "flux:isolate" {
      * anything never spawned.
      */
     terminate(): void
+    /**
+     * Settles once the child is gone: with the uncaught error that ended it,
+     * or `null` after `terminate()` or a clean end. Reading `exited` is a
+     * first use (it starts the child like a call does) and keeps the runtime
+     * watching the child - the loop stays open until the child exits, so an
+     * exit is noticed with no call in flight. Each read returns an
+     * equivalent promise.
+     */
+    readonly exited: Promise<string | null>
   }
 
   /**
    * A handle on an isolate module: a `"use isolate"` module in a SolidRT
    * project (id = its path relative to the source root, without extension),
-   * or `<id>.js` next to the entry under standalone flux. Each property is
+   * or `isolates/<id>.bin`/`.js` next to the entry under standalone flux. Each property is
    * an async function that runs the export of that name in a second runtime
    * on its own thread (own heap, own event loop, the non-gui `flux:*`
    * modules). Arguments and results are copied ({@link Sendable}).
    *
-   * The child starts on the first call and lives until `terminate()` or the
-   * parent's end; module state persists between calls; each `isolate()` call
-   * is its own instance. Calls start in call order and run concurrently, as
+   * The child starts on first use (a call, or reading `exited`) and lives
+   * until `terminate()` or the parent's end; module state persists between
+   * calls; each `isolate()` call is its own instance. Calls start in call order and run concurrently, as
    * the same functions would in-process: a sync export runs to completion
    * before anything else (one thread), an async export lets other calls and
    * stream steps run at each `await`; an export that must not interleave with
    * itself serialises inside the module. A throw in the export rejects that
-   * call (a throw in a generator rejects the pending step); an uncaught error
-   * that ends the child rejects pending and later calls with a message naming
-   * it. Awaiting a stream call rejects; iterating a plain call rejects. An
+   * call (a throw in a generator rejects the pending step) with the error
+   * rebuilt from its data: `name`, `message` and `stack` carry over, `e
+   * instanceof RangeError` holds for the standard error types (a custom error
+   * class arrives as an `Error` with its `name`), and the `cause` chain
+   * carries over - each cause another rebuilt error or a {@link Sendable}
+   * value (an unsendable cause is dropped; the chain is capped). A thrown
+   * non-Error rejects with the thrown value itself when it is sendable, else
+   * with an `Error` describing it. An uncaught
+   * error that ends the child rejects pending and later calls with a message
+   * naming it. Awaiting a stream call rejects; iterating a plain call rejects. An
    * open stream keeps both runtimes alive until it ends, `break`s, or the
-   * child is terminated. Reserved names: `terminate`, `then`.
+   * child is terminated. A sync generator export rejects when called: only
+   * async generators stream.
+   *
+   * An `AbortSignal` among a call's arguments (anywhere in the list; at most
+   * one, more throw) is consumed as the call's signal rather than sent: the
+   * export sees only the other arguments. On a plain call, aborting stops
+   * the waiting - the call rejects with `signal.reason` and the eventual
+   * result is dropped - but does not interrupt the export; interrupting is
+   * `terminate()`'s job. On a stream, aborting acts as `return()`: the
+   * generator ends in the isolate (its `finally` runs) and the `for await`
+   * loop finishes cleanly, like a `break` from outside it. A call on an
+   * already-aborted signal rejects without sending anything (or starting the
+   * child).
+   *
+   * Reserved names: `terminate`, `exited`, `then`.
    */
   export function isolate<T = Record<string, (...args: any[]) => any>>(id: string, opts?: IsolateOptions): Isolated<T>
 }

package/modules/net.d.ts

@@ -43,6 +43,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/sqlite.d.ts

@@ -1,12 +1,12 @@
 declare module "flux:sqlite" {
   /** Values accepted as bound parameters. booleans bind as 0/1. */
-  type SqlParam = null | boolean | number | string | Uint8Array
+  export type SqlParam = null | boolean | number | string | Uint8Array
   /** Values returned in result rows. BLOB comes back as Uint8Array. */
-  type SqlValue = null | number | string | Uint8Array
-  type Row = Record<string, SqlValue>
+  export type SqlValue = null | number | string | Uint8Array
+  export type Row = Record<string, SqlValue>
 
   /** The outcome of a write. */
-  type RunResult = { changes: number; lastInsertRowid: number }
+  export type RunResult = { changes: number; lastInsertRowid: number }
 
   /**
    * A reusable prepared statement. Created with {@link Database.query}; its
@@ -19,13 +19,20 @@ declare module "flux:sqlite" {
     get(params?: SqlParam[]): Promise<Row | undefined>
     /** Run the statement as a write and resolve to its {@link RunResult}. */
     run(params?: SqlParam[]): Promise<RunResult>
+    /**
+     * The tables this statement reads, sorted (SQLite's authorizer, captured
+     * during a compile; the statement is never run). Includes tables reached
+     * through views and subqueries. Pair with {@link Database.onWrite} to know
+     * when a re-read could return different rows.
+     */
+    tables(): Promise<string[]>
   }
 
   /**
    * Open mode: "ro" (default, read-only, must exist), "rw" (read-write, must
    * exist), "rw+" (read-write, create if missing).
    */
-  type OpenMode = "ro" | "rw" | "rw+"
+  export type OpenMode = "ro" | "rw" | "rw+"
 
   export class Database {
     /**
@@ -47,6 +54,21 @@ declare module "flux:sqlite" {
      * must be writes/DDL. Cannot branch on intermediate results.
      */
     transaction(statements: [string, SqlParam[]?][]): Promise<RunResult[]>
+    /**
+     * Subscribe to writes on this connection. After each command that changed
+     * rows, `callback` gets one call with the sorted names of the tables
+     * touched (SQLite's update hook, so trigger and cascade writes are
+     * included). Returns an unsubscribe function.
+     *
+     * Contract: only THIS connection's writes are seen (another connection or
+     * process writing the same file does not report); SQLite does not fire
+     * the hook for WITHOUT ROWID tables; a rolled-back transaction may still
+     * report its tables (a spurious re-read, never a stale one). A full-table
+     * `DELETE FROM t` reports correctly: the connection disables SQLite's
+     * truncate optimization, trading row-by-row deletion for a hook that
+     * cannot be silently skipped.
+     */
+    onWrite(callback: (tables: string[]) => void): () => void
     /** Close the connection. */
     close(): Promise<void>
   }