@promptctl/rich-js 0.19.0 → 0.20.0

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[])[];
@@ -54,12 +63,18 @@ export declare class WidgetApp implements FrameSource {
     /** 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,7 +41,7 @@ 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());
         this.app = new App({
             ...options,
@@ -51,7 +52,12 @@ export class WidgetApp {
             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();
@@ -72,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();
         }
     }
@@ -109,17 +111,25 @@ export class WidgetApp {
         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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",
@@ -61,26 +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",
-    "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",
-    "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": [
@@ -97,6 +98,9 @@
     "cli"
   ],
   "license": "MIT",
+  "devEngines": {
+    "runtime": { "name": "node", "version": "^22.18.0 || >=23.6.0", "onFail": "error" }
+  },
   "engines": {
     "node": ">=20"
   },