@solidrt/flux-types 0.0.69 → 0.0.71

package/README.md

@@ -51,9 +51,11 @@ 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`,
-  `TextEncoder`/`TextDecoder`, `crypto.subtle.digest`. These are deliberate subsets matching exactly what
-  the runtime implements.
+  `ReadableStream`/`WritableStream`/`TransformStream`,
+  `CompressionStream`/`DecompressionStream`,
+  `setTimeout`/`setInterval`/`setImmediate`/`requestIdleCallback`/`queueMicrotask`, `performance`, `WebSocket`,
+  `TextEncoder`/`TextDecoder` and `TextEncoderStream`/`TextDecoderStream`, `crypto.subtle.digest`.
+  These are deliberate subsets matching exactly what the runtime implements.
 - GUI globals (gui-enabled runtime only): `requestAnimationFrame` /
   `cancelAnimationFrame` (web-standard names, so kept global).
 

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`. */
@@ -219,15 +212,80 @@ declare module "flux:rendertree" {
    */
   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.
+   * One font to warm for {@link warmText}: a font (family, size, weight,
+   * style) as a `<text>` names it, and optionally a string the app will
+   * draw in it.
+   */
+  export type WarmTextEntry = MeasureTextOptions & { text?: string }
+  /**
+   * Make glyph cells 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 does not stop to
+   * make them. A cell a text needs that is not in the atlas is made in
+   * that frame, so text never draws with glyphs missing; warming only
+   * moves that work ahead of time. Each entry names a font as a `<text>`
+   * would (`lineHeight`, `maxLines`, `carets` and `runs` are ignored) and
+   * warms its printable ASCII; an entry with a `text` also warms the
+   * glyphs that string shapes to in the font, a ligature, a curly quote or
+   * a letter beyond ASCII included, on whichever face covers it. Anything
+   * else is made at first use.
+   */
+  export function warmText(entries: WarmTextEntry[]): 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 warmText(styles: MeasureTextOptions[]): void
+  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/index.d.ts

@@ -16,10 +16,13 @@
 
 // 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
-// console, fetch, the Fetch types, timers, WebSocket, the encoders, and crypto.
+// console, fetch, the Fetch types, the streams, the compression streams,
+// timers, WebSocket, the encoders, and crypto.
 /// <reference path="./standards/console.d.ts" />
 /// <reference path="./standards/time.d.ts" />
 /// <reference path="./standards/text.d.ts" />
+/// <reference path="./standards/streams.d.ts" />
+/// <reference path="./standards/compression.d.ts" />
 /// <reference path="./standards/base64.d.ts" />
 /// <reference path="./standards/fetch.d.ts" />
 /// <reference path="./standards/websocket.d.ts" />

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

@@ -68,27 +68,41 @@ declare module "flux:net" {
   }
 
   /**
-   * A connected TCP stream: a byte duplex. It is its own async iterator, so
-   * `for await (let chunk of conn)` reads it until end-of-stream.
+   * A connected TCP stream: a byte duplex as a `readable`/`writable` pair of
+   * web streams, the shape sockets have in every runtime with web streams.
+   * `for await (let chunk of conn.readable)` reads it, `conn.readable
+   * .pipeTo(other.writable)` is one half of a proxy, and a pipe carries the
+   * half-close: when the source ends, the destination's write side closes.
    */
-  export class Conn implements AsyncIterable<Uint8Array> {
+  export class Conn {
     /** The remote peer's address, e.g. "192.168.2.37:445". */
     readonly remoteAddr: string
-    /** Write all of `data`. Resolves once it is handed to the OS. */
-    write(data: string | Uint8Array): Promise<void>
     /**
-     * Half-close: flush and end the write side, so the peer sees end-of-stream
-     * while this side keeps reading until the peer closes. The way to signal
-     * "request done" to protocols that answer after EOF. After it, {@link write}
-     * throws. Idempotent, and a no-op once the connection is closed.
+     * What the peer sends, one chunk per read, pulled only as far as it is
+     * read. Ends when the peer ends its write side or closes, or on
+     * {@link close}; errors with the reason after `writable.abort(reason)`.
+     * `cancel()` stops reading and releases the read half: the write side
+     * stays usable and the connection stays open until {@link close}.
      */
-    closeWrite(): Promise<void>
+    readonly readable: ReadableStream<Uint8Array>
     /**
-     * Close the connection now: a pending read ends, the peer sees end-of-stream
-     * at once. Bytes already handed to the OS still flush.
+     * What to send: strings (as UTF-8) or `Uint8Array`s. A write resolves
+     * once the OS took the bytes, so a producer faster than the peer reads
+     * sees backpressure. `close()` is the half-close: it flushes and ends the
+     * write side, so the peer sees end-of-stream while this side keeps
+     * reading until the peer closes (the way to say "request done" to a
+     * protocol that answers after EOF); a later write rejects. `abort(reason)`
+     * tears the connection down with an error: a pending or later read of
+     * {@link readable} rejects with the reason. TCP has no abortive
+     * half-close, so the peer still sees a plain end-of-stream.
+     */
+    readonly writable: WritableStream<string | Uint8Array>
+    /**
+     * Close the connection now: a pending read ends, a pending write rejects,
+     * the peer sees end-of-stream at once. Bytes already handed to the OS
+     * still flush.
      */
     close(): void
-    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>
   }
 
   /**

package/modules/p2p.d.ts

@@ -47,19 +47,39 @@ declare module "flux:p2p" {
   }
 
   /**
-   * A single bidirectional p2p stream: a byte duplex. It is its own async
-   * iterator, so `for await (let chunk of stream)` reads the recv half.
+   * A single bidirectional p2p stream: a byte duplex as a `readable`/`writable`
+   * pair of web streams, the same shape as a `flux:net` `Conn`, so
+   * `stream.readable.pipeTo(conn.writable)` bridges the two.
    */
-  export class P2pStream implements AsyncIterable<Uint8Array> {
+  export class P2pStream {
     /** The remote peer's endpoint id. */
     readonly remoteId: string
-    /** Queue bytes on the send half. */
-    write(data: string | Uint8Array): void
-    /** Half-close: end the send half (QUIC FIN) after queued writes flush. The recv half stays open. */
-    closeWrite(): void
-    /** Tear the stream down: end the send half and stop reading. */
+    /**
+     * What the peer sends, one chunk per read, pulled only as far as it is
+     * read. Ends when the peer finishes its send half or closes, or on
+     * {@link close}; errors when the peer resets the stream, and with the
+     * reason after `writable.abort(reason)`. `cancel()` stops reading and
+     * releases the recv half, which tells the peer to stop sending (its
+     * writes reject); the send side stays usable until {@link close}.
+     */
+    readonly readable: ReadableStream<Uint8Array>
+    /**
+     * What to send: strings (as UTF-8) or `Uint8Array`s. A write resolves
+     * once the transport took the bytes, paced by QUIC flow control, so a
+     * producer faster than the peer reads sees backpressure; a write to a
+     * peer that went away or stopped reading rejects. `close()` finishes the
+     * send half (QUIC FIN): the peer sees end-of-stream, the recv half stays
+     * open for replies, and a later write rejects. `abort(reason)` resets the
+     * send half and tears the stream down with an error: the peer's read
+     * fails instead of ending, and a pending or later read of
+     * {@link readable} here rejects with the reason.
+     */
+    readonly writable: WritableStream<string | Uint8Array>
+    /**
+     * Tear the stream down: a pending read ends, the recv half is released and
+     * the send half finished.
+     */
     close(): void
-    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>
   }
 
   /** A bound iroh endpoint with a stable keypair. */
@@ -82,11 +102,15 @@ declare module "flux:p2p" {
     /**
      * Dial a peer and open one bidirectional stream over `protocol`. `peer` is
      * either a `ticket` (preferred; connects directly) or a bare endpoint `id`
-     * (needs discovery to resolve the address).
+     * (needs discovery to resolve the address). The peer sees the stream once
+     * this side writes to it (see {@link accept}).
      */
     connect(peer: string, protocol: string): Promise<P2pStream>
     /**
      * An async-iterable of incoming streams whose protocol matches `protocol`.
+     * A dialled stream arrives here with its first bytes (a QUIC stream is
+     * announced by its data), so the dialer writes first and the acceptor
+     * reads first: two sides that both wait for the other never meet.
      * Iterating ends when the endpoint is closed.
      */
     accept(protocol: string): AsyncIterable<P2pStream>

package/modules/subprocess.d.ts

@@ -5,7 +5,11 @@ declare module "flux:subprocess" {
     cwd?: string
     /** Extra env vars, added to / overriding the inherited environment. */
     env?: Record<string, string>
-    /** Bytes written to the child's stdin, after which stdin is closed. */
+    /**
+     * Bytes written to the child's stdin first. With {@link Command.output}
+     * stdin is closed after them; with {@link Command.spawn} it stays open for
+     * the child's `stdin` stream.
+     */
     stdin?: string | Uint8Array
     /** Kill the child if it has not exited within this many milliseconds. */
     timeoutMs?: number
@@ -17,7 +21,8 @@ declare module "flux:subprocess" {
     /**
      * `spawn()` only: the child outlives this engine and this process. It is
      * never killed on drop or reload, has no stdin/stdout/stderr pipes (all
-     * null: `stdout`/`stderr` iterate to nothing, `write` fails) and runs in
+     * null: `stdout`/`stderr` end at once, the first write to `stdin`
+     * rejects) and runs in
      * its own process group, so a Ctrl+C to the parent does not reach it.
      * `pid`, `kill()` and `status()` still work. Cannot combine with `stdin`.
      * What a dev tool uses to launch another runtime instance.
@@ -53,14 +58,19 @@ declare module "flux:subprocess" {
   type Child = {
     /** The OS process id, if available. */
     pid: number | undefined
-    /** Live stdout as an async-iterable of byte chunks. */
-    stdout: AsyncIterable<Uint8Array>
-    /** Live stderr as an async-iterable of byte chunks. */
-    stderr: AsyncIterable<Uint8Array>
-    /** Queue bytes to the child's stdin. Writes serialize and respect backpressure. */
-    write(data: string | Uint8Array): Promise<void>
-    /** Half-close: close the child's stdin (after queued writes drain) so it sees EOF. */
-    closeWrite(): Promise<void>
+    /** Live stdout as a stream of byte chunks, read as far as it is consumed. */
+    stdout: ReadableStream<Uint8Array>
+    /** Live stderr as a stream of byte chunks, read as far as it is consumed. */
+    stderr: ReadableStream<Uint8Array>
+    /**
+     * The child's stdin as a stream: strings (as UTF-8) or `Uint8Array`s,
+     * written after any {@link CommandOptions.stdin}. A write resolves once
+     * the pipe took the bytes, so a producer faster than the child reads
+     * sees backpressure. `close()` (and `abort()`) closes the pipe after the
+     * writes so far, so the child sees EOF; a later write rejects. A body
+     * piped in (`response.body.pipeTo(child.stdin)`) closes it at the end.
+     */
+    stdin: WritableStream<string | Uint8Array>
     /** Request termination (portable; SIGKILL / TerminateProcess). */
     kill(): void
     /** Resolves with the exit status when the child exits. */
@@ -73,7 +83,7 @@ declare module "flux:subprocess" {
     args: string[]
     /** Run the child to completion, buffering stdout/stderr. */
     output(): Promise<CommandOutput>
-    /** Spawn the child and return a handle with live streams, stdin, and control. */
+    /** Spawn the child and return a handle with live stdout/stderr, a stdin stream, and control. */
     spawn(): Child
   }
 

package/modules/test.d.ts

@@ -114,9 +114,11 @@ declare module "flux:test" {
     /**
      * A number within half a unit of the last of `digits` decimal places
      * (default 2): the difference is below `10 ** -digits / 2`. The way to
-     * compare floating point results.
+     * compare floating point results. An array of numbers (a point, a
+     * normal, a motion) compares to one of the same length entry by entry,
+     * and a failure prints both arrays whole.
      */
-    toBeCloseTo(expected: number, digits?: number): void
+    toBeCloseTo(expected: number | readonly number[], digits?: number): void
 
     /**
      * For a function: calling it throws. With a string, the thrown error's

package/package.json

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

package/standards/compression.d.ts

@@ -0,0 +1,32 @@
+// The Compression Streams API: CompressionStream and DecompressionStream,
+// TransformStreams over the deflate formats, with the standard's names and
+// shapes. A chunk written in is an ArrayBuffer or a view of one; what comes
+// out is Uint8Arrays of at most 64 KiB each, produced as the reader pulls,
+// so a small input that inflates to a lot never runs ahead of its reader.
+// The codec runs off the JS thread, a step per piece.
+//
+// Errors are the standard's TypeErrors: an unknown format throws from the
+// constructor; a chunk that is not a buffer, corrupt input, input cut short
+// when the writable side closes, and data after the end of the compressed
+// stream (a second gzip member included) error both sides of the stream.
+
+/**
+ * The formats: `gzip` (RFC 1952), `deflate` (the zlib format, RFC 1950: a
+ * two-byte header and an Adler-32 trailer) and `deflate-raw` (RFC 1951, the
+ * bare stream, what a ZIP entry holds).
+ */
+type CompressionFormat = "gzip" | "deflate" | "deflate-raw"
+
+declare class CompressionStream {
+  /** Any other `format` throws a TypeError. */
+  constructor(format: CompressionFormat)
+  readonly readable: ReadableStream<Uint8Array>
+  readonly writable: WritableStream<ArrayBuffer | ArrayBufferView>
+}
+
+declare class DecompressionStream {
+  /** Any other `format` throws a TypeError. */
+  constructor(format: CompressionFormat)
+  readonly readable: ReadableStream<Uint8Array>
+  readonly writable: WritableStream<ArrayBuffer | ArrayBufferView>
+}

package/standards/fetch.d.ts

@@ -1,6 +1,6 @@
 // The Fetch API cluster (Headers, Request, Response, fetch). A deliberate subset
 // of the WHATWG Fetch standard: flux provides exactly these members and no more
-// (no Blob, FormData, ReadableStream, clone(), ...).
+// (no Blob, FormData, clone(), ...). Bodies are ReadableStreams (streams.d.ts).
 // Grouped in one file because the four share BodyInit/HeadersInit and reference
 // each other.
 
@@ -11,11 +11,12 @@
 type HeadersInit = Record<string, string> | Headers
 
 /**
- * A message body: a string, raw bytes, or an async-iterable of string/byte
- * chunks (e.g. an `async function*`), which is sent as a stream. Any other
- * value throws (the web stringifies it).
+ * A message body: a string, raw bytes, or a stream of string/byte chunks (a
+ * `ReadableStream`, or any async-iterable such as an `async function*`),
+ * which is sent as it is produced. Any other value throws (the web
+ * stringifies it).
  */
-type BodyInit = string | Uint8Array | AsyncIterable<string | Uint8Array>
+type BodyInit = string | Uint8Array | ReadableStream<string | Uint8Array> | AsyncIterable<string | Uint8Array>
 
 /** A subset of the WHATWG Headers API. Names are case-insensitive. */
 interface Headers {
@@ -89,8 +90,12 @@ interface Request {
   readonly headers: Headers
   /** Route params from the matched pattern; an empty object for a JS-constructed Request. */
   readonly params: Record<string, string>
-  /** The body as an async-iterable of byte chunks (read once). */
-  readonly body: AsyncIterable<Uint8Array>
+  /**
+   * The body as a stream of byte chunks, read once: an incoming request's
+   * network stream, read as far as it is consumed; a buffered body as one
+   * chunk. Reading it with `for await` is the common form.
+   */
+  readonly body: ReadableStream<Uint8Array>
   /** Read the whole body as UTF-8 text. */
   text(): Promise<string>
   /** Read the whole body as raw bytes. */
@@ -122,26 +127,38 @@ interface Response {
   readonly ok: boolean
   readonly url: string
   readonly headers: Headers
-  /** The body as an async-iterable of byte chunks (read once). */
-  readonly body: AsyncIterable<Uint8Array>
-  /** Read the whole body as UTF-8 text. */
+  /**
+   * The body as a stream of byte chunks, read once: a fetched response's
+   * network stream, read as far as it is consumed; a buffered body as one
+   * chunk; a stream given to the constructor as it is. Reading it with
+   * `for await` is the common form.
+   */
+  readonly body: ReadableStream<Uint8Array>
+  /** Read the whole body as UTF-8 text. A stream body is drained. */
   text(): Promise<string>
-  /** Read the whole body as raw bytes. */
+  /** Read the whole body as raw bytes. A stream body is drained. */
   bytes(): Promise<Uint8Array>
-  /** Read the whole body as an ArrayBuffer. */
+  /** Read the whole body as an ArrayBuffer. A stream body is drained. */
   arrayBuffer(): Promise<ArrayBuffer>
-  /** Read and parse the whole body as JSON. */
+  /** Read and parse the whole body as JSON. A stream body is drained. */
   json(): Promise<any>
 }
 
 declare let Response: {
+  /**
+   * A stream body (a `ReadableStream`, or any async-iterable of string or
+   * byte chunks, wrapped as one) is sent as it is produced: served over
+   * chunked transfer encoding, or drained by `text()` and the other
+   * readers.
+   */
   new (body?: BodyInit | null, init?: ResponseInit): Response
   /** Build a JSON response (sets Content-Type to application/json when unset). */
   json(data: any, init?: ResponseInit): Response
 }
 
 /**
- * Fetch a resource over HTTP(S). The body may be a string, Uint8Array, or an
- * async-iterable (streamed). Resolves to a {@link Response}.
+ * Fetch a resource over HTTP(S). The body may be a string, Uint8Array, or a
+ * stream (a `ReadableStream` or any async-iterable, sent as it is
+ * produced). Resolves to a {@link Response}.
  */
 declare function fetch(url: string, options?: RequestInit): Promise<Response>

package/standards/streams.d.ts

@@ -0,0 +1,244 @@
+// The WHATWG Streams subset: ReadableStream, WritableStream, TransformStream
+// and the text streams. The names and shapes are the standard's; what is
+// left out is what a single known app has not needed: no BYOB readers or
+// byte streams (`type: "bytes"`), the only queuing strategy a chunk-count
+// `highWaterMark`, no `pipeTo` options (`preventClose`, `preventAbort`,
+// `preventCancel`, `signal`). Chunks are any JS value; a stream used as a
+// body (`new Response(stream)`, a fetch body) must yield strings or
+// Uint8Arrays.
+//
+// A ReadableStream is async-iterable, so `for await (let chunk of stream)`
+// works, and ending the loop early cancels the stream. `Response.body`,
+// `Request.body` and a child process's `stdout`/`stderr` are ReadableStreams
+// over the runtime's own byte sources: one chunk is pulled per read, so a
+// socket advances only as far as it is read, and cancelling the stream
+// releases it.
+
+/** The queuing strategy a stream takes: a chunk count, nothing else. */
+interface QueuingStrategy {
+  /**
+   * How many chunks the stream queues ahead of its consumer (a readable:
+   * before it stops pulling; a writable: before a writer sees
+   * backpressure). Defaults to 1.
+   */
+  highWaterMark?: number
+}
+
+interface ReadableStreamDefaultController<R = any> {
+  /** The chunks the queue has room for; null once the stream is errored. */
+  readonly desiredSize: number | null
+  /** Queue a chunk for the reader. Throws once the stream is closed. */
+  enqueue(chunk: R): void
+  /** End the stream after the queued chunks. */
+  close(): void
+  /** Error the stream: pending and later reads reject with `e`. */
+  error(e?: any): void
+}
+
+/** What `new ReadableStream(source)` takes. Each method is optional. */
+interface UnderlyingSource<R = any> {
+  /** Runs at construction; a returned promise delays the first pull. */
+  start?(controller: ReadableStreamDefaultController<R>): any
+  /**
+   * Called when the queue has room (and again once a returned promise
+   * settles), to produce the next chunk(s).
+   */
+  pull?(controller: ReadableStreamDefaultController<R>): any
+  /** Called when the consumer cancels the stream, with the reason. */
+  cancel?(reason?: any): any
+}
+
+interface ReadableStreamReadResult<R> {
+  value: R | undefined
+  done: boolean
+}
+
+interface ReadableStreamDefaultReader<R = any> {
+  /** Settles when the stream closes; rejects when it errors or the reader is released. */
+  readonly closed: Promise<void>
+  /** The next chunk, or `{ done: true }` at the end. */
+  read(): Promise<ReadableStreamReadResult<R>>
+  /** Cancel the stream, as {@link ReadableStream.cancel}. */
+  cancel(reason?: any): Promise<void>
+  /** Unlock the stream. Pending reads reject. */
+  releaseLock(): void
+}
+
+interface ReadableStreamIteratorOptions {
+  /** Keep the stream open when the loop ends early (`break`, a throw). */
+  preventCancel?: boolean
+}
+
+/** A pair a stream pipes through; a TransformStream is one. */
+interface ReadableWritablePair<R = any, W = any> {
+  readable: ReadableStream<R>
+  writable: WritableStream<W>
+}
+
+declare class ReadableStream<R = any> {
+  /** No `type: "bytes"`; a strategy is a chunk count. */
+  constructor(underlyingSource?: UnderlyingSource<R>, strategy?: QueuingStrategy)
+  /** True while a reader, a pipe or an iteration holds the stream. */
+  readonly locked: boolean
+  /**
+   * Lock the stream to a reader. One reader at a time: a second call
+   * throws until the first is released. No `mode: "byob"`.
+   */
+  getReader(): ReadableStreamDefaultReader<R>
+  /**
+   * Discard the stream: the source's `cancel` runs with `reason`, pending
+   * reads settle as done. Rejects while the stream is locked.
+   */
+  cancel(reason?: any): Promise<void>
+  /**
+   * Read the stream through `transform` and return its readable side. The
+   * pipe runs on its own; an error on either side propagates to the other.
+   * Throws when either stream is locked. No options.
+   */
+  pipeThrough<T>(transform: ReadableWritablePair<T, R>, options?: undefined): ReadableStream<T>
+  /**
+   * Read the stream into `destination` and close it at the end. An errored
+   * source aborts the destination, an errored or closed destination cancels
+   * the source, and the promise rejects with that error. No options.
+   */
+  pipeTo(destination: WritableStream<R>, options?: undefined): Promise<void>
+  /**
+   * Two streams over this one: every chunk goes to both, and the source is
+   * cancelled once both are. A slow branch makes the other wait, since
+   * chunks are not buffered per branch beyond its own queue.
+   */
+  tee(): [ReadableStream<R>, ReadableStream<R>]
+  /** The async iterator `for await` uses; `preventCancel` keeps `break` from cancelling. */
+  values(options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>
+  [Symbol.asyncIterator](): AsyncIterableIterator<R>
+  /**
+   * A stream over an async (or sync) iterable: one item is pulled per
+   * read, and cancelling the stream returns the iterator.
+   */
+  static from<R>(iterable: AsyncIterable<R> | Iterable<R | PromiseLike<R>>): ReadableStream<R>
+}
+
+interface WritableStreamDefaultController {
+  /** Error the stream: queued and later writes reject with `e`. */
+  error(e?: any): void
+}
+
+/** What `new WritableStream(sink)` takes. Each method is optional. */
+interface UnderlyingSink<W = any> {
+  /** Runs at construction; a returned promise delays the first write. */
+  start?(controller: WritableStreamDefaultController): any
+  /**
+   * Receives one chunk at a time; the next write waits for a returned
+   * promise, which is how a slow sink paces a fast writer.
+   */
+  write?(chunk: W, controller: WritableStreamDefaultController): any
+  /** Runs once after the last write when the stream is closed. */
+  close?(): any
+  /** Runs when the stream is aborted, with the reason. */
+  abort?(reason?: any): any
+}
+
+interface WritableStreamDefaultWriter<W = any> {
+  /** Fulfilled while the queue has room; a new promise each time it fills. */
+  readonly ready: Promise<void>
+  /** Settles when the stream closes; rejects when it errors or the writer is released. */
+  readonly closed: Promise<void>
+  /** The chunks the queue has room for; null once the stream is errored. */
+  readonly desiredSize: number | null
+  /**
+   * Queue a chunk. Resolves once the sink has accepted it, so awaiting each
+   * write is one way to see backpressure; `ready` is the other.
+   */
+  write(chunk: W): Promise<void>
+  /** Close the stream after the queued writes; resolves once the sink closed. */
+  close(): Promise<void>
+  /** Abort the stream, as {@link WritableStream.abort}. */
+  abort(reason?: any): Promise<void>
+  /** Unlock the stream. A pending `ready` or `closed` rejects. */
+  releaseLock(): void
+}
+
+declare class WritableStream<W = any> {
+  /** A strategy is a chunk count. */
+  constructor(underlyingSink?: UnderlyingSink<W>, strategy?: QueuingStrategy)
+  /** True while a writer or a pipe holds the stream. */
+  readonly locked: boolean
+  /**
+   * Lock the stream to a writer. One writer at a time: a second call throws
+   * until the first is released.
+   */
+  getWriter(): WritableStreamDefaultWriter<W>
+  /**
+   * Error the stream with `reason`: queued writes reject, the sink's
+   * `abort` runs once a write in flight has finished. Rejects while the
+   * stream is locked.
+   */
+  abort(reason?: any): Promise<void>
+  /** Close the stream after the queued writes. Rejects while the stream is locked. */
+  close(): Promise<void>
+}
+
+interface TransformStreamDefaultController<O = any> {
+  /** The readable side's room for chunks; null once it is errored. */
+  readonly desiredSize: number | null
+  /** Queue a chunk on the readable side. */
+  enqueue(chunk: O): void
+  /** Error both sides with `e`. */
+  error(e?: any): void
+  /** Close the readable side and error the writable side. */
+  terminate(): void
+}
+
+/** What `new TransformStream(transformer)` takes. Each method is optional. */
+interface Transformer<I = any, O = any> {
+  /** Runs at construction; a returned promise delays the first chunk. */
+  start?(controller: TransformStreamDefaultController<O>): any
+  /**
+   * Receives each written chunk, to enqueue zero or more chunks on the
+   * readable side. Absent, chunks pass through unchanged. A throw errors
+   * both sides.
+   */
+  transform?(chunk: I, controller: TransformStreamDefaultController<O>): any
+  /** Runs when the writable side closes, before the readable side does. */
+  flush?(controller: TransformStreamDefaultController<O>): any
+}
+
+declare class TransformStream<I = any, O = any> {
+  /**
+   * Strategies are chunk counts: the writable side's defaults to 1, the
+   * readable side's to 0, so a chunk is transformed as the reader asks. A
+   * write waits while the readable side's queue is full.
+   */
+  constructor(transformer?: Transformer<I, O>, writableStrategy?: QueuingStrategy, readableStrategy?: QueuingStrategy)
+  readonly readable: ReadableStream<O>
+  readonly writable: WritableStream<I>
+}
+
+/**
+ * A TransformStream from UTF-8 bytes (Uint8Array or ArrayBuffer chunks) to
+ * strings: a {@link TextDecoder} in `stream` mode, so a multibyte sequence
+ * split across chunks decodes whole. Chunks that decode to nothing are not
+ * enqueued.
+ */
+declare class TextDecoderStream {
+  /** As the {@link TextDecoder} constructor: UTF-8 labels only. */
+  constructor(label?: string, options?: TextDecoderOptions)
+  /** Always "utf-8". */
+  readonly encoding: string
+  readonly fatal: boolean
+  readonly ignoreBOM: boolean
+  readonly readable: ReadableStream<string>
+  readonly writable: WritableStream<Uint8Array | ArrayBuffer>
+}
+
+/**
+ * A TransformStream from strings to their UTF-8 bytes. A chunk ending in a
+ * high surrogate holds that half for the next chunk, so a surrogate pair
+ * split across chunks encodes as one character.
+ */
+declare class TextEncoderStream {
+  /** Always "utf-8". */
+  readonly encoding: string
+  readonly readable: ReadableStream<Uint8Array>
+  readonly writable: WritableStream<string>
+}

package/standards/text.d.ts

@@ -1,4 +1,5 @@
 // TextEncoder / TextDecoder. UTF-8 only (the only encoding the runtime needs).
+// Their stream forms, TextEncoderStream / TextDecoderStream, are in streams.d.ts.
 
 interface TextEncoder {
   /** Always "utf-8". */

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.