tickmarkr 1.81.0 → 1.83.0

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

@@ -1,3 +1,4 @@
+import { type RunViewId } from "./views.js";
 /**
  * THE key contract for the run cockpit. This registry is the single source of
  * truth for both halves of a key: what the keybar advertises and what the key
@@ -12,6 +13,7 @@ export type RunKeyEvent = {
         readonly upArrow?: boolean;
         readonly downArrow?: boolean;
         readonly leftArrow?: boolean;
+        readonly rightArrow?: boolean;
         readonly return?: boolean;
         readonly tab?: boolean;
         readonly escape?: boolean;
@@ -27,13 +29,21 @@ export type RunKeyEvent = {
  * byte-identical to a frame that carries no interaction state at all, and every
  * transition away from it is a change an operator can see.
  */
+/** The two top-level tabs: watch reads the engagement, setup writes to it. */
+export type RunTabId = "watch" | "setup";
 export type RunInteractionState = {
-    /** The journal row the pointer marks — moved by ↑↓, -1 while nothing is selected. */
-    readonly selection: number;
-    /** The focused panel, index into RUN_PANEL_FOCUS_ORDER — cycled by Tab. */
+    /** Which of the two tabs the surface draws — switched by Tab, never by a view. */
+    readonly tab: RunTabId;
+    /** The row in the active view the pointer marks; the overview has no rows. */
+    readonly selection: string | null;
+    /** The focused region, index into RUN_PANEL_FOCUS_ORDER — set by diving and backing out. */
     readonly panel: number;
-    /** The selection opened by ⏎, or null once ← returns from it. */
-    readonly opened: number | null;
+    /** The selected rail row, independent from the view currently open. */
+    readonly railSelection: number;
+    /** The view drawn in the main region. */
+    readonly activeView: RunViewId;
+    /** The active view row opened by ⏎, or null while drawing the view itself. */
+    readonly opened: string | null;
     /** Follow mode — toggled by f; drawn as a status-strip indicator while on. */
     readonly follow: boolean;
     /** The / prompt is open and taking filter text. */
@@ -47,10 +57,57 @@ export type RunInteractionState = {
 };
 export declare function initialRunInteractionState(): RunInteractionState;
 /**
- * The panels Tab cycles focus through, in cycle order; index 0 is the focus
- * the surface opens with, so the initial frame is the one the anchors pin.
+ * The panels the run surface's focus moves between, in their painted order;
+ * index 0 is the content panel, and the sidebar is the level every view backs
+ * out to. A width that hides the sidebar resolves every index onto the panel
+ * that remains (`runPanelFocusOrder`).
+ */
+export declare const RUN_PANEL_FOCUS_ORDER: readonly ["CONTENT", "VIEWS"];
+/**
+ * The state the live surface opens in: the watch tab, the sidebar focused, so
+ * the very first arrow key moves the view selection rather than a row. This is
+ * a second constructor rather than a change to the one above: the committed
+ * captures depict a surface with no interaction state at all, and only an
+ * operator-accepted capture may re-freeze them.
+ */
+export declare function openingRunInteractionState(tab?: RunTabId): RunInteractionState;
+/**
+ * The whole surface: the tab being drawn and the tab waiting behind it. Each
+ * half keeps its own selection, so Tab and Tab again returns an operator to
+ * exactly the row and view they left.
+ */
+export type RunSurfaceState = {
+    readonly interaction: RunInteractionState;
+    readonly stashed: RunInteractionState;
+};
+export declare function openingRunSurfaceState(): RunSurfaceState;
+/**
+ * The rows of a view a key may actually stand on. The journal is a tail, not a
+ * list: it is never selected, opened or filtered, in either tab. Stated once
+ * here so the dispatcher and the advertisement cannot disagree about it.
  */
-export declare const RUN_PANEL_FOCUS_ORDER: readonly ["RUN", "VIEWS", "KEYS"];
+export declare function selectableRunViewRowIds(viewId: RunViewId, rowIds: readonly string[]): readonly string[];
+/** The one width predicate shared by rendering, focus and key projection. */
+export declare const RUN_SIDE_RAIL_COLUMN_FLOOR = 80;
+export declare function runSideRailVisible(columns: number): boolean;
+export declare function runPanelFocusOrder(columns: number): readonly (typeof RUN_PANEL_FOCUS_ORDER)[number][];
+export type RunKeyProjectionContext = {
+    readonly interaction: RunInteractionState;
+    readonly columns: number;
+    /** Stable identities in the active view's filtered logical collection. */
+    readonly rowIds?: readonly string[];
+};
+export type RunKeyApplyContext = {
+    readonly rowIds: readonly string[];
+    /**
+     * The terminal width the dispatch was made at, so a handler resolves focus
+     * against the same effective width the advertisement did. Handlers invoked
+     * without a dispatch — tests driving a binding directly — assume the width
+     * that offers every key.
+     */
+    readonly columns?: number;
+};
+export declare function runFocusedPanel({ interaction, columns, }: RunKeyProjectionContext): (typeof RUN_PANEL_FOCUS_ORDER)[number];
 export type RunKeyBinding = {
     /** The glyph the keybar draws, e.g. "↑↓". */
     readonly key: string;
@@ -59,13 +116,23 @@ export type RunKeyBinding = {
     /** Whether a key event activates this binding. */
     readonly matches: (event: RunKeyEvent) => boolean;
     /** The state transition the label promises. */
-    readonly apply: (state: RunInteractionState, event: RunKeyEvent) => RunInteractionState;
+    readonly apply: (state: RunInteractionState, event: RunKeyEvent, context?: RunKeyApplyContext) => RunInteractionState;
+    /** Which projected contexts can actually observe this binding's transition. */
+    readonly available?: (context: RunKeyProjectionContext) => boolean;
+    /** Prompt bindings replace, rather than supplement, the normal roster. */
+    readonly scope?: "normal" | "filter-prompt";
     /**
      * How a binding that carries on/off state reports it — the brand's reserved
      * toggle glyphs, never bracket toggles. Present exactly on the bindings
      * whose state is on/off.
      */
     readonly report?: (state: RunInteractionState) => string;
+    /**
+     * The word naming where a switch key takes the operator from the current
+     * state — Tab promises the tab it will draw. Present exactly on bindings
+     * whose honest label depends on which side of the switch the surface is on.
+     */
+    readonly destination?: (state: RunInteractionState) => string;
 };
 /** A toggle's on/off report: the brand's reserved glyphs, never brackets. */
 export declare function toggleReport(label: string, on: boolean): string;
@@ -74,6 +141,18 @@ export declare function toggleReport(label: string, on: boolean): string;
  * its handler, so advertisement and behaviour cannot drift apart.
  */
 export declare const RUN_KEY_BINDINGS: readonly RunKeyBinding[];
+/**
+ * Number jumps name a view, and a digit means that one view on the whole
+ * surface — one key, one meaning, everywhere. Pressed on the setup tab, which
+ * holds sections rather than views, a digit switches to the tab that holds
+ * the views and lands on the one it numbers; setup waits behind with its own
+ * state intact for the round trip.
+ */
+export declare const RUN_VIEW_KEY_BINDING: RunKeyBinding;
+/** The filter prompt's own advertised and executable input roster. */
+export declare const RUN_FILTER_PROMPT_BINDINGS: readonly RunKeyBinding[];
+/** Every input binding the live run cockpit dispatches or the prompt owns. */
+export declare const RUN_INPUT_BINDINGS: readonly RunKeyBinding[];
 /** The panels the setup surface cycles through, in their painted order. */
 export declare const SETUP_PANEL_FOCUS_ORDER: readonly ["SETUP", "HARNESSES", "KEYS"];
 /**
@@ -115,19 +194,19 @@ export declare const SURFACE_KEY_BINDINGS: {
 };
 /** Save confirmation owns input until it is accepted or dismissed. */
 export declare function applySetupPromptInput(event: RunKeyEvent, state: SetupInteractionState): SetupInteractionState | undefined;
-/**
- * The transitions of the open / prompt. The prompt is not an advertised key,
- * so it has no binding — but its transitions live here beside the registry
- * because they rewrite the same interaction state: characters grow the query,
- * backspace shrinks it, ⏎ applies it (the journal stays narrowed), escape
- * cancels it. Anything else the prompt swallows unchanged.
- */
-export declare function applyFilterInput(event: RunKeyEvent, state: RunInteractionState): RunInteractionState | undefined;
 /** What an advertisement looks like once the handler is stripped away. */
 export type KeybarEntry = {
     readonly key: string;
     readonly label: string;
 };
+export type RunKeyProjection = (context: RunKeyProjectionContext) => readonly KeybarEntry[];
+/** The lossless text vocabulary shared by frame and plain advertisements. */
+export declare function formatKeybarEntries(entries: readonly KeybarEntry[]): string;
+/**
+ * THE one context projection over the one run registry. Consumers receive its
+ * return value whole; none may filter, append or independently map bindings.
+ */
+export declare function projectRunKeyEntries(context: RunKeyProjectionContext, bindings?: readonly RunKeyBinding[]): readonly KeybarEntry[];
 /**
  * The keybar's entries, derived from a binding registry. This is the only way
  * a keybar list is produced: remove a handler and its entry disappears.
@@ -138,11 +217,27 @@ export declare function keybarEntries(bindings: readonly {
 }[]): readonly KeybarEntry[];
 /** The binding a key event activates, or undefined when no handler owns it. */
 export declare function resolveRunKeyBinding(bindings: readonly RunKeyBinding[], event: RunKeyEvent): RunKeyBinding | undefined;
+/**
+ * Re-establish the row invariant after a derivation or filter changes. The
+ * identities themselves are authoritative: an in-range position is never a
+ * substitute for the row that used to occupy it.
+ */
+export declare function reconcileRunInteraction(state: RunInteractionState, rowIds: readonly string[]): RunInteractionState;
 /**
  * Send a key event to the registry: the matching binding's handler produces
- * the next interaction state. An event no handler owns changes nothing.
+ * the next interaction state. An event no handler owns changes nothing — and
+ * while the / prompt is open the prompt's own scope is the only roster that
+ * owns anything, so a character grows the query rather than quitting the
+ * surface. One dispatcher decides that, so no caller can own the prompt twice.
+ */
+export declare function dispatchRunKey(event: RunKeyEvent, state: RunInteractionState, bindings?: readonly RunKeyBinding[], rowIds?: readonly string[], columns?: number): RunInteractionState | undefined;
+/**
+ * Send a key event to the whole surface. The registry owns every transition,
+ * including the tab flip; the surface only decides what a flipped tab means —
+ * the tab that was waiting comes forward carrying the state it was left in, and
+ * the tab that was drawn is what waits now.
  */
-export declare function dispatchRunKey(event: RunKeyEvent, state: RunInteractionState, bindings?: readonly RunKeyBinding[]): RunInteractionState | undefined;
+export declare function dispatchRunSurfaceKey(event: RunKeyEvent, surface: RunSurfaceState, bindings?: readonly RunKeyBinding[], rowIds?: readonly string[], columns?: number): RunSurfaceState | undefined;
 /** The setup binding a key event activates, or undefined when none owns it. */
 export declare function resolveSetupKeyBinding(bindings: readonly SetupKeyBinding[], event: RunKeyEvent): SetupKeyBinding | undefined;
 /** Send a key event through the setup half of the shared surface registry. */