tmux-ide 2.6.0 → 2.7.0

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);
+}

package/packages/daemon/src/tui/mirror/palette.ts

@@ -0,0 +1,274 @@
+/**
+ * The command palette's action model (M18.4) — PURE so it unit-tests without
+ * OpenTUI. app.tsx opens a centered overlay (F5), feeds keystrokes to a query,
+ * and runs the selected {@link PaletteAction}; the DESCRIPTORS and the fuzzy
+ * filtering live here, the closures that actually attach/save/quit stay in the
+ * app (a `dispatch` switch over `action.kind`).
+ *
+ * Reuses {@link ../team/fuzzy.ts} for the same subsequence match the fleet
+ * quick-jump uses, so typing "ses" ranks "Attach session: …" the way a human
+ * expects. The dynamic "Open file: <query>" action is always offered when the
+ * query is non-empty (you can't fuzzy-match a path you're still typing), pinned
+ * to the top when the query looks like a path.
+ */
+import { fuzzyFilter } from "../team/fuzzy.ts";
+import type { Tab } from "./app-state.ts";
+import type { AgentRowInput } from "./agent-rows.ts";
+import { SETTINGS_PALETTE_COMMANDS, type SettingsCommandId } from "./settings-model.ts";
+
+/** One runnable palette entry. `label` is what the list shows and what the
+ *  fuzzy filter scores; `kind` (+ payload) is what the app dispatches on. */
+export type PaletteAction =
+  | { kind: "tab"; tab: Tab; label: string }
+  | { kind: "open-folder"; label: string }
+  | { kind: "attach"; session: string; label: string }
+  | { kind: "jump-agent"; paneId: string; session: string; windowIndex: number; label: string }
+  | { kind: "open-file"; path: string; label: string }
+  | { kind: "save"; label: string }
+  | { kind: "refresh-diff"; label: string }
+  | { kind: "paste-buffer"; label: string }
+  | { kind: "new-window"; label: string }
+  | { kind: "rename-window"; name: string; label: string }
+  | { kind: "kill-window"; label: string }
+  | { kind: "zoom-pane"; label: string }
+  | { kind: "swap-pane"; label: string }
+  | { kind: "break-pane"; label: string }
+  | { kind: "rotate-window"; label: string }
+  | { kind: "select-layout"; layout: string; label: string }
+  | { kind: "sync-toggle"; label: string }
+  | { kind: "select-text"; label: string }
+  | { kind: "resize-window"; label: string }
+  | { kind: "settings"; id: SettingsCommandId; label: string }
+  | { kind: "quit"; label: string };
+
+/** The five tmux `select-layout` presets, offered one palette action each so the
+ *  fuzzy filter finds "tiled" / "main-vertical" directly. Shared with the pane
+ *  context menu's Layouts submenu (menu-model). */
+export const LAYOUT_PRESETS = [
+  "even-horizontal",
+  "even-vertical",
+  "main-horizontal",
+  "main-vertical",
+  "tiled",
+] as const;
+
+/** Context the palette needs beyond the fuzzy query. `terminal` gates the
+ *  window/pane verbs (New/Rename/Kill window, Zoom pane) to the Terminal surface
+ *  — they are no-ops on Home/Files/Diff, so they only clutter the list there. */
+export interface PaletteContext {
+  terminal?: boolean;
+  /** The fleet's agents (M22.2) — the palette offers one "Agent: …" jump action
+   *  each, the keyboard twin of the sidebar's clickable agent rows. Already
+   *  sorted attention-first by the caller (fleetAgents). */
+  agents?: AgentRowInput[];
+  /** A co-attached terminal has sized the tmux window away from our canvas
+   *  (M22.8). Only then is the "Resize to fit this window" reclaim action worth
+   *  offering — otherwise it is a no-op that clutters the list. */
+  sizeMismatch?: boolean;
+  /** The focused pane's app turned mouse reporting on (M22.9) — only then is
+   *  "Select text in pane" offered (ordinary panes drag-select directly, so the
+   *  action would be a no-op that clutters the list). */
+  appMousePane?: boolean;
+}
+
+const TAB_LABELS: { tab: Tab; label: string }[] = [
+  { tab: "home", label: "Switch tab: Home" },
+  { tab: "terminal", label: "Switch tab: Terminal" },
+  { tab: "files", label: "Switch tab: Files" },
+  { tab: "diff", label: "Switch tab: Diff" },
+];
+
+/** PURE — the always-available static actions: the four tab switches, one
+ *  attach-session per fleet session, then Save / Refresh diff, the Terminal-only
+ *  window/pane verbs, and Quit. */
+export function staticPaletteActions(
+  sessions: string[],
+  ctx: PaletteContext = {},
+): PaletteAction[] {
+  const actions: PaletteAction[] = TAB_LABELS.map((t) => ({
+    kind: "tab" as const,
+    tab: t.tab,
+    label: t.label,
+  }));
+  // The non-technicals' front door (M22.5): a filesystem picker → create-or-
+  // attach a session in the chosen folder. Offered on every surface.
+  actions.push({ kind: "open-folder", label: "Open folder…" });
+  for (const s of sessions) {
+    actions.push({ kind: "attach", session: s, label: `Attach session: ${s}` });
+  }
+  // One jump per fleet agent (M22.2) — the sidebar rows' keyboard twin. Labeled
+  // "Agent: <kind> · <session> (<state>)" so the fuzzy filter finds it by kind,
+  // session, or state (typing "agent", "claude", or "blocked" all narrow to it).
+  for (const a of ctx.agents ?? []) {
+    actions.push({
+      kind: "jump-agent",
+      paneId: a.paneId,
+      session: a.session,
+      windowIndex: a.windowIndex,
+      label: `Agent: ${a.kind} · ${a.session} (${a.state})`,
+    });
+  }
+  actions.push({ kind: "save", label: "Save file" });
+  actions.push({ kind: "refresh-diff", label: "Refresh diff" });
+  // Paste target is the focused surface (a pane, or the editor buffer), so this
+  // is offered on every surface — selecting it opens a second-level list of the
+  // tmux paste buffers rather than dispatching directly.
+  actions.push({ kind: "paste-buffer", label: "Paste buffer…" });
+  // The SETTINGS category (M22.4) — every setting is a command; "Settings…" is
+  // the categorized umbrella over the same dialogs. Offered on every surface.
+  for (const c of SETTINGS_PALETTE_COMMANDS) {
+    actions.push({ kind: "settings", id: c.id, label: c.label });
+  }
+  if (ctx.terminal) {
+    actions.push({ kind: "new-window", label: "New window" });
+    actions.push({ kind: "kill-window", label: "Kill window" });
+    actions.push({ kind: "zoom-pane", label: "Zoom pane" });
+    actions.push({ kind: "swap-pane", label: "Swap pane with next" });
+    actions.push({ kind: "break-pane", label: "Break pane to window" });
+    actions.push({ kind: "rotate-window", label: "Rotate panes" });
+    actions.push({ kind: "sync-toggle", label: "Synchronize panes (toggle)" });
+    // Selection entry on app-mouse panes (M22.9) — the pane menu verb's
+    // keyboard twin, offered only where forwarding blocks a direct drag.
+    if (ctx.appMousePane) {
+      actions.push({ kind: "select-text", label: "Select text in pane" });
+    }
+    for (const layout of LAYOUT_PRESETS) {
+      actions.push({ kind: "select-layout", layout, label: `Layout: ${layout}` });
+    }
+    // Only when a co-attached terminal is dictating the window size — the reclaim
+    // is a no-op otherwise, and we never fight the other terminal unasked.
+    if (ctx.sizeMismatch) {
+      actions.push({ kind: "resize-window", label: "Resize to fit this window" });
+    }
+  }
+  actions.push({ kind: "quit", label: "Quit" });
+  return actions;
+}
+
+/** One tmux paste buffer for the picker: its `name` (e.g. `buffer0`) and a
+ *  short, control-char-sanitized `preview` of its content. */
+export interface TmuxBuffer {
+  name: string;
+  preview: string;
+}
+
+/**
+ * PURE — parse `list-buffers -F "#{buffer_name}\t#{buffer_sample}"` reply lines
+ * into pickable buffers. The sample is truncated to `previewLen` chars and any
+ * control characters (tabs/newlines that survived a sample, C0 bytes) collapse
+ * to a middle-dot so one buffer stays one clean row. Nameless/blank lines drop.
+ */
+export function parseBufferList(lines: readonly string[], previewLen = 40): TmuxBuffer[] {
+  const out: TmuxBuffer[] = [];
+  for (const raw of lines) {
+    if (!raw) continue;
+    const tab = raw.indexOf("\t");
+    const name = (tab === -1 ? raw : raw.slice(0, tab)).trim();
+    if (!name) continue;
+    const sample = tab === -1 ? "" : raw.slice(tab + 1);
+    const preview = sample
+      .slice(0, previewLen)
+      // eslint-disable-next-line no-control-regex
+      .replace(/[\x00-\x1f\x7f]/g, "·");
+    out.push({ name, preview });
+  }
+  return out;
+}
+
+// ── Overlay geometry (M21.9 — palette mouse support) ────────────────────────
+// The palette overlay is app-rendered (a centered <box border paddingLeft=1>),
+// so its full geometry is knowable by pure math. These helpers are shared by
+// the RENDER (placement) and the central mouse ROUTER (row hit-test / inside-
+// vs-outside), so a click can never land where a row isn't drawn. Layout, in
+// screen rows from `top`: border (top+0) · input/header line (top+1) · rule
+// (top+2) · result rows (top+3 …) · an optional "no matches" row when empty ·
+// border. Rows span the box interior in x: [left+1, left+width-1).
+
+/** Rows of chrome above the first result row: top border + input line + rule. */
+export const PALETTE_HEADER_ROWS = 3;
+
+/** The palette box geometry the router hit-tests: the placed box plus how many
+ *  result rows are currently visible (min(count - top, pageRows)). */
+export interface PaletteGeom {
+  left: number;
+  top: number;
+  width: number;
+  /** Result rows on screen right now (0 when the list is empty). */
+  visibleRows: number;
+}
+
+/** PURE — the overlay's placement for a terminal size: horizontally centered,
+ *  top at a sixth of the height (min 1 — below the surface tab bar). MUST match
+ *  the render's `left`/`top` props (the render calls this). */
+export function palettePos(
+  termW: number,
+  termH: number,
+  width: number,
+): { left: number; top: number } {
+  return {
+    left: Math.max(0, Math.floor((termW - width) / 2)),
+    top: Math.max(1, Math.floor(termH / 6)),
+  };
+}
+
+/** PURE — total box height for `visibleRows` results: header chrome + the rows
+ *  (an empty list still shows one "no matches"/"no buffers" row) + the bottom
+ *  border. Used for inside/outside containment. */
+export function paletteHeight(visibleRows: number): number {
+  return PALETTE_HEADER_ROWS + Math.max(1, visibleRows) + 1;
+}
+
+/** PURE — the VISIBLE result-row index under (x, y), or -1. Only real rows hit
+ *  (the "no matches" placeholder row is not clickable); x must be inside the
+ *  box interior (borders excluded). */
+export function paletteRowAt(g: PaletteGeom, x: number, y: number): number {
+  if (x < g.left + 1 || x >= g.left + g.width - 1) return -1;
+  const row = y - (g.top + PALETTE_HEADER_ROWS);
+  return row >= 0 && row < g.visibleRows ? row : -1;
+}
+
+/** PURE — whether (x, y) falls anywhere on the palette box (border included).
+ *  A press outside dismisses the overlay; inside-but-not-a-row is a no-op. */
+export function paletteContains(g: PaletteGeom, x: number, y: number): boolean {
+  return (
+    x >= g.left && x < g.left + g.width && y >= g.top && y < g.top + paletteHeight(g.visibleRows)
+  );
+}
+
+/** PURE — clamp a wheel-scrolled list top into [0, count - pageRows]. */
+export function clampPaletteTop(top: number, count: number, pageRows: number): number {
+  return Math.max(0, Math.min(top, count - pageRows));
+}
+
+/** A typed query "looks like a path" when it carries a separator or dot — then
+ *  the Open-file action is worth pinning to the top of the results. */
+function looksLikePath(q: string): boolean {
+  return /[/.~]/.test(q);
+}
+
+/**
+ * PURE — the palette result list for `query`: the static actions fuzzy-filtered
+ * and score-sorted, plus (when the query is non-empty) a dynamic
+ * "Open file: <query>" action. That open-file entry is pinned FIRST when the
+ * query looks like a path, otherwise appended LAST so it never buries a real
+ * match. An empty query returns every static action in natural order.
+ */
+export function filterPaletteActions(
+  query: string,
+  sessions: string[],
+  ctx: PaletteContext = {},
+): PaletteAction[] {
+  const statics = staticPaletteActions(sessions, ctx);
+  const q = query.trim();
+  const matched =
+    q.length === 0 ? statics : fuzzyFilter(query, statics, (a) => a.label).map((m) => m.item);
+  if (q.length === 0) return matched;
+  const dynamic: PaletteAction[] = [{ kind: "open-file", path: q, label: `Open file: ${q}` }];
+  // On the Terminal surface a non-empty query also offers a rename-to-<query>
+  // window verb (there is no way to fuzzy-match a name you are still typing —
+  // same reasoning as the open-file entry).
+  if (ctx.terminal) {
+    dynamic.push({ kind: "rename-window", name: q, label: `Rename window: ${q}` });
+  }
+  return looksLikePath(q) ? [...dynamic, ...matched] : [...matched, ...dynamic];
+}