@solidrt/flux-types 0.0.60 → 0.0.61

package/gui/gpu.d.ts

@@ -1104,6 +1104,11 @@ declare module "flux:gpu" {
       /** Draw the instance records in key order (see {@link InstanceOrder}). */
       instanceOrder?: InstanceOrder
       before?: DrawId
+      /** Debug name reported beside the entry in the resource inventory
+       * (`/gpu`, `get_gpu_resources`), so a draw is found by what it draws
+       * (a mesh's geometry label, a model part's name) rather than by
+       * matching counts. Free-form; the GPU never sees it. */
+      label?: string
     } & (DrawRange | (IndexBinding & IndexRange)),
   ): DrawId
   /**

package/gui/rendertree.d.ts

@@ -152,6 +152,34 @@ declare module "flux:rendertree" {
    * comes back on the sticky "pointerLock" bus event.
    */
   export function setPointerLock(locked: boolean): void
+  /** One image of a cursor frame: straight-alpha RGBA8, `width * height * 4` bytes. */
+  export interface CursorImage {
+    data: Uint8Array
+    width: number
+    height: number
+  }
+  /**
+   * One frame of a cursor. `images[0]` is the 1x representation; the rest
+   * are HiDPI alternates the platform picks by their size ratio to it (a
+   * 64x64 alternate of a 32x32 base serves 2x displays). `duration` is the
+   * frame's show time in milliseconds for an animated cursor (0 holds the
+   * frame, ending a one-shot animation on it); a static cursor is one frame.
+   */
+  export interface CursorFrame {
+    images: CursorImage[]
+    duration: number
+  }
+  /**
+   * Register an image cursor and return the handle an element's `cursor`
+   * property takes. `hotX`/`hotY` is the click point in the 1x image's
+   * pixels. Every frame must have the first frame's 1x size. Throws on an
+   * empty, mismatched or out-of-bounds payload; a platform that cannot
+   * create the cursor logs and shows the default shape for the handle.
+   * Handles die with the engine; drop one earlier with `dropCursor`.
+   */
+  export function createCursor(frames: CursorFrame[], hotX: number, hotY: number): number
+  /** Destroy a registered cursor; if it is showing, the default cursor returns. */
+  export function dropCursor(id: number): void
   /** Request that a frame be rendered soon (coalesced by the demand-driven loop). */
   export function requestFrame(): void
   /**

package/gui/spatial.d.ts

@@ -161,18 +161,62 @@ declare module "flux:spatial" {
    */
   export function writeTransform(node: NodeId, transform: Float32Array): void
   export function setVisible(node: NodeId, visible: boolean): void
+  /** What a draw sink writes and where it sorts (bindDraw). */
+  export type BindDrawOptions = {
+    /** The entry declares `uModel`: the flush writes the node's world
+     * matrix there. Default true; false binds the entry for its visibility
+     * switch and its sort key alone (a background pinned to a root). */
+    params?: boolean
+    /** Write `uNormal`, the world matrix's inverse-transpose, too. */
+    normal?: boolean
+    /** Write the LOD cross-fade band into `uLodFade` (see setLod). */
+    fade?: boolean
+    /** The instanceCount the entry is switched on with; default 1. */
+    count?: number
+    /** The sort queue on a sorted target (setDrawSort): 0 background,
+     * 1 opaque (the default), 2 cutout, 3 transparent. */
+    queue?: number
+    /** Ascending above depth inside the queue; default 0. */
+    renderOrder?: number
+  }
   /**
    * Route the node's world matrix to one draw entry's `uModel` (and
-   * `uNormal`, the inverse-transpose, when `normal`; and with `fade` the
-   * LOD cross-fade band into `uLodFade`, see setLod). Validated like
+   * `uNormal` and `uLodFade` when the options ask). 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.
+   * A node's draw sinks share one sort key: a bind keys every sink of
+   * the node with its `queue` and `renderOrder`.
+   */
+  export function bindDraw(node: NodeId, target: TextureId, draw: DrawId, opts?: BindDrawOptions): void
+  /** Re-key the node's draw sinks without a rebind (a renderOrder
+   * change): the queue codes of BindDrawOptions, and the renderOrder
+   * above depth inside the queue. Sorted targets re-sort at the next
+   * flush. */
+  export function setDrawKey(node: NodeId, queue: number, renderOrder: number): void
+  /**
+   * Whether the core orders the target's bound draw entries by queue:
+   * background entries first whatever their depth, opaque entries
+   * front-to-back by a logarithmic distance bucket of their world box
+   * center (four buckets per doubling, so a small camera move changes
+   * nothing), cutout entries (an alpha-tested fragment, no early-z) after
+   * them the same way, transparent entries last back-to-front by exact
+   * depth along the view, `renderOrder` above depth inside each queue,
+   * bind order breaking ties.
+   * Measured against the target's view (setView), so a target
+   * without one waits for it. Every flush that bound, unbound, re-keyed or
+   * moved an entry's node, or moved the view past the nearest opaque
+   * center's bucket margin, re-keys and issues one setDrawOrder when the
+   * permutation changed; entries the core does not bind draw first, before
+   * the background queue. Off (the default) writes no order: a shadow tile, an
+   * override-material view, a 2d target. Enabling a target already on
+   * re-issues its order at the next flush: call it after adding an
+   * unbound entry.
    */
