@promptctl/rich-js 0.19.0 → 0.20.0

package/dist/host/app.d.ts

@@ -23,6 +23,12 @@
  * 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";
@@ -30,6 +36,7 @@ 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 an app is in its life. `idle` has not run; `running` holds the
@@ -55,15 +62,39 @@ export interface AppOptions extends DrawOptions {
     readonly clock?: Clock;
     /** How often the app paints while something is animating. 30 frames a second, unless given. */
     readonly rate?: FrameRate;
+    /**
+     * 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 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 readonly rate;
+    private _rate;
     private readonly animations;
-    private stopTicking;
+    private ticking;
     private readonly console;
     private _phase;
     private _frame;
@@ -71,9 +102,21 @@ export declare class App {
     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[])[];
     /**
@@ -114,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;
     /**
@@ -126,6 +189,9 @@ export declare class App {
     private enter;
     private leave;
     private end;
+    private key;
+    private mouse;
+    private hear;
     private tick;
     private paint;
     private draw;

package/dist/host/app.js

@@ -23,6 +23,12 @@
  * 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";
@@ -30,6 +36,7 @@ import { Segment } from "../core/segment.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
@@ -46,6 +53,7 @@ function drawOptions(options) {
     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.
 // The terminal reports a pointer by its row on the screen, and an inline
@@ -55,15 +63,20 @@ const POINTER = {
     alternate: { on: "\x1b[?1006h\x1b[?1000h\x1b[?1003h", off: "\x1b[?1003l\x1b[?1000l\x1b[?1006l" },
     inline: { on: "", off: "" },
 };
+// 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;
+    _rate;
     // What is animating now: one token per `animate()` not yet released.
     animations = new Set();
-    stopTicking = null;
+    // 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.
@@ -74,6 +87,14 @@ export class App {
     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;
@@ -81,12 +102,25 @@ export class App {
         this.painter = new SurfacePainter(options.surface, (bytes) => this.host.write(bytes));
         this.view = options.view;
         this.clock = options.clock ?? systemClock();
-        this.rate = options.rate ?? DEFAULT_RATE;
+        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;
@@ -118,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,
@@ -201,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" });
@@ -227,33 +291,79 @@ export class App {
     }
     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);
     }
-    // [LAW:single-enforcer] Whether the clock is ticking follows from the
-    // phase and what is animating, and is brought in line with them here
-    // alone, after every change to either — so a timer runs exactly while a
-    // running app has something animating, and none outlives the app.
+    // --- 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;
-        const ticking = this.stopTicking;
-        if (ticking === null) {
-            if (wanted)
-                this.stopTicking = this.clock.every(this.rate, () => this.paint());
+        if (this.ticking !== null && (!wanted || this.ticking.rate.perSecond !== this._rate.perSecond)) {
+            this.ticking.stop();
+            this.ticking = null;
         }
-        else if (!wanted) {
-            ticking();
-            this.stopTicking = 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

package/dist/host/index.d.ts

@@ -2,5 +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 } 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 {};