tickmarkr 1.83.0 → 1.84.0

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

@@ -1,6 +1,21 @@
 import { type ReactElement, type ReactNode } from "react";
 import { TEXT_EMPHASIS_TOKENS } from "./theme.js";
 export { SPARKLINE_BUCKET_WINDOW } from "./derive.js";
+/**
+ * The hover highlight's non-colour half: one cell wide, drawn in the separator
+ * the row already spends, from the block family the cockpit already draws with.
+ * Colour is the other half and the louder one, but Chalk suppresses inverse and
+ * colour together at level 0, so a highlight made of ink alone does not exist
+ * under `NO_COLOR` or a colourless TTY. This is a character; it always does.
+ */
+export declare const HOVER_MARKER = "\u258C";
+/**
+ * The columns below which a bordered panel no longer reads — the floor a band
+ * allocation defends, and the floor planFrame's session resize override clamps
+ * the body panel at: a drag surrenders an element whole or not at all, it
+ * never collapses one below what reads.
+ */
+export declare const READABLE_PANEL_COLUMNS = 20;
 export declare const PANEL_CHROME_ROWS = 3;
 export declare const BAND_CONTINUATION_PREFIX = "\u21B3 ";
 export type BandColumnContent = {
@@ -98,11 +113,23 @@ export declare function StatusStrip({ items, width, }: {
     items: readonly StatusStripItem[];
     width: number;
 }): ReactElement;
-export declare function JournalRowPanel({ rows, width, focused, title, selection, }: {
+export declare function JournalRowPanel({ rows, width, focused, title, selection, hover, }: {
     rows: readonly JournalRow[];
     width?: number | string;
     focused?: boolean;
     title?: string;
     /** Index of the row the pointer marks; undefined draws no pointer. */
     selection?: number;
+    /**
+     * Index of the row a live pointer is resting on; undefined draws no
+     * highlight, which is every surface nobody is pointing at — a capture above
+     * all. The highlight is ink AND shape: the brightest step of the existing
+     * data ramp worn inverted, plus {@link HOVER_MARKER} standing in the one
+     * separator cell the row already spends between its state glyph and its text.
+     * Ink alone would be no highlight at all under `NO_COLOR` or a colourless
+     * TTY, where Chalk suppresses inverse and colour alike; the marker is a drawn
+     * character, so it survives every colour level. It costs the row no cell it
+     * did not already own, so a hover shifts nothing an operator was reading.
+     */
+    hover?: number;
 }): ReactElement;

package/dist/tui/cockpit/components.js

@@ -18,9 +18,23 @@ import { formatKeybarEntries, keybarEntries, SETUP_KEY_BINDINGS, } from "./keys.
  */
 import { cellWidth as stringWidth, sliceCells } from "./width.js";
 const SPARKLINE_GLYPHS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+/**
+ * The hover highlight's non-colour half: one cell wide, drawn in the separator
+ * the row already spends, from the block family the cockpit already draws with.
+ * Colour is the other half and the louder one, but Chalk suppresses inverse and
+ * colour together at level 0, so a highlight made of ink alone does not exist
+ * under `NO_COLOR` or a colourless TTY. This is a character; it always does.
+ */
+export const HOVER_MARKER = "▌";
 const BAND_GAP_COLUMNS = 1;
 const PANEL_HORIZONTAL_CHROME = 4;
-const READABLE_PANEL_COLUMNS = 20;
+/**
+ * The columns below which a bordered panel no longer reads — the floor a band
+ * allocation defends, and the floor planFrame's session resize override clamps
+ * the body panel at: a drag surrenders an element whole or not at all, it
+ * never collapses one below what reads.
+ */
+export const READABLE_PANEL_COLUMNS = 20;
 export const PANEL_CHROME_ROWS = 3;
 export const BAND_CONTINUATION_PREFIX = "↳ ";
 const SETUP_KEYS = keybarEntries(SETUP_KEY_BINDINGS);
@@ -269,6 +283,8 @@ export function KeyRoster({ entries, width, }) {
 export function StatusStrip({ items, width, }) {
     return (_jsx(OneLineItems, { width: width, label: "cockpit status", children: items.map((item, index) => (_jsxs(Box, { flexShrink: 0, children: [index > 0 && _jsx(BodyText, { emphasis: "dim", children: " \u00B7 " }), _jsx(StateGlyph, { state: item.state }), _jsxs(BodyText, { children: [" ", item.text] })] }, `${item.state}:${item.text}`))) }));
 }
-export function JournalRowPanel({ rows, width, focused, title = "JOURNAL", selection, }) {
-    return (_jsx(Panel, { title: title, focused: focused, width: width, children: rows.map((row, index) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "dim", children: row.time }), _jsx(BodyText, { children: " " }), _jsx(StateGlyph, { state: row.state }), _jsx(BodyText, { children: " " }), index === selection && (_jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " "] })), _jsx(BodyText, { children: row.text })] }, row.id))) }));
+export function JournalRowPanel({ rows, width, focused, title = "JOURNAL", selection, hover, }) {
+    return (_jsx(Panel, { title: title, focused: focused, width: width, children: rows.map((row, index) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "dim", children: row.time }), _jsx(BodyText, { children: " " }), _jsx(StateGlyph, { state: row.state }), _jsx(BodyText, { emphasis: index === hover ? "strong" : "normal", children: index === hover ? HOVER_MARKER : " " }), index === selection && (_jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " "] })), index === hover
+                    ? (_jsx(Text, { inverse: true, color: `ansi256(${COCKPIT_DATA_RAMP[0].xterm})`, children: row.text }))
+                    : _jsx(BodyText, { children: row.text })] }, row.id))) }));
 }

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

