@promptctl/rich-js 0.26.0 → 0.27.0

package/dist/core/animation.d.ts

@@ -137,14 +137,23 @@ export declare function stampFrame(segments: Iterable<Segment>, hold: Hold): Ite
  */
 export declare function frameTimeOf(options: RenderOptions): number;
 /**
- * An animation's face, `render`: drawn at the time of the frame it is drawn
- * in (`frameTimeOf`), the value `shownAt` picks, every segment stamped with
- * its hold there under whatever its own cells say, and the hold told to the
- * frame (`RenderOptions.onHold`), because a frame of no cells — an element
- * not yet entered — may have cells later, and must say when without taking a
- * row to say it in. A container — the library's or a user's — that draws its
- * children through `render` draws an animation among them with no word about
- * time: the hold goes back the way the time came in. [LAW:composability]
+ * An animation placed in the frame `options` draws: its value at the frame's
+ * time (`frameTimeOf`, `shownAt`), drawn by `draw`, every segment stamped
+ * with its hold there under whatever its own cells say, and the hold told to
+ * the frame (`RenderOptions.onHold`), because a frame of no cells — an
+ * element not yet entered — may have cells later, and must say when without
+ * taking a row to say it in. [LAW:single-enforcer] The one placement: an
+ * animation of renderables (`placedRender`) and a widget drawing one cell
+ * from an animation of its own (a caret's blink) place through it, so how a
+ * time reaches an animation and how its hold reaches the frame is written
+ * once.
+ */
+export declare function placed<T>(animation: Timed<T>, options: RenderOptions, draw: (value: T) => Iterable<Segment>): Iterable<Segment>;
+/**
+ * An animation's face, `render`: `placed`, its value drawn as the renderable
+ * it is. A container — the library's or a user's — that draws its children
+ * through `render` draws an animation among them with no word about time:
+ * the hold goes back the way the time came in. [LAW:composability]
  */
 export declare function placedRender(animation: Timed<unknown>, options: RenderOptions): Iterable<Segment>;
 /**
@@ -169,6 +178,15 @@ export declare const Animation: {
      * renderables throws when it is drawn.
      */
     of<X extends Timed<unknown>>(timed: X): Faced<NoInfer<X>>;
+    /**
+     * Whether `animation` never changes again from `t`: a one-shot that has
+     * run, a loop at a depth that shows no motion. [LAW:single-enforcer] The
+     * one reading of "never": a `Transition`'s `done` and a lifecycle's
+     * arrived and gone moments are this, so what ends a one-shot is written
+     * once. An early answer the contract allows is a finite one, so `Infinity`
+     * is only ever a true never.
+     */
+    done(animation: Timed<unknown>, t: number): boolean;
     /** `value` at every time, never changing. */
     constant<T>(value: T): Animation<T>;
     /**

package/dist/core/animation.js

@@ -126,22 +126,32 @@ function drawable(value) {
     return value;
 }
 /**
- * An animation's face, `render`: drawn at the time of the frame it is drawn
- * in (`frameTimeOf`), the value `shownAt` picks, every segment stamped with
- * its hold there under whatever its own cells say, and the hold told to the
- * frame (`RenderOptions.onHold`), because a frame of no cells — an element
- * not yet entered — may have cells later, and must say when without taking a
- * row to say it in. A container — the library's or a user's — that draws its
- * children through `render` draws an animation among them with no word about
- * time: the hold goes back the way the time came in. [LAW:composability]
+ * An animation placed in the frame `options` draws: its value at the frame's
+ * time (`frameTimeOf`, `shownAt`), drawn by `draw`, every segment stamped
+ * with its hold there under whatever its own cells say, and the hold told to
+ * the frame (`RenderOptions.onHold`), because a frame of no cells — an
+ * element not yet entered — may have cells later, and must say when without
+ * taking a row to say it in. [LAW:single-enforcer] The one placement: an
+ * animation of renderables (`placedRender`) and a widget drawing one cell
+ * from an animation of its own (a caret's blink) place through it, so how a
+ * time reaches an animation and how its hold reaches the frame is written
+ * once.
  */
