@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/host/app.js

@@ -23,68 +23,104 @@
  * 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 { frameRate, systemClock } from "../core/clock.js";
 import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
-import { segmentsToString } from "../core/render.js";
+import { SurfacePainter } from "../core/paint.js";
 import { fitHeight } from "../core/protocol.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
+// it knows, what happens to a style it cannot resolve, markup and
+// highlighting — is the console's to say, so App takes those options as the
+// console declares them. This list is both the type and what is copied: the
+// host alone decides the console's size, colours and sink, so no other
+// property of the options object reaches it, whatever the object carries.
+const DRAW_OPTIONS = ["asciiOnly", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+function drawOptions(options) {
+    const picked = {};
+    const copy = (key) => {
+        picked[key] = options[key];
+    };
+    DRAW_OPTIONS.forEach(copy);
+    return picked;
+}
+const DEFAULT_RATE = frameRate(30);
+const DEFAULT_QUIT_KEYS = ["ctrl+c"];
 // Button presses, motion and the wheel, in the SGR encoding: coordinates as
 // decimal numbers, so a terminal wider than 223 columns still reports them.
-const POINTER_ON = "\x1b[?1006h\x1b[?1000h\x1b[?1003h";
-const POINTER_OFF = "\x1b[?1003l\x1b[?1000l\x1b[?1006l";
-const SURFACES = {
-    alternate: {
-        exact: true,
-        enter: "\x1b[?1049h" + POINTER_ON,
-        leave: () => POINTER_OFF + "\x1b[?1049l",
-        home: () => "\x1b[H",
-        // The frame is every row of the screen, so there is nothing left under it
-        // — and after the terminal shrinks, painting the old count would scroll.
-        painted: (frameRows) => frameRows,
-    },
-    inline: {
-        exact: false,
-        enter: "",
-        // Below the frame, where the program's next line belongs.
-        leave: (rows) => (rows > 0 ? "\n" : ""),
-        // After N rows written with N-1 newlines between them, the cursor is on
-        // the last. `ESC[0A` still moves a row on some terminals, so a one-row
-        // frame is returned to with the carriage return alone.
-        home: (rows) => (rows > 1 ? `\x1b[${rows - 1}A\r` : "\r"),
-        // A shorter frame blanks the rows the last one left below it.
-        painted: (frameRows, lastRows) => Math.max(frameRows, lastRows),
-    },
+// The terminal reports a pointer by its row on the screen, and an inline
+// frame does not know which row of the screen it starts on, so only the
+// alternate surface gets them.
+const POINTER = {
+    alternate: { on: "\x1b[?1006h\x1b[?1000h\x1b[?1003h", off: "\x1b[?1003l\x1b[?1000l\x1b[?1006l" },
+    inline: { on: "", off: "" },
 };
-const HIDE_CURSOR = "\x1b[?25l";
-const SHOW_CURSOR = "\x1b[?25h";
-const RESET_STYLE = "\x1b[0m";
-const ERASE_LINE = "\x1b[2K";
+// The sideways wheel is not here: nothing scrolls by columns, inside an app or
+// around it.
+const WHEEL_LINES = { scroll_up: -1, scroll_down: 1 };
+const isWheelTurn = (event) => event.type in WHEEL_LINES;
 export class App {
     host;
     surface;
     view;
+    clock;
+    _rate;
+    // What is animating now: one token per `animate()` not yet released.
+    animations = new Set();
+    // The timer painting frames, and the rate it was started at.
+    ticking = null;
     // [LAW:one-source-of-truth] The host is the console's whole environment:
     // its size, its colours, where bytes go. Every frame renders with this
     // console's options and is encoded for its destination.
     console;
     _phase = "idle";
     _frame = [];
-    // The last frame's own rows on the terminal — what `home` rewinds.
-    rows = 0;
+    painter;
     refreshQueued = false;
     subscriptions = [];
     paintHandlers = new Set();
+    keyHandlers = new Set();
+    mouseHandlers = new Set();
+    wheelHandlers = new Set();
+    quitKeys;
+    input = new InputParser({
+        key: (press) => this.key(press),
+        mouse: (event) => this.mouse(event),
+    });
     settle = () => { };
     constructor(options) {
         this.host = options.host;
-        this.surface = SURFACES[options.surface];
+        this.surface = options.surface;
+        this.painter = new SurfacePainter(options.surface, (bytes) => this.host.write(bytes));
         this.view = options.view;
-        this.console = new Console({ environment: hostEnvironment(options.host), asciiOnly: options.asciiOnly });
+        this.clock = options.clock ?? systemClock();
+        this._rate = options.rate ?? DEFAULT_RATE;
+        this.quitKeys = new Set((options.quitKeys ?? DEFAULT_QUIT_KEYS).map(parseKeyName));
+        this.console = new Console({ ...drawOptions(options), environment: hostEnvironment(options.host) });
     }
     get phase() {
         return this._phase;
     }
+    /** How often the app paints while something is animating. */
+    get rate() {
+        return this._rate;
+    }
+    /**
+     * 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) {
+        this._rate = rate;
+        this.tick();
+    }
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame() {
         return this._frame;
@@ -116,6 +152,7 @@ export class App {
             this._phase = "running";
             this.host.start();
             this.subscriptions = [
+                this.host.onData((chunk) => this.input.feed(chunk)),
                 this.host.onResize(() => this.refresh()),
                 // The program is ending under the app — by a signal, a crash, or an
                 // exit the app's own code never saw. Ending hands the terminal back,
@@ -124,6 +161,7 @@ export class App {
             ];
             this.enter();
             this.paint();
+            this.tick();
         });
     }
     /**
@@ -140,6 +178,10 @@ export class App {
             return;
         this.refreshQueued = true;
         setTimeout(() => {
+            // A frame painted since it was asked for — a tick — drew every change
+            // made before it, so there is nothing left to paint.
+            if (!this.refreshQueued)
+                return;
             this.refreshQueued = false;
             // [LAW:types-are-the-program] Only a running app holds the terminal; a
             // suspended one repaints when it resumes, and a stopped one never does.
@@ -147,6 +189,24 @@ export class App {
                 this.paint();
         });
     }
+    /**
+     * 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() {
+        const animation = {};
+        this.animations.add(animation);
+        this.tick();
+        this.refresh();
+        return () => {
+            this.animations.delete(animation);
+            this.tick();
+        };
+    }
     /**
      * 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 —
@@ -156,6 +216,7 @@ export class App {
         if (this._phase !== "running")
             return;
         this._phase = "suspended";
+        this.tick();
         this.leave();
         await this.host.suspend();
         // Stopped while suspended — by a signal, say: the terminal is already
@@ -163,11 +224,9 @@ export class App {
         if (this._phase !== "suspended")
             return;
         this._phase = "running";
-        // What the last frame occupied is gone under whatever ran meanwhile, so
-        // the next one starts where the cursor is.
-        this.rows = 0;
         this.enter();
         this.paint();
+        this.tick();
     }
     /**
      * Hear each frame once it is on screen — what `frame` now returns. A
@@ -177,6 +236,35 @@ export class App {
         this.paintHandlers.add(handler);
         return () => this.paintHandlers.delete(handler);
     }
+    /**
+     * 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) {
+        this.keyHandlers.add(handler);
+        return () => this.keyHandlers.delete(handler);
+    }
+    /**
+     * 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) {
+        this.mouseHandlers.add(handler);
+        return () => this.mouseHandlers.delete(handler);
+    }
+    /**
+     * 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) {
+        this.wheelHandlers.add(handler);
+        return () => this.wheelHandlers.delete(handler);
+    }
     /** Hand the terminal back for good; `run` resolves. */
     stop() {
         this.end({ kind: "stopped" });
@@ -193,26 +281,91 @@ export class App {
     // --- the terminal ---
     enter() {
         this.host.setRawMode(true);
-        this.host.write(this.surface.enter + HIDE_CURSOR);
+        this.painter.take();
+        this.host.write(POINTER[this.surface].on);
     }
     leave() {
-        this.host.write(RESET_STYLE + SHOW_CURSOR + this.surface.leave(this.rows));
+        this.host.write(POINTER[this.surface].off);
+        this.painter.handBack();
         this.host.setRawMode(false);
     }
     end(outcome) {
         const phase = this._phase;
-        if (phase === "idle" || phase === "stopped")
+        // [LAW:no-silent-failure] An error after the app ended has no `run` left
+        // to reject, so it is thrown to whoever raised it instead of dropped.
+        if (phase === "idle" || phase === "stopped") {
+            if (outcome.kind === "failed")
+                throw outcome.error;
             return;
+        }
         this._phase = "stopped";
+        this.tick();
         for (const unsubscribe of this.subscriptions)
             unsubscribe();
         this.subscriptions = [];
+        this.input.reset();
         // A suspended app handed the terminal back when it suspended.
         if (phase === "running")
             this.leave();
         this.host.stop();
         this.settle(outcome);
     }
+    // --- input ---
+    key(press) {
+        if (this.quitKeys.has(keyName(press)))
+            return this.stop();
+        this.hear(this.keyHandlers, press);
+    }
+    // [LAW:dataflow-not-control-flow] One rule for every app: a wheel turn
+    // nothing in the app moved with goes outward. The vertical wheel reaches the
+    // program through `onWheel` alone, so moving something with it and claiming
+    // the turn are one act, and an app that reads no wheel passes every turn.
+    // [LAW:single-enforcer] Only a running app holds the terminal, so only a
+    // running app is offered a turn or passes one on.
+    mouse(event) {
+        if (!isWheelTurn(event))
+            return this.hear(this.mouseHandlers, event);
+        if (this._phase !== "running")
+            return;
+        const lines = WHEEL_LINES[event.type];
+        const wheel = { x: event.x, y: event.y, lines };
+        try {
+            const moved = [...this.wheelHandlers].some((handler) => this._phase === "running" && handler(wheel));
+            if (!moved && this._phase === "running")
+                this.host.passWheel(lines);
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    // [LAW:no-silent-failure] The host calls these handlers, not the program,
+    // so one that throws ends the app with its error, as a frame that throws
+    // does. A handler that stops the app is the last to hear the event.
+    hear(handlers, event) {
+        try {
+            for (const handler of [...handlers])
+                if (this._phase !== "stopped")
+                    handler(event);
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    // [LAW:single-enforcer] Whether the clock is ticking, and at what rate,
+    // follows from the phase, what is animating and the rate, and is brought
+    // in line with them here alone, after every change to any — so a timer
+    // runs exactly while a running app has something animating, at the rate
+    // the app has now, and none outlives the app.
+    tick() {
+        const wanted = this._phase === "running" && this.animations.size > 0;
+        if (this.ticking !== null && (!wanted || this.ticking.rate.perSecond !== this._rate.perSecond)) {
+            this.ticking.stop();
+            this.ticking = null;
+        }
+        if (wanted && this.ticking === null) {
+            this.ticking = { rate: this._rate, stop: this.clock.every(this._rate, () => this.paint()) };
+        }
+    }
     // [LAW:no-silent-failure] A frame that throws ends the app with that
     // error: the terminal is handed back, and `run` rejects with it.
     paint() {
@@ -224,31 +377,18 @@ export class App {
         }
     }
     draw() {
+        // This frame draws every change made before it, a queued refresh's included.
+        this.refreshQueued = false;
         const options = this.console.options;
-        const { maxWidth: cols } = options;
-        const height = { rows: options.height.rows, exact: this.surface.exact };
-        const lines = Segment.splitLines(this.view().render({ ...options, height }));
+        const height = this.painter.height(options.height.rows);
+        // [LAW:no-ambient-temporal-coupling] The frame owner reads the clock,
+        // once a frame; the view is handed the time as data.
+        const lines = Segment.splitLines(this.view(this.clock.now()).render({ ...options, height }));
         // The app set the budget, so the app shapes what comes back: no deeper
-        // than the terminal — a taller frame would scroll the rows `home` counts
-        // back over — and, as a region, exactly that deep. No row wider than the
-        // terminal either: one that soft-wrapped would push every row below it
-        // down a row the frame does not know about.
-        const frame = fitHeight(lines.slice(0, height.rows), height).map((line) => Segment.adjustLineLength(line, cols, undefined, false));
-        const painted = Math.min(this.surface.painted(frame.length, this.rows), height.rows);
-        // Each row is erased as it is reached rather than the frame cleared
-        // first, so no blank screen shows between two frames. The erase leads
-        // its row: after a row that fills the width, the cursor sits on its last
-        // cell, and an erase there would take it.
-        const destination = this.console.destination;
-        const body = Array.from({ length: painted }, (_, row) => ERASE_LINE + segmentsToString(frame[row] ?? [], destination)).join("\n");
-        // Rows blanked below the frame are not the frame's: the cursor goes back
-        // up to its last row, so the next frame and the program's next line start
-        // from the frame's own height.
-        const blanked = painted - Math.max(frame.length, 1);
-        const back = blanked > 0 ? `\x1b[${blanked}A` : "";
-        this.host.write(this.surface.home(this.rows) + body + back);
+        // than the terminal — a taller frame would scroll the rows the painter
+        // goes back over — and, as a region, exactly that deep.
+        const frame = this.painter.paint(() => fitHeight(lines.slice(0, height.rows), height), { rows: height.rows, cols: options.maxWidth }, this.console.destination);
         this._frame = frame;
-        this.rows = frame.length;
         for (const handler of [...this.paintHandlers])
             handler(frame);
     }

package/dist/host/index.d.ts

@@ -2,4 +2,7 @@ export { BrowserTerminalHost } from "./terminal-host.js";
 export type { TerminalHost, TerminalSize, DataHandler, ResizeHandler, ExitHandler, BrowserTerminalHostOptions, XtermTerminal, XtermDisposable, XtermResizeEvent, } from "./terminal-host.js";
 export { hostEnvironment } from "./host-environment.js";
 export { App } from "./app.js";
-export type { AppOptions, AppPhase, Surface } from "./app.js";
+export type { AppMouseEvent, AppOptions, AppPhase, Wheel } from "./app.js";
+export type { Surface } from "../core/paint.js";
+export { keyName } from "./input.js";
+export type { KeyPress, ScreenMouseEvent } from "./input.js";

package/dist/host/index.js

@@ -1,3 +1,4 @@
 export { BrowserTerminalHost } from "./terminal-host.js";
 export { hostEnvironment } from "./host-environment.js";
 export { App } from "./app.js";
+export { keyName } from "./input.js";

package/dist/host/input.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Terminal input: the bytes a terminal sends for keys and the pointer,
+ * parsed into `KeyPress` and `ScreenMouseEvent` values, and the one name
+ * each key goes by.
+ *
+ * [LAW:single-enforcer] Escape-sequence parsing lives only here. `App` owns
+ * the one parser over its host's input; a `WidgetApp` routes the events `App`
+ * hears, and no program reads its terminal's bytes itself.
+ *
+ * [LAW:dataflow-not-control-flow] The same parse pipeline runs for every
+ * input chunk: append → consume one event at a time until the buffer can't
+ * yield more. The byte's value, not a side-mode, decides which event is
+ * emitted. There is no "are we mid-sequence" mode flag — the buffer head
+ * carries all the state we need, so a UTF-8 character or an escape sequence
+ * split across two chunks is completed by the second.
+ *
+ * Lone-ESC handling: a bare `\x1b` is ambiguous (escape key vs. start of a
+ * CSI sequence). When the buffer is drained but ends with a lone ESC, the
+ * parser defers emission via setTimeout(0). The next chunk cancels the timer
+ * if it extends the sequence. `flush()` drains it synchronously.
+ */
+/** A key as the terminal reported it: plain data, with no say over who hears it. */
+export interface KeyPress {
+    readonly key: string;
+    /** The printable character the key types, or "" for a key that types none. */
+    readonly character: string;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+}
+export type ScreenMouseEvent = {
+    [T in MouseEventType]: MouseEventOf<T>;
+}[MouseEventType];
+type MouseEventType = "mouse_down" | "mouse_up" | "mouse_move" | "scroll_up" | "scroll_down" | "scroll_left" | "scroll_right";
+interface MouseEventOf<Type extends string> {
+    readonly type: Type;
+    readonly x: number;
+    readonly y: number;
+    readonly button: number;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+}
+/**
+ * The one name a key goes by — what a keymap is keyed by and what
+ * `quitKeys` lists. A key that types a character is named by it (`q`, `G`,
+ * `>`); any other is named by its key (`up`, `enter`, `space`, `f5`). Held
+ * modifiers come first, always in the order `ctrl+`, `meta+`, `shift+`:
+ * `ctrl+c`, `shift+tab`, `meta+left`. Shift is not named on a character,
+ * which already carries it: Shift+G is `G`.
+ */
+export declare function keyName(press: KeyPress): string;
+/** Where a parser delivers what it parses. */
+export interface InputSink {
+    key(press: KeyPress): void;
+    mouse(event: ScreenMouseEvent): void;
+}
+/**
+ * `name`, if `keyName` can produce it: modifiers in its order, then a named
+ * key or one glyph, with no `shift+` on a glyph and, after `ctrl+`, only a
+ * glyph a control byte stands for.
+ * [LAW:parse-dont-validate] A name no key can produce throws here, at the
+ * one place a program hands names in, rather than binding a key that never fires.
+ */
+export declare function parseKeyName(name: string): string;
+export declare class InputParser {
+    private readonly sink;
+    private buffer;
+    private escTimer;
+    constructor(sink: InputSink);
+    /** Feed a chunk of bytes (or a string of them) into the parser. */
+    feed(chunk: Uint8Array | string): void;
+    /** Force any pending lone ESC out of the buffer. */
+    flush(): void;
+    /** Drop what is buffered and any pending lone ESC: the parser as constructed. */
+    reset(): void;
+    private cancelEscape;
+    private drain;
+    private consumeOne;
+    private consumePrintable;
+    private consumeEscape;
+    private consumeSS3;
+    private consumeCSI;
+}
+export {};