tickmarkr 1.83.0 → 1.85.0

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;