@@ -87,11 +87,40 @@ export interface FrameState {
     detail?: boolean;
     /** Header caption, pre-measured in terminal cells by the caller. */
     captionCells?: number;
+    /**
+     * The session's panel resize override: the rail columns the operator dragged
+     * the boundary to. An INPUT to the plan, never a bypass of it — the plan
+     * recomputes from the measured size plus this override and the renderer
+     * draws the recomputed plan unmodified. It lives only in the running
+     * process: nothing writes it anywhere, and a relaunch plans the default
+     * layout. The plan clamps it at both panels' readable floors — see
+     * `planRailColumns`.
+     */
+    railColumns?: number;
 }
 export declare const FRAME_WIDTH_FLOOR = 40;
 export declare const FRAME_HEIGHT_FLOOR = 14;
 export declare const SIDEBAR_COLUMN_FLOOR = 64;
 export declare const RAIL_COLUMNS = 15;
+/**
+ * The narrowest rail that still reads: the selection marker, one space and the
+ * longest view name, whole — the name measured in display cells by the width
+ * authority, never String length, so a name that ever gains a wide glyph moves
+ * the floor with it. A drag never takes the rail below it — below the floor
+ * the element stands at the floor, surrendered whole per the contract, never
+ * collapsed.
+ */
+export declare const RAIL_READABLE_FLOOR_COLUMNS: number;
+/**
+ * The rail width the plan draws for a session resize override, clamped at both
+ * panels' readable floors: the rail never narrows past its own floor, and
+ * never widens past what leaves the body its readable floor
+ * (`READABLE_PANEL_COLUMNS`). The clamp is the plan's — the override is a
+ * request, the floors are the contract, and an element is surrendered whole or
+ * not at all, never collapsed by a drag. No override is the contract's
+ * constant rail.
+ */
+export declare function planRailColumns(columns: number, override?: number): number;
 export declare const STANDARD_TAIL_HEIGHT = 16;
 export declare const FULL_TAIL_HEIGHT = 24;
 export declare const TAIL_STANDARD_ROWS = 1;
