@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/widgets/themed-widget.js

@@ -0,0 +1,89 @@
+/**
+ * ThemedWidget — a widget that draws every cell it owns from one theme's
+ * palette: the interactive widgets, as against `StaticItem`, which shows
+ * content it did not draw.
+ *
+ * [LAW:one-type-per-behavior] The theme, how it is swapped, what a disabled
+ * widget looks like, and the ground a padded row stands on are the same for
+ * every such widget, so they live here once.
+ */
+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 { observableRef, action } from "mobx";
+import { Style } from "../core/style.js";
+import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
+import { WidgetBase } from "./widget-base.js";
+import { ink } from "./ink.js";
+let ThemedWidget = (() => {
+    let _classSuper = WidgetBase;
+    let _instanceExtraInitializers = [];
+    let _theme_decorators;
+    let _theme_initializers = [];
+    let _theme_extraInitializers = [];
+    let _setTheme_decorators;
+    return class ThemedWidget extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _theme_decorators = [observableRef];
+            _setTheme_decorators = [action];
+            __esDecorate(this, null, _theme_decorators, { kind: "accessor", name: "theme", static: false, private: false, access: { has: obj => "theme" in obj, get: obj => obj.theme, set: (obj, value) => { obj.theme = value; } }, metadata: _metadata }, _theme_initializers, _theme_extraInitializers);
+            __esDecorate(this, null, _setTheme_decorators, { kind: "method", name: "setTheme", static: false, private: false, access: { has: obj => "setTheme" in obj, get: obj => obj.setTheme }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        #theme_accessor_storage = (__runInitializers(this, _instanceExtraInitializers), __runInitializers(this, _theme_initializers, void 0));
+        // [LAW:types-are-the-program] @observableRef so setTheme() triggers a
+        // re-render: every draw reads its colours through this reference.
+        get theme() { return this.#theme_accessor_storage; }
+        set theme(value) { this.#theme_accessor_storage = value; }
+        constructor(theme) {
+            super();
+            __runInitializers(this, _theme_extraInitializers);
+            this.theme = theme ?? DEFAULT_TERMINAL_THEME;
+        }
+        setTheme(theme) {
+            this.theme = theme;
+        }
+        get ground() {
+            return new Style(ink(this.theme, "foreground", "background"));
+        }
+        // [LAW:one-source-of-truth] How every widget looks while disabled: the
+        // palette's de-emphasized text on its ground. WCAG sets no contrast floor for
+        // an inactive control, and this sits under the one for text on purpose.
+        get disabledInk() {
+            return ink(this.theme, "foreground-muted", "background");
+        }
+    };
+})();
+export { ThemedWidget };

package/dist/widgets/toggle.d.ts

@@ -13,7 +13,7 @@
 import { Segment } from "../core/segment.js";
 import type { RenderOptions } from "../core/protocol.js";
 import type { TerminalTheme } from "../core/color.js";
-import { WidgetBase } from "./widget-base.js";
+import { ThemedWidget } from "./themed-widget.js";
 import type { KeyEvent, WidgetMouseEvent } from "./types.js";
 export type ToggleVariant = "default" | "primary" | "success" | "warning" | "danger";
 export interface ToggleOptions {
@@ -24,15 +24,13 @@ export interface ToggleOptions {
     theme?: TerminalTheme;
     variant?: ToggleVariant;
 }
-export declare class Toggle extends WidgetBase {
+export declare class Toggle extends ThemedWidget {
     readonly id: string;
     readonly focusable = true;
     accessor label: string;
     accessor on: boolean;
     accessor variant: ToggleVariant;
-    private accessor _theme;
     constructor(options: ToggleOptions);
-    setTheme(theme: TerminalTheme): void;
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     protected draw(_options: RenderOptions): Iterable<Segment>;
@@ -40,5 +38,4 @@ export declare class Toggle extends WidgetBase {
         minimum: number;
         maximum: number;
     };
-    private resolvePalette;
 }

package/dist/widgets/toggle.js

@@ -47,10 +47,9 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 import { observable, action, observableRef } from "mobx";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
-import { ColorSpec } from "../core/color.js";
 import { cellLen } from "../core/cells.js";
-import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
-import { WidgetBase } from "./widget-base.js";
+import { ThemedWidget } from "./themed-widget.js";
+import { ink } from "./ink.js";
 // onFg uses on-${accent} (WCAG-correct contrast, picked once at palette
 // build time) so the ON state stays readable on a full accent bg. Earlier
 // versions used text-${accent} here, which is mostly-accent and clashed
@@ -64,7 +63,7 @@ const VARIANT_KEYS = {
     danger: { onBg: "error", onFg: "on-error", offBg: "error-muted", offFg: "text-error" },
 };
 let Toggle = (() => {
-    let _classSuper = WidgetBase;
+    let _classSuper = ThemedWidget;
     let _instanceExtraInitializers = [];
     let _label_decorators;
     let _label_initializers = [];
@@ -75,10 +74,6 @@ let Toggle = (() => {
     let _variant_decorators;
     let _variant_initializers = [];
     let _variant_extraInitializers = [];
-    let __theme_decorators;
-    let __theme_initializers = [];
-    let __theme_extraInitializers = [];
-    let _setTheme_decorators;
     let _handleKey_decorators;
     let _handleMouse_decorators;
     return class Toggle extends _classSuper {
@@ -87,15 +82,11 @@ let Toggle = (() => {
             _label_decorators = [observable];
             _on_decorators = [observable];
             _variant_decorators = [observableRef];
-            __theme_decorators = [observableRef];
-            _setTheme_decorators = [action];
             _handleKey_decorators = [action];
             _handleMouse_decorators = [action];
             __esDecorate(this, null, _label_decorators, { kind: "accessor", name: "label", static: false, private: false, access: { has: obj => "label" in obj, get: obj => obj.label, set: (obj, value) => { obj.label = value; } }, metadata: _metadata }, _label_initializers, _label_extraInitializers);
             __esDecorate(this, null, _on_decorators, { kind: "accessor", name: "on", static: false, private: false, access: { has: obj => "on" in obj, get: obj => obj.on, set: (obj, value) => { obj.on = value; } }, metadata: _metadata }, _on_initializers, _on_extraInitializers);
             __esDecorate(this, null, _variant_decorators, { kind: "accessor", name: "variant", static: false, private: false, access: { has: obj => "variant" in obj, get: obj => obj.variant, set: (obj, value) => { obj.variant = value; } }, metadata: _metadata }, _variant_initializers, _variant_extraInitializers);
-            __esDecorate(this, null, __theme_decorators, { kind: "accessor", name: "_theme", static: false, private: false, access: { has: obj => "_theme" in obj, get: obj => obj._theme, set: (obj, value) => { obj._theme = value; } }, metadata: _metadata }, __theme_initializers, __theme_extraInitializers);
-            __esDecorate(this, null, _setTheme_decorators, { kind: "method", name: "setTheme", static: false, private: false, access: { has: obj => "setTheme" in obj, get: obj => obj.setTheme }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _handleKey_decorators, { kind: "method", name: "handleKey", static: false, private: false, access: { has: obj => "handleKey" in obj, get: obj => obj.handleKey }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _handleMouse_decorators, { kind: "method", name: "handleMouse", static: false, private: false, access: { has: obj => "handleMouse" in obj, get: obj => obj.handleMouse }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
@@ -111,22 +102,15 @@ let Toggle = (() => {
         #variant_accessor_storage = (__runInitializers(this, _on_extraInitializers), __runInitializers(this, _variant_initializers, void 0));
         get variant() { return this.#variant_accessor_storage; }
         set variant(value) { this.#variant_accessor_storage = value; }
-        #_theme_accessor_storage = (__runInitializers(this, _variant_extraInitializers), __runInitializers(this, __theme_initializers, void 0));
-        // [LAW:types-are-the-program] @observableRef so setTheme() triggers a
-        // re-render — see slider.ts.
-        get _theme() { return this.#_theme_accessor_storage; }
-        set _theme(value) { this.#_theme_accessor_storage = value; }
         constructor(options) {
-            super();
-            __runInitializers(this, __theme_extraInitializers);
+            super(options.theme);
+            __runInitializers(this, _variant_extraInitializers);
             this.id = options.id ?? `toggle-${options.label.toLowerCase().replace(/\s+/g, "-")}`;
             this.label = options.label;
             this.on = options.on ?? false;
             this.variant = options.variant ?? "default";
             this.disabled = options.disabled ?? false;
-            this._theme = options.theme ?? DEFAULT_TERMINAL_THEME;
         }
-        setTheme(theme) { this._theme = theme; }
         // --- Event handlers ---
         handleKey(event) {
             if (this.disabled)
@@ -157,24 +141,17 @@ let Toggle = (() => {
             const indicator = this.on ? "[ON] " : "[OFF]";
             const text = `${indicator} ${this.label}`;
             if (this.disabled) {
-                return [new Segment(text, new Style({ color: "#666666", bgcolor: "#333333", dim: true }))];
+                return [new Segment(text, new Style(this.disabledInk))];
             }
             const keys = VARIANT_KEYS[this.variant];
-            const fg = this.resolvePalette(this.on ? keys.onFg : keys.offFg);
-            const bg = this.resolvePalette(this.on ? keys.onBg : keys.offBg);
-            return [new Segment(text, new Style({ color: fg, bgcolor: bg, underline: this.focused }))];
+            const colors = this.on ? ink(this.theme, keys.onFg, keys.onBg) : ink(this.theme, keys.offFg, keys.offBg);
+            return [new Segment(text, new Style({ ...colors, underline: this.focused }))];
         }
         measure(_options) {
             // [LAW:one-source-of-truth] cellLen — see button.ts.
             const width = 5 + 1 + cellLen(this.label);
             return { minimum: width, maximum: width };
         }
-        // --- Palette resolution ---
-        resolvePalette(key) {
-            const rgba = this._theme.palette.get(key);
-            // [LAW:no-defensive-null-guards] palette must contain all keys; missing is a construction bug.
-            return ColorSpec.fromRgba(rgba);
-        }
     };
 })();
 export { Toggle };

package/dist/widgets/types.d.ts

@@ -8,21 +8,15 @@
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import type { Segment } from "../core/segment.js";
 import type { Unsubscribe } from "../core/subscription.js";
-export interface KeyEventInit {
-    key: string;
-    character: string;
-    shift: boolean;
-    ctrl: boolean;
-    meta: boolean;
-}
-export declare class KeyEvent {
+import type { KeyPress, ScreenMouseEvent } from "../host/input.js";
+export declare class KeyEvent implements KeyPress {
     readonly key: string;
     readonly character: string;
     readonly shift: boolean;
     readonly ctrl: boolean;
     readonly meta: boolean;
     private _stopped;
-    constructor(init: KeyEventInit);
+    constructor(init: KeyPress);
     get stopped(): boolean;
     stop(): void;
 }
@@ -30,21 +24,11 @@ export type KeyHandlerPriority = "high" | "normal";
 export interface KeyHandlerOptions {
     priority?: KeyHandlerPriority;
 }
-export type ScreenMouseEvent = {
-    [T in MouseEventType]: MouseEventOf<T>;
-}[MouseEventType];
-type MouseEventType = "mouse_down" | "mouse_up" | "mouse_move" | "scroll_up" | "scroll_down";
-interface MouseEventOf<Type extends string> {
-    type: Type;
-    x: number;
-    y: number;
-    button: number;
-    shift: boolean;
-    ctrl: boolean;
-}
-export interface WidgetMouseEvent extends MouseEventOf<"mouse_down" | "mouse_up" | "mouse_move"> {
-    over: boolean;
-}
+export type WidgetMouseEvent = Extract<ScreenMouseEvent, {
+    type: "mouse_down" | "mouse_up" | "mouse_move";
+}> & {
+    readonly over: boolean;
+};
 export interface WidgetFocusEvent {
     type: "focus" | "blur";
 }
@@ -84,4 +68,3 @@ export interface FrameSource {
     readonly frame: readonly (readonly Segment[])[];
     refresh(): void;
 }
-export {};

package/dist/widgets/types.js

@@ -5,6 +5,14 @@
  * producing Segment[] from current state. They have no knowledge of stdin,
  * terminal escape sequences, or their host environment.
  */
+// --- Event types ---
+// [LAW:types-are-the-program] KeyEvent is a `KeyPress` the app heard, plus
+// the say over who else hears it. It carries a single mutable signal
+// (`stopped`) that participants in the dispatch chain set by calling
+// `stop()`. Treating it as an interface would force every handler to
+// shuttle a return value upward and the router to interpret it — the
+// class collapses that into one self-describing value flowing through
+// the chain.
 export class KeyEvent {
     key;
     character;

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

@@ -20,12 +20,21 @@
  *
  * [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.
+ * the view is a renderable, `onPaint` hears the frame, and `onKey`/`onMouse`
+ * hear the input.
  */
 import { Segment } from "../core/segment.js";
 import type { Unsubscribe } from "../core/subscription.js";
-import { type AppOptions, type AppPhase } from "../host/app.js";
-import type { FocusManager, FrameSource, KeyEvent, KeyHandlerOptions, ScreenMouseEvent } from "./types.js";
+import { type AppOptions, type AppPhase, type Wheel } from "../host/app.js";
+import type { FocusManager, FrameSource, KeyEvent, KeyHandlerOptions } from "./types.js";
+import type { AppMouseEvent } from "../host/app.js";
+export interface WidgetAppOptions extends AppOptions {
+    /**
+     * Whether a left-button press focuses the widget under it, before it hears the
+     * press. `true` unless given.
+     */
+    readonly focusOnClick?: boolean;
+}
 export declare class WidgetApp implements FrameSource {
     readonly focusManager: FocusManager;
     private readonly focus;
@@ -33,7 +42,7 @@ export declare class WidgetApp implements FrameSource {
     private readonly router;
     private readonly reaction;
     private drawn;
-    constructor(options: AppOptions);
+    constructor(options: WidgetAppOptions);
     get phase(): AppPhase;
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
@@ -51,13 +60,21 @@ export declare class WidgetApp implements FrameSource {
      */
     refresh(): void;
     suspend(): Promise<void>;
+    /** Paint at the app's rate until the returned function is called, as `App.animate` does. */
+    animate(): Unsubscribe;
     /**
-     * Hear every key. A `high` handler hears it before the focused widget, a
+     * Hear every key the app does not quit on. 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: (event: KeyEvent) => void, options?: KeyHandlerOptions): Unsubscribe;
-    /** Hear every pointer event, in terminal cells, before any widget does. */
-    onMouse(handler: (event: ScreenMouseEvent) => void): Unsubscribe;
+    /** Hear every pointer event but the vertical wheel, in terminal cells, before any widget does. */
+    onMouse(handler: (event: AppMouseEvent) => void): Unsubscribe;
+    /**
+     * Offer each wheel turn the viewport under the pointer did not move with to
+     * `handler`, as `App.onWheel` does: it returns whether it moved something,
+     * and a turn nothing moved with is passed outward.
+     */
+    onWheel(handler: (wheel: Wheel) => boolean): Unsubscribe;
     private compose;
 }

package/dist/widgets/widget-app.js

@@ -20,7 +20,8 @@
  *
  * [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.
+ * the view is a renderable, `onPaint` hears the frame, and `onKey`/`onMouse`
+ * hear the input.
  */
 import { Reaction } from "mobx";
 import { Segment } from "../core/segment.js";
@@ -40,16 +41,23 @@ export class WidgetApp {
     // The widgets the view drew for the frame on screen, in document order.
     drawn = [];
     constructor(options) {
-        const { view } = options;
+        const { view, focusOnClick = true } = options;
         this.reaction = new Reaction("WidgetApp", () => this.app.refresh());
-        const root = { render: (renderOptions) => this.compose(view, renderOptions) };
-        this.app = new App({ ...options, view: () => root });
+        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.router = new EventRouter({ source: this, focusOnClick });
+        // [LAW:single-enforcer] The app reads the terminal; the router routes
+        // what it hears, after the app's quit keys.
+        this.app.onKey((press) => this.router.key(press));
+        this.app.onMouse((event) => this.router.mouse(event));
+        this.app.onWheel((wheel) => this.router.wheel(wheel));
         this.app.onPaint(() => {
             this.focus.settle(this.drawn);
             this.router.framePainted();
@@ -70,18 +78,14 @@ export class WidgetApp {
      * 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.
+        // App refuses a second run; this one must not end the state 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;
+            await this.app.run();
         }
         finally {
-            this.router.stop();
+            this.router.reset();
             this.reaction.dispose();
         }
     }
@@ -102,18 +106,30 @@ export class WidgetApp {
     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
+     * Hear every key the app does not quit on. 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. */
+    /** Hear every pointer event but the vertical wheel, in terminal cells, before any widget does. */
     onMouse(handler) {
         return this.router.onMouse(handler);
     }
+    /**
+     * Offer each wheel turn the viewport under the pointer did not move with to
+     * `handler`, as `App.onWheel` does: it returns whether it moved something,
+     * and a turn nothing moved with is passed outward.
+     */
+    onWheel(handler) {
+        return this.app.onWheel(handler);
+    }
     compose(view, options) {
         const drawn = new Set();
         // [LAW:parse-dont-validate] An owner is any object; only a `WidgetBase`
@@ -176,12 +192,13 @@ function paintOverlay(lines, widget, options) {
     const at = footprintOf(lines, widget);
     if (!at)
         return;
-    // An overlay floats over the frame; no region holds it.
-    const overlay = widget.renderOverlay({ ...options, height: undefined });
+    // 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 width = Math.max(0, options.maxWidth - at.x);
-    const rows = Segment.anchorLines(Segment.splitLines(overlay), widget, at.rows).map((line) => Segment.adjustLineLength(line, width, undefined, false));
+    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`

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

@@ -8,6 +8,7 @@
  * 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";
@@ -32,6 +33,7 @@ export declare abstract class WidgetBase implements InteractiveWidget {
     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;

package/dist/widgets/widget-base.js

@@ -43,6 +43,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 };
 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;
@@ -150,16 +151,22 @@ let WidgetBase = (() => {
         // 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`.
+        // 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);
+            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,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",
@@ -61,25 +61,27 @@
     "build": "npm run clean && tsc",
     "test": "vitest run",
     "test:watch": "vitest",
+    "prelint": "node scripts/stage-repo-files.ts",
     "lint": "tsc --noEmit && tsc -p tsconfig.scripts.json && tsc -p tsconfig.test.json",
     "clean": "rm -rf dist",
-    "docs:dev": "npm run demos:build && vitepress dev docs",
-    "docs:build": "npm run demos:build && vitepress build docs",
+    "predocs:dev": "node scripts/stage-repo-files.ts",
+    "docs:dev": "vitepress dev docs",
+    "predocs:build": "node scripts/stage-repo-files.ts",
+    "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "demo": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-explore/index.js",
-    "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",
-    "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",
-    "demo:dropdown": "tsc -p tsconfig.demo.json && node dist-demo/examples/dropdown-demo/index.js",
-    "dash": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-dash/index.js",
-    "template-bindings": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-template-bindings/index.js",
-    "themes-and-color-studio": "tsc -p tsconfig.demo.json && node dist-demo/examples/themes-and-color-studio/index.js",
-    "harness:browser-host": "tsc -p tsconfig.demo.json && echo 'Serving harness at http://localhost:8080/examples/browser-terminal-host-harness/' && npx --yes http-server@14.1.1 -p 8080 -c-1 -s .",
-    "demos:build": "tsc -p tsconfig.demo.json && vite build --config vite.config.demos.ts",
-    "demos:preview": "vite preview --config vite.config.demos.ts",
+    "demo": "node scripts/build-demos.ts && node dist-demo/examples/rich-explore/node.js",
+    "demo:build": "node scripts/build-demos.ts",
+    "sessions": "node scripts/build-demos.ts && node dist-demo/examples/claude-sessions/node.js",
+    "strip": "node scripts/build-demos.ts && node dist-demo/examples/rich-strip/main.js",
+    "effects-feel": "node scripts/build-demos.ts && node dist-demo/examples/effects-feel/index.js",
+    "viewport": "node scripts/build-demos.ts && node dist-demo/examples/rich-viewport/main.js",
+    "markup-plugins": "node scripts/build-demos.ts && node dist-demo/examples/rich-markup-plugins/main.js",
+    "demo-inputs": "node scripts/build-demos.ts && node dist-demo/examples/rich-config/main.js",
+    "demo:dropdown": "node scripts/build-demos.ts && node dist-demo/examples/dropdown-demo/main.js",
+    "dash": "node scripts/build-demos.ts && node dist-demo/examples/rich-dash/node.js",
+    "template-bindings": "node scripts/build-demos.ts && node dist-demo/examples/rich-template-bindings/main.js",
+    "themes-and-color-studio": "node scripts/build-demos.ts && node dist-demo/examples/themes-and-color-studio/node.js",
+    "terminal-host": "node scripts/build-demos.ts && node dist-demo/examples/terminal-host/main.js",
     "test:demos": "playwright test"
   },
   "keywords": [
@@ -96,20 +98,32 @@
     "cli"
   ],
   "license": "MIT",
+  "devEngines": {
+    "runtime": { "name": "node", "version": "^22.18.0 || >=23.6.0", "onFail": "error" }
+  },
   "engines": {
     "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",