@solidrt/flux-types 0.0.69 → 0.0.70

package/README.md

@@ -51,7 +51,7 @@ rely on must be named.
   `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`,
+  `setTimeout`/`setInterval`/`setImmediate`/`requestIdleCallback`/`queueMicrotask`, `performance`, `WebSocket`,
   `TextEncoder`/`TextDecoder`, `crypto.subtle.digest`. These are deliberate subsets matching exactly what
   the runtime implements.
 - GUI globals (gui-enabled runtime only): `requestAnimationFrame` /

package/gui/font.d.ts

@@ -14,7 +14,7 @@
 
 declare module "flux:font" {
   import type { TextureId } from "flux:gpu"
-  import type { PreparedText } from "flux:rendertree"
+  import type { TextUnit } from "flux:rendertree"
 
   /** A created font, valid until {@link destroyFont}. */
   type FontId = number
@@ -34,6 +34,8 @@ declare module "flux:font" {
     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), what {@link prepareText} shapes with by default; default 0. */
+    letterSpacing?: number
     /** Line height as a multiplier of the size, 0 for the font's own line. */
     lineHeight?: number
   }
@@ -54,6 +56,14 @@ declare module "flux:font" {
     range?: number
     /** Keep a mip chain on the atlas texture: default true for msdf (sampled at every zoom), false for mask. */
     mipmap?: boolean
+    /**
+     * mask only: how the cells are hinted. "light" snaps baseline, x-height
+     * and cap height to pixel rows (`true` means the same); "full" snaps
+     * stems to whole pixels as well, which a grid of cells drawn at whole
+     * pixels (a terminal) wants; false (default) keeps the outline as the
+     * font draws it. An msdf atlas is never hinted.
+     */
+    hint?: boolean | "light" | "full"
     /** Debug label of the atlas texture. */
     label?: string
   }
@@ -71,6 +81,8 @@ declare module "flux:font" {
     fontSize: number
     /** msdf: the distance range in texels; 0 for a mask atlas. */
     range: number
+    /** How the cells are hinted; "off" for an msdf atlas. */
+    hint: "off" | "light" | "full"
   }
 
   /**
@@ -97,10 +109,29 @@ declare module "flux:font" {
     fontSize?: number
     /** Line height multiplier; default the face's. */
     lineHeight?: number
+    /** Extra advance after every character in pixels, at `fontSize`; default the face's. */
+    letterSpacing?: number
     /** Also report each unit's caret stops (one pass over the cluster map). */
     carets?: boolean
   }
 
+  /**
+   * A wrap unit shaped on a font: `flux:rendertree`'s unit plus the unit's
+   * glyphs - the font's glyph `id` (a cell of this font's atlas), the glyph
+   * origin `x`/`y` from the unit's pen position (kerned, letter-spaced, y
+   * down) and the pen `advance` it contributes - all in pixels at the
+   * shaping size.
+   */
+  type FontTextUnit = TextUnit & {
+    glyphs: { id: number, x: number, y: number, advance: number }[]
+  }
+
+  /** A text shaped on a font: `flux:rendertree`'s `PreparedText` with every unit carrying its glyphs. */
+  type FontPreparedText = {
+    text: string
+    units: FontTextUnit[]
+  }
+
   /**
    * 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
@@ -112,17 +143,16 @@ declare module "flux:font" {
   /** 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.
+   * Shape `text` on the font (the runtime's own shaper): the units of
+   * `flux:rendertree`'s prepareText, each also carrying its glyphs, 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
+  function prepareText(font: FontId, text: string, options?: FontPrepareOptions): FontPreparedText
   /**
    * 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

package/gui/rendertree.d.ts

@@ -79,13 +79,6 @@ declare module "flux:rendertree" {
      * 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`. */
