@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/text.js

@@ -1,15 +1,18 @@
 /**
  * RichText — styled text with spans. The primary text type for the library.
  */
-import { cellLen, cellCount, cellFit, cellFitEnd, asCellCol } from "./cells.js";
-import { divideLine } from "./wrap.js";
+import { cellLen, cellCount, cellFit, cellFitEnd, asCellCol, expandTabs, parseTabSize } from "./cells.js";
+import { divideLine, wordWidths } from "./wrap.js";
 import { Segment } from "./segment.js";
 import { Style, NULL_STYLE, StyleSyntaxError } from "./style.js";
 import { stripOscTerminators } from "./osc8.js";
 import { drawable, getStyle, withBoundedWidth } from "./protocol.js";
-// Strip control characters except \t and \n
+// Every C0 control and DEL except \t and \n. Rich's `Text` strips only
+// `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR); the rest of the set is the
+// port's extension, so no C0 byte of content can start an escape sequence or
+// move the cursor on the wire. C1 controls (U+0080–U+009F) pass, as in Rich.
 // [LAW:single-enforcer] Single place where control chars are sanitized
-const CONTROL_CHARS_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+const CONTROL_CHARS_RE = /[\x00-\x08\x0B-\x1F\x7F]/g;
 export function stripControlChars(text) {
     return text.replace(CONTROL_CHARS_RE, "");
 }