-  export function bindDraw(node: NodeId, target: TextureId, draw: DrawId, normal: boolean, count: number, fade: boolean): void
+  export function setDrawSort(target: TextureId, enabled: boolean): 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
@@ -212,14 +256,20 @@ declare module "flux:spatial" {
    * follows the flush; hidden nodes stay in and are skipped at query time. */
   export function setBounds(node: NodeId, bounds: Float32Array | null): void
   /**
-   * The clip volume gating every draw sink on `target`: its view-projection
-   * (Float32Array of 16, column-major), or null to lift it. An entry whose
-   * node box (grown by its cull margin) falls wholly outside reads
-   * instanceCount 0 like a hidden node, and comes back with a fresh params
-   * write. Nodes without a box, or with culling off, are never gated. Read
-   * at flush: set it before the flush that should see it.
+   * What `target` sees: its view (world to camera) and projection
+   * (camera to clip), two Float32Arrays of 16, column-major - or null to
+   * forget the target (its view, LOD bias and LOD reference). The core
+   * derives everything a target measures with from them: the clip volume
+   * gating every draw sink on it (an entry whose node box, grown by its
+   * cull margin, falls wholly outside reads instanceCount 0 like a hidden
+   * node, and comes back with a fresh params write; nodes without a box,
+   * or with culling off, are never gated), the LOD view (eye, forward,
+   * vertical focal factor, orthographic or not - setLod) and the view the
+   * draw sort measures depth against (setDrawSort). Read at flush: set it
+   * before the flush that should see it, on every camera move.
    */
-  export function setFrustum(target: TextureId, viewProj: Float32Array | null): void
+  export function setView(target: TextureId, view: Float32Array, proj: Float32Array): void
+  export function setView(target: TextureId, view: null): void
   /** Whether frustums gate the node's draw sinks (default true), and the
    * world-unit margin the test grows its box by (default 0). */
   export function setCull(node: NodeId, enabled: boolean, margin: number): void
@@ -243,7 +293,7 @@ declare module "flux:spatial" {
    * `levels` nearest first with strictly descending sizes, all naming a
    * child or none at all (never mixed); the last level's size is the cull
    * threshold, 0 for never culled. After the walk each flush measures the
-   * group on every target with a LOD view (setLodView) - the sphere
+   * group on every target with a view (setView) - the sphere
    * around its own box, else around its levels' world boxes - and gates
    * the draw sinks under each level to the level that target picked, so
    * a thousand groups cost no JS per frame. `fade` widens each threshold
@@ -257,18 +307,23 @@ declare module "flux:spatial" {
    * picked its level. A target with no LOD view draws the first level.
    */
   export function setLod(node: NodeId, levels: LodLevel[], fade: number, reference?: TextureId): void
-  /**
-   * What `target` measures projected size with: a Float32Array of 6 - the
-   * eye position xyz, the projection's vertical focal factor (the
-   * magnitude of `proj[5]`: `1 / tan(fov / 2)` for a perspective
-   * projection, `2 / (top - bottom)` for an orthographic one - positive,
-   * whatever clip flip the projection bakes in), 1 for orthographic else
-   * 0, and a bias every
-   * measured size is multiplied by (below 1 switches sooner) - or null to
-   * lift it. Read at flush, like setFrustum; set it beside the frustum on
-   * every camera move.
-   */
-  export function setLodView(target: TextureId, view: Float32Array | null): void
+  /** The bias every projected size measured on `target` is multiplied by
+   * (default 1; below 1 switches levels sooner, a quality knob). Kept
+   * across setView writes; a target measuring by a reference takes the
+   * reference's. */
+  export function setLodBias(target: TextureId, bias: number): void
+  /** The level a LOD group (setLod) draws on `target`: the index into its
+   * levels, the level count when culled past the last threshold, null
+   * before the target measured it. Throws for a node without levels. A
+   * population group's members pick per instance; this is the group's
+   * own pick. */
+  export function lodLevel(node: NodeId, target: TextureId): number | null
+  /** Make `target` measure projected size by `source`'s view instead of
+   * its own (null: its own again): a shadow tile culls by its light but
+   * draws the level the scene camera sees, so its shadow matches. Only the
+   * LOD measurement follows; culling and the draw sort stay the target's
+   * own. Set once; a source view move re-measures the target. */
+  export function setLodReference(target: TextureId, source: TextureId | null): void
   /**
    * A geometry's positions as the core keeps them, one copy shared by
    * every node that references it: the source of those nodes' local

package/gui/video.d.ts

@@ -3,8 +3,11 @@
 // a texture player's `texture` id is displayed with <texture>/<d-texture>,
 // and a richer Video component composes in a higher layer. A plane player
 // (Android) has no texture at all: the platform composites the decoded
-// picture fullscreen beneath the UI, off the frame loop entirely, and it
-// streams: its source may be a URL, read as it plays.
+// picture fullscreen beneath the UI. Both players run off the frame loop
+// (demux, decode, the clock, frame selection and audio on their own
+// threads; a texture player's frames are shown at the UI's cadence, the
+// way a browser's compositor shows a video's) and both stream: the source
+// may be a URL, read as it plays.
 
 declare module "flux:video" {
   import type { FluxFile } from "flux:fs"
@@ -41,9 +44,9 @@ declare module "flux:video" {
     /** Whether the file has a playable audio track. */
     hasAudio: boolean
     /**
-     * Whether `seek` does anything. False for a texture player, and for a
-     * source that cannot be read at an offset (an HTTP response without
-     * Range support); `seek` is then a no-op.
+     * Whether `seek` does anything. False for a source that cannot be read
+     * at an offset (an HTTP response without Range support); `seek` is
+     * then a no-op.
      */
     seekable: boolean
     /** Start or resume playback. */
@@ -58,7 +61,11 @@ declare module "flux:video" {
     seek(seconds: number): void
     /** Whether playback is running. */
     playing(): boolean
-    /** Presentation time of the displayed frame, in seconds. */
+    /**
+     * Presentation time of the displayed frame, in seconds: for a texture
+     * player the frame on screen (the one the compositor last latched),
+     * for a plane the frame last released to the surface.
+     */
     currentTime(): number
     /**
      * Whether the last frame has been displayed. A failure does not set
@@ -67,8 +74,7 @@ declare module "flux:video" {
     finished(): boolean
     /**
      * Whether playback is held for the source to catch up: playing, with
-     * the picture and the sound paused until enough is read ahead. Never
-     * true for a texture player.
+     * the picture and the sound paused until enough is read ahead.
      */
     buffering(): boolean
     /**
@@ -88,11 +94,15 @@ declare module "flux:video" {
     close(): void
   }
 
-  /** A texture player: frames land in a GPU texture on the UI's clock. */
+  /**
+   * A texture player: frames are decoded off the frame loop and shown in
+   * a GPU texture at the UI's cadence, each at the frame closest to its
+   * time.
+   */
   export type VideoPlayer = VideoTransport & {
     /**
-     * GPU texture id decoded frames are uploaded into (use as a texture
-     * source). Holds the current frame; black until playback starts.
+     * GPU texture id decoded frames land in (use as a texture source).
+     * Holds the current frame; black until playback starts.
      */
     texture: TextureId
   }
@@ -110,9 +120,8 @@ declare module "flux:video" {
    * A video source: a path resolved like file() paths (through the app's
    * assets in a packed app), an http: or https: URL, or a file() from
    * flux:fs (a packed asset is read out of the exe). Any other scheme
-   * throws. A URL plays on a plane only, and is read by the runtime
-   * directly: no disk cache, no dev-server proxying, so the device must
-   * reach the host itself.
+   * throws. A URL is read by the runtime directly: no disk cache, no
+   * dev-server proxying, so the device must reach the host itself.
    */
   export type VideoSource = string | FluxFile
 
@@ -121,8 +130,7 @@ declare module "flux:video" {
     present?: "texture"
     /**
      * Aborting it abandons the open: the promise rejects with the signal's
-     * reason and the source is closed. (A texture player opens at once;
-     * the signal matters for a plane's streamed open.)
+     * reason and the source is closed.
      */
     signal?: AbortSignal
   }
@@ -140,11 +148,11 @@ declare module "flux:video" {
    * audio plays, other audio tracks are ignored). Playback starts paused;
    * call `play()`. Rejects with a VideoError: "network" when the source
    * cannot be opened (or does not answer within the open timeout),
-   * "unsupported" when its codec is not played or a URL is given to a
-   * texture player, "no-plane" for `present: "plane"` on a platform without
-   * a video plane (Android only) or while another plane is open or opening.
-   * A plane open reads the header off the JS thread and resolves once the
-   * plane exists; a texture player opens at once.
+   * "unsupported" when its codec is not played, "no-plane" for
+   * `present: "plane"` on a platform without a video plane (Android only)
+   * or while another plane is open or opening. The header is read off the
+   * JS thread; the promise resolves once the player (and, for a plane, the
+   * plane) exists.
    *
    * Encode with `ffmpeg -c:v libvpx-vp9 -c:a libopus out.webm`; VP9 and
    * Opus are royalty-free, so both decoders ship on every platform.

package/modules/fs.d.ts

@@ -36,6 +36,15 @@ declare module "flux:fs" {
     append(data: string | Uint8Array): Promise<void>
     /** Remove the file. A missing file is not an error. */
     remove(): Promise<void>
+    /**
+     * Move the file to `to` (the OS rename: an existing target is replaced,
+     * a missing source rejects, a move across filesystems rejects rather
+     * than copying, and `to`'s parent directories are not created). The
+     * atomic-write step: write a temporary file, then rename it over the
+     * real one. This handle keeps its old `path`; open the new one with
+     * `file(to)`.
+     */
+    rename(to: string): Promise<void>
   }
 
   /**
@@ -77,9 +86,11 @@ declare module "flux:fs" {
   /**
    * Reference a file by path. Lazy: no I/O happens until a method is called.
    *
-   * Relative paths resolve against the process cwd. Exception: in a SolidRT
-   * app running an installed version, paths under `assets/` resolve read-only
-   * into that version's immutable assets tree (writes there error).
+   * Relative paths resolve against the process cwd, which in a SolidRT app
+   * is the app's per-app persistent storage folder (kept across updates), so
+   * `flux.file("notes.json")` is the app's own durable file. Exception: in a
+   * SolidRT app running an installed version, paths under `assets/` resolve
+   * read-only into that version's immutable assets tree (writes there error).
    *
    * @param path  Path to the file.
    */

package/modules/sqlite.d.ts

@@ -38,7 +38,10 @@ declare module "flux:sqlite" {
     /**
      * Open a connection to the database at `path`.
      *
-     * @param path  Database file path.
+     * @param path  Database file path. A relative path resolves against the
+     *   process cwd, which in a SolidRT app is the app's per-app persistent
+     *   storage folder (kept across updates), so `"app.db"` is the app's own
+     *   durable database.
      * @param mode  Open mode; defaults to "ro".
      */
     static open(path: string, mode?: OpenMode): Promise<Database>

package/package.json

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

package/standards/time.d.ts

@@ -1,6 +1,5 @@
 // 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.
+// from the browser in one way: no extra callback arguments are forwarded.
 //
 // In a GUI runtime the timers are FRAME-QUANTIZED but WALL-ACCURATE: a
 // deadline is measured against the real clock from the moment of
@@ -18,17 +17,18 @@
 // servers) keeps ordinary wall-clock timers.
 
 /**
- * Run `callback` after at least `ms` milliseconds. Returns a timer id for
+ * Run `callback` after at least `ms` milliseconds (default 0, as on the
+ * web: the next frame in a GUI runtime). Returns a timer id for
  * {@link clearTimeout}.
  */
-declare function setTimeout(callback: () => void, ms: number): number
+declare function setTimeout(callback: () => void, ms?: number): number
 /** Cancel a pending timeout. Unknown or missing ids are ignored. */
 declare function clearTimeout(id?: number): void
 /**
- * Run `callback` every `ms` milliseconds. Returns a timer id for
- * {@link clearInterval}.
+ * Run `callback` every `ms` milliseconds (default 0: once per frame in a
+ * GUI runtime). Returns a timer id for {@link clearInterval}.
  */
-declare function setInterval(callback: () => void, ms: number): number
+declare function setInterval(callback: () => void, ms?: number): number
 /** Cancel a running interval. Unknown or missing ids are ignored. */
 declare function clearInterval(id?: number): void
 /**