@solidrt/flux-types 0.0.48 → 0.0.49

package/gui/rendertree.d.ts

@@ -61,9 +61,11 @@ declare module "flux:rendertree" {
   /** Request that a frame be rendered soon (coalesced by the demand-driven loop). */
   export function requestFrame(): void
   /**
-   * Lay out, paint and submit the whole tree to the screen now (one frame). The
-   * direct draw path for a flux + alloy app; requestFrame only schedules a
-   * future frame and leaves the actual draw to the runner.
+   * Put the current tree on screen now (one frame). The direct draw path for
+   * a flux + alloy app; requestFrame only schedules a future frame and leaves
+   * the actual draw to the runner. When nothing changed since the last call
+   * the retained frame is re-presented instead of laid out and painted again;
+   * changed texture contents (uploads, camera frames) still show either way.
    */
   export function render(): void
   /**

package/gui/video.d.ts

@@ -0,0 +1,48 @@
+// 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.
+
+declare module "flux:video" {
+  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. */
+    width: number
+    /** Frame height in pixels. */
+    height: number
+    /** Duration in seconds. */
+    duration: number
+    /** Whether the file has a playable audio track. */
+    hasAudio: boolean
+    /** Start or resume playback. */
+    play(): void
+    /** Pause playback (the current frame stays displayed). */
+    pause(): void
+    /** Whether playback is running. */
+    playing(): boolean
+    /** Presentation time of the displayed frame, in seconds. */
+    currentTime(): number
+    /** Whether the last frame has been displayed. */
+    finished(): boolean
+    /** Stop playback and release the decoder, texture, and audio sink. */
+    close(): void
+  }
+
+  /**
+   * Open a video file (MP4 with H.264 video; 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.
+   *
+   * The built-in software decoder does not decode B-frames; encode dev
+   * content with `-bf 0` until the platform hardware decoders land.
+   */
+  export function open(path: string): Promise<VideoPlayer>
+}

package/index.d.ts

@@ -11,6 +11,7 @@
 /// <reference path="./modules/mdns.d.ts" />
 /// <reference path="./modules/wasm.d.ts" />
 /// <reference path="./modules/ffi.d.ts" />
+/// <reference path="./modules/isolate.d.ts" />
 
 // 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
@@ -32,6 +33,7 @@
 /// <reference path="./gui/microphone.d.ts" />
 /// <reference path="./gui/audio.d.ts" />
 /// <reference path="./gui/gpu.d.ts" />
