@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/widgets/widget-app.js

@@ -0,0 +1,206 @@
+/**
+ * WidgetApp — an `App` whose view has widgets in it: keys reach the focused
+ * widget, the pointer reaches the widget that drew the cell under it, and a
+ * change to anything a frame read paints the next one.
+ *
+ * A widget goes wherever a renderable goes — in a `Panel`, a `Layout` pane, a
+ * `Table` cell — and nothing lays it out a second time. Everything added here
+ * reads the frame the view drew:
+ *
+ * - Focus moves in document order: the order widgets start to render in
+ *   (`RenderOptions.onDraw`), among those with a cell on the frame on screen.
+ *   Not reading order — in a `Layout` split into columns, reading order
+ *   zigzags between the columns row by row.
+ * - Overlays are painted over the view's frame, in document order, directly
+ *   below their owner's footprint (`OverlayRenderable`). Paint order is the
+ *   z-order: a later overlay covers an earlier one.
+ * - A pointer event goes to the innermost widget that drew the cell under it
+ *   (`widgetAt`), in that widget's own coordinates; the wheel goes to the
+ *   innermost `Viewport` that can move (`scrollTargetAt`).
+ *
+ * [LAW:locality-or-seam] `App` knows nothing of widgets — `host/` depends on
+ * `core/` alone — and this reaches it only through the seams it already has:
+ * the view is a renderable, and `onPaint` hears the frame.
+ */
+import { Reaction } from "mobx";
+import { Segment } from "../core/segment.js";
+import { App } from "../host/app.js";
+import { DefaultFocusManager } from "./focus-manager.js";
+import { EventRouter } from "./event-router.js";
+import { footprintOf, ownersOn } from "./hit.js";
+import { hasOverlay } from "./types.js";
+import { WidgetBase } from "./widget-base.js";
+export class WidgetApp {
+    focusManager;
+    focus;
+    app;
+    router;
+    // Paints the next frame when anything the last one read changes.
+    reaction;
+    // The widgets the view drew for the frame on screen, in document order.
+    drawn = [];
+    constructor(options) {
+        const { view } = options;
+        this.reaction = new Reaction("WidgetApp", () => this.app.refresh());
+        this.app = new App({
+            ...options,
+            view: (t) => ({ render: (renderOptions) => this.compose(() => view(t), renderOptions) }),
+        });
+        this.focus = new DefaultFocusManager(() => {
+            const owners = ownersOn(this.app.frame);
+            return this.drawn.filter((widget) => owners.has(widget));
+        });
+        this.focusManager = this.focus;
+        this.router = new EventRouter({ source: this, host: options.host });
+        this.app.onPaint(() => {
+            this.focus.settle(this.drawn);
+            this.router.framePainted();
+        });
+        // [LAW:single-enforcer] `settle` judges every focus move, so every move
+        // paints — including one onto a widget no frame has read yet.
+        this.focus.onChange(() => this.app.refresh());
+    }
+    get phase() {
+        return this.app.phase;
+    }
+    /** The rows on screen now, as painted: what a pointer event lands on. */
+    get frame() {
+        return this.app.frame;
+    }
+    /**
+     * Take the terminal, paint the first frame, and route input to its widgets
+     * until the app stops — `App.run`, with the input.
+     */
+    async run() {
+        // App refuses a second run; this one must not end the input of the first.
+        if (this.app.phase !== "idle")
+            return this.app.run();
+        // Listening before the app starts, so a first frame that throws — and
+        // stops the host — is not followed by a subscription that restarts it.
+        this.router.start();
+        const running = this.app.run();
+        try {
+            await running;
+        }
+        finally {
+            this.router.stop();
+            this.reaction.dispose();
+        }
+    }
+    stop() {
+        this.app.stop();
+    }
+    fail(error) {
+        this.app.fail(error);
+    }
+    /**
+     * Paint the next frame, as `App.refresh` does. A change to an observable
+     * the view read needs none; one no observable carries — a `Viewport`
+     * scrolled from a key handler — does.
+     */
+    refresh() {
+        this.app.refresh();
+    }
+    suspend() {
+        return this.app.suspend();
+    }
+    /** Paint at the app's rate until the returned function is called, as `App.animate` does. */
+    animate() {
+        return this.app.animate();
+    }
+    /**
+     * Hear every key. A `high` handler hears it before the focused widget, a
+     * `normal` one after it — and after Tab has moved focus — and a handler
+     * that calls `event.stop()` ends the key there.
+     */
+    onKey(handler, options) {
+        return this.router.onKey(handler, options);
+    }
+    /** Hear every pointer event, in terminal cells, before any widget does. */
+    onMouse(handler) {
+        return this.router.onMouse(handler);
+    }
+    compose(view, options) {
+        const drawn = new Set();
+        // [LAW:parse-dont-validate] An owner is any object; only a `WidgetBase`
+        // reports itself as a widget, so this is where `object` becomes one.
+        const onDraw = (owner) => {
+            if (owner instanceof WidgetBase)
+                drawn.add(owner);
+        };
+        // The view, its render and the overlays are all tracked, so an observable
+        // any of them reads — a label, `focused`, the state that picks what the
+        // view shows — paints the next frame when it changes.
+        // An overlay reports what it draws too: a widget in it is on the frame,
+        // and visiting `drawn` in insertion order paints its overlay in turn.
+        const render = { ...options, onDraw };
+        const lines = tracked(this.reaction, () => {
+            const base = Segment.splitLines(view().render(render));
+            for (const widget of drawn)
+                paintOverlay(base, widget, render);
+            return base;
+        });
+        this.drawn = [...drawn];
+        return lines.flatMap((line) => [...line, Segment.line()]);
+    }
+}
+/**
+ * `fn`, with every observable it reads subscribed to by `reaction`.
+ *
+ * [LAW:no-silent-failure] mobx reports an error thrown inside `track` and
+ * carries on, which would paint an empty frame for a view that threw. The
+ * error is carried out instead, and fails the app as `App` fails on any frame
+ * that throws.
+ */
+function tracked(reaction, fn) {
+    // Written inside `track`, which the compiler cannot see run.
+    let outcome = {
+        ok: false,
+        error: new Error("WidgetApp: a frame drawn after the app stopped"),
+    };
+    reaction.track(() => {
+        try {
+            outcome = { ok: true, value: fn() };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+    });
+    if (!outcome.ok)
+        throw outcome.error;
+    return outcome.value;
+}
+/**
+ * Paint `widget`'s overlay over `lines`, below its footprint and at the column
+ * of its row 0, each overlay row stamped as the widget's row below its last —
+ * so a click there reaches the widget, in its own coordinates. A widget whose
+ * row 0 is not on the frame has nowhere to hang an overlay, and paints none.
+ */
+function paintOverlay(lines, widget, options) {
+    if (!hasOverlay(widget))
+        return;
+    const at = footprintOf(lines, widget);
+    if (!at)
+        return;
+    // An overlay floats over the frame; no region holds it, and the cells right
+    // of its column are all it can reach.
+    const width = Math.max(0, options.maxWidth - at.x);
+    const overlay = widget.renderOverlay({ ...options, maxWidth: width, height: undefined });
+    if (overlay === null)
+        return;
+    const rows = Segment.anchorLines(Segment.splitLines(Segment.cropLines(overlay, width)), widget, at.rows);
+    paintLines(lines, rows, at.x, at.y + at.rows);
+}
+// Paint `rows` into `lines` with its top-left cell at (x, y), growing `lines`
+// as needed; each painted cell replaces the one beneath it.
+function paintLines(lines, rows, x, y) {
+    while (lines.length < y + rows.length)
+        lines.push([]);
+    rows.forEach((source, i) => {
+        const row = lines[y + i];
+        // Padded to `x`, so a row that ends short of the overlay still reaches it.
+        const gap = Math.max(0, x - Segment.getLineLength(row));
+        const [before = [], , after = []] = Segment.divide([...row, new Segment(" ".repeat(gap))], [x, x + Segment.getLineLength(source)]);
+        lines[y + i] = [...before, ...source, ...after];
+    });
+}

package/dist/widgets/widget-base.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WidgetBase — shared MobX observable foundation for interactive widgets.
+ * [LAW:one-type-per-behavior] All widgets share the same base; differences
+ * are in configuration and state, not in infrastructure.
+ *
+ * Reactive state is declared with TC39 decorators, which MobX 7 requires on
+ * `accessor` members. Each decorator registers its own member, so there is no
+ * makeObservable call and subclasses add observables the same way.
+ */
+import { Segment } from "../core/segment.js";
+import { type Style } from "../core/style.js";
+import type { RenderOptions } from "../core/protocol.js";
+import type { InteractiveWidget, KeyEvent, WidgetMouseEvent, WidgetFocusEvent } from "./types.js";
+import type { Unsubscribe } from "../core/subscription.js";
+export declare abstract class WidgetBase implements InteractiveWidget {
+    abstract readonly id: string;
+    abstract readonly focusable: boolean;
+    accessor focused: boolean;
+    accessor hovered: boolean;
+    accessor active: boolean;
+    accessor disabled: boolean;
+    private readonly changeHandlers;
+    private readonly submitHandlers;
+    abstract handleKey(event: KeyEvent): void;
+    handleMouse(_event: WidgetMouseEvent): void;
+    handleFocus(event: WidgetFocusEvent): void;
+    focus(): void;
+    blur(): void;
+    setDisabled(value: boolean): void;
+    setHovered(value: boolean): void;
+    onChange(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+    onSubmit(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+    protected emitChange(): void;
+    protected emitSubmit(): void;
+    render(options: RenderOptions): Iterable<Segment>;
+    protected get ground(): Style;
+    protected abstract draw(options: RenderOptions): Iterable<Segment>;
+    abstract measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/widgets/widget-base.js

@@ -0,0 +1,172 @@
+/**
+ * WidgetBase — shared MobX observable foundation for interactive widgets.
+ * [LAW:one-type-per-behavior] All widgets share the same base; differences
+ * are in configuration and state, not in infrastructure.
+ *
+ * Reactive state is declared with TC39 decorators, which MobX 7 requires on
+ * `accessor` members. Each decorator registers its own member, so there is no
+ * makeObservable call and subclasses add observables the same way.
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { observable, action } from "mobx";
+import { Segment } from "../core/segment.js";
+import { NULL_STYLE } from "../core/style.js";
+let WidgetBase = (() => {
+    let _instanceExtraInitializers = [];
+    let _focused_decorators;
+    let _focused_initializers = [];
+    let _focused_extraInitializers = [];
+    let _hovered_decorators;
+    let _hovered_initializers = [];
+    let _hovered_extraInitializers = [];
+    let _active_decorators;
+    let _active_initializers = [];
+    let _active_extraInitializers = [];
+    let _disabled_decorators;
+    let _disabled_initializers = [];
+    let _disabled_extraInitializers = [];
+    let _handleFocus_decorators;
+    let _focus_decorators;
+    let _blur_decorators;
+    let _setDisabled_decorators;
+    let _setHovered_decorators;
+    return class WidgetBase {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _focused_decorators = [observable];
+            _hovered_decorators = [observable];
+            _active_decorators = [observable];
+            _disabled_decorators = [observable];
+            _handleFocus_decorators = [action];
+            _focus_decorators = [action];
+            _blur_decorators = [action];
+            _setDisabled_decorators = [action];
+            _setHovered_decorators = [action];
+            __esDecorate(this, null, _focused_decorators, { kind: "accessor", name: "focused", static: false, private: false, access: { has: obj => "focused" in obj, get: obj => obj.focused, set: (obj, value) => { obj.focused = value; } }, metadata: _metadata }, _focused_initializers, _focused_extraInitializers);
+            __esDecorate(this, null, _hovered_decorators, { kind: "accessor", name: "hovered", static: false, private: false, access: { has: obj => "hovered" in obj, get: obj => obj.hovered, set: (obj, value) => { obj.hovered = value; } }, metadata: _metadata }, _hovered_initializers, _hovered_extraInitializers);
+            __esDecorate(this, null, _active_decorators, { kind: "accessor", name: "active", static: false, private: false, access: { has: obj => "active" in obj, get: obj => obj.active, set: (obj, value) => { obj.active = value; } }, metadata: _metadata }, _active_initializers, _active_extraInitializers);
+            __esDecorate(this, null, _disabled_decorators, { kind: "accessor", name: "disabled", static: false, private: false, access: { has: obj => "disabled" in obj, get: obj => obj.disabled, set: (obj, value) => { obj.disabled = value; } }, metadata: _metadata }, _disabled_initializers, _disabled_extraInitializers);
+            __esDecorate(this, null, _handleFocus_decorators, { kind: "method", name: "handleFocus", static: false, private: false, access: { has: obj => "handleFocus" in obj, get: obj => obj.handleFocus }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _focus_decorators, { kind: "method", name: "focus", static: false, private: false, access: { has: obj => "focus" in obj, get: obj => obj.focus }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _blur_decorators, { kind: "method", name: "blur", static: false, private: false, access: { has: obj => "blur" in obj, get: obj => obj.blur }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setDisabled_decorators, { kind: "method", name: "setDisabled", static: false, private: false, access: { has: obj => "setDisabled" in obj, get: obj => obj.setDisabled }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setHovered_decorators, { kind: "method", name: "setHovered", static: false, private: false, access: { has: obj => "setHovered" in obj, get: obj => obj.setHovered }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        #focused_accessor_storage = (__runInitializers(this, _instanceExtraInitializers), __runInitializers(this, _focused_initializers, false));
+        get focused() { return this.#focused_accessor_storage; }
+        set focused(value) { this.#focused_accessor_storage = value; }
+        #hovered_accessor_storage = (__runInitializers(this, _focused_extraInitializers), __runInitializers(this, _hovered_initializers, false));
+        get hovered() { return this.#hovered_accessor_storage; }
+        set hovered(value) { this.#hovered_accessor_storage = value; }
+        #active_accessor_storage = (__runInitializers(this, _hovered_extraInitializers), __runInitializers(this, _active_initializers, false));
+        get active() { return this.#active_accessor_storage; }
+        set active(value) { this.#active_accessor_storage = value; }
+        #disabled_accessor_storage = (__runInitializers(this, _active_extraInitializers), __runInitializers(this, _disabled_initializers, false));
+        get disabled() { return this.#disabled_accessor_storage; }
+        set disabled(value) { this.#disabled_accessor_storage = value; }
+        changeHandlers = (__runInitializers(this, _disabled_extraInitializers), new Set());
+        submitHandlers = new Set();
+        handleMouse(_event) { }
+        handleFocus(event) {
+            this.focused = event.type === "focus";
+        }
+        // --- Programmatic control ---
+        // [LAW:single-enforcer] focus()/blur() route through handleFocus so any
+        // subclass override (e.g. Dropdown collapsing its overlay on blur)
+        // participates in the same transition path the event router uses. There
+        // is no second code path that flips `focused` directly from the outside.
+        focus() {
+            this.handleFocus({ type: "focus" });
+        }
+        blur() {
+            this.handleFocus({ type: "blur" });
+        }
+        setDisabled(value) {
+            this.disabled = value;
+        }
+        // [LAW:single-enforcer] One canonical setter for hover state lives on
+        // the base. EventRouter calls it when the pointer moves onto or off this
+        // widget; widgets that need to react to hover transitions override
+        // handleMouse and read the synthesized `mouse_move`.
+        setHovered(value) {
+            this.hovered = value;
+        }
+        // --- Subscriptions ---
+        onChange(handler) {
+            this.changeHandlers.add(handler);
+            return () => this.changeHandlers.delete(handler);
+        }
+        onSubmit(handler) {
+            this.submitHandlers.add(handler);
+            return () => this.submitHandlers.delete(handler);
+        }
+        emitChange() {
+            for (const handler of this.changeHandlers) {
+                handler(this);
+            }
+        }
+        emitSubmit() {
+            for (const handler of this.submitHandlers) {
+                handler(this);
+            }
+        }
+        // --- Renderable + Measurable ---
+        // [LAW:single-enforcer] The one place a widget's cells get their anchor, so
+        // a hit on any cell names this widget and the cell's place in its output
+        // (`widgetAt`). Subclasses draw; none stamps itself. A `RichText` admits no
+        // anchor, so stamping has to follow every text layout `draw` does.
+        // Every row is padded to the widest, so the widget owns its whole rectangle
+        // and a click past the end of a short row still reaches it; every row ends
+        // in a newline, so a blank last row survives the next `splitLines`. The
+        // padding stands on `ground`, whatever the widget draws its own cells on.
+        // Reporting itself before it draws is what puts a widget ahead of the
+        // widgets nested in it in document order — the order focus traverses.
+        render(options) {
+            options.onDraw?.(this);
+            const drawn = Segment.splitLines(this.draw(options));
+            const [width] = Segment.getShape(drawn);
+            const lines = Segment.anchorLines(drawn.map((line) => Segment.adjustLineLength(line, width, this.ground)), this);
+            return lines.flatMap((line) => [...line, Segment.line()]);
+        }
+        // What a padded row stands on. None by default: the padding shows whatever
+        // the widget is drawn over, as the cells of content it did not draw do.
+        get ground() {
+            return NULL_STYLE;
+        }
+    };
+})();
+export { WidgetBase };

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brandon-fryslie/rich-js"
+  },
   "type": "module",
   "sideEffects": false,
   "main": "dist/index.js",
@@ -53,7 +57,7 @@
     "THIRD-PARTY-NOTICES"
   ],
   "scripts": {
-    "prepublishOnly": "node scripts/verify-release-tag.mjs",
+    "prepublishOnly": "node scripts/verify-release-tag.mjs && node scripts/verify-entry-points.mjs",
     "build": "npm run clean && tsc",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -66,6 +70,7 @@
     "demo:build": "tsc -p tsconfig.demo.json",
     "sessions": "tsc -p tsconfig.demo.json && node dist-demo/examples/claude-sessions/index.js",
     "strip": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-strip/index.js",
+    "effects-feel": "tsc -p tsconfig.demo.json && node dist-demo/examples/effects-feel/index.js",
     "viewport": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-viewport/index.js",
     "markup-plugins": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-markup-plugins/index.js",
     "demo-inputs": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-config/index.js",
@@ -96,16 +101,25 @@
     "node": ">=20"
   },
   "devDependencies": {
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.13",
+    "@lezer/highlight": "^1.2.5",
     "@playwright/test": "^1.63.0",
     "@promptctl/go-template-js": "^0.10.0",
     "@types/markdown-it": "^14.2.0",
     "@types/node": "^26.5.1",
     "@types/semver": "^7.8.0",
+    "@xterm/headless": "^6.0.0",
     "markdown-it": "^14.3.2",
     "markdown-it-container": "^4.0.0",
     "mobx": "^7.0.3",
+    "node-inspect-extracted": "^3.3.3",
     "semver": "^7.8.5",
     "strip-ansi": "^7.2.0",
+    "sucrase": "^3.35.1",
     "typescript": "^6.0.3",
     "vite": "^8.3.0",
     "vitepress": "^1.6.4",