tickmarkr 1.83.0 → 1.84.0

package/dist/tui/cockpit/live.js

@@ -1,12 +1,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { render, useApp, useInput } from "ink";
-import { createElement, useEffect, useRef, useSyncExternalStore } from "react";
+import { createElement, useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 import { graphPath, loadGraph, stateDirName } from "../../graph/graph.js";
 import { Journal, parseRunId } from "../../run/journal.js";
 import { deriveRunCockpitData } from "./derive.js";
-import { deriveRunViewRows, runKeyColumns, RunCockpitFrame } from "./run-cockpit.js";
+import { deriveRunViewRows, drawnRunViewRowIds, planRunCockpitFrame, runKeyColumns, RunCockpitFrame, } from "./run-cockpit.js";
 import { dispatchRunSurfaceKey, openingRunSurfaceState, reconcileRunInteraction, RUN_INPUT_BINDINGS, selectableRunViewRowIds, } from "./keys.js";
+import { applyPointerReport, borrowPointerTracking, createPointerReportReader, } from "./pointer.js";
 // ponytail: fixed 2s re-derive cadence, matching `status --watch`; promote to a
 // config knob only if an operator asks.
 const REFRESH_MS = 2_000;
@@ -110,7 +111,44 @@ export function liveRunViewRowIds(interaction, data) {
     deriveRunViewRows(data, interaction.activeView, interaction.filterQuery)
         .map((row) => row.id));
 }
