@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/themes/data/types.d.ts

@@ -11,5 +11,21 @@
 export interface ThemePaletteData {
     readonly name: string;
     readonly dark: boolean;
+    /**
+     * The sixteen colours a terminal showing this theme draws `red`, `blue`,
+     * `bright_black` and the rest in. A theme without its own table would draw
+     * them in the VGA defaults (`blue` as #000080), which belong to no theme.
+     */
+    readonly ansi: AnsiColorsData;
     readonly vars: Readonly<Record<string, string>>;
 }
+/**
+ * ANSI colour numbers 0–15 in order: the eight normal colours, then their
+ * bright forms. Named rather than positional so a data file cannot shift a
+ * colour into its neighbour's slot by miscounting.
+ */
+export declare const ANSI_SLOTS: readonly ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite"];
+/** One `#RRGGBB` per ANSI colour number, keyed by `ANSI_SLOTS`. */
+export type AnsiColorsData = {
+    readonly [K in (typeof ANSI_SLOTS)[number]]: string;
+};

package/dist/themes/data/types.js

@@ -1 +1,10 @@
-export {};
+/**
+ * ANSI colour numbers 0–15 in order: the eight normal colours, then their
+ * bright forms. Named rather than positional so a data file cannot shift a
+ * colour into its neighbour's slot by miscounting.
+ */
+export const ANSI_SLOTS = [
+    "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white",
+    "brightBlack", "brightRed", "brightGreen", "brightYellow",
+    "brightBlue", "brightMagenta", "brightCyan", "brightWhite",
+];

package/dist/themes/registry.d.ts

@@ -1,4 +1,4 @@
-import { ColorRgba } from "../core/color.js";
+import { ColorRgba, ColorTable } from "../core/color.js";
 import { Palette } from "./palette.js";
 import { type ThemeName } from "./data/index.js";
 export type { ThemeName };