@@ -228,6 +221,61 @@ declare module "flux:rendertree" {
    * made at first use.
    */
   export function warmText(styles: MeasureTextOptions[]): void
+  /** How every text is rendered, for {@link setTextRendering}. */
+  export interface TextRenderingOptions {
+    /**
+     * How a glyph's coverage becomes color: "naive" takes it as is;
+     * "linearLight", "polarityRemap" and "polarityLinear" remap it by
+     * `gamma` for light text on a dark ground; "directWrite" applies
+     * DirectWrite's contrast boost (`contrast`) and gamma alpha correction
+     * (`gamma`, 1.0 to 2.2).
+     */
+    coverage?: "naive" | "linearLight" | "polarityRemap" | "polarityLinear" | "directWrite"
+    /** The exponent of the remaps, or the DirectWrite gamma; positive. */
+    gamma?: number
+    /** The DirectWrite mode's enhanced contrast; positive, 1 is its default. */
+    contrast?: number
+    /**
+     * Stem darkening of every glyph in em per side, at any display scale;
+     * null restores the default (a low-DPI strength below 2x, none above).
+     */
+    darken?: number | null
+    /**
+     * How glyph cells are hinted, at any display scale: "light" (the
+     * autohinter's light mode: baseline, x-height and cap height snap to
+     * pixel rows, stems and advances untouched; `true` means the same),
+     * "full" (stems snap to whole pixels as well, letterforms rounded per
+     * size: a 1x screen read from a distance) or `false` (the outline as
+     * the font draws it). null restores the default: light below 2x,
+     * off above.
+     */
+    hint?: boolean | "light" | "full" | null
+  }
+  /**
+   * Change how every text is rendered. Each option given replaces its part
+   * of the current policy and the rest stays; every text redraws at the
+   * next frame. The defaults are what an app that says nothing gets; this
+   * is the knob for judging a policy by eye on a running app. Throws on an
+   * unknown mode or an invalid number.
+   */
+  export function setTextRendering(options: TextRenderingOptions): void
+  /** The text rendering policy as it stands, resolved for this display: what {@link textRendering} returns. */
+  export interface TextRenderingPolicy {
+    coverage: "naive" | "linearLight" | "polarityRemap" | "polarityLinear" | "directWrite"
+    gamma: number
+    contrast: number
+    /** The stem darkening in effect on this display, em per side. */
+    darken: number
+    /** The hinting in effect on this display. */
+    hint: false | "light" | "full"
+  }
+  /**
+   * The current text rendering policy, resolved for this display: a
+   * `darken` or `hint` left at its default reads as the value the display
+   * scale gives it, so a settings screen shows what is in effect, and
+   * setting the result back changes nothing on this display.
+   */
+  export function textRendering(): TextRenderingPolicy
   /**
    * The node's bounding box from the most recent layout, relative to its
    * nearest positioning context (an ancestor with an explicit

package/modules/isolate.d.ts

@@ -107,6 +107,13 @@ declare module "flux:isolate" {
    * already-aborted signal rejects without sending anything (or starting the
    * child).
    *
+   * A child that cannot start (an id no module resolves to or a malformed
+   * one, a module that does not decode, a runtime that cannot spawn
+   * isolates) never throws from the call expression: the first use rejects
+   * with the failure as an `Error`, a `for await` over it throws that error
+   * on its first step, and `exited` settles with the message. Nothing is
+   * remembered, so a later use tries again.
+   *
    * Reserved names: `terminate`, `exited`, `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.69",
+  "version": "0.0.70",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",

package/standards/time.d.ts

@@ -1,5 +1,13 @@
-// Timers, microtask scheduling, and the monotonic clock. flux's timers differ
-// from the browser in one way: no extra callback arguments are forwarded.
+// Timers, task scheduling, idle callbacks, microtask scheduling, and the
+// monotonic clock. flux's timers differ from the browser in one way: no
+// extra callback arguments are forwarded.
+//
+// Two kinds of scheduling. What names a point in time (setTimeout,
+// setInterval, requestAnimationFrame) runs on the app's frame clock, as
+// described next. What names a turn (queueMicrotask, setImmediate) runs on
+// the engine loop whenever it is ready: between frames in a GUI runtime,
+// never waiting for one, and not held by a paused clock. requestIdleCallback
+// sits on the frame side: its idle period is what is left of a frame.
 //
 // In a GUI runtime the timers are FRAME-QUANTIZED but WALL-ACCURATE: a
 // deadline is measured against the real clock from the moment of
@@ -31,6 +39,50 @@ declare function clearTimeout(id?: number): void
 declare function setInterval(callback: () => void, ms?: number): number
 /** Cancel a running interval. Unknown or missing ids are ignored. */
 declare function clearInterval(id?: number): void
+/**
+ * Run `callback` on the next turn of the engine loop: after the current
+ * task and its microtasks, with no delay floor. Not a timer: in a GUI
+ * runtime it runs between frames (a chain of immediates makes progress at
+ * CPU speed while frames keep coming) and a paused clock does not hold it;
+ * it always runs before a `setTimeout(fn, 0)` registered with it there.
+ * Returns an id for {@link clearImmediate}.
+ */
+declare function setImmediate(callback: () => void): number
+/** Cancel a pending immediate. Unknown or missing ids are ignored. */
+declare function clearImmediate(id?: number): void
+
+/** What an idle callback is handed: how much of the idle period is left. */
+interface IdleDeadline {
+  /** Milliseconds left in the idle period; 0 once it has passed. */
+  timeRemaining(): number
+  /** Whether the `timeout` ran the callback instead of an idle period. */
+  readonly didTimeout: boolean
+}
+
+interface IdleRequestOptions {
+  /**
+   * If no idle period has run the callback after this many ms, run it as
+   * a task anyway, with `didTimeout` true and no time remaining. That
+   * task is a timer, so in a GUI runtime it fires on a frame boundary,
+   * like `setTimeout`.
+   */
+  timeout?: number
+}
+
+/**
+ * Run `callback` in an idle period, oldest registration first, with an
+ * {@link IdleDeadline}. In a GUI runtime an idle period is what is left of a
+ * frame after its work: it begins once the frame's callbacks, flush and
+ * draw are done and its microtasks have run, and ends when the frame is
+ * due on screen, at most 50 ms later. Callbacks that do not fit wait for
+ * the next frame's period, and one registered during a period waits for
+ * the next. A paused clock holds the frames and with them the idle
+ * periods. Headless flux has no frames: the callback runs on the next
+ * turn with the full 50 ms. Returns an id for {@link cancelIdleCallback}.
+ */
+declare function requestIdleCallback(callback: (deadline: IdleDeadline) => void, options?: IdleRequestOptions): number
+/** Cancel a pending idle callback. Unknown or missing ids are ignored. */
+declare function cancelIdleCallback(id?: number): void
 /**
  * Queue `callback` to run as a microtask: after the current job finishes, before
  * any timer fires.