-export function* placedRender(animation, options) {
+export function* placed(animation, options, draw) {
     const t = frameTimeOf(options);
     const shown = shownAt(animation, t, options);
-    const value = drawable(shown.value);
     const hold = holdOf(shown, t);
     options.onHold?.(hold);
-    yield* stampFrame(render(value, options), hold);
+    yield* stampFrame(draw(shown.value), hold);
+}
+/**
+ * An animation's face, `render`: `placed`, its value drawn as the renderable
+ * it is. A container — the library's or a user's — that draws its children
+ * through `render` draws an animation among them with no word about time:
+ * the hold goes back the way the time came in. [LAW:composability]
+ */
+export function placedRender(animation, options) {
+    return placed(animation, options, (value) => render(drawable(value), options));
 }
 /**
  * An animation's face, `measure`: what it shows at the frame's time, measured,
@@ -191,6 +201,17 @@ export const Animation = {
         });
         return faced;
     },
+    /**
+     * Whether `animation` never changes again from `t`: a one-shot that has
+     * run, a loop at a depth that shows no motion. [LAW:single-enforcer] The
+     * one reading of "never": a `Transition`'s `done` and a lifecycle's
+     * arrived and gone moments are this, so what ends a one-shot is written
+     * once. An early answer the contract allows is a finite one, so `Infinity`
+     * is only ever a true never.
+     */
+    done(animation, t) {
+        return animation.nextChange(t) === Number.POSITIVE_INFINITY;
+    },
     /** `value` at every time, never changing. */
     constant(value) {
         const still = Animation.of({ at: () => value, nextChange: () => Number.POSITIVE_INFINITY, lastChange: () => Number.NEGATIVE_INFINITY, reduced: () => still });

package/dist/core/color.d.ts

@@ -2,6 +2,7 @@
  * Terminal color representation, parsing, downgrading, and ANSI code generation.
  */
 import type { Env } from "./env.js";
+import type { Palette } from "../themes/palette.js";
 /**
  * Immutable RGBA color value. Alpha defaults to 1 (fully opaque).
  *
@@ -244,7 +245,7 @@ export declare class ColorSpec {
     /**
      * Resolves to an actual RGB(A) value for any color type.
      */
-    getTruecolor(theme?: TerminalTheme, foreground?: boolean): ColorRgba;
+    getTruecolor(theme?: TerminalColors, foreground?: boolean): ColorRgba;
     static default(): ColorSpec;
     static fromAnsi(n: number): ColorSpec;
     static fromRgba(value: ColorRgba): ColorSpec;
@@ -275,7 +276,7 @@ export declare class ColorSpec {
      * `value` is opaque: a translucent colour has no one look until it is laid
      * on a ground (`flattenAlpha`).
      */
-    static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec;
+    static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalColors, foreground: boolean): ColorSpec;
     /**
      * Every colour `depth` writes by index, each with the colour a terminal
      * known to show `theme` draws it in, lowest index first: the theme's
@@ -285,7 +286,7 @@ export declare class ColorSpec {
      * depth only the default, so neither writes any by index. The colours
      * `matchOn` rounds to, but for the default, read off the same two tables.
      */
-    static indexed(depth: ColorDepth, theme: TerminalTheme): readonly (readonly [ColorSpec, ColorRgba])[];
+    static indexed(depth: ColorDepth, theme: TerminalColors): readonly (readonly [ColorSpec, ColorRgba])[];
     /**
      * The spec a slot is written in once its colour moves from `was`, what its
      * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or
@@ -294,7 +295,7 @@ export declare class ColorSpec {
      * off any colour the depth can write — a theme slot, the default colour,
      * the cube — keeps the spec it was written in.
      */
-    static matchMove(was: ColorRgba, now: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec | undefined;
+    static matchMove(was: ColorRgba, now: ColorRgba, depth: ColorDepth, theme: TerminalColors, foreground: boolean): ColorSpec | undefined;
     /**
      * Parse a color string. Memoized (`Memo`): a string parsed again while
      * remembered returns the same instance.
@@ -312,6 +313,17 @@ export declare function parseRgbaHex(hex: string): ColorRgba;
  */
 export declare function parseHexColor(literal: string): ColorRgba;
 export declare function blendRgb(color1: ColorRgba, color2: ColorRgba, crossFade?: number): ColorRgba;
+/**
+ * What a terminal draws with: the part of a `TerminalTheme` a colour resolves
+ * against.
+ */
+export declare class TerminalColors {
+    readonly backgroundColor: ColorRgba;
+    readonly foregroundColor: ColorRgba;
+    readonly ansiColors: ColorTable;
+    private readonly checked;
+    constructor(backgroundColor: ColorRgba, foregroundColor: ColorRgba, ansiColors: ColorTable);
+}
 /**
  * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
  * and a semantic palette.
@@ -321,12 +333,9 @@ export declare function blendRgb(color1: ColorRgba, color2: ColorRgba, crossFade
  * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
  * as it is in Rich, where each `TerminalTheme` carries its own table.
  */
-export declare class TerminalTheme {
-    readonly backgroundColor: ColorRgba;
-    readonly foregroundColor: ColorRgba;
-    readonly ansiColors: ColorTable;
-    readonly palette: import("../themes/palette.js").Palette;
-    constructor(backgroundColor: ColorRgba, foregroundColor: ColorRgba, ansiColors: ColorTable, palette: import("../themes/palette.js").Palette);
+export declare class TerminalTheme extends TerminalColors {
+    readonly palette: Palette;
+    constructor(backgroundColor: ColorRgba, foregroundColor: ColorRgba, ansiColors: ColorTable, palette: Palette);
 }
 export declare const STANDARD_TABLE: ColorTable;
 export declare const EIGHT_BIT_TABLE: ColorTable;
@@ -345,7 +354,7 @@ export declare const WINDOWS_TABLE: ColorTable;
  * that reads it. (Widgets fall back to `DEFAULT_TERMINAL_THEME`, which carries a
  * palette this does not.)
  */
-export declare function resolveTerminal(theme: TerminalTheme | undefined, depth: ColorDepth): TerminalTheme;
+export declare function resolveTerminal(theme: TerminalColors | undefined, depth: ColorDepth): TerminalColors;
 /**
  * The table a downgrade to `depth` rounds a fixed colour against.
  * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a colour is

package/dist/core/color.js

@@ -3,9 +3,6 @@
  */
 import { Memo, WeakMemo } from "./memo.js";
 import { pattern } from "./pattern.js";
-// Runtime-importing `Palette` from `themes/palette.ts` is safe: that module
-// only `import type`s from `core/color.ts`, so there is no runtime cycle.
-import { Palette } from "../themes/palette.js";
 // --- ColorRgba ---
 function hex2(byte) {
     return byte.toString(16).padStart(2, "0");
@@ -844,24 +841,17 @@ export function blendRgb(color1, color2, crossFade = 0.5) {
 }
 // --- TerminalTheme ---
 /**
- * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
- * and a semantic palette.
- *
- * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
- * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
- * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
- * as it is in Rich, where each `TerminalTheme` carries its own table.
+ * What a terminal draws with: the part of a `TerminalTheme` a colour resolves
+ * against.
  */
-export class TerminalTheme {
+export class TerminalColors {
     backgroundColor;
     foregroundColor;
     ansiColors;
-    palette;
-    constructor(backgroundColor, foregroundColor, ansiColors, palette) {
+    constructor(backgroundColor, foregroundColor, ansiColors) {
         this.backgroundColor = backgroundColor;
         this.foregroundColor = foregroundColor;
         this.ansiColors = ansiColors;
-        this.palette = palette;
         // [LAW:parse-dont-validate] Every reader indexes `ansiColors` 0–15 as the
         // terminal's sixteen, so a theme is the proof it holds exactly those.
         if (ansiColors.firstIndex !== 0 || ansiColors.size !== 16) {
@@ -869,6 +859,22 @@ export class TerminalTheme {
         }
     }
 }
+/**
+ * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
+ * and a semantic palette.
+ *
+ * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
+ * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
+ * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
+ * as it is in Rich, where each `TerminalTheme` carries its own table.
+ */
+export class TerminalTheme extends TerminalColors {
+    palette;
+    constructor(backgroundColor, foregroundColor, ansiColors, palette) {
+        super(backgroundColor, foregroundColor, ansiColors);
+        this.palette = palette;
+    }
+}
 // --- ColorTable data ---
 function buildStandard16() {
     return [
@@ -943,7 +949,7 @@ export const EIGHT_BIT_TABLE = new ColorTable(build256Table());
  */
 export const EIGHT_BIT_DOWNGRADE_TABLE = new ColorTable(build256Table().slice(16), 16);
 export const WINDOWS_TABLE = new ColorTable(buildWindowsTable());
-// --- Internal fallback theme ---
+// --- Internal fallback terminals ---
 //
 // [LAW:one-way-deps] Preset themes (DEFAULT_TERMINAL_THEME, MONOKAI, NORD, ...)
 // live in `src/themes/terminalThemes.ts` because they need `buildPalette` from
@@ -951,12 +957,11 @@ export const WINDOWS_TABLE = new ColorTable(buildWindowsTable());
 // `themes/* -> core/color`, with no runtime back-edge.
 //
 // `getTruecolor()` retains a fallback for callers that omit `theme`: the
-// terminal a colour's depth assumes, built from that depth's own sixteen with
-// an empty Palette — sufficient for the lookups it serves, which never read
-// `palette`.
-const INTERNAL_DEFAULT_THEME = new TerminalTheme(new ColorRgba(0, 0, 0), new ColorRgba(255, 255, 255), STANDARD_TABLE, new Palette("default", true, new Map()));
+// terminal a colour's depth assumes, its own sixteen and no palette, which the
+// lookups it serves never read.
+const INTERNAL_DEFAULT_TERMINAL = new TerminalColors(new ColorRgba(0, 0, 0), new ColorRgba(255, 255, 255), STANDARD_TABLE);
 /** The Windows console in its default Campbell scheme: a WINDOWS colour's terminal. */
-const WINDOWS_CONSOLE_THEME = new TerminalTheme(WINDOWS_TABLE.get(0), WINDOWS_TABLE.get(7), WINDOWS_TABLE, new Palette("windows", true, new Map()));
+const WINDOWS_CONSOLE_TERMINAL = new TerminalColors(WINDOWS_TABLE.get(0), WINDOWS_TABLE.get(7), WINDOWS_TABLE);
 /**
  * The terminal a colour at `depth` is drawn by: `theme`, or when a caller names
  * none, the one the depth assumes — the Windows console at WINDOWS, the VGA
@@ -965,7 +970,7 @@ const WINDOWS_CONSOLE_THEME = new TerminalTheme(WINDOWS_TABLE.get(0), WINDOWS_TA
  * palette this does not.)
  */
 export function resolveTerminal(theme, depth) {
-    return theme ?? (depth === ColorDepth.WINDOWS ? WINDOWS_CONSOLE_THEME : INTERNAL_DEFAULT_THEME);
+    return theme ?? (depth === ColorDepth.WINDOWS ? WINDOWS_CONSOLE_TERMINAL : INTERNAL_DEFAULT_TERMINAL);
 }
 /**
  * The table a downgrade to `depth` rounds a fixed colour against.

package/dist/core/console.d.ts

@@ -10,6 +10,7 @@ import { type JSONOptions } from "./json.js";
 import type { Highlighter } from "./highlighter.js";
 import { type RuleOptions } from "../renderables/rule.js";
 import type { Height, OverflowMethod, RenderOptions, StyleErrorHandler } from "./protocol.js";
+import { type HostFrame } from "./protocol.js";
 import type { Unsubscribe } from "./subscription.js";
 export interface ConsoleSink {
     write(chunk: string | Uint8Array): unknown;
@@ -125,6 +126,13 @@ export interface ConsoleOptions {
 }
 export interface PrintOptions {
     style?: string | Style;
+    /**
+     * The frame this print is drawn in (`RenderOptions.frame`): the moment
+     * everything in it that moves is drawn for, named by the caller — a host's
+     * `frameNow()`. [LAW:single-enforcer] The one place a print's time is
+     * decided; absent, the print is drawn for no moment, 0 (`frameTimeOf`).
+     */
+    frame?: HostFrame;
     justify?: "default" | "left" | "center" | "right" | "full";
     overflow?: OverflowMethod;
     highlight?: boolean;

package/dist/core/console.js

@@ -317,7 +317,7 @@ export class Console {
             !isRenderable(lastArg) &&
             ("style" in lastArg || "justify" in lastArg || "markup" in lastArg ||
                 "highlight" in lastArg || "overflow" in lastArg || "end" in lastArg ||
-                "softWrap" in lastArg || "crop" in lastArg || "sep" in lastArg)) {
+                "softWrap" in lastArg || "crop" in lastArg || "sep" in lastArg || "frame" in lastArg)) {
             opts = lastArg;
             items = args.slice(0, -1);
         }
@@ -407,6 +407,7 @@ export class Console {
         const renderOpts = {
             ...options,
             ...strings,
+            frame: opts.frame,
             justify: opts.justify === "default" ? undefined : opts.justify,
             overflow: opts.overflow ?? (softWrap ? "ignore" : undefined),
             noWrap: softWrap,

package/dist/core/easing.js

@@ -379,7 +379,12 @@ export function passAt(what, t, period) {
     // takes off; carrying a pass's start out of `t` itself would leave each
     // sample its own rounding. `+ 0` turns the `-0` a small negative `t` rounds
     // to into pass 0, so the pass is a plain integer whoever reads it.
-    return { pass: Math.round((t - into) / period) + 0, into };
+    const pass = Math.round((t - into) / period) + 0;
+    // [LAW:no-silent-failure] Past where a pass is a float, `period` is finer than time resolves: the refusal a
+    // boundary walked there gives, said of `t` and not of the infinite sum a pass that overflowed would build.
+    if (!Number.isFinite(pass))
+        throw new RangeError(`${what}: a period of ${period} s is finer than time resolves near t = ${t}`);
+    return { pass, into };
 }
 /** The least normal double, 2^-1022: below it every double is a multiple of `Number.MIN_VALUE`. */
 const MIN_NORMAL = 2 ** -1022;

package/dist/core/oklch.d.ts

@@ -64,6 +64,8 @@ export declare const INVERT_LIGHTNESS: ThemeKey;
  * the predicate lives once, here.
  */
 export declare function isIdentityKey(k: ThemeKey): boolean;
+export declare function srgbToLinear(v: number): number;
+export declare function linearToSrgb(v: number): number;
 /**
  * Immutable OKLCH color. `l` ∈ [0, 1] (lightness), `c` ≥ 0 (chroma; typical
  * sRGB-representable colors top out near 0.32), `h` ∈ [0, 360) (hue

package/dist/core/oklch.js

@@ -57,12 +57,12 @@ export function isIdentityKey(k) {
         k.lightnessShift === 0);
 }
 // ---------------------------------------------------------------------------
-// Pure conversion helpers (private).
+// Pure conversion helpers.
 // ---------------------------------------------------------------------------
-function srgbToLinear(v) {
+export function srgbToLinear(v) {
     return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
 }
-function linearToSrgb(v) {
+export function linearToSrgb(v) {
     return v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
 }
 function clamp01(v) {

package/dist/core/protocol.d.ts

@@ -18,13 +18,27 @@ import type { Highlighter } from "./highlighter.js";
  */
 export type OverflowMethod = "fold" | "crop" | "ellipsis" | "ignore";
 /**
- * What draws frames — a `Live`, an `App` — as what draws in them sees it:
- * the time a frame drawn now is drawn for, the host's clock read through its
- * timeline for a view on it (`frameTime`, `./view.ts`). Not a `Clock`: under
- * a paused timeline it holds, and under a reversed one it runs backwards.
+ * The frame being drawn, as a value: `time`, the moment it is drawn for, in
+ * seconds, on the clock its cells' `nextChange` stamps are read on, and
+ * `host`, the identity of what drew it — nothing to read, so what draws in
+ * the frame has one time, this one, and cannot ask the host for another.
+ * [LAW:types-are-the-program] A `Progress` keeps the identity to refuse a
+ * frame of a host other than the one its tasks are timed on.
+ */
+export interface HostFrame {
+    readonly time: number;
+    readonly host: object;
+}
+/**
+ * What draws frames — a `Live`, an `App` — as what runs between them sees
+ * it: the frame it would draw now, its time the host's clock read through
+ * its timeline (`frameNow`, `./view.ts`). Not a `Clock`: under a paused
+ * timeline it holds, and under a reversed one it runs backwards. Asked
+ * inside a render it throws (`RenderClockError`): a frame has the time it was
+ * drawn for, and a renderable reads that one.
  */
 export interface FrameHost {
-    readonly frameTime: number;
+    frameNow(): HostFrame;
 }
 export interface RenderOptions {
     /**
@@ -105,18 +119,14 @@ export interface RenderOptions {
      */
     reducedMotion?: boolean;
     /**
-     * The frame being drawn: `time`, the moment it is drawn for, in seconds, on
-     * the clock its cells' `nextChange` stamps are read on, and `host`, the
-     * host drawing it, whose `frameTime` that moment was. It is how a
-     * renderable that lives across frames — a widget, a `Progress` — draws for
-     * the time without being rebuilt each frame with one, and without reading
-     * a clock. Absent, the frame is drawn for no moment — a `print` — and
-     * nothing drawn from it moves.
+     * The frame being drawn (`HostFrame`): how a renderable that lives across
+     * frames — a widget, a `Progress` — draws for the time without being
+     * rebuilt each frame with one, and without reading a clock. A host writes
+     * it once a frame, and a print writes the one its caller named
+     * (`PrintOptions.frame`). Absent, the frame is drawn for no moment, 0
+     * (`frameTimeOf`, `./animation.ts`), and nothing drawn from it moves.
      */
-    frame?: {
-        readonly time: number;
-        readonly host: FrameHost;
-    };
+    frame?: HostFrame;
     /**
      * Told of every renderable `render` is asked for, as it is asked, so the
      * calls arrive in document order: a container before what it holds, what

package/dist/core/render.d.ts

@@ -49,7 +49,7 @@ import type { ColorSystemName, Destination } from "./color.js";
 import type { Env } from "./env.js";
 import { Segment } from "./segment.js";
 import type { Renderable, RenderOptions } from "./protocol.js";
-export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "reducedMotion" | "theme" | "onStyleError" | "highlight" | "highlighter"> {
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "reducedMotion" | "theme" | "onStyleError" | "highlight" | "highlighter" | "frame"> {
     /** Cell width to render into. Default 80. */
     width?: number;
     /**

package/dist/core/render.js

@@ -118,6 +118,7 @@ export function renderToString(renderable, options) {
         onStyleError: options?.onStyleError,
         highlight: options?.highlight,
         highlighter: options?.highlighter,
+        frame: options?.frame,
         // [LAW:one-source-of-truth] The depth the segments below are encoded at,
         // so a renderable measures what this very call will draw.
         colorSystem: destination.colorSystem,

package/dist/core/view.d.ts

@@ -36,7 +36,7 @@
  * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
  * [LAW:one-way-deps]
  */
-import { type FrameHost, type Renderable, type RenderOptions } from "./protocol.js";
+import { type HostFrame, type Renderable, type RenderOptions } from "./protocol.js";
 import { Segment } from "./segment.js";
 import { Timeline } from "./timeline.js";
 /**
@@ -61,12 +61,26 @@ export interface HostTime {
 /**
  * The time a frame drawn at `time` is drawn for, on the clock its cells are
  * stamped on: the time the timeline maps `now` to. [LAW:single-enforcer]
- * `drawView` draws at it and hands it to the frame as
- * `RenderOptions.frame`, and a host reads it here for anything heard between
- * frames — a key — so a moment a widget keeps and the frame it is compared
- * against are on one clock.
+ * `frameNow` puts it on the frame `drawView` draws and on the one a host
+ * hands out between frames (`frameNow`) — what a key is stamped with — so a
+ * moment a widget keeps and the frame it is compared against are on one
+ * clock.
  */
 export declare function frameTime(time: HostTime): number;
+/** A host's frame was asked for during a render or measure. */
+export declare class RenderClockError extends Error {
+    constructor();
+}
+/**
+ * The frame `host` draws now, at `time`: what every host hands out as
+ * `frameNow()`, and what `drawView` draws. [LAW:single-enforcer] The one
+ * place a host's time is read for a frame, so the one place it is refused
+ * inside a render or measure (`RenderClockError`): a renderable drawing in a
+ * frame has that frame's time and asks nothing else, as `State.set` is
+ * refused there (`./state.ts`). A frame is a value with no clock on it, so a
+ * renderable handed one cannot read a second, moving time mid-render.
+ */
+export declare function frameNow(host: object, time: HostTime): HostFrame;
 /** What a frame drawn at host time `t` says about when it changes. */
 export interface FrameSays {
     /** The host time the frame was drawn at. */
@@ -86,7 +100,7 @@ export declare const undrawn: (t: number) => FrameSays;
  * overflow — and when the frame changes on the host's clock: the hold its
  * cells say, carried back through the timeline. [LAW:one-source-of-truth]
  * `options` is the one place the frame reads the reader's preference for
- * motion, handed on to `draw` with the frame: the time it is drawn for
- * (`frameTime`) and `drawnBy`, the host whose time that is.
+ * motion, handed on to `draw` with the frame (`frameNow`): the time it is
+ * drawn for and `drawnBy`, the host whose time that is.
  */
-export declare function drawView(view: Renderable, time: HostTime, drawnBy: FrameHost, options: RenderOptions, draw: (renderable: Renderable, options: RenderOptions) => Segment[][]): DrawnView;
+export declare function drawView(view: Renderable, time: HostTime, drawnBy: object, options: RenderOptions, draw: (renderable: Renderable, options: RenderOptions) => Segment[][]): DrawnView;

package/dist/core/view.js

@@ -36,7 +36,7 @@
  * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
  * [LAW:one-way-deps]
  */
-import { render } from "./protocol.js";
+import { activePass, render } from "./protocol.js";
 import { Segment } from "./segment.js";
 import { Timeline } from "./timeline.js";
 /** `view` as the renderable a host holds: a function is asked each time it is drawn. */
@@ -46,14 +46,36 @@ export function hostView(view) {
 /**
  * The time a frame drawn at `time` is drawn for, on the clock its cells are
  * stamped on: the time the timeline maps `now` to. [LAW:single-enforcer]
- * `drawView` draws at it and hands it to the frame as
- * `RenderOptions.frame`, and a host reads it here for anything heard between
- * frames — a key — so a moment a widget keeps and the frame it is compared
- * against are on one clock.
+ * `frameNow` puts it on the frame `drawView` draws and on the one a host
+ * hands out between frames (`frameNow`) — what a key is stamped with — so a
+ * moment a widget keeps and the frame it is compared against are on one
+ * clock.
  */
 export function frameTime(time) {
     return Timeline.at(time.timeline, time.now);
 }
+/** A host's frame was asked for during a render or measure. */
+export class RenderClockError extends Error {
+    constructor() {
+        super("a host's frame was asked for during a render or measure. A frame has one time, the one it is drawn for: " +
+            "read it from the render options' `frame`, or ask the host between frames.");
+        this.name = "RenderClockError";
+    }
+}
+/**
+ * The frame `host` draws now, at `time`: what every host hands out as
+ * `frameNow()`, and what `drawView` draws. [LAW:single-enforcer] The one
+ * place a host's time is read for a frame, so the one place it is refused
+ * inside a render or measure (`RenderClockError`): a renderable drawing in a
+ * frame has that frame's time and asks nothing else, as `State.set` is
+ * refused there (`./state.ts`). A frame is a value with no clock on it, so a
+ * renderable handed one cannot read a second, moving time mid-render.
+ */
+export function frameNow(host, time) {
+    if (activePass() !== undefined)
+        throw new RenderClockError();
+    return { time: frameTime(time), host };
+}
 /** What a frame not yet drawn at host time `t` says: nothing. */
 export const undrawn = (t) => ({ t, nextChange: Number.POSITIVE_INFINITY });
 /** The hold of the frame `lines` draw, told `told` besides: the intersection of its cells' holds and it. */
@@ -64,8 +86,8 @@ const frameHold = (lines, told) => lines.reduce((hold, row) => ({ lastChange: Ma
  * overflow — and when the frame changes on the host's clock: the hold its
  * cells say, carried back through the timeline. [LAW:one-source-of-truth]
  * `options` is the one place the frame reads the reader's preference for
- * motion, handed on to `draw` with the frame: the time it is drawn for
- * (`frameTime`) and `drawnBy`, the host whose time that is.
+ * motion, handed on to `draw` with the frame (`frameNow`): the time it is
+ * drawn for and `drawnBy`, the host whose time that is.
  */
 export function drawView(view, time, drawnBy, options, draw) {
     const { now: host, timeline } = time;
@@ -73,7 +95,9 @@ export function drawView(view, time, drawnBy, options, draw) {
     const onHold = (hold) => {
         told = { lastChange: Math.max(told.lastChange, hold.lastChange), nextChange: Math.min(told.nextChange, hold.nextChange) };
     };
-    const lines = draw(view, { ...options, frame: { time: frameTime(time), host: drawnBy }, onHold });
+    // Made before the render opens: the one time the frame has.
+    const frame = frameNow(drawnBy, time);
+    const lines = draw(view, { ...options, frame, onHold });
     const hold = frameHold(lines, told);
     // The frame as the sample of the view it is, on the timeline's clock; the
     // timeline says when the host's clock leaves its hold.

package/dist/host/app.d.ts

@@ -34,7 +34,7 @@ import { type Clock, type FrameRate } from "../core/clock.js";
 import { type ConsoleOptions } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { type Surface } from "../core/paint.js";
-import { type FrameHost } from "../core/protocol.js";
+import { type HostFrame, type FrameHost } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import { Timeline } from "../core/timeline.js";
 import { type View } from "../core/view.js";
@@ -149,12 +149,12 @@ export declare class App implements FrameHost {
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
     /**
-     * The time a frame drawn now is drawn for (`RenderOptions.frame`): the
-     * clock's now, through the timeline. What a moment heard
+     * The frame this app draws now (`FrameHost`): the clock's now, through the
+     * timeline, on a frame it is the host of. Its time is what a moment heard
      * between frames — a key — is stamped with, so it is on the clock the
      * frame is.
      */
-    get frameTime(): number;
+    frameNow(): HostFrame;
     private _time;
     /**
      * Take the terminal, paint the first frame, and resolve when the app stops

package/dist/host/app.js

@@ -36,7 +36,7 @@ import { Segment } from "../core/segment.js";
 import { SurfacePainter } from "../core/paint.js";
 import { fitHeight, render } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
-import { drawView, frameTime, hostView, undrawn } from "../core/view.js";
+import { drawView, frameNow, hostView, undrawn } from "../core/view.js";
 import { hostEnvironment } from "./host-environment.js";
 import { InputParser, keyName, parseKeyName } from "./input.js";
 // [LAW:one-source-of-truth] How a frame draws — its glyphs, the style names
@@ -153,13 +153,13 @@ export class App {
         return this._frame;
     }
     /**
-     * The time a frame drawn now is drawn for (`RenderOptions.frame`): the
-     * clock's now, through the timeline. What a moment heard
+     * The frame this app draws now (`FrameHost`): the clock's now, through the
+     * timeline, on a frame it is the host of. Its time is what a moment heard
      * between frames — a key — is stamped with, so it is on the clock the
      * frame is.
      */
-    get frameTime() {
-        return frameTime(this._time());
+    frameNow() {
+        return frameNow(this, this._time());
     }
     _time() {
         return { now: this._clock.now(), epoch: this._epoch, timeline: this._timeline };