@@ -17,7 +17,7 @@ export declare function listThemePalettes(): readonly ThemeName[];
 export declare function getThemePalette(name: ThemeName): Palette;
 export declare function getThemePalette(name: string): Palette | null;
 /**
- * The eight base colors every theme must declare. Returned by
+ * The eight base colors every theme must declare, and its ANSI table. Returned by
  * `getThemeBaseColors` for callers (notably `terminalThemes.ts`) that only
  * need the substrate and would otherwise pay the cost of hydrating the
  * full ~150-var palette and polluting the registry cache.
@@ -33,6 +33,7 @@ export interface ThemeBaseColors {
     readonly success: ColorRgba;
     readonly warning: ColorRgba;
     readonly error: ColorRgba;
+    readonly ansi: ColorTable;
 }
 /**
  * Read just the eight base colors from a theme's data file. Cheap — parses

package/dist/themes/registry.js

@@ -1,6 +1,7 @@
-import { parseRgbHex, parseRgbaHex } from "../core/color.js";
+import { ColorTable, parseRgbHex, parseRgbaHex } from "../core/color.js";
 import { Palette } from "./palette.js";
 import { THEMES } from "./data/index.js";
+import { ANSI_SLOTS } from "./data/types.js";
 const THEME_NAMES = Object.freeze(Object.keys(THEMES).sort());
 const cache = new Map();
 /**
@@ -41,6 +42,7 @@ export function getThemeBaseColors(name) {
         success: requireBaseVar(data, "success"),
         warning: requireBaseVar(data, "warning"),
         error: requireBaseVar(data, "error"),
+        ansi: new ColorTable(ANSI_SLOTS.map((slot) => parseOpaqueHex(data.ansi[slot], data.name, `ansi.${slot}`))),
     };
 }
 function requireBaseVar(data, key) {
@@ -72,6 +74,16 @@ function hydrate(data) {
 // the untrusted side (authored data files) and the place that has to
 // reject `"0G"`, `""`, `"#GGGGGG"`, etc.
 const HEX_RE = /^[0-9a-fA-F]+$/;
+/**
+ * An ANSI slot is a colour a terminal paints, never a blend, so it takes no
+ * alpha: `flattenAlpha` leaves a STANDARD spec alone and would pass one through.
+ */
+function parseOpaqueHex(value, theme, key) {
+    if (!/^#[0-9A-Fa-f]{6}$/.test(value)) {
+        throw new Error(`Theme ${theme}: ${key} has invalid hex ${JSON.stringify(value)} (expected #RRGGBB)`);
+    }
+    return parseRgbHex(value.slice(1));
+}
 function parseHex(value, theme, key) {
     const hex = value.startsWith("#") ? value.slice(1) : value;
     if ((hex.length !== 6 && hex.length !== 8) || !HEX_RE.test(hex)) {

package/dist/themes/terminalThemes.d.ts

@@ -11,8 +11,8 @@
  *
  * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`. This
  * module is a derived view that builds a `TerminalTheme` from each
- * theme's eight base colors via `buildPalette` for the substrate palette
- * and `STANDARD_TABLE` for the ANSI substrate.
+ * theme's eight base colors via `buildPalette` for the substrate palette,
+ * and from the theme's own ANSI table for the sixteen named colours.
  *
  * [LAW:one-type-per-behavior] Every theme has the same shape — name,
  * `dark` flag, full Palette in the registry, `TerminalTheme` constant
@@ -22,11 +22,6 @@
  * [LAW:one-way-deps] `core/color → themes/palette` remains the only edge
  * into themes/. This file imports only sibling theme modules and core
  * color primitives; nothing in `core/` imports back.
- *
- * Note on `ansiColors`: every preset theme uses `STANDARD_TABLE`. Theme
- * identity lives in the semantic `palette`, not in the standard ANSI
- * 16/256 LUT — `ColorSpec.parse("red")` is intentionally canonical across
- * themes, matching Textual's model.
  */
 import { TerminalTheme } from "../core/color.js";
 export declare const DEFAULT_TERMINAL_THEME: TerminalTheme;

package/dist/themes/terminalThemes.js

@@ -11,8 +11,8 @@
  *
  * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`. This
  * module is a derived view that builds a `TerminalTheme` from each
- * theme's eight base colors via `buildPalette` for the substrate palette
- * and `STANDARD_TABLE` for the ANSI substrate.
+ * theme's eight base colors via `buildPalette` for the substrate palette,
+ * and from the theme's own ANSI table for the sixteen named colours.
  *
  * [LAW:one-type-per-behavior] Every theme has the same shape — name,
  * `dark` flag, full Palette in the registry, `TerminalTheme` constant
@@ -22,17 +22,12 @@
  * [LAW:one-way-deps] `core/color → themes/palette` remains the only edge
  * into themes/. This file imports only sibling theme modules and core
  * color primitives; nothing in `core/` imports back.
- *
- * Note on `ansiColors`: every preset theme uses `STANDARD_TABLE`. Theme
- * identity lives in the semantic `palette`, not in the standard ANSI
- * 16/256 LUT — `ColorSpec.parse("red")` is intentionally canonical across
- * themes, matching Textual's model.
  */
-import { STANDARD_TABLE, TerminalTheme, } from "../core/color.js";
+import { TerminalTheme } from "../core/color.js";
 import { buildPalette } from "./buildPalette.js";
 import { getThemeBaseColors } from "./registry.js";
 function defineTheme(d) {
-    return new TerminalTheme(d.bg, d.fg, STANDARD_TABLE, buildPalette(d.name, d.dark, {
+    return new TerminalTheme(d.bg, d.fg, d.ansi, buildPalette(d.name, d.dark, {
         primary: d.primary,
         secondary: d.secondary,
         accent: d.accent,

package/dist/widgets/button.d.ts

@@ -39,7 +39,7 @@ export declare class Button extends WidgetBase {
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     setActive(value: boolean): void;
-    render(_options: RenderOptions): Iterable<Segment>;
+    protected draw(_options: RenderOptions): Iterable<Segment>;
     measure(_options: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/widgets/button.js

@@ -151,17 +151,19 @@ let Button = (() => {
             if (event.type === "mouse_down") {
                 this.active = true;
             }
+            // A release that dragged off the button cancels the press.
             if (event.type === "mouse_up") {
                 if (this.active) {
                     this.active = false;
-                    this.emitSubmit();
+                    if (event.over)
+                        this.emitSubmit();
                 }
             }
         }
         // --- Active mutator (the keyboard-activation microtask uses this) ---
         setActive(value) { this.active = value; }
         // --- Rendering ---
-        render(_options) {
+        draw(_options) {
             // [LAW:dataflow-not-control-flow] same segment count and width every state
             const focused = this.focused;
             const left = focused ? "[" : " ";

package/dist/widgets/checkbox.d.ts

@@ -11,7 +11,7 @@
  *   disabled  — dimmed
  */
 import { Segment } from "../core/segment.js";
-import type { RenderOptions } from "../core/protocol.js";
+import { type RenderOptions } from "../core/protocol.js";
 import type { TerminalTheme } from "../core/color.js";
 import { WidgetBase } from "./widget-base.js";
 import type { KeyEvent, WidgetMouseEvent } from "./types.js";
@@ -32,7 +32,7 @@ export declare class Checkbox extends WidgetBase {
     setTheme(theme: TerminalTheme): void;
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
-    render(options: RenderOptions): Iterable<Segment>;
+    protected draw(options: RenderOptions): Iterable<Segment>;
     measure(_options: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/widgets/checkbox.js

@@ -50,6 +50,7 @@ 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 { drawable } from "../core/protocol.js";
 import { WidgetBase } from "./widget-base.js";
 let Checkbox = (() => {
     let _classSuper = WidgetBase;
@@ -124,14 +125,15 @@ let Checkbox = (() => {
         handleMouse(event) {
             if (this.disabled)
                 return;
-            if (event.type === "mouse_up") {
+            // A release that dragged off the checkbox cancels the press.
+            if (event.type === "mouse_up" && event.over) {
                 this.checked = !this.checked;
                 this.emitChange();
             }
         }
         // --- Rendering ---
-        render(options) {
-            const indicator = this.checked ? (options.asciiOnly ? "x" : "✓") : " ";
+        draw(options) {
+            const indicator = this.checked ? drawable(options, "✓", "x") : " ";
             const text = `[${indicator}] ${this.label}`;
             if (this.disabled) {
                 return [new Segment(text, new Style({ color: "#666666", bgcolor: "#333333", dim: true }))];

package/dist/widgets/dropdown.d.ts

@@ -23,7 +23,7 @@
  * than the header. See docs/widgets.md → Dropdown.
  */
 import { Segment } from "../core/segment.js";
-import type { RenderOptions } from "../core/protocol.js";
+import { type RenderOptions } from "../core/protocol.js";
 import type { TerminalTheme } from "../core/color.js";
 import { WidgetBase } from "./widget-base.js";
 import type { KeyEvent, WidgetMouseEvent, WidgetFocusEvent, OverlayRenderable } from "./types.js";
@@ -53,7 +53,7 @@ export declare class Dropdown extends WidgetBase implements OverlayRenderable {
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     handleFocus(event: WidgetFocusEvent): void;
-    render(options: RenderOptions): Iterable<Segment>;
+    protected draw(options: RenderOptions): Iterable<Segment>;
     private headerText;
     renderOverlay(_options: RenderOptions): Iterable<Segment> | null;
     private renderNoMatchRow;

package/dist/widgets/dropdown.js

@@ -62,6 +62,7 @@ import { Style } from "../core/style.js";
 import { ColorSpec } from "../core/color.js";
 import { cellLen, setCellSize, splitText, asCellCol } from "../core/cells.js";
 import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
+import { drawable } from "../core/protocol.js";
 import { WidgetBase } from "./widget-base.js";
 let Dropdown = (() => {
     let _classSuper = WidgetBase;
@@ -263,13 +264,11 @@ let Dropdown = (() => {
                 return;
             if (event.type !== "mouse_up")
                 return;
-            const b = this.bounds;
-            if (!b)
-                return;
-            const inside = event.x >= b.x &&
-                event.x < b.x + b.width &&
-                event.y >= b.y &&
-                event.y < b.y + b.height;
+            // [LAW:one-source-of-truth] Whether the release is on this dropdown is
+            // read off the frame (`over`), not its own idea of its size; a press on
+            // it that dragged away releases elsewhere. Row 0 is the header, and the
+            // overlay rows continue below it.
+            const inside = event.over;
             if (!this.expanded) {
                 if (inside) {
                     this.expanded = true;
@@ -284,15 +283,14 @@ let Dropdown = (() => {
                 this.expanded = false;
                 return;
             }
-            const rowOffset = event.y - b.y;
-            if (rowOffset === 0) {
+            if (event.y === 0) {
                 // Click the header → collapse + clear filter, no selection change.
                 this.filter = "";
                 this.expanded = false;
                 return;
             }
             // [LAW:one-source-of-truth] Filtered position → canonical idx.
-            const picked = this.filteredOptions[rowOffset - 1];
+            const picked = this.filteredOptions[event.y - 1];
             if (picked === undefined)
                 return;
             this.selectedIndex = picked.idx;
@@ -314,15 +312,14 @@ let Dropdown = (() => {
             }
         }
         // --- Rendering ---
-        render(options) {
+        draw(options) {
             // Header only — the inline footprint that flow layout sees. Always
             // 1 row regardless of `expanded`/`filter`. Option rows live in
             // renderOverlay. Width invariant: maxLabelLen + 4.
-            const arrowChar = options.asciiOnly ? "v" : "▾";
-            // [LAW:one-source-of-truth] render() owns the asciiOnly switch; the
-            // caret character flows into headerText as data rather than headerText
-            // re-reading the option flag. Same arrow / caret resolution path.
-            const caret = this.focused ? (options.asciiOnly ? "|" : "│") : "";
+            const arrowChar = drawable(options, "▾", "v");
+            // [LAW:one-source-of-truth] Both glyphs are resolved here, once, and flow
+            // into headerText as data rather than headerText re-reading the options.
+            const caret = this.focused ? drawable(options, "│", "|") : "";
             const maxLabelLen = this.maxLabelLen();
             const baseStyle = this.disabled
                 ? new Style({ color: "#666666", bgcolor: "#333333", dim: true })

package/dist/widgets/event-router.d.ts

@@ -1,6 +1,9 @@
 /**
- * EventRouter — parses raw stdin into KeyEvent / WidgetMouseEvent values
- * and dispatches them to widgets via the Screen's FocusManager and bounds.
+ * EventRouter — parses raw stdin into KeyEvent / ScreenMouseEvent values
+ * and dispatches them to widgets via a FocusManager and the frame on screen.
+ *
+ * It reads the terminal and never sets it up: raw mode and mouse tracking are
+ * the runtime's (`App`), which undoes them on every path out.
  *
  * [LAW:single-enforcer] ANSI escape parsing lives only here — widgets never
  * see raw bytes. One parser, one dispatch surface.
@@ -17,51 +20,40 @@
  * if it extends the sequence. Tests can call `flush()` to drain synchronously.
  */
 import { KeyEvent } from "./types.js";
-import type { Screen, FocusManager, InteractiveWidget, WidgetMouseEvent, KeyHandlerOptions } from "./types.js";
+import type { FrameSource, ScreenMouseEvent, KeyHandlerOptions } from "./types.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import type { TerminalHost } from "../host/terminal-host.js";
 type KeyHandler = (event: KeyEvent) => void;
-type WidgetSource = {
-    focusManager: FocusManager;
-    getWidgets: () => readonly InteractiveWidget[];
-};
 export interface EventRouterOptions {
-    screen: Screen | WidgetSource;
-    /**
-     * The I/O capability the router reads input from and writes
-     * mouse-tracking sequences to. Construct a `NodeTerminalHost` for
-     * production node demos; tests pass a host that wraps mock streams.
-     */
+    source: FrameSource;
+    /** The I/O capability the router reads input from. */
     host: TerminalHost;
-    /**
-     * When true (default when the host reports `isTTY`), enable mouse
-     * tracking on `start()` and disable on `stop()`. Disable in tests /
-     * non-TTY environments.
-     */
-    manageMouse?: boolean;
-    /**
-     * When true (default when the host reports `isTTY`), switch the host
-     * into raw mode on `start()` and restore on `stop()`.
-     */
-    manageRawMode?: boolean;
 }
 export declare class EventRouter {
     private readonly source;
     private readonly host;
-    private readonly manageMouse;
-    private readonly manageRawMode;
     private buffer;
     private running;
     private dataUnsubscribe;
     private escTimer;
-    private capturedWidget;
+    private captured;
+    private pointer;
+    private hoveredWidget;
     private readonly keyChain;
     private readonly mouseHandlers;
     constructor(options: EventRouterOptions);
     start(): void;
     stop(): void;
+    /**
+     * Read hover again off the frame just painted: under a pointer that has not
+     * moved, a widget may have gone, moved, or arrived.
+     *
+     * [LAW:one-source-of-truth] Hover is the widget under the pointer on the
+     * frame on screen, so it is re-read whenever either one changes.
+     */
+    framePainted(): void;
     onKey(handler: KeyHandler, options?: KeyHandlerOptions): Unsubscribe;
-    onMouse(handler: (event: WidgetMouseEvent) => void): Unsubscribe;
+    onMouse(handler: (event: ScreenMouseEvent) => void): Unsubscribe;
     /** Feed a chunk of bytes (or a string of bytes) into the parser. */
     feed(chunk: Uint8Array | string): void;
     /** Force any pending lone ESC out of the buffer. */
@@ -74,5 +66,6 @@ export declare class EventRouter {
     private consumeCSI;
     private dispatchKey;
     private dispatchMouse;
+    private hover;
 }
 export {};

package/dist/widgets/event-router.js

@@ -1,6 +1,9 @@
 /**
- * EventRouter — parses raw stdin into KeyEvent / WidgetMouseEvent values
- * and dispatches them to widgets via the Screen's FocusManager and bounds.
+ * EventRouter — parses raw stdin into KeyEvent / ScreenMouseEvent values
+ * and dispatches them to widgets via a FocusManager and the frame on screen.
+ *
+ * It reads the terminal and never sets it up: raw mode and mouse tracking are
+ * the runtime's (`App`), which undoes them on every path out.
  *
  * [LAW:single-enforcer] ANSI escape parsing lives only here — widgets never
  * see raw bytes. One parser, one dispatch surface.
@@ -17,6 +20,7 @@
  * if it extends the sequence. Tests can call `flush()` to drain synchronously.
  */
 import { KeyEvent } from "./types.js";
+import { drew, originOf, scrollTargetAt, widgetAt } from "./hit.js";
 // Single-byte → key name table for the trivial cases.
 const SINGLE_BYTE_KEYS = {
     0x09: "tab",
@@ -79,8 +83,6 @@ const LANGLE = 0x3c; // <
 const O_BYTE = 0x4f; // O
 const M_UPPER = 0x4d; // M
 const M_LOWER = 0x6d; // m
-const MOUSE_TRACK_ON = "\x1b[?1006h\x1b[?1000h\x1b[?1003h";
-const MOUSE_TRACK_OFF = "\x1b[?1003l\x1b[?1000l\x1b[?1006l";
 // [LAW:single-enforcer] Shared encode/decode singletons. The parser
 // receives `Uint8Array | string` from the host and walks bytes through
 // its state machine; conversion happens at the two boundaries (string
@@ -107,8 +109,6 @@ function concatBytes(a, b) {
 export class EventRouter {
     source;
     host;
-    manageMouse;
-    manageRawMode;
     // [LAW:types-are-the-program] The parse buffer is `Uint8Array`, not
     // `Buffer` — node's Buffer extends Uint8Array, so Buffer chunks from
     // process.stdin satisfy this type and the parser still works on node,
@@ -123,29 +123,25 @@ export class EventRouter {
     // microtasks drain), without forcing a `setImmediate` polyfill on the
     // browser host.
     escTimer;
-    // [LAW:single-enforcer] Drag capture lives only here. A mouse_down's hit
-    // widget is recorded; mouse_move/mouse_up between then and the next
-    // mouse_up route to this widget unconditionally so dragging outside its
-    // bounds still drives state (e.g. Slider's _dragging). Cleared on the
-    // next mouse_up.
-    capturedWidget = null;
+    // [LAW:single-enforcer] Drag capture lives only here. A mouse_down's
+    // target is recorded; mouse_move/mouse_up between then and the next
+    // mouse_up route to it unconditionally and relative to where it is painted
+    // (`relocate`), so a drag past the widget's edge still drives its state
+    // (Slider's _dragging) and reports a column outside it. Cleared on the next
+    // mouse_up.
+    captured = null;
+    // Where the terminal last reported the pointer, and the widget under it on
+    // the frame on screen — the one widget `hovered` is true on.
+    pointer = null;
+    hoveredWidget = null;
     // [LAW:dataflow-not-control-flow] Ordered chain; the dispatcher walks it
     // in priority tiers and stops as soon as some participant calls
     // `event.stop()`. Insertion order is preserved within each tier.
     keyChain = [];
     mouseHandlers = new Set();
     constructor(options) {
-        const { screen } = options;
-        this.source = isWidgetSource(screen)
-            ? screen
-            : { focusManager: screen.focusManager, getWidgets: () => screen.widgets };
+        this.source = options.source;
         this.host = options.host;
-        // [LAW:one-source-of-truth] The host owns the "is this a real
-        // terminal?" question. Both raw-mode and mouse-tracking defaults
-        // derive from the same isTTY — no separate input/output skew.
-        const isTTY = this.host.isTTY;
-        this.manageRawMode = options.manageRawMode ?? isTTY;
-        this.manageMouse = options.manageMouse ?? isTTY;
         // [LAW:single-enforcer] FocusManager owns Tab/Shift+Tab traversal —
         // register it as a normal-priority handler so it participates in the
         // chain. This MUST be the first registration so it lands ahead of any
@@ -159,14 +155,8 @@ export class EventRouter {
         if (this.running)
             return;
         this.running = true;
-        // [LAW:dataflow-not-control-flow] No `if (host.setRawMode)` capability
-        // check — the host absorbs that. Same goes for resume(): subscribing
-        // via host.onData triggers the underlying stream's flow on node, no-ops
-        // on transports that don't have a paused mode.
-        if (this.manageRawMode)
-            this.host.setRawMode(true);
-        if (this.manageMouse)
-            this.host.write(MOUSE_TRACK_ON);
+        // Subscribing starts the underlying stream flowing on node, and is all
+        // it takes on a transport with no paused mode.
         this.dataUnsubscribe = this.host.onData((chunk) => this.feed(chunk));
     }
     stop() {
@@ -176,14 +166,11 @@ export class EventRouter {
                 this.dataUnsubscribe();
                 this.dataUnsubscribe = undefined;
             }
-            if (this.manageMouse)
-                this.host.write(MOUSE_TRACK_OFF);
-            if (this.manageRawMode)
-                this.host.setRawMode(false);
         }
         // [LAW:one-source-of-truth] Per-session state belongs to one session.
         // stop() leaves the router in the same shape a fresh construction
-        // would: empty parse buffer, no captured widget, no pending ESC timer.
+        // would: empty parse buffer, no captured widget, nothing hovered, no
+        // pending ESC timer.
         // All cleanup is outside the `running` guard because feed() can arm
         // escTimer (and grow buffer) even when running is false — without
         // those, a pre-start feed could leave a deferred escape firing into
@@ -194,7 +181,20 @@ export class EventRouter {
             this.escTimer = undefined;
         }
         this.buffer = EMPTY_BYTES;
-        this.capturedWidget = null;
+        this.captured = null;
+        this.pointer = null;
+        this.hover(null);
+    }
+    /**
+     * Read hover again off the frame just painted: under a pointer that has not
+     * moved, a widget may have gone, moved, or arrived.
+     *
+     * [LAW:one-source-of-truth] Hover is the widget under the pointer on the
+     * frame on screen, so it is re-read whenever either one changes.
+     */
+    framePainted() {
+        const hit = this.pointer && widgetAt(this.source.frame, this.pointer.x, this.pointer.y);
+        this.hover(hit ? hit.widget : null);
     }
     // --- External hooks ---
     onKey(handler, options) {
@@ -502,42 +502,59 @@ export class EventRouter {
     dispatchMouse(event) {
         for (const handler of this.mouseHandlers)
             handler(event);
-        const widgets = this.source.getWidgets();
-        // Hover tracking: any widget whose hover state changed gets an update
-        // via the canonical setHovered (on WidgetBase). One setter, no fallback.
-        if (event.type === "mouse_move") {
-            for (const w of widgets) {
-                if (!w.visible)
-                    continue;
-                const inside = w.containsPoint(event.x, event.y);
-                if (inside !== w.hovered)
-                    w.setHovered(inside);
-            }
+        const frame = this.source.frame;
+        const hit = widgetAt(frame, event.x, event.y);
+        this.pointer = { x: event.x, y: event.y };
+        this.hover(hit?.widget ?? null);
+        // The wheel scrolls the innermost viewport under the pointer that can
+        // move, a line a notch, past any widget it shows there and whatever a
+        // drag captured. With none, nothing moved and there is nothing to paint.
+        if (event.type === "scroll_up" || event.type === "scroll_down") {
+            const lines = event.type === "scroll_down" ? 1 : -1;
+            const target = scrollTargetAt(frame, event.x, event.y, lines);
+            if (!target)
+                return;
+            target.scrollBy(lines);
+            this.source.refresh();
+            return;
         }
         // [LAW:dataflow-not-control-flow] Same pipeline every event; the
         // capture value and event type pick the target. mouse_down opens a
         // capture, mouse_up closes it, mouse_move in between routes to the
-        // captured widget regardless of pointer position. Scroll events
-        // bypass capture (they're not drag-scoped).
-        const useCapture = this.capturedWidget !== null &&
-            (event.type === "mouse_move" || event.type === "mouse_up");
-        const target = useCapture
-            ? this.capturedWidget
-            : topmostHit(widgets, event.x, event.y);
-        if (target)
-            target.handleMouse(event);
+        // captured widget regardless of pointer position. A hit's origin puts the
+        // pressed cell at its own column and row, so every delivery is the same
+        // subtraction.
+        const useCapture = event.type === "mouse_move" || event.type === "mouse_up";
+        const target = (useCapture && this.captured ? relocate(frame, this.captured) : null) ??
+            (hit ? { widget: hit.widget, originX: event.x - hit.col, originY: event.y - hit.row } : null);
+        target?.widget.handleMouse({
+            ...event,
+            x: event.x - target.originX,
+            y: event.y - target.originY,
+            over: drew(frame, target.widget, event.x, event.y),
+        });
         if (event.type === "mouse_down")
-            this.capturedWidget = target;
+            this.captured = target;
         else if (event.type === "mouse_up")
-            this.capturedWidget = null;
+            this.captured = null;
+    }
+    // [LAW:single-enforcer] The canonical setter on the widget is the only
+    // writer of `hovered`; this is the only caller, and only on a change.
+    hover(widget) {
+        if (widget === this.hoveredWidget)
+            return;
+        this.hoveredWidget?.setHovered(false);
+        widget?.setHovered(true);
+        this.hoveredWidget = widget;
     }
 }
 // --- Helpers ---
-function isWidgetSource(value) {
-    return (!!value &&
-        typeof value === "object" &&
-        "getWidgets" in value &&
-        typeof value.getWidgets === "function");
+// [LAW:one-source-of-truth] A captured widget's origin is read off the frame
+// just painted, so a drag follows the widget if it moved since the press; one
+// no longer painted is where the press found it.
+function relocate(frame, target) {
+    const origin = originOf(frame, target.widget);
+    return origin ? { widget: target.widget, originX: origin.x, originY: origin.y } : target;
 }
 function decodeMouseFromCb(cb, x, y, isPress) {
     const isMotion = (cb & 32) !== 0;
@@ -610,13 +627,3 @@ function decodeModifier(mod) {
         ctrl: (bits & 4) !== 0,
     };
 }
-function topmostHit(widgets, x, y) {
-    for (let i = widgets.length - 1; i >= 0; i--) {
-        const w = widgets[i];
-        if (!w.visible)
-            continue;
-        if (w.containsPoint(x, y))
-            return w;
-    }
-    return null;
-}