@solidrt/flux-types 0.0.59 → 0.0.61

package/gui/audio.d.ts

@@ -144,9 +144,10 @@ declare module "flux:audio" {
   /**
    * Open a clip for streaming: it is decoded on demand instead of loaded fully
    * into memory, so a large track needs little RAM. Takes a `file()` from
-   * `flux:fs` (not a path), so the source rides the `file()` proxy override - a
-   * dev-server-proxied file streams from the server. Play the result as a single
-   * playback; do not overlap a stream with itself. Call `unload()` when done.
+   * `flux:fs` (not a path), read from local storage like any `file()` (the
+   * app's assets in a packed app); there is no network streaming. Play the
+   * result as a single playback; do not overlap a stream with itself. Call
+   * `unload()` when done.
    */
   export function stream(source: ReturnType<typeof import("flux:fs").file>): Clip
   /**

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

@@ -1,49 +1,162 @@
 // Video playback (gui-enabled runtime only). The imperative primitive;
 // @solidrt/core wraps it with SolidJS reactivity. There is no video element:
-// the player's `texture` id is displayed with <texture>/<d-texture>, and a
-// richer Video component composes in a higher layer.
+// 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. 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"
   import type { TextureId } from "flux:gpu"
 
-  /** An opened video: the frame texture plus controls bound to it. */
-  type VideoPlayer = {
-    /**
-     * GPU texture id decoded frames are uploaded into (use as a texture
-     * source). Holds the current frame; black until playback starts.
-     */
-    texture: TextureId
-    /** Frame width in pixels. */
+  /**
+   * What went wrong with a stream, for the app to key on:
+   * - "network": the source could not be opened or stopped delivering (an
+   *   unreachable or failing server, an unreadable file, a truncated body);
+   * - "decode": the bytes are not a stream the decoders can follow;
+   * - "unsupported": a stream, codec or feature this player does not play;
+   * - "no-plane": no video plane (not on this platform, or one is open).
+   * An app falling back from a plane to a texture keys on "no-plane" only:
+   * a network error would fail the texture the same way.
+   */
+  export type VideoErrorKind = "network" | "decode" | "unsupported" | "no-plane"
+
+  /** The Error `open` rejects with and `error()` returns. */
+  export interface VideoError extends Error {
+    kind: VideoErrorKind
+  }
+
+  /** Controls and facts shared by both kinds of player. */
+  export type VideoTransport = {
+    /** Frame width in pixels, at open. */
     width: number
-    /** Frame height in pixels. */
+    /** Frame height in pixels, at open. */
     height: number
-    /** Duration in seconds. */
-    duration: number
+    /**
+     * Duration in seconds; undefined when the source has no known end (a
+     * live stream, a container written to a pipe).
+     */
+    duration: number | undefined
     /** Whether the file has a playable audio track. */
     hasAudio: boolean
+    /**
+     * 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. */
     play(): void
     /** Pause playback (the current frame stays displayed). */
     pause(): void
+    /**
+     * Seek to a time in seconds. Lands on the frame at that time (decoding
+     * from the preceding keyframe); while paused the target frame is shown.
+     * A no-op when `seekable` is false.
+     */
+    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. */
+    /**
+     * Whether the last frame has been displayed. A failure does not set
+     * it: see `error`.
+     */
     finished(): boolean
-    /** Stop playback and release the decoder, texture, and audio sink. */
+    /**
+     * Whether playback is held for the source to catch up: playing, with
+     * the picture and the sound paused until enough is read ahead.
+     */
+    buffering(): boolean
+    /**
+     * The failure that stopped playback, if one did: the reader could not
+     * read on, or the decoder gave up. Playback stops where it was
+     * (`playing()` goes false, the last frame stays up); a `seek` retries
+     * the source. The same object `failed` resolves with.
+     */
+    error(): VideoError | undefined
+    /**
+     * Resolves with the failure that stops playback, once, or with
+     * undefined when the player closes without one. What a reactive layer
+     * watches instead of polling `error()`.
+     */
+    failed: Promise<VideoError | undefined>
+    /** Stop playback and release everything the player holds. */
     close(): void
   }
 
   /**
-   * Open a video file (MP4 with 8-bit 4:2:0 VP9 video, i.e. profile 0;
-   * AAC audio plays, other audio tracks are ignored). The path resolves
-   * like file() paths (through the app's assets in a packed app). Playback
-   * starts paused; call `play()`. Rejects when the file is unreadable or
-   * its codec unsupported.
+   * 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 land in (use as a texture source).
+     * Holds the current frame; black until playback starts.
+     */
+    texture: TextureId
+  }
+
+  /**
+   * A plane player: the decoder renders into the platform's own video
+   * surface, fullscreen beneath the UI, on the video's clock. Exists from
+   * open until close; one at a time. The UI draws over it wherever it
+   * paints, and the window's uncovered pixels show the video. Its audio
+   * track plays on the default output, in sync with the picture.
+   */
+  export type VideoPlane = VideoTransport
+
+  /**
+   * 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 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
+
+  export type VideoOpenOptions = {
+    /** Where the picture goes: a texture (default) or the platform's video plane. */
+    present?: "texture"
+    /**
+     * Aborting it abandons the open: the promise rejects with the signal's
+     * reason and the source is closed.
+     */
+    signal?: AbortSignal
+  }
+
+  export type VideoPlaneOptions = {
+    present: "plane"
+    /** How the picture fits the window: letterboxed (default) or cropped to fill. */
+    fit?: "contain" | "cover"
+    /** Aborting it abandons the open (see VideoOpenOptions). */
+    signal?: AbortSignal
+  }
+
+  /**
+   * Open a video (WebM with 8-bit 4:2:0 VP9 video, i.e. profile 0; Opus
+   * 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, "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 aac out.mp4`; VP9 is
-   * royalty-free, so the decoder ships on every platform.
+   * 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.
    */
-  export function open(path: string): Promise<VideoPlayer>
+  export function open(source: VideoSource, options?: VideoOpenOptions): Promise<VideoPlayer>
+  export function open(source: VideoSource, options: VideoPlaneOptions): Promise<VideoPlane>
 }

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.59",
+  "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
 /**