@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/widgets/themed-widget.js

@@ -41,7 +41,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { observableRef, action } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 import { Style } from "../core/style.js";
 import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
 import { WidgetBase } from "./widget-base.js";

package/dist/widgets/toggle.js

@@ -44,7 +44,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { observable, action, observableRef } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { cellLen } from "../core/cells.js";
@@ -79,8 +80,8 @@ let Toggle = (() => {
     return class Toggle extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _label_decorators = [observable];
-            _on_decorators = [observable];
+            _label_decorators = [observableRef];
+            _on_decorators = [observableRef];
             _variant_decorators = [observableRef];
             _handleKey_decorators = [action];
             _handleMouse_decorators = [action];

package/dist/widgets/types.d.ts

@@ -7,6 +7,7 @@
  */
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import type { Segment } from "../core/segment.js";
+import type { Anchor } from "../core/anchor.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import type { KeyPress, ScreenMouseEvent } from "../host/input.js";
 export declare class KeyEvent implements KeyPress {
@@ -15,8 +16,9 @@ export declare class KeyEvent implements KeyPress {
     readonly shift: boolean;
     readonly ctrl: boolean;
     readonly meta: boolean;
+    readonly time: number;
     private _stopped;
-    constructor(init: KeyPress);
+    constructor(init: KeyPress, time: number);
     get stopped(): boolean;
     stop(): void;
 }
@@ -28,9 +30,12 @@ export type WidgetMouseEvent = Extract<ScreenMouseEvent, {
     type: "mouse_down" | "mouse_up" | "mouse_move";
 }> & {
     readonly over: boolean;
+    readonly cell: Anchor | undefined;
+    readonly time: number;
 };
 export interface WidgetFocusEvent {
-    type: "focus" | "blur";
+    readonly type: "focus" | "blur";
+    readonly time: number;
 }
 export interface InteractiveWidget extends Renderable, Measurable {
     readonly id: string;
@@ -42,8 +47,8 @@ export interface InteractiveWidget extends Renderable, Measurable {
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     handleFocus(event: WidgetFocusEvent): void;
-    focus(): void;
-    blur(): void;
+    focus(time: number): void;
+    blur(time: number): void;
     setDisabled(value: boolean): void;
     setHovered(value: boolean): void;
     onChange(handler: (widget: InteractiveWidget) => void): Unsubscribe;
@@ -66,5 +71,6 @@ export interface FocusManager {
 export interface FrameSource {
     readonly focusManager: FocusManager;
     readonly frame: readonly (readonly Segment[])[];
+    readonly frameTime: number;
     refresh(): void;
 }

package/dist/widgets/types.js

@@ -6,8 +6,12 @@
  * terminal escape sequences, or their host environment.
  */
 // --- Event types ---
+// Every event a widget hears carries `time`: when it was heard, on the clock
+// the frame's cells are read on (`RenderOptions.frame`), so a widget
+// keeping the moment of its last interaction — a caret's blink restarting —
+// compares it with the frame it draws and never reads a clock.
 // [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
+// when it was heard and 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
@@ -19,13 +23,15 @@ export class KeyEvent {
     shift;
     ctrl;
     meta;
+    time;
     _stopped = false;
-    constructor(init) {
+    constructor(init, time) {
         this.key = init.key;
         this.character = init.character;
         this.shift = init.shift;
         this.ctrl = init.ctrl;
         this.meta = init.meta;
+        this.time = time;
     }
     get stopped() { return this._stopped; }
     // Claim this key. Halts further chain dispatch — no high/normal handler

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

@@ -7,8 +7,10 @@
  * `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.
+ * - Focus moves in document order: the order the view reports its widgets in
+ *   (`RenderOptions.onPresent`), among those with a cell on the frame on screen.
+ *   A widget its container hands no column is reported held, not drawn: it is
+ *   in the view, so it keeps focus, and it has no cell, so Tab passes it.
  *   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
@@ -24,10 +26,14 @@
  * hear the input.
  */
 import { Segment } from "../core/segment.js";
+import type { FrameHost, Presence } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
+import type { Clock, FrameRate } from "../core/clock.js";
+import type { Timeline } from "../core/timeline.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";
+import { WidgetBase } from "./widget-base.js";
 export interface WidgetAppOptions extends AppOptions {
     /**
      * Whether a left-button press focuses the widget under it, before it hears the
@@ -35,17 +41,39 @@ export interface WidgetAppOptions extends AppOptions {
      */
     readonly focusOnClick?: boolean;
 }
-export declare class WidgetApp implements FrameSource {
+/** A widget the view reported for a frame, and whether it was drawn or held. */
+export interface WidgetPresence {
+    readonly widget: WidgetBase;
+    readonly presence: Presence;
+}
+export declare class WidgetApp implements FrameSource, FrameHost {
     readonly focusManager: FocusManager;
     private readonly focus;
     private readonly app;
     private readonly router;
     private readonly reaction;
-    private drawn;
+    private _present;
     constructor(options: WidgetAppOptions);
     get phase(): AppPhase;
+    /** The clock the app reads the time from: where the host time a `Timeline` operation takes is read. */
+    get clock(): Clock;
+    /** The map from the clock to the time the view is drawn for; setting it paints the frame for the new time, as `App.timeline` does. */
+    get timeline(): Timeline;
+    set timeline(timeline: Timeline);
+    /** How often the app paints while what it shows moves; setting it goes on at the new rate from the next frame, as `App.rate` does. */
+    get rate(): FrameRate;
+    set rate(rate: FrameRate);
+    /**
+     * The widgets the view reported for the frame on screen, in document order,
+     * each drawn or held (`RenderOptions.onPresent`). A held widget is one its
+     * container handed no column: in the view, with no cell on the frame.
+     */
+    get present(): readonly WidgetPresence[];
+    private get widgets();
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
+    /** The time a frame drawn now is drawn for, as `App.frameTime` reads it. */
+    get frameTime(): number;
     /**
      * Take the terminal, paint the first frame, and route input to its widgets
      * until the app stops — `App.run`, with the input.
@@ -60,8 +88,6 @@ 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 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

package/dist/widgets/widget-app.js

@@ -7,8 +7,10 @@
  * `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.
+ * - Focus moves in document order: the order the view reports its widgets in
+ *   (`RenderOptions.onPresent`), among those with a cell on the frame on screen.
+ *   A widget its container hands no column is reported held, not drawn: it is
+ *   in the view, so it keeps focus, and it has no cell, so Tab passes it.
  *   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
@@ -25,6 +27,8 @@
  */
 import { Reaction } from "mobx";
 import { Segment } from "../core/segment.js";
+import { render } from "../core/protocol.js";
+import { hostView } from "../core/view.js";
 import { App } from "../host/app.js";
 import { DefaultFocusManager } from "./focus-manager.js";
 import { EventRouter } from "./event-router.js";
@@ -38,18 +42,30 @@ export class WidgetApp {
     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 = [];
+    _present = [];
     constructor(options) {
-        const { view, focusOnClick = true } = options;
+        const { focusOnClick = true } = options;
+        const view = hostView(options.view);
         this.reaction = new Reaction("WidgetApp", () => this.app.refresh());
+        // The view is drawn inside `compose`, where what it reads is tracked —
+        // a function view asked there too — and when it changes is its own to
+        // say, as it would be to the App.
+        // Its frames are its own, drawn for its `frameTime`: what draws in them
+        // is told this app is the host, not the App it paints through, so
+        // `drawnBy: widgetApp` names the host its frames carry.
         this.app = new App({
             ...options,
-            view: (t) => ({ render: (renderOptions) => this.compose(() => view(t), renderOptions) }),
+            view: {
+                render: (renderOptions) => this.compose(view, { ...renderOptions, frame: renderOptions.frame && { time: renderOptions.frame.time, host: this } }),
+            },
         });
-        this.focus = new DefaultFocusManager(() => {
-            const owners = ownersOn(this.app.frame);
-            return this.drawn.filter((widget) => owners.has(widget));
+        this.focus = new DefaultFocusManager({
+            present: () => this.widgets,
+            onScreen: () => {
+                const owners = ownersOn(this.app.frame);
+                return this.widgets.filter((widget) => owners.has(widget));
+            },
+            frameTime: () => this.frameTime,
         });
         this.focusManager = this.focus;
         this.router = new EventRouter({ source: this, focusOnClick });
@@ -59,7 +75,7 @@ export class WidgetApp {
         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.focus.settle();
             this.router.framePainted();
         });
         // [LAW:single-enforcer] `settle` judges every focus move, so every move
@@ -69,10 +85,43 @@ export class WidgetApp {
     get phase() {
         return this.app.phase;
     }
+    /** The clock the app reads the time from: where the host time a `Timeline` operation takes is read. */
+    get clock() {
+        return this.app.clock;
+    }
+    /** The map from the clock to the time the view is drawn for; setting it paints the frame for the new time, as `App.timeline` does. */
+    get timeline() {
+        return this.app.timeline;
+    }
+    set timeline(timeline) {
+        this.app.timeline = timeline;
+    }
+    /** How often the app paints while what it shows moves; setting it goes on at the new rate from the next frame, as `App.rate` does. */
+    get rate() {
+        return this.app.rate;
+    }
+    set rate(rate) {
+        this.app.rate = rate;
+    }
+    /**
+     * The widgets the view reported for the frame on screen, in document order,
+     * each drawn or held (`RenderOptions.onPresent`). A held widget is one its
+     * container handed no column: in the view, with no cell on the frame.
+     */
+    get present() {
+        return this._present;
+    }
+    get widgets() {
+        return this._present.map(({ widget }) => widget);
+    }
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame() {
         return this.app.frame;
     }
+    /** The time a frame drawn now is drawn for, as `App.frameTime` reads it. */
+    get frameTime() {
+        return this.app.frameTime;
+    }
     /**
      * Take the terminal, paint the first frame, and route input to its widgets
      * until the app stops — `App.run`, with the input.
@@ -106,10 +155,6 @@ 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 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
@@ -131,26 +176,28 @@ export class WidgetApp {
         return this.app.onWheel(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);
+        // Each widget once, where it was first reported; drawn anywhere, it is drawn.
+        const present = new Map();
+        // [LAW:parse-dont-validate] What the view reports is any renderable; only
+        // a `WidgetBase` is a widget, so this is where a renderable becomes one.
+        const onPresent = (renderable, presence) => {
+            if (renderable instanceof WidgetBase)
+                present.set(renderable, present.get(renderable) === "drawn" ? "drawn" : presence);
         };
         // 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 };
+        // An overlay reports what it draws too: a widget in it is in the view,
+        // and visiting `present` in report order paints its overlay in turn. A
+        // held widget has no footprint on the frame, and so paints none.
+        const drawing = { ...options, onPresent };
         const lines = tracked(this.reaction, () => {
-            const base = Segment.splitLines(view().render(render));
-            for (const widget of drawn)
-                paintOverlay(base, widget, render);
+            const base = Segment.splitLines(render(view, drawing));
+            for (const widget of present.keys())
+                paintOverlay(base, widget, drawing);
             return base;
         });
-        this.drawn = [...drawn];
+        this._present = [...present].map(([widget, presence]) => ({ widget, presence }));
         return lines.flatMap((line) => [...line, Segment.line()]);
     }
 }

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

@@ -24,8 +24,8 @@ export declare abstract class WidgetBase implements InteractiveWidget {
     abstract handleKey(event: KeyEvent): void;
     handleMouse(_event: WidgetMouseEvent): void;
     handleFocus(event: WidgetFocusEvent): void;
-    focus(): void;
-    blur(): void;
+    focus(time: number): void;
+    blur(time: number): void;
     setDisabled(value: boolean): void;
     setHovered(value: boolean): void;
     onChange(handler: (widget: InteractiveWidget) => void): Unsubscribe;

package/dist/widgets/widget-base.js

@@ -41,9 +41,11 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { observable, action } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
+import { State } from "../core/state.js";
 let WidgetBase = (() => {
     let _instanceExtraInitializers = [];
     let _focused_decorators;
@@ -66,10 +68,10 @@ let WidgetBase = (() => {
     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];
+            _focused_decorators = [observableRef];
+            _hovered_decorators = [observableRef];
+            _active_decorators = [observableRef];
+            _disabled_decorators = [observableRef];
             _handleFocus_decorators = [action];
             _focus_decorators = [action];
             _blur_decorators = [action];
@@ -98,8 +100,9 @@ let WidgetBase = (() => {
         #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();
+        // Subscribed and let go between frames; each set is replaced whole.
+        changeHandlers = (__runInitializers(this, _disabled_extraInitializers), new State(new Set()));
+        submitHandlers = new State(new Set());
         handleMouse(_event) { }
         handleFocus(event) {
             this.focused = event.type === "focus";
@@ -109,11 +112,11 @@ let WidgetBase = (() => {
         // 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" });
+        focus(time) {
+            this.handleFocus({ type: "focus", time });
         }
-        blur() {
-            this.handleFocus({ type: "blur" });
+        blur(time) {
+            this.handleFocus({ type: "blur", time });
         }
         setDisabled(value) {
             this.disabled = value;
@@ -127,36 +130,32 @@ let WidgetBase = (() => {
         }
         // --- Subscriptions ---
         onChange(handler) {
-            this.changeHandlers.add(handler);
-            return () => this.changeHandlers.delete(handler);
+            return subscribe(this.changeHandlers, handler);
         }
         onSubmit(handler) {
-            this.submitHandlers.add(handler);
-            return () => this.submitHandlers.delete(handler);
+            return subscribe(this.submitHandlers, handler);
         }
         emitChange() {
-            for (const handler of this.changeHandlers) {
+            for (const handler of this.changeHandlers.get()) {
                 handler(this);
             }
         }
         emitSubmit() {
-            for (const handler of this.submitHandlers) {
+            for (const handler of this.submitHandlers.get()) {
                 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
+        // (`widgetAt`). Subclasses draw; none stamps itself — what a draw stamps
+        // inside this stamp is its own (`WidgetMouseEvent.cell`). 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);
@@ -170,3 +169,12 @@ let WidgetBase = (() => {
     };
 })();
 export { WidgetBase };
+/** `handler` added to `handlers` until the returned call takes it out. */
+function subscribe(handlers, handler) {
+    handlers.set(new Set(handlers.get()).add(handler));
+    return () => {
+        const left = new Set(handlers.get());
+        left.delete(handler);
+        handlers.set(left);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",
@@ -74,6 +74,13 @@
     "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",
+    "glyph-effects": "node scripts/build-demos.ts && node dist-demo/examples/glyph-effects/index.js",
+    "attribute-effects": "node scripts/build-demos.ts && node dist-demo/examples/attribute-effects/index.js",
+    "gradient-effects": "node scripts/build-demos.ts && node dist-demo/examples/gradient-effects/index.js",
+    "transitions": "node scripts/build-demos.ts && node dist-demo/examples/transitions/index.js",
+    "lifecycle": "node scripts/build-demos.ts && node dist-demo/examples/lifecycle/index.js",
+    "animation-playground": "node scripts/build-demos.ts && node dist-demo/examples/animation-playground/main.js",
+    "scroll": "node scripts/build-demos.ts && node dist-demo/examples/scroll/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",
@@ -101,7 +108,7 @@
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": "^22.18.0 || >=23.6.0",
+      "version": "^22.19.0 || >=23.9.0",
       "onFail": "error"
     }
   },
@@ -133,9 +140,6 @@
     "vitepress": "^1.6.4",
     "vitest": "^5.0.0"
   },
-  "dependencies": {
-    "string-width": "^8.2.2"
-  },
   "peerDependencies": {
     "@promptctl/go-template-js": "^0.10.0",
     "mobx": "^7.0.3"