@solidrt/flux-types 0.0.66 → 0.0.68

package/README.md

@@ -46,9 +46,10 @@ rely on must be named.
 
 - `Flux` global (`version`, `capabilities`).
 - `flux:*` modules: `flux:http`, `flux:fs`, `flux:sqlite`, `flux:subprocess`,
-  `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:tty`, `flux:path`, `flux:wasm`, `flux:ffi`,
+  `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:tty`, `flux:path`, `flux:wasm`,
   and (on a gui-enabled runtime)
-  `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`, `flux:spatial`.
+  `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`, `flux:spatial`,
+  `flux:font`.
 - Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,
   `setTimeout`/`setInterval`/`queueMicrotask`, `performance`, `WebSocket`,
   `TextEncoder`/`TextDecoder`, `crypto.subtle.digest`. These are deliberate subsets matching exactly what

package/gui/font.d.ts

@@ -0,0 +1,137 @@
+// The glyph engine (gui-enabled runtime only): a registered font shaped on
+// the runtime's own shaper, its glyphs rasterized into an atlas texture a
+// consumer samples itself - the sprite layer's world-space text, a terminal
+// grid, anything that draws glyph quads. `<text>` does not draw through
+// this; it is the primitive beneath that for text the tree cannot carry.
+//
+// A font handle is one face (family, weight, style) with one atlas of one
+// cell kind. Prepare text over it to get units whose glyphs are named and
+// placed, ask for the cells of the glyphs you draw, then draw each glyph as
+// a quad at its placement sampling the atlas rect. Cells are made on a
+// worker thread and land at a later frame: draw a glyph whose cell has not
+// arrived as nothing at its advance, and re-read the cells when the promise
+// resolves.
+
+declare module "flux:font" {
+  import type { TextureId } from "flux:gpu"
+  import type { PreparedText } from "flux:rendertree"
+
+  /** A created font, valid until {@link destroyFont}. */
+  type FontId = number
+
+  /**
+   * The face a font shapes and rasterizes with: the same vocabulary as a
+   * `<text>`'s font props, resolved the same way (a role alias such as
+   * "sans", "serif" or "mono", or a registered family name; an unknown
+   * family falls back to sans). `fontSize` is the size a "mask" atlas is
+   * made at and the default size {@link prepareText} shapes at; an "msdf"
+   * atlas is size-independent.
+   */
+  type FontFace = {
+    fontFamily?: "sans" | "serif" | "mono" | (string & {})
+    fontSize?: number
+    fontStyle?: "normal" | "italic"
+    fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    /** Width as a percentage of normal (CSS font-stretch), on the font's width axis; default 100. */
+    fontStretch?: number
+    /** Line height as a multiplier of the size, 0 for the font's own line. */
+    lineHeight?: number
+  }
+
+  /** Options for {@link createFont}. */
+  type FontAtlasOptions = {
+    /**
+     * What the atlas holds. "msdf" (default): multi-channel signed distance
+     * fields at `size` texels per em, one cell for every zoom; the consumer
+     * decodes the field in its shader (the sprite layer's text does).
+     * "mask": coverage masks at the face's pixel size, premultiplied white,
+     * drawn 1:1 as a plain texture - a terminal, a HUD at a fixed size.
+     */
+    cells?: "mask" | "msdf"
+    /** Texels per em of the cells: the face's `fontSize` for a mask atlas, 48 for an msdf one. */
+    size?: number
+    /** msdf only: the distance range in texels (default 8), the room an outline has. */
+    range?: number
+    /** Keep a mip chain on the atlas texture: default true for msdf (sampled at every zoom), false for mask. */
+    mipmap?: boolean
+    /** Debug label of the atlas texture. */
+    label?: string
+  }
+
+  /** The atlas of a font: its texture, its current size and what its cells are. */
+  type FontAtlas = {
+    texture: TextureId
+    /** Current size in texels. The atlas grows as glyphs arrive; a change of size means EVERY cell moved, so re-read placements with {@link glyphCells}. */
+    width: number
+    height: number
+    cells: "mask" | "msdf"
+    /** Texels per em the cells were made at. */
+    size: number
+    /** The face's size: what {@link prepareText} shapes at by default (the runtime's text default when the face named none). */
+    fontSize: number
+    /** msdf: the distance range in texels; 0 for a mask atlas. */
+    range: number
+  }
+
+  /**
+   * Where a glyph's cell sits in the atlas (`x`, `y`, `width`, `height`,
+   * texels) and how the cell sits on the glyph: `left` texels right of the
+   * glyph origin, `top` texels above the baseline. To draw a glyph placed
+   * at pen (px, py) in a text prepared at `fontSize`, scale by
+   * `fontSize / atlas.size` and put the cell's top-left at
+   * `(px + left * s, py + ascent - top * s)`.
+   */
+  type GlyphCell = {
+    glyph: number
+    x: number
+    y: number
+    width: number
+    height: number
+    left: number
+    top: number
+  }
+
+  /** Options for {@link prepareText} over a font. */
+  type FontPrepareOptions = {
+    /** Pixels per em to shape at; default the face's `fontSize`. */
+    fontSize?: number
+    /** Line height multiplier; default the face's. */
+    lineHeight?: number
+    /** Also report each unit's caret stops (one pass over the cluster map). */
+    carets?: boolean
+  }
+
+  /**
+   * Create a font: one face with an empty atlas. Throws on an unknown cells
+   * kind or a non-positive size. The atlas texture exists from here, so a
+   * layer can declare it at creation and draw from it as cells arrive.
+   */
+  function createFont(face?: FontFace, options?: FontAtlasOptions): FontId
+  /** Free the font and its atlas texture. Requests still pending on it reject. */
+  function destroyFont(font: FontId): void
+  /** The font's atlas as it is now. */
+  function fontAtlas(font: FontId): FontAtlas
+  /**
+   * Shape `text` on the font (the runtime's own shaper): the same
+   * `PreparedText` as `flux:rendertree`'s, every unit also carrying its
+   * `glyphs` - ids and pen positions, kerned, in pixels at `fontSize` -
+   * for app-side line breaking with `layoutNextLine` and glyph placement.
+   * The font is one face and its atlas holds that face's cells only, so a
+   * character the face lacks shapes to its missing glyph (id 0) with no
+   * fallback to another font, where a `<text>` would borrow the glyph;
+   * whitespace and control characters the face lacks take the space's
+   * advance.
+   */
+  function prepareText(font: FontId, text: string, options?: FontPrepareOptions): PreparedText
+  /**
+   * Make the cells of `glyphs` (ids from prepared units) that the atlas
+   * does not hold yet, on the worker thread. Resolves once every glyph is
+   * placed or has failed (a glyph the font cannot rasterize, or an atlas
+   * at the device's texture size cap), with one {@link GlyphCell} per
+   * requested glyph, null for a failed one. Work in flight: `settle`
+   * waits for it. Rejects if the font is destroyed first.
+   */
+  function requestGlyphs(font: FontId, glyphs: number[]): Promise<(GlyphCell | null)[]>
+  /** The cells of `glyphs` as the atlas holds them now, null for a glyph not (yet) in it. */
+  function glyphCells(font: FontId, glyphs: number[]): (GlyphCell | null)[]
+}

