tmux-ide 2.6.1 → 2.7.0

package/packages/daemon/src/tui/mirror/focus-border.ts

@@ -0,0 +1,57 @@
+/**
+ * Focus-border geometry (M22.7): the accent strips drawn in the canvas GUTTER
+ * cells around the focused pane, so focus is pane-level obvious without
+ * consuming any terminal cells (a real box border would shrink the grid).
+ *
+ * Strips exist only where the pane has a neighboring gutter INSIDE the canvas —
+ * a pane flush to a canvas edge has no room on that side (tmux gives edge panes
+ * flush edges), and a single-pane window renders no strips at all (there is no
+ * ambiguity to resolve, and no gutters to paint). Horizontal strips extend one
+ * cell into the adjacent vertical gutters so the corners fill.
+ *
+ * PURE — rect math only; the app renders each strip as one background-tinted
+ * box, and the strips are handler-less so gutter presses still bubble to the
+ * central router (border drags keep working).
+ */
+
+export interface PaneRectLike {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface FocusStrip {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * The gutter strips around `pane` within a `cols`×`rows` canvas — empty when
+ * the window has a single pane (`paneCount < 2`) or the rect is degenerate.
+ */
+export function focusStrips(
+  pane: PaneRectLike,
+  cols: number,
+  rows: number,
+  paneCount: number,
+): FocusStrip[] {
+  if (paneCount < 2) return [];
+  if (pane.width <= 0 || pane.height <= 0) return [];
+  const strips: FocusStrip[] = [];
+  const hasLeft = pane.left > 0;
+  const hasRight = pane.left + pane.width < cols;
+  const hasTop = pane.top > 0;
+  const hasBottom = pane.top + pane.height < rows;
+  // Horizontal strips reach into the side gutters so corners fill.
+  const hx = hasLeft ? pane.left - 1 : pane.left;
+  const hw = pane.width + (hasLeft ? 1 : 0) + (hasRight ? 1 : 0);
+  if (hasTop) strips.push({ left: hx, top: pane.top - 1, width: hw, height: 1 });
+  if (hasBottom) strips.push({ left: hx, top: pane.top + pane.height, width: hw, height: 1 });
+  if (hasLeft) strips.push({ left: pane.left - 1, top: pane.top, width: 1, height: pane.height });
+  if (hasRight)
+    strips.push({ left: pane.left + pane.width, top: pane.top, width: 1, height: pane.height });
+  return strips;
+}

package/packages/daemon/src/tui/mirror/folder-picker.ts

@@ -0,0 +1,124 @@
+/**
+ * The "open a folder" picker's PURE model (M22.5) — the filesystem browser
+ * behind the home screen's non-technical entry point. The picker is a
+ * {@link ../mirror/dialog-stack.ts} DialogSelect flow: app.tsx does the async
+ * `readdir`/`stat` (the header's async-only fs law) and drives the browse loop;
+ * everything here — how a directory's entries become rows, how the breadcrumb
+ * reads, how a typed path expands, how an invalid path is explained — is pure so
+ * it unit-tests without OpenTUI or a filesystem.
+ *
+ * Row id scheme (what a chosen row dispatches on):
+ *   picker:open            → open the folder we are browsing
+ *   picker:hidden          → toggle whether dot-leading folders show
+ *   picker:up              → ascend to the parent
+ *   picker:type            → the "type a path…" escape hatch (a DialogPrompt)
+ *   picker:dir:<name>      → descend into <name>
+ *
+ * The hidden-folders toggle is a ROW (not a ctrl chord): terminal-native,
+ * `ctrl+h` is byte-identical to Backspace, so a chord can't carry it — and a
+ * row is mouse-clickable and keyboard-selectable, which suits the audience.
+ */
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import type { DialogSelectItem } from "./dialog-model.ts";
+
+export const PICKER_OPEN_ID = "picker:open";
+export const PICKER_HIDDEN_ID = "picker:hidden";
+export const PICKER_UP_ID = "picker:up";
+export const PICKER_TYPE_ID = "picker:type";
+export const PICKER_DIR_PREFIX = "picker:dir:";
+
+/** How many breadcrumb segments the title keeps before eliding the front with
+ *  an ellipsis (deep paths stay one readable line). */
+const BREADCRUMB_MAX_SEGMENTS = 4;
+
+/** PURE — expand a user-typed path: a leading `~` (or `~/…`) becomes `home`,
+ *  then relative paths resolve against `base`. An absolute path is returned as
+ *  given (normalized). Blank input resolves to `base`. */
+export function expandUserPath(input: string, home: string, base: string): string {
+  const raw = input.trim();
+  if (raw.length === 0) return base;
+  if (raw === "~") return home;
+  if (raw.startsWith("~/")) return join(home, raw.slice(2));
+  if (isAbsolute(raw)) return resolve(raw);
+  return resolve(base, raw);
+}
+
+/** PURE — the parent directory, stopping at the filesystem root (dirname of
+ *  `/` is `/`). */
+export function pickerParent(dir: string): string {
+  return dirname(dir);
+}
+
+/** PURE — whether `dir` is the filesystem root (no higher parent). */
+export function isPickerRoot(dir: string): boolean {
+  return dirname(dir) === dir;
+}
+
+/** PURE — the subdirectory names to show: hidden (dot-leading) folders are
+ *  dropped unless `showHidden`, `.`/`..` never appear, and the rest sort
+ *  case-insensitively so the list reads like a file manager. */
+export function filterDirs(names: readonly string[], showHidden: boolean): string[] {
+  return names
+    .filter((n) => n !== "." && n !== "..")
+    .filter((n) => showHidden || !n.startsWith("."))
+    .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+}
+
+/** PURE — a compact breadcrumb for the dialog title: the home prefix collapses
+ *  to `~`, segments join with ` › `, and a path deeper than
+ *  {@link BREADCRUMB_MAX_SEGMENTS} elides its front with `…`. The root shows as
+ *  `/`. */
+export function pickerBreadcrumb(dir: string, home: string): string {
+  let rest = dir;
+  let head = "";
+  if (home.length > 0 && (dir === home || dir.startsWith(`${home}/`))) {
+    head = "~";
+    rest = dir.slice(home.length);
+  }
+  const segs = rest.split("/").filter(Boolean);
+  const parts = head ? [head, ...segs] : segs;
+  if (parts.length === 0) return "/";
+  if (parts.length <= BREADCRUMB_MAX_SEGMENTS) return parts.join(" › ");
+  return ["…", ...parts.slice(parts.length - BREADCRUMB_MAX_SEGMENTS)].join(" › ");
+}
+
+/** PURE — the picker rows for a directory: an explicit "open this folder" row
+ *  first, then the hidden-folders toggle, the ascend row (unless at the root),
+ *  the subdirectories (already filtered/sorted by {@link filterDirs}), and the
+ *  "type a path…" escape hatch last. Descending happens on a `picker:dir:*` /
+ *  `picker:up` row; opening on `picker:open`; the toggle flips `showHidden`. */
+export function pickerRows(
+  dir: string,
+  subdirs: readonly string[],
+  showHidden: boolean,
+): DialogSelectItem[] {
+  const rows: DialogSelectItem[] = [
+    { id: PICKER_OPEN_ID, label: "＋ Open this folder", detail: basename(dir) || dir },
+    {
+      id: PICKER_HIDDEN_ID,
+      label: showHidden ? "Hide hidden folders" : "Show hidden folders",
+      detail: showHidden ? "on" : "off",
+    },
+  ];
+  if (!isPickerRoot(dir)) rows.push({ id: PICKER_UP_ID, label: "..", detail: "up a level" });
+  for (const name of subdirs) rows.push({ id: `${PICKER_DIR_PREFIX}${name}`, label: `${name}/` });
+  rows.push({ id: PICKER_TYPE_ID, label: "Type a path…", detail: "enter a folder path" });
+  return rows;
+}
+
+/** PURE — the subdirectory name a `picker:dir:*` row descends into, or null for
+ *  any other id. */
+export function pickerDirName(id: string): string | null {
+  return id.startsWith(PICKER_DIR_PREFIX) ? id.slice(PICKER_DIR_PREFIX.length) : null;
+}
+
+/** The three outcomes of stat-ing a typed path. */
+export type PathKind = "dir" | "file" | "missing";
+
+/** PURE — the plain-language footer error for a typed path that isn't a folder
+ *  (never called for `"dir"` — that path is accepted). */
+export function pathKindHint(kind: "file" | "missing"): string {
+  return kind === "file"
+    ? "That's a file, not a folder — pick a directory"
+    : "No folder there — check the path and try again";
+}

package/packages/daemon/src/tui/mirror/home-model.ts

@@ -0,0 +1,174 @@
+/**
+ * The HOME panel's row model (M21.9) — PURE so it unit-tests without OpenTUI.
+ *
+ * Home used to be a flat list of live sessions; now it is a list of ITEMS:
+ * every live session (unchanged, first), then — when the project registry has
+ * projects with no live session — a section header followed by one launchable
+ * row per registered-but-not-running project. That surfaces the registry as a
+ * mouse-first "open project" affordance: clicking (or pressing enter on) a
+ * project row launches a detached session in its dir and opens it as the
+ * workspace.
+ *
+ * The item list is what the render walks AND what the router's `gy - 2` row
+ * math indexes, so selection/hover/click all share one geometry. Headers are
+ * not selectable; the step/clamp helpers keep the keyboard selection on real
+ * rows without the app hand-rolling skip loops.
+ */
+import { basename } from "node:path";
+import type { AgentStatus } from "../detect/classify.ts";
+import type { AppKeys } from "../../lib/app-config.ts";
+import { prefixTwinFor } from "./settings-model.ts";
+
+/** A live tmux session row — click/enter opens it as the workspace. */
+export interface HomeSessionItem {
+  kind: "session";
+  session: string;
+  project: string;
+  status: AgentStatus;
+  windows: number;
+  dir: string | null;
+}
+/** A registered project with no live session — click/enter launches it. */
+export interface HomeProjectItem {
+  kind: "project";
+  name: string;
+  dir: string | null;
+}
+/** A recently-opened folder with no live session or registry entry (M22.5) —
+ *  click/enter re-opens it (create-or-attach a session in `dir`). */
+export interface HomeRecentItem {
+  kind: "recent";
+  name: string;
+  dir: string;
+}
+/** A non-selectable section label between the sessions and the registry. */
+export interface HomeHeaderItem {
+  kind: "header";
+  label: string;
+}
+export type HomeItem = HomeSessionItem | HomeProjectItem | HomeRecentItem | HomeHeaderItem;
+
+/** The slice of the `tmux-ide team --json` payload this model reads (kept
+ *  structural so the app's locally-declared fleet shape satisfies it). */
+export interface HomeFleetProject {
+  name: string;
+  dir: string | null;
+  registered: boolean;
+  running: boolean;
+  sessions: Array<{
+    name: string;
+    status: AgentStatus;
+    windows: Array<unknown>;
+  }>;
+}
+
+export const REGISTRY_HEADER_LABEL = "registered projects — not running";
+export const RECENTS_HEADER_LABEL = "recently opened";
+
+/** PURE — the ordered home items: every project's live sessions first (the
+ *  exact rows home always showed), then a header + one row per registered
+ *  project that has no live session, then (M22.5) a "recently opened" section.
+ *  Recents dedupe against the REGISTRY (registry wins) — a folder you saved as
+ *  a project shows only as its project row, never doubled as a recent. Recents
+ *  are NOT deduped against live sessions: opening a folder spins up a session,
+ *  yet the folder still belongs in "recent" for one-click reopen later. */
+export function buildHomeItems(
+  projects: readonly HomeFleetProject[],
+  recents: readonly string[] = [],
+): HomeItem[] {
+  const items: HomeItem[] = [];
+  for (const p of projects) {
+    for (const s of p.sessions) {
+      items.push({
+        kind: "session",
+        session: s.name,
+        project: p.name,
+        status: s.status,
+        windows: s.windows.length,
+        dir: p.dir,
+      });
+    }
+  }
+  const idle = projects.filter((p) => p.registered && !p.running);
+  if (idle.length > 0) {
+    items.push({ kind: "header", label: REGISTRY_HEADER_LABEL });
+    for (const p of idle) items.push({ kind: "project", name: p.name, dir: p.dir });
+  }
+  // A folder already saved as a registered project is not repeated under
+  // "recent" (registry wins the dedupe).
+  const registeredDirs = new Set<string>();
+  for (const p of projects) if (p.dir && p.registered) registeredDirs.add(p.dir);
+  const freshRecents = recents.filter((d) => d.length > 0 && !registeredDirs.has(d));
+  if (freshRecents.length > 0) {
+    items.push({ kind: "header", label: RECENTS_HEADER_LABEL });
+    for (const dir of freshRecents) {
+      items.push({ kind: "recent", name: basename(dir) || dir, dir });
+    }
+  }
+  return items;
+}
+
+/** PURE — first-run when the fleet has no live sessions AND no registered
+ *  projects (M22.5). Recently-opened folders alone do NOT count — the welcome
+ *  still greets someone who has only browsed folders, and hides the moment a
+ *  session or project exists. */
+export function isFirstRun(projects: readonly HomeFleetProject[]): boolean {
+  const hasSession = projects.some((p) => p.sessions.length > 0);
+  const hasProject = projects.some((p) => p.registered);
+  return !hasSession && !hasProject;
+}
+
+/** PURE — the one-line first-run tip built from the USER'S ACTUAL keybindings
+ *  (M22.5): the reliable `prefix <letter>` twin for each action, falling back
+ *  to the raw Alt key when a letter is claimed by a stock tmux bind. */
+export function firstRunTip(keys: AppKeys): string {
+  const k = (alt: string): string => {
+    const twin = prefixTwinFor(alt);
+    return twin ? `prefix ${twin}` : alt;
+  };
+  return `Your keys: ${k(keys.home)} home · ${k(keys.popup)} switch sessions · ${k(keys.menu)} actions`;
+}
+
+/** PURE — the leading-space padding that horizontally centers a `len`-wide run
+ *  in a `width`-wide area (never negative). Shared by the welcome render and
+ *  the click router so a centered clickable lands where it is drawn. */
+export function centerPad(width: number, len: number): number {
+  return Math.max(0, Math.floor((width - len) / 2));
+}
+
+/** PURE — whether an item takes selection / clicks as a row. */
+export function isSelectable(item: HomeItem | undefined): boolean {
+  return item !== undefined && item.kind !== "header";
+}
+
+/** PURE — clamp a selection index onto a selectable item: into range first,
+ *  then the nearest selectable at-or-above, falling back downward. Returns 0
+ *  for an empty list (matching the old `Math.min(sel, len - 1)` behavior). */
+export function clampSelectable(items: readonly HomeItem[], sel: number): number {
+  if (items.length === 0) return 0;
+  const start = Math.max(0, Math.min(sel, items.length - 1));
+  for (let i = start; i < items.length; i++) if (isSelectable(items[i])) return i;
+  for (let i = start - 1; i >= 0; i--) if (isSelectable(items[i])) return i;
+  return 0;
+}
+
+/** PURE — move the selection one selectable row in `delta`'s direction (±1),
+ *  skipping headers; stays put at either end. */
+export function stepSelectable(items: readonly HomeItem[], from: number, delta: 1 | -1): number {
+  for (let i = from + delta; i >= 0 && i < items.length; i += delta) {
+    if (isSelectable(items[i])) return i;
+  }
+  return from;
+}
+
+/** PURE — a tmux-legal session name for a project: tmux forbids `:` and `.`
+ *  in session names (target syntax), and spaces only invite quoting bugs —
+ *  all collapse to `-`. */
+export function sessionNameFor(project: string): string {
+  return project.replace(/[.:\s]+/g, "-");
+}
+
+/** PURE — whether a user-typed session name is directly usable. */
+export function isValidSessionName(name: string): boolean {
+  return name.length > 0 && !/[.:\s]/.test(name);
+}

package/packages/daemon/src/tui/mirror/input-coalescer.ts

@@ -0,0 +1,105 @@
+/**
+ * InputCoalescer — the pure core of the input fast path (M21.5).
+ *
+ * Burst-typed LITERAL characters coalesce into one buffered run per pane and
+ * leave as a single `send-keys -H <hex…>` write per flush; named/ctrl keys
+ * (Enter, C-c, Up, …) are emitted immediately. THE ordering invariant: any
+ * buffered literal run flushes BEFORE a named key — or a literal for a
+ * DIFFERENT pane — is emitted, so bytes reach the pane in exactly the order
+ * the user produced them.
+ *
+ * Pure core, io shell: this class owns no timers and does no io. The caller
+ * injects `emit` (where flushed actions go — the control client's
+ * fire-and-forget write in production) and `schedule` (when a pending literal
+ * buffer should auto-flush — a microtask in production, a hand-cranked stub in
+ * tests). A microtask flush still happens inside the same macrotask that
+ * buffered the keystroke — strictly before the process can read more input —
+ * so coalescing adds no perceivable latency; it only merges keystrokes that
+ * arrived together.
+ *
+ * Flushes re-chunk the buffered run under {@link SEND_KEYS_CHUNK_BYTES} so a
+ * large paste routed through the same path never produces an oversized
+ * control-mode command.
+ */
+import { chunkByBytes } from "./selection.ts";
+
+/**
+ * Max UTF-8 payload bytes per `send-keys -H` write. Every byte travels as its
+ * own `xx` argv token, and each token hits tmux's yacc command parser — which
+ * is the REAL constraint, measured empirically against tmux 3.6b control mode
+ * (M21.5), not a line-length cap:
+ *
+ *   - HARD LIMIT: a 16 KB payload (≈16k tokens) is REJECTED outright with
+ *     `%error: yacc stack overflow` (yacc's ~10k-entry stack).
+ *   - PARSE COST is superlinear in tokens: one command's reply takes ~3 ms at
+ *     1 KB, ~9 ms at 2 KB, ~56 ms at 4 KB, ~170 ms at 8 KB — big chunks STALL
+ *     the tmux server (and every interleaved keystroke behind it).
+ *   - END-TO-END, a 100 KB paste lands byte-perfect in ~246/155/180/233/255/
+ *     561/1483 ms at 64/128/256/512/1024/2048/4096-byte chunks — the optimum
+ *     is ~128–256 B; the pre-M21.5 1024 was past the knee, and RAISING the
+ *     chunk (the naive read of "fewer commands = faster") is strictly worse.
+ *
+ * 256 B is chosen: within noise of the throughput optimum, ~1 ms of server
+ * parse per command (imperceptible for input interleaving), 5× headroom from
+ * nothing, and 40× from the yacc cliff.
+ */
+export const SEND_KEYS_CHUNK_BYTES = 256;
+
+/** One flushed input action, ready to become a control-mode write. */
+export type InputAction =
+  | { kind: "literal"; pane: string; text: string }
+  | { kind: "key"; pane: string; key: string };
+
+export class InputCoalescer {
+  private pane = "";
+  private buf = "";
+  private scheduled = false;
+
+  constructor(
+    private readonly emit: (action: InputAction) => void,
+    private readonly schedule: (flush: () => void) => void,
+    private readonly maxChunkBytes: number = SEND_KEYS_CHUNK_BYTES,
+  ) {}
+
+  /** Buffer literal text for `pane`; a pending run for ANOTHER pane flushes
+   *  first so cross-pane order is preserved. Schedules an auto-flush once per
+   *  pending run. */
+  literal(pane: string, text: string): void {
+    if (!pane || !text) return;
+    if (this.buf.length > 0 && this.pane !== pane) this.flush();
+    this.pane = pane;
+    this.buf += text;
+    if (!this.scheduled) {
+      this.scheduled = true;
+      this.schedule(() => {
+        this.scheduled = false;
+        this.flush();
+      });
+    }
+  }
+
+  /** Emit a named tmux key (Enter, C-c, Up, …) — pending literals flush first
+   *  (synchronously) so the key can never overtake buffered characters. */
+  key(pane: string, key: string): void {
+    if (!pane || !key) return;
+    this.flush();
+    this.emit({ kind: "key", pane, key });
+  }
+
+  /** Drain the pending literal run now (chunked under the byte cap). Also the
+   *  ordering barrier callers place before reply-matched structural commands. */
+  flush(): void {
+    if (this.buf.length === 0) return;
+    const pane = this.pane;
+    const text = this.buf;
+    this.buf = "";
+    for (const chunk of chunkByBytes(text, this.maxChunkBytes)) {
+      this.emit({ kind: "literal", pane, text: chunk });
+    }
+  }
+
+  /** Buffered-but-unflushed character count (tests/introspection only). */
+  pending(): number {
+    return this.buf.length;
+  }
+}

package/packages/daemon/src/tui/mirror/menu-model.ts

@@ -0,0 +1,187 @@
+/**
+ * The right-click context-menu model (M19.2) — PURE so it unit-tests without
+ * OpenTUI. app.tsx opens a small overlay at the pointer on a right-button press
+ * (SGR button 2); the ITEM DESCRIPTORS per region and all the geometry (dims,
+ * on-screen clamp, click hit-test) live here, while the closures that actually
+ * attach / kill / split / rename stay in the app (a `run` switch over the
+ * item's `id`).
+ *
+ * The overlay is late-mounted inside a <Show>, so — per the app's mouse
+ * landmine laws — it carries NO per-item handlers: clicks are routed centrally
+ * by coordinate math against {@link menuItemAt}, exactly the way the surface
+ * tab bar and window strip resolve their clicks by x-span math. Keeping that
+ * math in one tested place is the whole point.
+ */
+
+/** The surfaces a right-click can target. Each maps to a fixed item list; the
+ *  concrete payload (session name, file path, pane id) rides in the app's menu
+ *  state, not here. */
+export type MenuRegion = "session" | "file" | "difffile" | "pane" | "window";
+
+/** One menu entry. `id` is what the app dispatches on; `danger` items rearm to
+ *  a "confirm: y" state instead of firing immediately; `input` items open an
+ *  inline text line (the string is the prompt) before firing; `children` items
+ *  open a SUBMENU column beside the row (one nesting level); `checkbox` items
+ *  carry a live ✓/✗ state the app supplies (the toggle keeps the menu open). */
+export interface MenuItem {
+  id: string;
+  label: string;
+  danger?: boolean;
+  input?: string;
+  children?: MenuItem[];
+  checkbox?: boolean;
+}
+
+/** PURE — the fixed item list for each region. The app supplies the context. */
+export const MENU_ITEMS: Record<MenuRegion, MenuItem[]> = {
+  session: [
+    { id: "attach", label: "Attach" },
+    { id: "rename", label: "Rename", input: "rename to" },
+    { id: "kill", label: "Kill session", danger: true },
+  ],
+  file: [
+    { id: "open", label: "Open" },
+    { id: "newfile", label: "New file", input: "new file" },
+    { id: "rename", label: "Rename", input: "rename to" },
+    { id: "delete", label: "Delete", danger: true },
+  ],
+  difffile: [
+    { id: "open", label: "Open in editor" },
+    { id: "copypath", label: "Copy path" },
+  ],
+  pane: [
+    { id: "split-h", label: "Split horizontal" },
+    { id: "split-v", label: "Split vertical" },
+    { id: "zoom", label: "Zoom toggle" },
+    { id: "swap-next", label: "Swap with next" },
+    { id: "break", label: "Break to window" },
+    { id: "rotate", label: "Rotate panes" },
+    {
+      id: "layouts",
+      label: "Layouts",
+      children: [
+        { id: "layout:even-horizontal", label: "even-horizontal" },
+        { id: "layout:even-vertical", label: "even-vertical" },
+        { id: "layout:main-horizontal", label: "main-horizontal" },
+        { id: "layout:main-vertical", label: "main-vertical" },
+        { id: "layout:tiled", label: "tiled" },
+      ],
+    },
+    { id: "sync-toggle", label: "Synchronize panes", checkbox: true },
+    { id: "kill", label: "Kill pane", danger: true },
+  ],
+  window: [
+    { id: "new", label: "New window" },
+    { id: "rename", label: "Rename window", input: "rename to" },
+    { id: "kill", label: "Kill window", danger: true },
+  ],
+};
+
+/** PURE — the pane menu's item list for a concrete pane (M22.9). App-mouse
+ *  panes (the app turned mouse reporting on — presses are forwarded, so a drag
+ *  can't start a selection) get a leading "Select text…" verb that pauses
+ *  forwarding for that pane; while its select mode is active the entry flips to
+ *  the exit verb. Ordinary panes keep the fixed list untouched. */
+export function paneMenuItems(appMouse: boolean, selectModeOn: boolean): MenuItem[] {
+  if (!appMouse) return MENU_ITEMS.pane;
+  const entry: MenuItem = selectModeOn
+    ? { id: "select-text-off", label: "Stop selecting" }
+    : { id: "select-text", label: "Select text…" };
+  return [entry, ...MENU_ITEMS.pane];
+}
+
+/** The overlay's border (1) + horizontal padding (1 each side). The header row
+ *  and every item row live INSIDE this frame. */
+const BORDER = 1;
+const PAD = 1;
+/** A minimum inner text width so a short menu still reads as a panel. */
+const MIN_INNER = 16;
+/** The suffix a destructive item rearms to (label + this). Reserved in the
+ *  width so "confirm: y" is never clipped — the render appends the SAME string. */
+export const CONFIRM_SUFFIX = "  confirm: y";
+/** The caret a `children` item renders flush-right ("› Layouts        ▸"): a
+ *  leading space + the glyph, reserved in the width so a submenu row's caret is
+ *  never clipped. The base "› " prefix (2) already sits on every row. */
+export const SUBMENU_CARET = " ▸";
+
+/** PURE — the overlay's cell dimensions for `title` + `items`. Width fits the
+ *  longest of the title and item rows (each item reserves 2 cells for the "› "
+ *  selection prefix); height is the top border + header + items + bottom border.
+ *  Item labels leave slack for the longer "confirm: y" / input renderings, which
+ *  never need to exceed the base width in practice. */
+export function menuDims(title: string, items: MenuItem[]): { width: number; height: number } {
+  const inner = Math.max(
+    MIN_INNER,
+    title.length,
+    // A danger item's rearmed "label  confirm: y" must fit; a `children` item
+    // reserves the "› " prefix AND the flush-right submenu caret; a `checkbox`
+    // item's ✓/✗ mark is the same width as the "› " prefix it replaces. Others
+    // reserve 2 cells for the "› " selection prefix.
+    ...items.map((it) => {
+      if (it.danger) return it.label.length + CONFIRM_SUFFIX.length;
+      if (it.children) return it.label.length + 2 + SUBMENU_CARET.length;
+      return it.label.length + 2;
+    }),
+  );
+  return { width: inner + PAD * 2 + BORDER * 2, height: items.length + 3 };
+}
+
+/** PURE — the on-screen top-left for a menu of `width`×`height` opened at
+ *  (`x`,`y`), clamped so the whole box stays on a `screenW`×`screenH` grid. */
+export function clampMenuPos(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  screenW: number,
+  screenH: number,
+): { left: number; top: number } {
+  const left = Math.max(0, Math.min(x, screenW - width));
+  const top = Math.max(0, Math.min(y, screenH - height));
+  return { left, top };
+}
+
+/** The placed overlay's geometry — what the hit-tests need. */
+export interface MenuGeom {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  itemCount: number;
+}
+
+/** PURE — the item index under (`x`,`y`), or -1 when the point is not on an item
+ *  row (the border, the header, or outside the box). Item `i` renders one row
+ *  below the top border + header, i.e. at screen y = top + 2 + i. */
+export function menuItemAt(m: MenuGeom, x: number, y: number): number {
+  if (x < m.left || x >= m.left + m.width) return -1;
+  const i = y - (m.top + BORDER + 1);
+  return i >= 0 && i < m.itemCount ? i : -1;
+}
+
+/** PURE — is (`x`,`y`) anywhere inside the overlay box (item, header, or border)?
+ *  A down INSIDE that isn't on an item is a no-op (menu stays); a down OUTSIDE
+ *  closes the menu. */
+export function pointInMenu(m: MenuGeom, x: number, y: number): boolean {
+  return x >= m.left && x < m.left + m.width && y >= m.top && y < m.top + m.height;
+}
+
+/** PURE — the on-screen top-left for the SUBMENU column that opens beside the
+ *  `parent` item at `parentItemIndex`. It opens to the RIGHT of the parent, its
+ *  top border aligned with the parent item's row, then clamps fully on-screen
+ *  (sliding left over the parent if the right edge would overflow — acceptable
+ *  since the keyboard/coordinate router owns whichever column is focused). */
+export function submenuPos(
+  parent: MenuGeom,
+  parentItemIndex: number,
+  width: number,
+  height: number,
+  screenW: number,
+  screenH: number,
+): { left: number; top: number } {
+  const x = parent.left + parent.width;
+  // The parent item renders at y = parent.top + BORDER + header(1) + index; put
+  // the submenu's top border on that same row so the columns read as connected.
+  const y = parent.top + BORDER + 1 + parentItemIndex;
+  return clampMenuPos(x, y, width, height, screenW, screenH);
+}