+/// <reference path="./gui/video.d.ts" />
 /// <reference path="./gui/raf.d.ts" />
 
 declare let Flux: {

package/modules/ffi.d.ts

@@ -5,12 +5,26 @@ declare module "flux:ffi" {
    * loss). A number is also accepted where an i64 or ptr is expected.
    */
   type FfiValue = number | bigint
+  /**
+   * What a `symbols.*` call accepts per argument. Where a `ptr` is declared,
+   * an ArrayBuffer or typed array may be passed instead of an address: its
+   * data pointer (view offset respected) is handed to the native call and the
+   * buffer stays valid for the call's duration, so native code may read from
+   * and write into it (out-parameters, result buffers). Do not keep such an
+   * address past the call. A detached buffer throws.
+   */
+  type FfiArg = FfiValue | ArrayBuffer | ArrayBufferView
   type FfiTypeName = "i32" | "i64" | "f32" | "f64" | "ptr"
 
-  /** One symbol declaration. `returns` defaults to "void". */
+  /**
+   * One symbol declaration. `returns` defaults to "void". A missing symbol
+   * fails the load unless `optional` is set, in which case its `symbols`
+   * entry is `undefined` (test for it before calling).
+   */
   type SymbolDecl = {
     args: FfiTypeName[]
     returns?: FfiTypeName | "void"
+    optional?: boolean
   }
 
   /** The symbols to resolve at load time, keyed by exported name. */
@@ -19,7 +33,9 @@ declare module "flux:ffi" {
   /**
    * A JS function backing a minted C function pointer. Called synchronously
    * while a `symbols.*` call is on the stack; its return value is coerced to
-   * the callback's declared result type ("void" ignores it). A throw cannot
+   * the callback's declared result type ("void" ignores it). Unlike a call
+   * argument, a callback may not return a buffer as a ptr (the address would
+   * dangle once the callback returns). A throw cannot
    * abort the native frame: the callback returns zeroes, the native call runs
    * to completion, and the exception is rethrown after it returns.
    */
@@ -27,7 +43,8 @@ declare module "flux:ffi" {
 
   /**
    * A native shared library. The native counterpart of `flux:wasm`'s Module:
-   * declare what you need up front, every declared symbol must resolve.
+   * declare what you need up front, every declared symbol must resolve
+   * (unless marked optional).
    *
    * There is NO sandbox: the library runs with full process rights, loading
    * runs its constructors, and a declared signature that does not match the
@@ -37,14 +54,15 @@ declare module "flux:ffi" {
     /**
      * Load a shared library from bytes (e.g. a bundled binary import; written
      * to a temp file behind the scenes) or a filesystem path, and resolve
-     * every declared symbol. A missing symbol throws.
+     * every declared symbol. A missing symbol throws unless declared
+     * `optional`.
      */
     constructor(source: Uint8Array | ArrayBuffer | string, symbols: Symbols)
     /**
      * The declared symbols as bound JS functions, keyed by name. Destructure
      * once and reuse: the object is rebuilt on each access.
      */
-    readonly symbols: Record<string, (...args: FfiValue[]) => FfiValue | undefined>
+    readonly symbols: Record<string, (...args: FfiArg[]) => FfiValue | undefined>
     /**
      * Mint a C function pointer (returned as a BigInt address) that invokes
      * `func` when the library calls it during a `symbols.*` call. Callbacks
@@ -53,11 +71,22 @@ declare module "flux:ffi" {
      */
     callback(func: CallbackFunction, decl: SymbolDecl): bigint
     /**
-     * Copy `len` bytes out of process memory at `ptr`. No bounds checking is
-     * possible: a bad pointer is undefined behavior.
+     * Copy `count` elements out of process memory at `ptr`, in native byte
+     * order. Without `type` (or with "u8") that is `count` bytes as a
+     * Uint8Array; with an ffi type name it is `count` elements as the matching
+     * typed array. No bounds checking is possible: a bad pointer is undefined
+     * behavior.
+     */
+    readMemory(ptr: FfiValue, count: number, type?: "u8"): Uint8Array
+    readMemory(ptr: FfiValue, count: number, type: "i32"): Int32Array
+    readMemory(ptr: FfiValue, count: number, type: "i64"): BigInt64Array
+    readMemory(ptr: FfiValue, count: number, type: "f32"): Float32Array
+    readMemory(ptr: FfiValue, count: number, type: "f64"): Float64Array
+    readMemory(ptr: FfiValue, count: number, type: "ptr"): BigUint64Array
+    /**
+     * Copy the bytes of a typed array or ArrayBuffer into process memory at
+     * `ptr`. Same caveat as readMemory.
      */
-    readMemory(ptr: FfiValue, len: number): Uint8Array
-    /** Copy `bytes` into process memory at `ptr`. Same caveat as readMemory. */
-    writeMemory(ptr: FfiValue, bytes: Uint8Array | ArrayBuffer): void
+    writeMemory(ptr: FfiValue, bytes: ArrayBufferView | ArrayBuffer): void
   }
 }

package/modules/isolate.d.ts

@@ -0,0 +1,73 @@
+declare module "flux:isolate" {
+  /**
+   * A value that can cross to or from an isolate: null (undefined becomes
+   * null), boolean, number, string, any typed-array view (arrives as a copy
+   * of the same kind: a Float32Array stays a Float32Array) or ArrayBuffer
+   * (arrives as a Uint8Array copy), arrays and plain objects of these.
+   * Anything else (functions, class instances, Date/Map/Set, BigInt, symbols)
+   * throws a TypeError as an argument and rejects the call as a result.
+   */
+  type Sendable =
+    | null
+    | undefined
+    | boolean
+    | number
+    | string
+    | ArrayBuffer
+    | ArrayBufferView
+    | Sendable[]
+    | { [key: string]: Sendable }
+
+  /** Options for {@link isolate}. */
+  type IsolateOptions = {
+    /** The child's `flux:process` `argv`. Default `[]`. */
+    args?: string[]
+  }
+
+  /**
+   * The isolate view of a module's exports: every function returns a Promise
+   * of what it returns in the isolate (an async function stays as it is); an
+   * async generator returns a stream to iterate with `for await` (one item is
+   * pulled per step; `break` ends the generator in the isolate); plus
+   * `terminate()`. Non-function exports are not reachable.
+   */
+  type Isolated<T> = {
+    [K in keyof T as T[K] extends (...args: any[]) => any ? K : never]: T[K] extends (...args: infer A) => infer R
+      ? 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>>
+      : never
+  } & {
+    /**
+     * Kill the child now: busy JS is interrupted, the child runtime is
+     * dropped, pending and later calls reject. A handle that never called
+     * anything never spawned.
+     */
+    terminate(): void
+  }
+
+  /**
+   * 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
+   * 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 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
+   * open stream keeps both runtimes alive until it ends, `break`s, or the
+   * child is terminated. Reserved names: `terminate`, `then`.
+   */
+  export function isolate<T = Record<string, (...args: any[]) => any>>(id: string, opts?: IsolateOptions): Isolated<T>
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.48",
+  "version": "0.0.49",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",