@promptctl/rich-js 0.24.1 → 0.25.1

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

@@ -26,8 +26,10 @@
  * hear the input.
  */
 import { Segment } from "../core/segment.js";
-import type { Presence } from "../core/protocol.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";
@@ -44,7 +46,7 @@ export interface WidgetPresence {
     readonly widget: WidgetBase;
     readonly presence: Presence;
 }
-export declare class WidgetApp implements FrameSource {
+export declare class WidgetApp implements FrameSource, FrameHost {
     readonly focusManager: FocusManager;
     private readonly focus;
     private readonly app;
@@ -53,6 +55,14 @@ export declare class WidgetApp implements FrameSource {
     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
@@ -62,6 +72,8 @@ export declare class WidgetApp implements FrameSource {
     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.
@@ -76,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

@@ -28,6 +28,7 @@
 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";
@@ -43,11 +44,20 @@ export class WidgetApp {
     reaction;
     _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({
             present: () => this.widgets,
@@ -55,6 +65,7 @@ export class WidgetApp {
                 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 });
@@ -74,6 +85,24 @@ 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
@@ -89,6 +118,10 @@ export class WidgetApp {
     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.
@@ -122,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
@@ -163,7 +192,7 @@ export class WidgetApp {
         // 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(render(view(), drawing));
+            const base = Segment.splitLines(render(view, drawing));
             for (const widget of present.keys())
                 paintOverlay(base, widget, drawing);
             return base;

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,27 +130,26 @@ 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
@@ -167,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.1",
+  "version": "0.25.1",
   "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",