@solidrt/flux-types 0.0.48 → 0.0.50

package/gui/gpu.d.ts

@@ -397,9 +397,25 @@ declare module "flux:gpu" {
    * depth-tested additive pass usually pairs with `depthWrite: false`; with
    * writes on, unsorted geometry depth-rejects its own later fragments and
    * accumulation becomes draw-order-dependent. That pairing is the app's to
-   * state - neither option implies the other.
-   */
-  export type BlendMode = "none" | "add"
+   * state - neither option implies the other. "multiply" scales
+   * (glBlendFunc(DST_COLOR, ZERO)): each fragment multiplies what is already
+   * in the target, all four channels, so it darkens where "add" brightens -
+   * a projected shadow, a dust pass. Order-independent like "add", same
+   * `depthWrite: false` pairing. On the premultiplied target a uniform factor
+   * across rgb and alpha fades the existing pixels; alpha 1 with rgb below 1
+   * darkens color only - so a strength-weighted shadow is
+   * `vec4(mix(vec3(1.0), shadowColor, strength), 1.0)`, not alpha =
+   * strength (that fades instead). "alpha" composites OVER
+   * (glBlendFunc(ONE, ONE_MINUS_SRC_ALPHA)): classic translucency, with the
+   * fragment written premultiplied like every target pixel -
+   * `vec4(color * a, a)`, never straight rgb with a loose alpha. It is the
+   * one order-DEPENDENT mode: the result follows draw-list order, so
+   * translucent geometry must land back-to-front - by draw-list ordering
+   * (`before`, `setDrawOrder`) or a sorting layer above - and normally after
+   * the opaque draws with `depthWrite: false`, so it depth-tests against them
+   * without occluding what it only tints. Nothing sorts for you here.
+   */
+  export type BlendMode = "none" | "add" | "multiply" | "alpha"
   /**
    * Face culling for a pipeline's draws. "none" (default) rasters both faces
    * - the two-sided fallback open surfaces need. "back" discards faces wound

package/gui/rendertree.d.ts

@@ -5,15 +5,44 @@
 // module; requestFrame here only schedules a future frame.
 
 declare module "flux:rendertree" {
-  /** Font options for {@link measureText}. */
+  /** Font options for {@link measureText} and {@link prepareText}. */
   export interface MeasureTextOptions {
     fontFamily?: "sans" | "serif" | "mono" | (string & {})
     fontSize?: number
     fontStyle?: "normal" | "italic"
     fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    lineHeight?: number
+    /** measureText only. */
     maxLines?: number
   }
 
+  /**
+   * One wrap unit (a word plus its trailing whitespace, or an empty unit at
+   * a blank line) of a {@link prepareText} result: everything the engine
+   * knows about it, for app-side line breaking.
+   */
+  export interface TextUnit {
+    /** The unit's text without its break characters. */
+    text: string
+    /** Offsets into the prepared text (JS string indexing), break characters included: the ranges tile the text. */
+    start: number
+    end: number
+    /** Horizontal extent including trailing whitespace: what the next unit's pen position advances by. */
+    advance: number
+    /** Ink extent without trailing whitespace: what the unit needs at the end of a line. */
+    width: number
+    ascent: number
+    descent: number
+    /** The unit ends at a hard line break (newline). */
+    hardBreak: boolean
+  }
+
+  /** The wrap units of a text in one font, shaped once. Plain data; layout is arithmetic over `units`. */
+  export interface PreparedText {
+    text: string
+    units: TextUnit[]
+  }
+
   /** 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. */
@@ -61,9 +90,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
   /**
@@ -71,6 +102,12 @@ declare module "flux:rendertree" {
    * adding it to the tree.
    */
   export function measureText(text: string, options?: MeasureTextOptions): { width: number, height: number }
+  /**
+   * Segment `text` into wrap units and shape each in the given font (through
+   * the shared word cache), for laying lines out in app code; see
+   * layoutNextLine in @solidrt/core. Single style; `maxLines` is ignored.
+   */
+  export function prepareText(text: string, options?: MeasureTextOptions): PreparedText
   /**
    * The node's bounding box from the most recent layout, relative to its
    * nearest positioning context (an ancestor with an explicit

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/modules/wasm.d.ts

@@ -1,5 +1,11 @@
 // There is no `WebAssembly` global in flux; this module is the entire wasm
-// surface. Imports must be scalar-signature functions only (no imported
+// surface. Modules run in a pure interpreter (wasmi, no JIT), so this is a
+// portability tool - one compiled module runs on every flux target with no
+// native binaries or dlopen - not a speed tool. Tight typed compute runs
+// somewhat faster than the same loop in JavaScript (a small constant
+// factor, nowhere near browser wasm speed), and every host call costs
+// extra marshalling, so call-heavy code can end up slower.
+// Imports must be scalar-signature functions only (no imported
 // memory, globals or tables), which constrains the toolchain on the other
 // side: default emscripten output imports its memory and is rejected, while
 // `emcc -sSTANDALONE_WASM=1 --no-entry` produces a module that fits.

package/package.json

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