package/gui/gpu.d.ts

@@ -358,13 +358,20 @@ declare module "flux:gpu" {
    * for byte formats, Float32Array for float formats).
    */
   export function createMutableTexture(data: Uint8Array | Float32Array | Uint32Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
+  /** A rect of a texture, in texels from its top-left: the third argument of {@link uploadTexture}. */
+  export type TextureRect = { x: number, y: number, width: number, height: number }
   /**
    * Replace a mutable texture's pixels; the frame size and required view
    * type (Uint8Array for byte formats, Float32Array for float formats)
    * follow the format the id was created with. `data` may hold several
-   * frames; `offset` (default 0) selects which frame to upload.
+   * frames; a numeric `at` (default 0) selects which frame to upload. A
+   * rect `at` uploads `data` as exactly that rect of the texture instead -
+   * `data` then holds `width * height` pixels - and the rect must lie
+   * inside the texture (GL's texSubImage2D with an offset): how a runtime
+   * atlas writes one cell without re-sending the sheet. A mip chain
+   * regenerates after either form.
    */
-  export function uploadTexture(id: TextureId, data: Uint8Array | Float32Array | Uint32Array, offset?: number): void
+  export function uploadTexture(id: TextureId, data: Uint8Array | Float32Array | Uint32Array, at?: number | TextureRect): void
   /**
    * Replace a texture's storage with a new size at the same id (an id-stable
    * resize): `<texture src>` references and shader sampler bindings keep

package/gui/rendertree.d.ts

@@ -12,6 +12,10 @@ declare module "flux:rendertree" {
     fontSize?: number
     fontStyle?: "normal" | "italic"
     fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    /** Width as a percentage of normal (CSS font-stretch), on the font's width axis; default 100. */
+    fontStretch?: number
+    /** Extra advance after every character in pixels (CSS letter-spacing); default 0. */
+    letterSpacing?: number
     lineHeight?: number
     /** measureText only. */
     maxLines?: number
@@ -35,6 +39,8 @@ declare module "flux:rendertree" {
     fontSize?: number
     fontStyle?: "normal" | "italic"
     fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    fontStretch?: number
+    letterSpacing?: number
     lineHeight?: number
   }
 
@@ -66,12 +72,20 @@ declare module "flux:rendertree" {
      * 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. These are
-     * the per-glyph x positions of the shaping that is drawn, kerning
-     * included: for placing or animating single glyphs, use them rather
+     * the runtime's own shaper's glyph positions for the unit, kerning
+     * included, within a texel of what is drawn and ending on the unit's
+     * drawn advance: for placing or animating single glyphs, use them rather
      * than measuring characters one at a time with measureText, which sees
      * no neighbors and drifts on every kerning pair.
      */
     carets?: { offset: number, x: number }[]
+    /**
+     * The unit's glyphs, from `flux:font`'s prepareText only (its ids name
+     * cells of that font's atlas): the font's glyph `id`, the glyph origin
+     * `x`/`y` from the unit's pen position (kerned, y down) and the pen
+     * `advance` it contributes.
+     */
+    glyphs?: { id: number, x: number, y: number, advance: number }[]
   }
 
   /** The wrap units of a text in one font, shaped once. Plain data; layout is arithmetic over `units`. */
@@ -200,10 +214,20 @@ declare module "flux:rendertree" {
    * the shared word cache, so a text already drawn or prepared costs no
    * shaping), for app-side line breaking - text into a shape, around an
    * obstacle, across columns, fitted by size, per glyph; see layoutNextLine
-   * in @solidrt/core. `runs` restyle ranges, `carets` adds glyph positions;
+   * in @solidrt/core. `runs` restyle ranges, `carets` adds caret stops;
    * `maxLines` is ignored.
    */
   export function prepareText(text: string, options?: MeasureTextOptions): PreparedText
+  /**
+   * Make the glyph cells of printable ASCII for these font styles ahead of
+   * their first use, on the engine's worker thread: the type scale an app
+   * draws its screens in, called at startup under the splash, so a first
+   * paint in any of them never waits for cells. Each entry names a font
+   * (family, size, weight, style) as a `<text>` would; `lineHeight`,
+   * `maxLines`, `carets` and `runs` are ignored. Glyphs outside ASCII are
+   * made at first use.
+   */
+  export function warmText(styles: MeasureTextOptions[]): void
   /**
    * The node's bounding box from the most recent layout, relative to its
    * nearest positioning context (an ancestor with an explicit

package/index.d.ts

@@ -11,7 +11,6 @@
 /// <reference path="./modules/net.d.ts" />
 /// <reference path="./modules/mdns.d.ts" />
 /// <reference path="./modules/wasm.d.ts" />
-/// <reference path="./modules/ffi.d.ts" />
 /// <reference path="./modules/isolate.d.ts" />
 /// <reference path="./modules/test.d.ts" />
 
@@ -39,6 +38,7 @@
 /// <reference path="./gui/audio.d.ts" />
 /// <reference path="./gui/gpu.d.ts" />
 /// <reference path="./gui/spatial.d.ts" />
+/// <reference path="./gui/font.d.ts" />
 /// <reference path="./gui/video.d.ts" />
 /// <reference path="./gui/raf.d.ts" />
 /// <reference path="./gui/test.d.ts" />

package/modules/wasm.d.ts

@@ -1,10 +1,16 @@
 // There is no `WebAssembly` global in flux; this module is the entire wasm
-// 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.
+// surface. One compiled module runs on every flux target with no native
+// binaries or dlopen, and it is the route for app code that needs more than
+// the JavaScript interpreter. Where the device allows generated code
+// (desktop, 64-bit Android) a module is compiled to machine code on the
+// device the first time it is seen - at install for a `.wasm` under
+// `assets/`, otherwise at `new Module` - and `Flux.capabilities` lists
+// `wasm-native`; a tight typed kernel then runs 18x to 960x faster than the
+// same loop in JavaScript. Where it does not (iOS, 32-bit Android) the
+// module is interpreted and still runs compute 4x to 88x faster than
+// JavaScript. The boundary is the cost on both lanes: a host call out of
+// the module costs 3x to 7x a plain JavaScript call, so keep calls coarse:
+// one call per frame handing over a buffer, never one per entity.
 // 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

package/package.json

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

package/modules/ffi.d.ts

@@ -1,92 +0,0 @@
-declare module "flux:ffi" {
-  /**
-   * A scalar ffi value. i32/f32/f64 marshal as number; i64 and ptr marshal as
-   * BigInt (an address or i64 does not fit a JS number without precision
-   * 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". 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. */
-  type Symbols = Record<string, SymbolDecl>
-
-  /**
-   * 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). 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.
-   */
-  type CallbackFunction = (...args: FfiValue[]) => FfiValue | void
-
-  /**
-   * A native shared library. The native counterpart of `flux:wasm`'s Module:
-   * 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
-   * real ABI is undefined behavior. Only load trusted code.
-   */
-  export class Library {
-    /**
-     * 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 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: 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
-     * may only fire while such a call is on the stack, on the same thread;
-     * the pointer stays valid for the lifetime of the library.
-     */
-    callback(func: CallbackFunction, decl: SymbolDecl): bigint
-    /**
-     * 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.
-     */
-    writeMemory(ptr: FfiValue, bytes: ArrayBufferView | ArrayBuffer): void
-  }
-}