@@ -64,8 +67,8 @@ function sanitizeStyleLink(style) {
  * A style as a RichText keeps it: as given. A name stays a name because what
  * it stands for depends on the theme of the render that draws it, which no
  * RichText knows when the name arrives — the reference stores span styles the
- * same way. A string holds no link until it is parsed, so only a `Style` has
- * one to sanitize here.
+ * same way. A string holds no link until it is parsed, so only a `Style` —
+ * alone or laid over a name — has one to sanitize here.
  *
  * [LAW:single-enforcer] Nor does a RichText keep an anchor (`./anchor.ts`). It
  * lays its text out anew, so a stamp naming where a cell sat in the output it
@@ -73,8 +76,13 @@ function sanitizeStyleLink(style) {
  * owner that renders the RichText is the one that stamps its cells.
  */
 function admitStyle(style) {
-    if (!(style instanceof Style))
+    if (typeof style === "string")
         return style;
+    if (style instanceof Style)
+        return admitDefined(style);
+    return { under: style.under, over: admitDefined(style.over) };
+}
+function admitDefined(style) {
     return sanitizeStyleLink(style.anchor ? style.withAnchor(undefined) : style);
 }
 /** A style that adds nothing: the empty definition, or a null `Style`. */
@@ -82,13 +90,16 @@ function isEmptyStyle(style) {
     return style instanceof Style ? style.isNull : style === "";
 }
 /**
- * The style a stored `string | Style` stands for in this render.
+ * The style a stored `TextStyle` stands for in this render.
  *
  * A parsed string can carry a link, so the result is sanitized on the way out
  * as well.
  */
-function resolveStyle(options, style) {
-    return sanitizeStyleLink(style instanceof Style ? style : resolveDefinition(options, style));
+export function resolveStyle(options, style) {
+    const resolved = style instanceof Style ? style
+        : typeof style === "string" ? resolveDefinition(options, style)
+            : resolveDefinition(options, style.under).add(style.over);
+    return sanitizeStyleLink(resolved);
 }
 /**
  * [LAW:single-enforcer] Styling is non-critical — an unrecognized style name
@@ -163,7 +174,7 @@ export class RichText {
         this._justify = options?.justify;
         this._overflow = options?.overflow;
         this._end = options?.end ?? "\n";
-        this._tabSize = options?.tabSize ?? 8;
+        this._tabSize = parseTabSize(options?.tabSize ?? 8);
         this._noWrap = options?.noWrap ?? false;
     }
     // --- Properties ---
@@ -182,13 +193,21 @@ export class RichText {
     get length() {
         return this._text.length;
     }
+    /**
+     * The cells of the plain text with each tab widened to its stop counted from
+     * this text's own column 0, as `render` widens it — so it is the drawn width
+     * of a one-line text set at a stop. A deliberate departure from Rich, whose
+     * `Text.cell_len` counts a tab as no cells, so everything sized by it — a
+     * truncation, an alignment, a header's remaining width — decided on a width
+     * no render draws.
+     */
     get cellLength() {
-        return cellLen(this._text);
+        return cellLen(expandTabs(this._text, this._tabSize).text);
     }
     get hasContent() {
         return this._text.length > 0;
     }
-    /** The base style every span layers over: a `Style`, or a name resolved at render. */
+    /** The base style every span layers over, resolved at render unless it is a `Style`. */
     get style() {
         return this._style;
     }
@@ -458,6 +477,17 @@ export class RichText {
         this._text = padding + this._text + padding;
         return this;
     }
+    /**
+     * Each tab widened to the next tab stop, in place, as Rich's
+     * `Text.expand_tabs` widens it: spans move with the characters they style, so
+     * the text measures what it will draw.
+     */
+    expandTabs() {
+        const expanded = expandTabs(this._text, this._tabSize);
+        this._spans = this._spans.map((s) => new Span(expanded.offsetOf(s.start), expanded.offsetOf(s.end), s.style));
+        this._text = expanded.text;
+        return this;
+    }
     padLeft(count, char) {
         const c = char ?? " ";
         this._spans = this._spans.map((s) => s.move(count));
@@ -506,6 +536,10 @@ export class RichText {
      * styling; the marker (if any) is inserted as plain text with no span.
      * Use `stylize(...)` on the result to color the marker if needed.
      *
+     * Text that fits comes back untouched. Text that is cut has its tabs widened
+     * to their stops first, as `expandTabs` widens them, so the width cut to is
+     * the width drawn.
+     *
      * [LAW:dataflow-not-control-flow] mode/marker/width all flow as values;
      * the walk is the same shape regardless. No "if truncated then rebuild"
      * branch \u2014 the unchanged path just early-returns when content fits.
@@ -513,6 +547,9 @@ export class RichText {
     truncate(width, options) {
         if (this.cellLength <= width)
             return this;
+        // [LAW:one-source-of-truth] Cut what is drawn: once a tab is spaces, a cell
+        // of the plain text is a cell of the output, so the cut lands where it looks.
+        this.expandTabs();
         const mode = options?.mode ?? "right";
         // [LAW:dataflow-not-control-flow] the marker is fitted to the width as a
         // value, so width 0 and a marker wider than the width run the same walk
@@ -592,6 +629,9 @@ export class RichText {
         const currentWidth = this.cellLength;
         if (currentWidth >= width)
             return this;
+        // Padded to `width`, the text claims that width only while its tab stops
+        // hold: widened now, padding on either side cannot move them.
+        this.expandTabs();
         const gap = width - currentWidth;
         switch (justify) {
             case "left":
@@ -670,9 +710,17 @@ export class RichText {
     }
     // --- Renderable ---
     *render(options) {
-        const text = this._expandTabs(this._text);
+        const expanded = expandTabs(this._text, this._tabSize);
         const base = this.resolvedStyle(options);
-        const allSegments = this._buildSegments(text, base, options);
+        const { segments: allSegments, covered } = this._buildSegments(expanded, base, options);
+        const spanFree = spanFreeLines(allSegments, covered);
+        // Rich wraps the lines of `split(allow_blank=True)`: n line breaks make
+        // n + 1 lines, the last one blank when the text ends in a break, and that
+        // blank line is justified like any other. `Segment.splitLines` is Rich's
+        // `Segment.split_lines`, which drops a trailing empty line, so the text is
+        // handed to it closed by one more break — the dropped line is then always
+        // that one, and every line the text has comes back.
+        allSegments.push(Segment.line());
         const logicalLines = Segment.splitLines(allSegments);
         // [LAW:single-enforcer] The one crossing for this renderable's width, and
         // the call every other renderable already makes. A bare `cellCount` stood
@@ -703,16 +751,19 @@ export class RichText {
         const justify = overflow === "ignore" ? undefined : this._justify ?? options.justify;
         // One cell either way, so the marker's stand-in leaves the cut where it was.
         const ellipsis = drawable(options, "\u2026", ".");
-        const endsWithNewline = text.endsWith("\n");
         for (let index = 0; index < logicalLines.length; index += 1) {
             const line = logicalLines[index];
-            const terminateLine = index < logicalLines.length - 1 || endsWithNewline;
+            const free = spanFree[index];
+            const terminateLine = index < logicalLines.length - 1;
             // Wrap first, overflow last — the reference's order, and the reason a
             // long sentence grows a table row while an unbreakable word in the same
             // column still ellipsizes.
             const cuts = divideLine(plainOf(line), wrapAt, { fold: overflow === "fold" });
             const wrapped = Segment.divide(line, cuts);
-            const placed = this._justifyLines(wrapped.map((piece) => [...this._fitLine(piece, edge, overflow, ellipsis)]), maxWidth, base, justify);
+            const placed = this._justifyLines(wrapped.map((piece, at) => ({
+                segments: [...this._fitLine(piece, edge, overflow, ellipsis)],
+                free: (cell) => free(at === 0 ? cell : cuts[at - 1] + cell),
+            })), maxWidth, base, justify);
             for (let piece = 0; piece < placed.length; piece += 1) {
                 yield* placed[piece];
                 if (piece < placed.length - 1 || terminateLine) {
@@ -724,29 +775,23 @@ export class RichText {
         // non-empty text alike — the pre-fix code checked it once for empty text
         // (truthy) and again for non-empty text (truthy and not the default
         // "\n"), which gave `end` two meanings depending on whether the text was
-        // empty (rich-text-5ai). Empty text takes zero iterations of the loop
-        // above, so this is reached either way with nothing yielded but this.
+        // empty (rich-text-5ai).
         if (this._end) {
             yield new Segment(this._end);
         }
     }
     // --- Measurable ---
     measure(options) {
-        const text = this._expandTabs(this._text);
-        const lines = text.split("\n");
-        let maxLineWidth = 0;
-        let maxWordWidth = 0;
-        for (const line of lines) {
-            const lineWidth = cellLen(line);
-            maxLineWidth = Math.max(maxLineWidth, lineWidth);
-            // Minimum is the longest word
-            const words = line.split(/\s+/);
-            for (const word of words) {
-                if (word.length > 0) {
-                    maxWordWidth = Math.max(maxWordWidth, cellLen(word));
-                }
-            }
-        }
+        const lines = expandTabs(this._text, this._tabSize).text.split("\n");
+        const maxLineWidth = lines.reduce((widest, line) => Math.max(widest, cellLen(line)), 0);
+        // [LAW:one-source-of-truth] The minimum is the widest piece the wrapper
+        // never breaks, asked of the wrapper — so a line's indent, which wraps
+        // with its first word, counts toward it. Rich splits on whitespace here
+        // and drops the indent, then wraps with it kept: a container sized by
+        // that minimum cuts the word it was meant to hold whole. Text with no word
+        // at all is all whitespace, and as in Rich its whole width is the minimum.
+        const widths = lines.flatMap(wordWidths);
+        const maxWordWidth = widths.length > 0 ? widths.reduce((widest, w) => Math.max(widest, w), 0) : maxLineWidth;
         // Parsed for the same reason `render` parses it: an unparsed NaN ceiling
         // makes both `Math.min` calls NaN, and a range of NaN..NaN is one no parent
         // layout can divide.
@@ -757,11 +802,6 @@ export class RichText {
         };
     }
     // --- Internal ---
-    _expandTabs(text) {
-        if (!text.includes("\t"))
-            return text;
-        return text.replace(/\t/g, " ".repeat(this._tabSize));
-    }
     /**
      * The rendered text cut at every span edge, each piece carrying the base
      * style plus every span covering it.
@@ -787,27 +827,41 @@ export class RichText {
      * always did, and then folds into no piece at all: its range comes out empty
      * and no case handles it.
      */
-    _buildSegments(text, base, options) {
-        const clamp = (offset) => Math.max(0, Math.min(offset, text.length));
-        const positions = new Set([0, text.length]);
+    _buildSegments({ text, offsetOf }, base, options) {
+        // A span is written against the text as given; `offsetOf` moves its edges
+        // past every tab that widened before them.
+        const clamp = (offset) => Math.max(0, Math.min(offsetOf(offset), text.length));
+        // The text's own start and end are always the outer boundaries, even when
+        // they are one offset: empty text is one empty piece, as Rich's
+        // `Text.render` yields `Segment("")` for it. That piece writes no bytes,
+        // and it is what makes empty text one line to everything that splits a
+        // render into lines — a panel's body, a table cell — where Rich draws one.
+        const inner = new Set();
         for (const span of this._spans) {
-            positions.add(clamp(span.start));
-            positions.add(clamp(span.end));
+            inner.add(clamp(span.start));
+            inner.add(clamp(span.end));
         }
-        const boundaries = [...positions].sort((a, b) => a - b);
+        inner.delete(0);
+        inner.delete(text.length);
+        const boundaries = [0, ...[...inner].sort((a, b) => a - b), text.length];
         // Every span edge is a boundary, so where a span's range opens is a lookup
-        // rather than a search.
-        const pieceAt = new Map(boundaries.map((position, piece) => [position, piece]));
+        // rather than a search. Where two boundaries share an offset — empty
+        // text's start and end — the first wins, so the offset names the piece
+        // that opens there rather than the one past the last.
+        const pieceAt = new Map(boundaries.map((position, piece) => [position, piece]).reverse());
         const styles = boundaries.slice(0, -1).map(() => base);
+        const covered = styles.map(() => false);
         for (const span of this._spans) {
             const end = clamp(span.end);
             const style = resolveStyle(options, span.style);
             const opensAt = pieceAt.get(clamp(span.start));
             for (let piece = opensAt; boundaries[piece] < end; piece++) {
                 styles[piece] = styles[piece].add(style);
+                covered[piece] = true;
             }
         }
-        return styles.map((style, piece) => new Segment(text.slice(boundaries[piece], boundaries[piece + 1]), style.isNull ? undefined : style));
+        const segments = styles.map((style, piece) => new Segment(text.slice(boundaries[piece], boundaries[piece + 1]), style.isNull ? undefined : style));
+        return { segments, covered };
     }
     /**
      * The pieces one logical line wrapped into, each placed in a canvas
@@ -823,9 +877,9 @@ export class RichText {
      */
     _justifyLines(lines, maxWidth, base, justify) {
         if (justify !== "full") {
-            return lines.map((line) => [...this._justifyLine(line, maxWidth, justify)]);
+            return lines.map((line) => [...this._justifyLine(line, maxWidth, base, justify)]);
         }
-        return lines.map((line, index) => index === lines.length - 1 ? line : this._fillLine(line, maxWidth, base));
+        return lines.map(({ segments }, index) => index === lines.length - 1 ? segments : this._fillLine(segments, maxWidth, base));
     }
     /**
      * One line placed in a canvas `maxWidth` wide.
@@ -840,29 +894,28 @@ export class RichText {
      * `undefined` is not `"left"`: it is Rich's `"default"`, which places the
      * line without padding it at all. That distinction is what lets a soft-wrapped
      * `Console.print` leave its lines at their natural width.
+     *
+     * The padding is drawn in the text's base style, as the reference pads
+     * inside the `Text` it justifies: a title "on red" fills its row in red.
      */
-    *_justifyLine(line, maxWidth, 
+    *_justifyLine({ segments: line, free }, maxWidth, base, 
     // [LAW:types-are-the-program] `full` is absent rather than ignored: it
     // needs the lines either side of this one, so the type refuses it here
     // instead of a branch quietly rendering it as `left`, which is the bug
     // this signature replaces (rich-justify-0cr.1).
     justify) {
+        const padStyle = base.isNull ? undefined : base;
         switch (justify) {
             case "center":
             case "right": {
                 const body = Segment.adjustLineLength(line, Segment.getLineLength(line) - hangingWhitespace(line), undefined, false);
                 const gap = Math.max(maxWidth - Segment.getLineLength(body), 0);
                 const leftPad = justify === "center" ? Math.floor(gap / 2) : gap;
-                if (leftPad > 0)
-                    yield new Segment(" ".repeat(leftPad));
-                yield* body;
-                const rightPad = gap - leftPad;
-                if (rightPad > 0)
-                    yield new Segment(" ".repeat(rightPad));
+                yield* padded(body, free, leftPad, gap - leftPad, padStyle);
                 break;
             }
             case "left":
-                yield* Segment.adjustLineLength(line, Math.max(maxWidth, Segment.getLineLength(line)));
+                yield* padded(line, free, 0, Math.max(maxWidth - Segment.getLineLength(line), 0), padStyle);
                 break;
             default:
                 yield* line;
@@ -974,3 +1027,71 @@ export class RichText {
         yield* Segment.adjustLineLength(line, maxWidth, undefined, false);
     }
 }
+/**
+ * For each logical line of a render, whether the cell at an offset is covered
+ * by no span. `covered` is `_buildSegments`'s answer per piece; a piece split
+ * by a line break answers for both halves.
+ */
+function spanFreeLines(segments, covered) {
+    // Per line, the cell each run ends at and whether that run is span-free.
+    const lines = [[]];
+    segments.forEach((segment, piece) => {
+        segment.text.split("\n").forEach((part, at) => {
+            if (at > 0)
+                lines.push([]);
+            const runs = lines.at(-1);
+            runs.push({ end: (runs.at(-1)?.end ?? 0) + cellLen(part), free: !covered[piece] });
+        });
+    });
+    return lines.map((runs) => (cell) => {
+        let lo = 0;
+        let hi = runs.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (runs[mid].end <= cell)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return runs[lo].free;
+    });
+}
+/**
+ * A line with `left` and `right` cells of padding in `style` either side.
+ *
+ * The reference pads inside the `Text` it justifies and cuts its output at
+ * span edges, so a pad and the run of the line beside it that no span covers
+ * are one piece, and Rich emits them as one segment; a run a span covers stays
+ * its own segment even when its style draws the same as the pad
+ * (rich-table-qj6i). A span-free run is drawn in `style` alone, which is what
+ * makes the joined segment's style exact.
+ */
+function* padded(drawn, free, left, right, style) {
+    if (left + right === 0)
+        return yield* drawn;
+    // An empty piece writes no bytes, and at an edge it would take the join that
+    // belongs to the run behind it.
+    const line = drawn.filter((segment) => segment.text !== "");
+    const pad = (cells) => " ".repeat(cells);
+    const width = Segment.getLineLength(line);
+    // A line with no cells has no run to join; the pads alone are its one piece.
+    if (width === 0)
+        return yield new Segment(pad(left + right), style);
+    const last = line.length - 1;
+    // A zero-width segment has no cell of its own to ask about, so it never
+    // joins: merged on its neighbour's answer it would lose its own style.
+    const head = left > 0 && line[0].cellLength > 0 && free(0);
+    const tail = right > 0 && line[last].cellLength > 0 && free(width - 1);
+    const from = head ? 1 : 0;
+    const to = tail ? last : last + 1;
+    // One run joined on both sides: the pads and it are one piece.
+    if (from > to) {
+        yield new Segment(pad(left) + line[0].text + pad(right), style);
+        return;
+    }
+    if (left > 0)
+        yield new Segment(pad(left) + (head ? line[0].text : ""), style);
+    yield* line.slice(from, to);
+    if (right > 0)
+        yield new Segment((tail ? line[last].text : "") + pad(right), style);
+}

package/dist/core/wrap.d.ts

@@ -20,6 +20,11 @@
  * same cell still ellipsizes.
  */
 import { type CellCol } from "./cells.js";
+/**
+ * The cells each word of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word.
+ */
+export declare function wordWidths(text: string): number[];
 /**
  * The cell offsets `text` should be cut at to wrap it into lines of at most
  * `width` cells, for `Segment.divide` to apply to the styled line.

package/dist/core/wrap.js

@@ -39,6 +39,21 @@ function* words(text) {
         yield match[0];
     }
 }
+/**
+ * The cells a word needs on a line: all of it but its trailing whitespace,
+ * which may hang past the edge for the caller to crop. Its leading whitespace
+ * counts — that is a line's indent, and it is not a place to break.
+ */
+function widthOf(word) {
+    return cellLen(word.trimEnd());
+}
+/**
+ * The cells each word of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word.
+ */
+export function wordWidths(text) {
+    return Array.from(words(text), widthOf);
+}
 /**
  * A word chopped into pieces of at most `width` cells, as the reference chops
  * it.
@@ -92,9 +107,7 @@ export function divideLine(text, width, options) {
     let used = 0; // cells already committed to the line being filled
     let wordStart = 0; // absolute cell offset where the current word begins
     for (const word of words(text)) {
-        // Measured without its trailing whitespace: a word is allowed to end the
-        // line with its spaces hanging past the edge, and the caller crops them.
-        const wordWidth = cellLen(word.trimEnd());
+        const wordWidth = widthOf(word);
         if (width - used >= wordWidth) {
             used += cellLen(word);
         }

package/dist/host/app.d.ts

@@ -23,56 +23,100 @@
  * frame's encoding. What differs per host — whether the program can end
  * under us, how it is suspended — is the `TerminalHost`'s, so the same app
  * runs in node and in a browser with no path of its own for either.
+ *
+ * [LAW:single-enforcer] Input has one reader: the app subscribes to its
+ * host's bytes once and parses them (`host/input`), so a program hears keys
+ * and the pointer as events and never decodes a byte. The quit keys are
+ * checked here, before any handler hears the key, so nothing a program binds
+ * — a focused field in a `WidgetApp` included — can swallow them.
  */
+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 Renderable } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
+import { type KeyPress, type ScreenMouseEvent } from "./input.js";
 import type { TerminalHost } from "./terminal-host.js";
-/**
- * Where the frame is painted. `alternate` is the whole terminal, in the
- * alternate screen buffer, so the rows the program printed before it are
- * there again when it stops; the terminal reports the pointer on it. `inline`
- * starts at the cursor's line, as tall as the frame, and stays on the
- * terminal when the app stops. It gets no pointer events: the terminal
- * reports a pointer by its row on the screen, and the app does not know
- * which row of the screen its frame starts on.
- */
-export type Surface = "alternate" | "inline";
 /**
  * Where an app is in its life. `idle` has not run; `running` holds the
  * terminal and paints; `suspended` has handed it back until the host resumes
  * the program; `stopped` has handed it back for good.
  */
 export type AppPhase = "idle" | "running" | "suspended" | "stopped";
-export interface AppOptions {
+declare const DRAW_OPTIONS: readonly ["asciiOnly", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+type DrawOption = (typeof DRAW_OPTIONS)[number];
+type DrawOptions = Readonly<Pick<ConsoleOptions, DrawOption>>;
+export interface AppOptions extends DrawOptions {
     /** The terminal the app runs on. The app starts and stops it. */
     readonly host: TerminalHost;
     readonly surface: Surface;
     /**
      * The app's root renderable, asked for once per frame, so a view of the
-     * app's state is drawn from the state as it is at that frame.
+     * app's state is drawn from the state as it is at that frame. `t` is the
+     * frame's time in seconds on the app's `clock`, which is what an effect is
+     * sampled at.
      */
-    readonly view: () => Renderable;
+    readonly view: (t: number) => Renderable;
+    /** What the app reads the time from and ticks on. The platform's, unless given. */
+    readonly clock?: Clock;
+    /** How often the app paints while something is animating. 30 frames a second, unless given. */
+    readonly rate?: FrameRate;
     /**
-     * The terminal can draw only ASCII, so every frame draws its boxes, guides
-     * and widget marks with ASCII characters. Default false.
+     * The keys that stop the app, by `keyName`, heard before any `onKey`
+     * handler. `["ctrl+c"]` unless given; `[]` leaves every key to the program.
+     * A name no key goes by throws here.
      */
-    readonly asciiOnly?: boolean;
+    readonly quitKeys?: readonly string[];
+}
+/**
+ * A turn of the wheel, where the pointer was when it turned: `lines` is
+ * positive towards the end of the content, a line a notch.
+ */
+export interface Wheel {
+    readonly x: number;
+    readonly y: number;
+    readonly lines: number;
 }
+declare const WHEEL_LINES: {
+    readonly scroll_up: -1;
+    readonly scroll_down: 1;
+};
+type WheelTurn = Extract<ScreenMouseEvent, {
+    type: keyof typeof WHEEL_LINES;
+}>;
+/** A pointer event `onMouse` hears: every one but the vertical wheel, which is `onWheel`'s. */
+export type AppMouseEvent = Exclude<ScreenMouseEvent, WheelTurn>;
 export declare class App {
     private readonly host;
     private readonly surface;
     private readonly view;
+    private readonly clock;
+    private _rate;
+    private readonly animations;
+    private ticking;
     private readonly console;
     private _phase;
     private _frame;
-    private rows;
+    private readonly painter;
     private refreshQueued;
     private subscriptions;
     private readonly paintHandlers;
+    private readonly keyHandlers;
+    private readonly mouseHandlers;
+    private readonly wheelHandlers;
+    private readonly quitKeys;
+    private readonly input;
     private settle;
     constructor(options: AppOptions);
     get phase(): AppPhase;
+    /** How often the app paints while something is animating. */
+    get rate(): FrameRate;
+    /**
+     * Set how often the app paints: an animation under way goes on at the new
+     * rate from its next frame, without a frame lost or one painted twice.
+     */
+    set rate(rate: FrameRate);
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
     /**
@@ -93,6 +137,15 @@ export declare class App {
      * for as long as it ran.
      */
     refresh(): void;
+    /**
+     * Paint at the app's `rate` until the returned function is called: what an
+     * effect sampled at the frame's time asks for while it moves. The app ticks
+     * while anything is animating and it holds the terminal, and stops when
+     * nothing is, so a still app paints only when asked. The animation's first
+     * frame does not wait out an interval: at one frame every two seconds, that
+     * would hold its start off screen for two.
+     */
+    animate(): Unsubscribe;
     /**
      * Hand the terminal to whatever launched the program, and take it back and
      * repaint when that resumes it. What sends the app here is the app's own —
@@ -104,6 +157,26 @@ export declare class App {
      * handler that throws fails the app as a frame that throws does.
      */
     onPaint(handler: (frame: readonly (readonly Segment[])[]) => void): Unsubscribe;
+    /**
+     * Hear every key the app does not quit on, by the `KeyPress` the terminal
+     * reported; `keyName` names it. A handler that throws fails the app.
+     */
+    onKey(handler: (press: KeyPress) => void): Unsubscribe;
+    /**
+     * Hear every pointer event but the vertical wheel, which is `onWheel`'s,
+     * in terminal cells. Only the alternate surface reports the pointer. A
+     * handler that throws fails the app.
+     */
+    onMouse(handler: (event: AppMouseEvent) => void): Unsubscribe;
+    /**
+     * Offer every wheel turn to `handler`, which returns whether it moved
+     * something. A turn no handler moves anything with is passed outward to the
+     * host (`TerminalHost.passWheel`), so the page or terminal around the app
+     * scrolls instead. Handlers are offered a turn in the order they subscribed,
+     * and the first that moves something takes it. A handler that throws fails
+     * the app.
+     */
+    onWheel(handler: (wheel: Wheel) => boolean): Unsubscribe;
     /** Hand the terminal back for good; `run` resolves. */
     stop(): void;
     /**
@@ -116,6 +189,11 @@ export declare class App {
     private enter;
     private leave;
     private end;
+    private key;
+    private mouse;
+    private hear;
+    private tick;
     private paint;
     private draw;
 }
+export {};