-function createLiveCockpitDelivery({ cwd, runId, binaryVersion, now, }) {
+/**
+ * The pointer surface a committed frame carries: the plan the paint drew and
+ * the rows drawn into its body, both read off the renderer's own output. This
+ * is the only composition the live input path resolves through — it holds no
+ * planner and no geometry of its own, so a hit can never land on bands or
+ * rows the operator has not seen.
+ */
+function committedRunPointerSurface(planned, data) {
+    if (planned.plan.kind !== "frame" || planned.content === undefined) {
+        return undefined;
+    }
+    return {
+        interaction: planned.interaction,
+        // The plan is the whole geometry the pointer receives: the item rows it
+        // resolves a hit through are the plan's own `items` band, the same region
+        // the paint draws its list into, so there is no second reading of where the
+        // list starts.
+        plan: planned.plan,
+        drawnRowIds: drawnRunViewRowIds(data, planned.interaction, planned.content.items.rows),
+        rowIds: liveRunViewRowIds(planned.interaction, data),
+    };
+}
+/**
+ * The suite's own planning of the surface a frame at this data, state and
+ * measured size commits — the same composition the renderer publishes through
+ * its commit seam, so a hit is tested against the frame production actually
+ * painted. The live input path never calls this: it resolves through the
+ * committed frame, and what nothing has painted yet has no geometry.
+ */
+export function liveRunPointerSurface(data, interaction, size) {
+    return committedRunPointerSurface(planRunCockpitFrame({
+        data,
+        columns: size.columns,
+        rows: size.rows,
+        interaction,
+    }), data);
+}
+function createLiveCockpitDelivery({ cwd, runId, binaryVersion, now, size, }) {
     // Both sources are read every refresh: a recompile between refreshes changes
     // which tasks exist, and the surface must draw the graph the repository has
     // now rather than the one it had when the cockpit opened.
@@ -124,6 +162,15 @@ function createLiveCockpitDelivery({ cwd, runId, binaryVersion, now, }) {
     const listeners = new Set();
     let batchDepth = 0;
     let pendingDraw = false;
+    /**
+     * The frame on the screen, published by the renderer each time it commits
+     * one. Pointer reports resolve through this and only this: the input path
+     * plans nothing and caches no geometry, so a refresh, resize or key that
+     * nothing has painted yet cannot move a hit — the target set is the bands
+     * and rows the operator is actually looking at, until the paint replaces
+     * them.
+     */
+    let committedPointerSurface;
     const publish = () => {
         if (batchDepth > 0) {
             pendingDraw = true;
@@ -154,6 +201,9 @@ function createLiveCockpitDelivery({ cwd, runId, binaryVersion, now, }) {
             finally {
                 batchDepth -= 1;
                 if (batchDepth === 0 && pendingDraw) {
+                    // The batch ends and the surface is drawn again; the renderer's
+                    // commit of that draw publishes the frame the next report resolves
+                    // through.
                     pendingDraw = false;
                     publish();
                 }
@@ -178,10 +228,12 @@ function createLiveCockpitDelivery({ cwd, runId, binaryVersion, now, }) {
         // can be in. The prompt is a scope inside that registry rather than an
         // owner in front of it, so a global key — Tab above all — reaches its
         // handler with a prompt open exactly as it does without one.
-        key: (event, columns = Number.MAX_SAFE_INTEGER) => transition((current) => {
+        key: (event) => transition((current) => {
             const next = dispatchRunSurfaceKey(event, { interaction: current.interaction, stashed: current.stashed }, RUN_INPUT_BINDINGS, liveRunViewRowIds(current.interaction, current.data), 
-            // The dispatcher decides on rail visibility, and the plan owns that.
-            runKeyColumns(columns));
+            // The dispatcher decides on rail visibility from the width the surface
+            // is measured at. A default here routed every key as if the rail were
+            // drawn, at widths where the plan draws no rail at all.
+            runKeyColumns(size().columns));
             if (next === undefined)
                 return current;
             const interaction = reconcileLiveRunInteraction(next.interaction, current.data);
@@ -189,9 +241,40 @@ function createLiveCockpitDelivery({ cwd, runId, binaryVersion, now, }) {
                 ? current
                 : { ...current, interaction, stashed: next.stashed };
         }),
+        // A pointer report resolves through the committed frame — the plan and
+        // the drawn rows the paint has on the screen, and nothing the input path
+        // derives for itself. Adjacent reports — a double click above all —
+        // arrive in one batch, which defers the redraw: they all resolve through
+        // the ONE committed frame still on the screen, and only the state each
+        // transition is dispatched FROM moves. The first press's own new scroll
+        // window cannot slide the list under the second press, because that
+        // window does not exist until the paint draws it.
+        pointer: (report) => transition((current) => {
+            const drawn = committedPointerSurface;
+            if (drawn === undefined)
+                return current;
+            const next = applyPointerReport(report, {
+                ...drawn,
+                interaction: current.interaction,
+            });
+            if (next === undefined)
+                return current;
+            const interaction = reconcileLiveRunInteraction(next, current.data);
+            return interaction === current.interaction
+                ? current
+                : { ...current, interaction };
+        }),
+        commitPointerSurface: (surface) => {
+            committedPointerSurface = surface;
+        },
     };
     return delivery;
 }
+/** The measured size a snapshot states, in the whole cells a plan is made of. */
+function parseMeasuredSize(snapshot) {
+    const [columns, rows] = snapshot.split(":").map((part) => Math.max(0, Math.floor(Number(part))));
+    return { columns, rows };
+}
 function measureOutput(output) {
     const read = () => `${output.columns ?? 80}:${output.rows ?? 24}`;
     let size = read();
@@ -245,11 +328,83 @@ function measureOutput(output) {
         close: () => output.off("resize", resized),
     };
 }
+/**
+ * The stdin the surface's keyboard reads: the real stream with every pointer
+ * report taken out of it. Reports and keys arrive interleaved on one stream, and
+ * a reader beside Ink's would not be enough — Ink would still see the report
+ * bytes and read a whole one as an unnameable escape sequence, or half of one as
+ * the single character its chunk happens to end on, dispatching either into
+ * whatever scope is live. So the split sits in the pull Ink already does
+ * (`read()` under its `readable` listener): reports are handed to the pointer
+ * boundary, and only what was left is ever read as a keystroke. A chunk that was
+ * nothing but reports reads as no input at all rather than as empty input.
+ */
+function pointerFilteredInput(input, deliver) {
+    const reader = createPointerReportReader();
+    const tokens = [];
+    let pendingEscape;
+    const clearPendingEscape = () => {
+        if (pendingEscape === undefined)
+            return;
+        clearImmediate(pendingEscape);
+        pendingEscape = undefined;
+    };
+    const wake = () => {
+        input.emit("readable");
+    };
+    const schedulePendingEscape = () => {
+        clearPendingEscape();
+        // The same next-turn grace Ink gives an ambiguous ESC: a continuation that
+        // arrives first completes the report; otherwise ESC becomes keyboard input.
+        if (reader.pending() !== "\x1b")
+            return;
+        pendingEscape = setImmediate(() => {
+            pendingEscape = undefined;
+            tokens.push(...reader.flush().tokens);
+            wake();
+        });
+    };
+    const read = (...args) => {
+        while (true) {
+            const token = tokens.shift();
+            if (token?.type === "pointer") {
+                const reports = [token.report];
+                while (tokens[0]?.type === "pointer") {
+                    const adjacent = tokens.shift();
+                    if (adjacent?.type === "pointer")
+                        reports.push(adjacent.report);
+                }
+                deliver(reports);
+                continue;
+            }
+            if (token?.type === "keys")
+                return token.bytes;
+            const chunk = input.read(...args);
+            if (chunk === null || chunk === undefined)
+                return null;
+            clearPendingEscape();
+            const readout = reader(String(chunk));
+            tokens.push(...readout.tokens);
+            schedulePendingEscape();
+        }
+    };
+    const stdin = new Proxy(input, {
+        get(target, property) {
+            if (property === "read")
+                return read;
+            const value = Reflect.get(target, property);
+            return typeof value === "function" && !Object.hasOwn(target, property)
+                ? value.bind(target)
+                : value;
+        },
+    });
+    return { stdin, close: clearPendingEscape };
+}
 function LiveApp({ delivery, size, refreshMs, }) {
     const { exit } = useApp();
     const surface = useSyncExternalStore(delivery.subscribe, delivery.snapshot, delivery.snapshot);
     const measuredSize = useSyncExternalStore(size.subscribe, size.snapshot, size.snapshot);
-    const [columns, rows] = measuredSize.split(":").map((part) => Math.max(0, Math.floor(Number(part))));
+    const { columns, rows } = parseMeasuredSize(measuredSize);
     const drawnSize = useRef(measuredSize);
     useEffect(() => {
         if (drawnSize.current === measuredSize)
@@ -270,42 +425,81 @@ function LiveApp({ delivery, size, refreshMs, }) {
             exit();
             return;
         }
-        delivery.key({ input, key }, columns);
+        delivery.key({ input, key });
     });
+    // Every frame the renderer commits is published to the delivery, so a
+    // pointer report resolves against the plan and the drawn rows of the frame
+    // on the screen — the input path never plans one of its own.
+    const commitFrame = useCallback((planned, frameData) => {
+        delivery.commitPointerSurface(committedRunPointerSurface(planned, frameData));
+    }, [delivery]);
     return createElement(RunCockpitFrame, {
         data: surface.data,
         columns,
         rows,
         interaction: surface.interaction,
+        onCommittedFrame: commitFrame,
     });
 }
 export async function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs = REFRESH_MS, now = Date.now, debug = false, onDelivery, }) {
-    const delivery = createLiveCockpitDelivery({
-        cwd,
-        runId,
-        binaryVersion,
-        now,
-    });
-    onDelivery?.(delivery);
     // Subscribe before Ink mounts so no stale-size repaint can overtake the
-    // surface's newly planned frame.
+    // surface's newly planned frame — and before the delivery exists, which
+    // routes every input against this measurement.
     const size = measureOutput(output);
-    const app = render(createElement(LiveApp, {
-        delivery,
-        size,
-        refreshMs,
-    }), {
-        stdin: input,
-        stdout: size.stdout,
-        debug,
-        exitOnCtrlC: false,
-        patchConsole: false,
-    });
+    let app;
+    let filteredInput;
+    let releasePointerTracking;
     try {
+        const delivery = createLiveCockpitDelivery({
+            cwd,
+            runId,
+            binaryVersion,
+            now,
+            size: () => parseMeasuredSize(size.snapshot()),
+        });
+        onDelivery?.(delivery);
+        // Pointer reports are their own input class: they are taken off the stream
+        // before the keyboard reads it and delivered to the pointer boundary, never
+        // handed to a key handler. A batch keeps adjacent reports to one redraw.
+        filteredInput = pointerFilteredInput(input, (reports) => {
+            delivery.batch(() => {
+                for (const report of reports)
+                    delivery.pointer(report);
+            });
+        });
+        // One loan owns the complete live lifecycle. Its signal repayments stand
+        // before the ask, then remain installed through mount, paint, input and
+        // unmount. Non-tty output borrows nothing and writes nothing.
+        releasePointerTracking = borrowPointerTracking(output);
+        app = render(createElement(LiveApp, {
+            delivery,
+            size,
+            refreshMs,
+        }), {
+            stdin: filteredInput.stdin,
+            stdout: size.stdout,
+            debug,
+            exitOnCtrlC: false,
+            patchConsole: false,
+        });
         await app.waitUntilExit();
     }
     finally {
-        size.close();
-        app.unmount();
+        try {
+            filteredInput?.close();
+        }
+        finally {
+            try {
+                app?.unmount();
+            }
+            finally {
+                try {
+                    releasePointerTracking?.();
+                }
+                finally {
+                    size.close();
+                }
+            }
+        }
     }
 }

package/dist/tui/cockpit/pointer.d.ts

@@ -0,0 +1,261 @@
+import { type RunInteractionState } from "./keys.js";
+import { type FrameRegion, type PlannedFrame } from "./layout.js";
+/**
+ * The terminal reports no pointer at all until it is asked to, so the parser
+ * above reads nothing until these bytes are written. DECSET 1000 turns on normal
+ * tracking — presses, releases and the wheel. DECSET 1006 asks for them in SGR
+ * encoding: the one grammar `SGR_POINTER_REPORT` reads, and the only one that
+ * can state a cell past column 223 at all. DECSET 1003 widens that to motion
+ * with no button held — the only way a terminal ever says where the pointer is
+ * merely resting, and therefore the whole reason a hover highlight can exist
+ * at all. It is asked for last, so the widest tracking mode is the one asked
+ * for in the grammar already selected. The request lives beside the parser so a
+ * change to what is read cannot leave what is asked for behind.
+ */
+export declare const POINTER_TRACKING_ON = "\u001B[?1000h\u001B[?1006h\u001B[?1003h";
+/** The same three modes turned off, in exact reverse of the order they were
+ * asked for — a terminal left tracking writes reports into whatever runs after
+ * the cockpit exits. */
+export declare const POINTER_TRACKING_OFF = "\u001B[?1003l\u001B[?1006l\u001B[?1000l";
+/**
+ * The signals that end a process where nothing else repays the loan: they run
+ * no `finally`, unwind no stack and unmount no renderer, so a surface killed by
+ * one would leave the operator's terminal reporting a pointer into whatever
+ * shell comes next. Listening for them is the only way to hand the modes back.
+ *
+ * The roster is every catchable POSIX terminator an interactive cockpit is
+ * actually killed by — ⌃C, a `kill`, a closed terminal, and ⌃\ — not a
+ * shortlist of the three that came to mind. A signal missing from here is a
+ * terminal left reporting, so the test that guards it names its own required
+ * set rather than reading this one back.
+ */
+export declare const POINTER_RELEASE_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+/** A cell the pointer can be at, counted from zero like every planned region. */
+export type PointerCell = {
+    readonly column: number;
+    readonly row: number;
+};
+/**
+ * The cell the pointer is resting on, or none. The same reference for as long
+ * as it has not moved, so a watcher redraws when the pointer moves and at no
+ * other time.
+ */
+export declare function pointerRestingCell(): PointerCell | null;
+/** Watch the resting cell. The returned call stops watching. */
+export declare function watchPointerRest(watcher: () => void): () => void;
+/**
+ * The rail columns the session dragged the boundary to, or none. The same
+ * reference for as long as it has not changed, so a watcher redraws when the
+ * drag moves the boundary and at no other time.
+ */
+export declare function sessionRailOverride(): number | null;
+/** Watch the session override. The returned call stops watching. */
+export declare function watchSessionRailOverride(watcher: () => void): () => void;
+/**
+ * The session boundary the relaunch contract is stated against: the override
+ * and any drag in progress are gone, exactly as a new process starts. The
+ * production marker is the tracking loan — a fresh borrow is a fresh session.
+ */
+export declare function resetSessionRailOverride(): void;
+/** The stream the modes are asked of — a real terminal, or something that is not one. */
+export type PointerTrackingTerminal = {
+    readonly isTTY?: boolean;
+    readonly write: (bytes: string) => unknown;
+};
+/** The process the loan registers its last-resort repayment with. */
+export type PointerTrackingHost = {
+    readonly pid: number;
+    readonly on: (signal: NodeJS.Signals, listener: () => void) => unknown;
+    readonly off: (signal: NodeJS.Signals, listener: () => void) => unknown;
+    readonly kill: (pid: number, signal: NodeJS.Signals) => unknown;
+    /** Which signals this host can be killed by at all — `process.platform`. */
+    readonly platform?: NodeJS.Platform;
+};
+/**
+ * Borrow pointer reporting, and return the one way to repay it.
+ *
+ * The loan is the whole lifecycle in one expression, so no caller can hold half
+ * of it. Only an interactive terminal is asked at all: writing mode requests
+ * into a pipe puts escape bytes in a capture rather than a mouse on a surface
+ * nobody is pointing at, so the non-tty and CI surfaces carry no enable
+ * sequence because none is ever written — not because a later guard strips one.
+ *
+ * Repayment is idempotent and reachable from every exit: the returned release
+ * for an ordinary return, the same release run from a `finally` or a renderer's
+ * cleanup for a thrown failure, and the signal listeners registered here for
+ * the exits that run neither. A listener repays and then re-raises its own
+ * signal with our listener removed, so the process still ends exactly the way
+ * the signal meant it to.
+ */
+export declare function borrowPointerTracking(terminal: PointerTrackingTerminal, host?: PointerTrackingHost): () => void;
+export type PointerAction = "press" | "release" | "move" | "wheel-up" | "wheel-down";
+/** One reported pointer event, its cell zero-based like every planned region. */
+export type PointerReport = {
+    readonly action: PointerAction;
+    readonly column: number;
+    readonly row: number;
+    /**
+     * The raw SGR button code the report arrived with. The action alone throws
+     * information away that a drag latch cannot survive without: under DECSET
+     * 1003 a motion with NO button held reports button 35 — `(button & 3) === 3`
+     * — and that no-button motion is the only signal that a release lost
+     * outside the window (the pointer let go past the terminal's edge, which
+     * sends no release at all) has already happened. Absent only on a report
+     * built by hand rather than parsed off the wire; a hand-built move is read
+     * as a drag-motion, the reading that cannot end a drag its producer had no
+     * way to describe.
+     */
+    readonly button?: number;
+};
+/** What one chunk of terminal input turned out to be: the reports it carried,
+ * and the bytes that were not part of any — the keyboard's own input. */
+export type PointerReadout = {
+    /** Keyboard and pointer input in the byte order the terminal delivered it. */
+    readonly tokens: readonly PointerInputToken[];
+    readonly reports: readonly PointerReport[];
+    readonly keys: string;
+};
+export type PointerInputToken = {
+    readonly type: "keys";
+    readonly bytes: string;
+} | {
+    readonly type: "pointer";
+    readonly report: PointerReport;
+};
+export type PointerReportReader = {
+    (chunk: string): PointerReadout;
+    /** Release a prefix that did not receive the bytes needed to become a report. */
+    flush(): PointerReadout;
+    /** The incomplete report prefix currently withheld from the keyboard. */
+    pending(): string;
+};
+/**
+ * The pointer reports carried by a chunk of terminal input. Bytes that are not
+ * a report are not pointer input and are left for whoever else reads the
+ * stream; a torn or malformed sequence simply reports nothing.
+ */
+export declare function parsePointerReports(bytes: string): readonly PointerReport[];
+/**
+ * A reader over the input stream rather than over one chunk. The terminal
+ * writes bytes, not messages: a single report is free to arrive split across
+ * chunks, and chunk-at-a-time parsing silently drops every report that lands on
+ * a boundary. The reader carries the torn tail into the next chunk and reports
+ * only sequences that have completed.
+ *
+ * It also states what was left — the bytes of that chunk that belonged to no
+ * report, including none at all while a torn one is still arriving. Reports and
+ * keys share one stream, so this is the only place that can tell them apart:
+ * downstream, a whole report is an unnameable escape sequence and half a report
+ * is the single character it happens to end on, either of which would be read as
+ * a keystroke by whatever scope is live.
+ */
+export declare function createPointerReportReader(): PointerReportReader;
+/**
+ * The width the key registry resolves at for the bands THIS plan drew. The
+ * focus order follows the plan rather than a second reading of the terminal:
+ * between 64 and 79 columns the plan draws the rail at a width the key floor
+ * alone would deny it, and the click targets and the focus order have to agree
+ * about that band or a click would act on a panel the frame does not show.
+ */
+export declare function plannedKeyColumns(plan: PlannedFrame): number;
+export type PointerTarget = {
+    /** The tightest planned region containing the cell. */
+    readonly region: FrameRegion;
+    /** The rail's menu row under the cell, when the cell is on one. */
+    readonly view?: number;
+    /** The body's drawn row under the cell, counted from the planned item region's own first row. */
+    readonly row?: number;
+};
+/**
+ * What the plan says is under a cell. The rail's view rows are
+ * `plan.sidebar.viewRows` — frame rows planFrame itself computed, where the
+ * label row was decided — so the menu's shape is looked up rather than
+ * reconstructed from `menuRows` out here. The body's item rows are a planned
+ * band of their own, so the tightest-region lookup lands on them directly and
+ * the first item's offset is the region's own row. The view strip the plan draws
+ * instead of a rail below 64 columns is one span with no per-view columns in it,
+ * so nothing here invents any: a strip cell resolves to the strip band and no
+ * further.
+ */
+export declare function resolvePointerTarget(plan: PlannedFrame, cell: {
+    readonly column: number;
+    readonly row: number;
+}): PointerTarget | undefined;
+/**
+ * The focus index a target's band carries at the width the plan drew — the same
+ * order the frame paints its focus ring from, so a click can never focus a
+ * panel the frame does not show as focusable.
+ */
+export declare function pointerFocusPanel(plan: PlannedFrame, target: PointerTarget): number | undefined;
+/**
+ * The half of a surface a row hit resolves through: the plan the paint drew,
+ * and the identities the rows drawn into it carry.
+ */
+export type PointerRowSurface = {
+    readonly plan: PlannedFrame;
+    /** The identities the body's drawn rows carry, top to bottom. */
+    readonly drawnRowIds: readonly string[];
+};
+/**
+ * The item a cell acts on — THE resolution, shared by every pointer path.
+ * A click reads it to decide what to select, and a hover highlight reads the
+ * same call to decide what to mark, so the highlight cannot name a row a click
+ * at that cell would miss: there is one answer, not two agreeing ones. A cell
+ * the plan does not place on an item row, and an item row the paint drew
+ * nothing into, are both nothing here rather than a nearest guess.
+ */
+export declare function pointerRowAt(surface: PointerRowSurface, cell: {
+    readonly column: number;
+    readonly row: number;
+}): string | undefined;
+/** The surface a pointer report acts on: the plan the paint drew, and the rows drawn into it. */
+export type PointerSurface = {
+    /** planFrame's own output — the only geometry a hit resolves through. */
+    readonly plan: PlannedFrame;
+    readonly interaction: RunInteractionState;
+    /** The identities the body's drawn rows carry, top to bottom. */
+    readonly drawnRowIds: readonly string[];
+    /** The rows a key may stand on, in the active view's own order. */
+    readonly rowIds: readonly string[];
+};
+/**
+ * The transition a pointer report makes, or undefined when nothing owns the
+ * cell. A click on a view name is that view's own number key; a click on the
+ * row already marked is ⏎; moving between panels is the advertised dive/back
+ * grammar; and a wheel is ↑↓ only when the panel under it already owns ↑↓.
+ * An off-focus wheel is not an action: borrowing focus or prompt scope and then
+ * restoring it would create a frame no advertised key sequence can reach.
+ *
+ * A drag of the panel boundary is the exception that proves the second law:
+ * it is no transition at all. The press landing on the boundary grabs it; each
+ * move hands the plan a new input through the session override; the release
+ * lets go — and when the release never arrives because the pointer was let go
+ * outside the window, the first no-button motion says so in its stead, so no
+ * latch outlives the drag it latched. The interaction comes back untouched —
+ * the drag re-plans the frame rather than moving anything inside it.
+ */
+export declare function applyPointerReport(report: PointerReport, surface: PointerSurface): RunInteractionState | undefined;
+/**
+ * The item a hover highlight marks: the one a click at that cell would ACT ON.
+ *
+ * `pointerRowAt` answers a smaller question — which drawn row the plan places
+ * under the cell — and a click is not only that lookup. It is a route: the /
+ * prompt applied, focus dived or backed to the panel under the pointer, and only
+ * then the row. Any of those may legitimately land somewhere else, the plainest
+ * case is the rail marker standing on a view the body is not drawing: the click
+ * that dives into content opens the MARKED view and selects no row at all, while
+ * the rows under the pointer belong to the view being left behind.
+ *
+ * So the highlight is not decided by the lookup. It is decided by running the
+ * click's own transition and asking what it settled on — the same
+ * `pointerTransition` the live report path dispatches through, on the same
+ * surface, so an answer these two could disagree about is not expressible. A
+ * click that acts on something else, or on nothing, lights nothing up.
+ *
+ * It reports no rest and returns no state: asking is not pointing and not
+ * clicking, so the surface is exactly as it was.
+ */
+export declare function pointerHoverRow(surface: PointerSurface, cell: {
+    readonly column: number;
+    readonly row: number;
+}): string | undefined;