@@ -127,7 +156,24 @@ export interface FrameFit {
  * ordering decision — not a comment about one.
  */
 export declare const FRAME_SURRENDER_FIT: Readonly<Record<SurrenderedRegionId, (fit: FrameFit) => boolean>>;
-export type FrameRegionId = "header" | "rule" | "strip" | "rail" | "body" | "rule2" | "tail" | "status" | "keybar" | "caption";
+export type FrameRegionId = "header" | "rule" | "strip" | "rail" | "body" | "items" | "rule2" | "tail" | "status" | "keybar" | "caption";
+/**
+ * Border plus horizontal padding the drawn panel charges around its body —
+ * half of it on each side. The plan owns this because the plan owns the item
+ * rows: the paint draws its list into the region planned below, and nothing
+ * downstream subtracts chrome of its own to find it again.
+ */
+export declare const RUN_PANEL_HORIZONTAL_CHROME = 4;
+/**
+ * Row bands drawn INSIDE another band rather than beside it, mapped to the band
+ * that hosts them. A nested band refines its host's rows, so the band walk skips
+ * it when tiling the height and asserts containment instead. It is no less a
+ * member of `rowSpans` for that: the oracle pins its span against the planned
+ * region, and demands the paint register a node at exactly that rectangle —
+ * which is precisely what a parallel field beside the plan could never be held
+ * to.
+ */
+export declare const FRAME_NESTED_ROW_BANDS: Readonly<Partial<Record<FrameRegionId, FrameRegionId>>>;
 /** The vitals elements in block order, top first; a short rail surrenders from the top, so the meter is the last to go. */
 export declare const SIDEBAR_VITALS_ORDER: readonly ["tasks", "gates", "meter"];
 export type SidebarVitalsElement = (typeof SIDEBAR_VITALS_ORDER)[number];
@@ -139,6 +185,13 @@ export declare const SIDEBAR_VITALS_COMPACT_ELEMENT_ROWS = 1;
 export interface SidebarPlan {
     /** Rows the menu block occupies at the rail's top: the five views, plus the label row when it fits. */
     menuRows: number;
+    /**
+     * The frame row each view's name is drawn on. The plan does the menu's
+     * arithmetic once, here, where the label row is decided — so a rail hit is a
+     * lookup in the plan's own rows rather than a second reconstruction of the
+     * menu's shape from `menuRows`.
+     */
+    viewRows: Readonly<Record<FrameView, number>>;
     /**
      * Blank rows between the last menu row and the first vitals row. Never zero
      * while any vitals element draws — a short rail surrenders whole vitals
@@ -157,8 +210,14 @@ export interface SidebarPlan {
  * one gap row is the vitals budget, spent on the full two-row block when it
  * fits whole, else on the one-row elements, surrendered from the top of the
  * block with the meter surrendered last. An element draws whole or not at all.
+ * `railRow` is the frame row the rail band starts at, so the view rows the plan
+ * reports are frame rows a reported cell is compared against directly. It is
+ * required for that reason: a default here would answer rail-relative rows in a
+ * field documented as frame rows — the same defaulted-measurement defect the key
+ * delivery carried, and this one would land in the rows a rail hit resolves
+ * through.
  */
-export declare function planSidebar(railRows: number): SidebarPlan;
+export declare function planSidebar(railRows: number, railRow: number): SidebarPlan;
 export interface FrameRegion {
     id: FrameRegionId;
     row: number;
@@ -182,8 +241,11 @@ export interface PlannedFrame {
     content: FrameBandContent;
     regions: readonly FrameRegion[];
     /**
-     * Row bands, top to bottom; their spans tile the height exactly. A band
-     * map: the nested caption sub-region is deliberately excluded.
+     * Row bands, top to bottom. `items` is nested inside the body band and so
+     * refines it rather than tiling beside it (see FRAME_NESTED_ROW_BANDS); the
+     * remaining spans tile the height exactly. The caption is excluded: it adds
+     * no row extent of its own, being the header's own row refined on the column
+     * axis, and the column map already carries no row.
      */
     rowSpans: Readonly<Record<string, number>>;
     /**
@@ -217,7 +279,9 @@ export type FramePlan = PlannedFrame | PlainFallbackPlan;
  * height exactly — header, rule, the view strip (40–63 columns), the body
  * band, a second rule, the journal tail surrendered whole by height tier,
  * status, keybar — and, at ≥64 columns, column bands that tile the width
- * exactly: the constant 15-column rail beside the body. The body is the sole
+ * exactly: the rail beside the body, at the constant 15 columns or at the
+ * session's dragged override clamped to both panels' readable floors
+ * (`planRailColumns`). The body is the sole
  * flexible element on both axes. The view and state decide what the flexible
  * bands draw (the Journal view is the full-height tail; SETUP turns the tail
  * into PENDING WRITES; an open detail owns the body) without moving any
@@ -231,7 +295,12 @@ export type FramePlan = PlannedFrame | PlainFallbackPlan;
  * of the block, the meter last, rather than closing the gap. rowSpans and
  * columnSpans are band maps: they deliberately exclude the nested caption,
  * and column bands are reported for the body band only, so each map's spans
- * sum to the full height and width respectively.
+ * sum to the full height and width respectively. The body band's item rows are
+ * a band of the plan in their own right — a region in `regions` and a span in
+ * `rowSpans`, nested inside the body band rather than tiling beside it — so the
+ * region the paint draws its list into and the region a pointer resolves a row
+ * through are the one thing the oracle pins, and neither subtracts the drawn
+ * panel's chrome for itself.
  */
 export declare function planFrame(size: MeasuredSize, view?: FrameView, state?: FrameState): FramePlan;
 export declare function resolveCockpitLayout(columns: number, rows: number): CockpitLayout;

package/dist/tui/cockpit/layout.js

@@ -1,3 +1,4 @@
+import { PANEL_CHROME_ROWS, READABLE_PANEL_COLUMNS } from "./components.js";
 import { cellWidth } from "./width.js";
 export const COCKPIT_ROW_FLOOR = 14;
 export const COCKPIT_COLUMN_FLOOR = 40;
@@ -57,6 +58,30 @@ export const FRAME_WIDTH_FLOOR = COCKPIT_COLUMN_FLOOR;
 export const FRAME_HEIGHT_FLOOR = COCKPIT_ROW_FLOOR;
 export const SIDEBAR_COLUMN_FLOOR = 64;
 export const RAIL_COLUMNS = 15;
+/**
+ * The narrowest rail that still reads: the selection marker, one space and the
+ * longest view name, whole — the name measured in display cells by the width
+ * authority, never String length, so a name that ever gains a wide glyph moves
+ * the floor with it. A drag never takes the rail below it — below the floor
+ * the element stands at the floor, surrendered whole per the contract, never
+ * collapsed.
+ */
+export const RAIL_READABLE_FLOOR_COLUMNS = Math.max(...FRAME_VIEWS.map((view) => cellWidth(view))) + 2;
+/**
+ * The rail width the plan draws for a session resize override, clamped at both
+ * panels' readable floors: the rail never narrows past its own floor, and
+ * never widens past what leaves the body its readable floor
+ * (`READABLE_PANEL_COLUMNS`). The clamp is the plan's — the override is a
+ * request, the floors are the contract, and an element is surrendered whole or
+ * not at all, never collapsed by a drag. No override is the contract's
+ * constant rail.
+ */
+export function planRailColumns(columns, override) {
+    if (override === undefined || !Number.isFinite(override))
+        return RAIL_COLUMNS;
+    const ceiling = Math.max(RAIL_READABLE_FLOOR_COLUMNS, Math.floor(columns) - READABLE_PANEL_COLUMNS);
+    return Math.min(ceiling, Math.max(RAIL_READABLE_FLOOR_COLUMNS, Math.floor(override)));
+}
 export const STANDARD_TAIL_HEIGHT = 16;
 export const FULL_TAIL_HEIGHT = 24;
 export const TAIL_STANDARD_ROWS = 1;
@@ -93,6 +118,23 @@ export const FRAME_SURRENDER_FIT = {
     caption: ({ captionCells, columns }) => captionCells >= 1 && captionCells <= columns - HEADER_FIXED_CELLS,
     tail: ({ tailRows }) => tailRows > 0,
 };
+/**
+ * Border plus horizontal padding the drawn panel charges around its body —
+ * half of it on each side. The plan owns this because the plan owns the item
+ * rows: the paint draws its list into the region planned below, and nothing
+ * downstream subtracts chrome of its own to find it again.
+ */
+export const RUN_PANEL_HORIZONTAL_CHROME = 4;
+/**
+ * Row bands drawn INSIDE another band rather than beside it, mapped to the band
+ * that hosts them. A nested band refines its host's rows, so the band walk skips
+ * it when tiling the height and asserts containment instead. It is no less a
+ * member of `rowSpans` for that: the oracle pins its span against the planned
+ * region, and demands the paint register a node at exactly that rectangle —
+ * which is precisely what a parallel field beside the plan could never be held
+ * to.
+ */
+export const FRAME_NESTED_ROW_BANDS = { items: "body" };
 /* ------------------------------------------------------------------ */
 /* The sidebar band's composition: the menu at the rail's top, the     */
 /* vitals anchored to the rail's bottom, and at least one blank row    */
@@ -113,17 +155,28 @@ export const SIDEBAR_VITALS_COMPACT_ELEMENT_ROWS = 1;
  * one gap row is the vitals budget, spent on the full two-row block when it
  * fits whole, else on the one-row elements, surrendered from the top of the
  * block with the meter surrendered last. An element draws whole or not at all.
+ * `railRow` is the frame row the rail band starts at, so the view rows the plan
+ * reports are frame rows a reported cell is compared against directly. It is
+ * required for that reason: a default here would answer rail-relative rows in a
+ * field documented as frame rows — the same defaulted-measurement defect the key
+ * delivery carried, and this one would land in the rows a rail hit resolves
+ * through.
  */
-export function planSidebar(railRows) {
+export function planSidebar(railRows, railRow) {
     const menuRows = railRows >= SIDEBAR_MENU_LABEL_ROWS
         ? 1 + FRAME_VIEWS.length
         : FRAME_VIEWS.length;
+    // The views occupy the menu block's last rows: whatever the block exceeds
+    // them by is the label row the plan funded above them.
+    const firstViewRow = railRow + (menuRows - FRAME_VIEWS.length);
+    const viewRows = Object.fromEntries(FRAME_VIEWS.map((view, index) => [view, firstViewRow + index]));
     const fullRows = SIDEBAR_VITALS_ORDER.length * SIDEBAR_VITALS_FULL_ELEMENT_ROWS;
     // The gap is funded before the vitals are: the budget is what remains after it.
     const budget = railRows - menuRows - 1;
     if (budget >= fullRows) {
         return {
             menuRows,
+            viewRows,
             gapRows: railRows - menuRows - fullRows,
             vitalsMode: "full",
             vitals: SIDEBAR_VITALS_ORDER,
@@ -132,11 +185,29 @@ export function planSidebar(railRows) {
     const kept = Math.max(0, Math.min(SIDEBAR_VITALS_ORDER.length, Math.floor(budget)));
     return {
         menuRows,
+        viewRows,
         gapRows: kept > 0 ? railRows - menuRows - kept : 0,
         vitalsMode: "compact",
         vitals: SIDEBAR_VITALS_ORDER.slice(SIDEBAR_VITALS_ORDER.length - kept),
     };
 }
+/**
+ * The item rows of a body band: the band less the chrome the drawn panel puts
+ * around its list — the border row and the title row above the first item, the
+ * border row below it, and a bordered padded column on each side. THE ONE
+ * PLACE that subtraction happens, and it happens in the plan: paint and hit
+ * resolution alike consume this region rather than deriving it again.
+ */
+function planItemRows(body) {
+    const heading = PANEL_CHROME_ROWS - 1; // border row, then the title row
+    return {
+        id: "items",
+        row: body.row + heading,
+        rows: Math.max(1, body.rows - PANEL_CHROME_ROWS),
+        column: body.column + RUN_PANEL_HORIZONTAL_CHROME / 2,
+        columns: Math.max(1, body.columns - RUN_PANEL_HORIZONTAL_CHROME),
+    };
+}
 function tailRowsFor(rows) {
     if (rows >= FULL_TAIL_HEIGHT)
         return TAIL_FULL_ROWS;
@@ -151,7 +222,9 @@ function tailRowsFor(rows) {
  * height exactly — header, rule, the view strip (40–63 columns), the body
  * band, a second rule, the journal tail surrendered whole by height tier,
  * status, keybar — and, at ≥64 columns, column bands that tile the width
- * exactly: the constant 15-column rail beside the body. The body is the sole
+ * exactly: the rail beside the body, at the constant 15 columns or at the
+ * session's dragged override clamped to both panels' readable floors
+ * (`planRailColumns`). The body is the sole
  * flexible element on both axes. The view and state decide what the flexible
  * bands draw (the Journal view is the full-height tail; SETUP turns the tail
  * into PENDING WRITES; an open detail owns the body) without moving any
@@ -165,7 +238,12 @@ function tailRowsFor(rows) {
  * of the block, the meter last, rather than closing the gap. rowSpans and
  * columnSpans are band maps: they deliberately exclude the nested caption,
  * and column bands are reported for the body band only, so each map's spans
- * sum to the full height and width respectively.
+ * sum to the full height and width respectively. The body band's item rows are
+ * a band of the plan in their own right — a region in `regions` and a span in
+ * `rowSpans`, nested inside the body band rather than tiling beside it — so the
+ * region the paint draws its list into and the region a pointer resolves a row
+ * through are the one thing the oracle pins, and neither subtracts the drawn
+ * panel's chrome for itself.
  */
 export function planFrame(size, view = "tasks", state = {}) {
     const columns = Math.floor(size.columns);
@@ -178,6 +256,9 @@ export function planFrame(size, view = "tasks", state = {}) {
     }
     const tab = state.tab ?? "watch";
     const band = columns >= SIDEBAR_COLUMN_FLOOR ? "sidebar" : "strip";
+    // The one panel the session can resize: the rail, at the operator's dragged
+    // override clamped to the readable floors, or the contract's constant rail.
+    const railColumns = planRailColumns(columns, state.railColumns);
     const stripRows = band === "strip" ? 1 : 0;
     const tailRows = tailRowsFor(rows);
     // Fixed chrome is five rows: header, rule, a second rule below the body
@@ -221,25 +302,21 @@ export function planFrame(size, view = "tasks", state = {}) {
             row: bodyRow,
             rows: bodyRows,
             column: 0,
-            columns: RAIL_COLUMNS,
-        });
-        regions.push({
-            id: "body",
-            row: bodyRow,
-            rows: bodyRows,
-            column: RAIL_COLUMNS,
-            columns: columns - RAIL_COLUMNS,
+            columns: railColumns,
         });
     }
-    else {
-        regions.push({
+    const bodyRegion = band === "sidebar"
+        ? {
             id: "body",
             row: bodyRow,
             rows: bodyRows,
-            column: 0,
-            columns,
-        });
-    }
+            column: railColumns,
+            columns: columns - railColumns,
+        }
+        : { id: "body", row: bodyRow, rows: bodyRows, column: 0, columns };
+    regions.push(bodyRegion);
+    const itemsRegion = planItemRows(bodyRegion);
+    regions.push(itemsRegion);
     if (captionFits) {
         regions.push({
             id: "caption",
@@ -253,13 +330,14 @@ export function planFrame(size, view = "tasks", state = {}) {
     if (stripRows > 0)
         rowSpans.strip = stripRows;
     rowSpans.body = bodyRows;
+    rowSpans.items = itemsRegion.rows;
     rowSpans.rule2 = 1;
     if (tailRows > 0)
         rowSpans.tail = tailRows;
     rowSpans.status = 1;
     rowSpans.keybar = 1;
     const columnSpans = band === "sidebar"
-        ? { rail: RAIL_COLUMNS, body: columns - RAIL_COLUMNS }
+        ? { rail: railColumns, body: columns - railColumns }
         : { body: columns };
     return {
         kind: "frame",
@@ -275,7 +353,7 @@ export function planFrame(size, view = "tasks", state = {}) {
         rowSpans,
         columnSpans,
         flexible: { row: "body", column: "body" },
-        sidebar: band === "sidebar" ? planSidebar(bodyRows) : null,
+        sidebar: band === "sidebar" ? planSidebar(bodyRows, bodyRow) : null,
         surrendered,
     };
 }

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

@@ -1,5 +1,6 @@
 import type { CockpitGraph, RunCockpitData, RunCockpitSource } from "./derive.js";
 import { type RunInteractionState, type RunKeyEvent } from "./keys.js";
+import { type PointerReport, type PointerSurface } from "./pointer.js";
 /**
  * THE engagement selection rule — stated once, here, so it can change in one
  * place without touching the renderer or the command: an explicit engagement
@@ -46,6 +47,17 @@ export declare function reconcileLiveRunInteraction(interaction: RunInteractionS
  * one place rows enter the dispatcher, so no key can reach a journal row.
  */
 export declare function liveRunViewRowIds(interaction: RunInteractionState, data: RunCockpitData): readonly string[];
+/**
+ * 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 declare function liveRunPointerSurface(data: RunCockpitData, interaction: RunInteractionState, size: {
+    readonly columns: number;
+    readonly rows: number;
+}): PointerSurface | undefined;
 export type LiveCockpitSurface = {
     readonly data: RunCockpitData;
     readonly interaction: RunInteractionState;
@@ -62,7 +74,8 @@ export type LiveCockpitSurface = {
 export type LiveCockpitDelivery = {
     readonly snapshot: () => LiveCockpitSurface;
     readonly refresh: () => boolean;
-    readonly key: (event: RunKeyEvent, columns?: number) => boolean;
+    readonly key: (event: RunKeyEvent) => boolean;
+    readonly pointer: (report: PointerReport) => boolean;
     readonly batch: <Result>(deliver: () => Result) => Result;
 };
 export declare function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs, now, debug, onDelivery, }: {