tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/tui/chrome/events.d.ts

@@ -0,0 +1,51 @@
+import type { AgentStatus } from "../detect/classify.ts";
+/** A single session-level status transition. `from` is null the first time a session is seen. */
+export interface AgentEvent {
+    ts: string;
+    session: string;
+    from: AgentStatus | null;
+    to: AgentStatus;
+}
+/** A transition before it's been stamped with a timestamp (what {@link diffFleet} emits). */
+export type AgentEventInit = Omit<AgentEvent, "ts">;
+/** Rotate the log once it grows past this many bytes (crude one-generation rotation). */
+export declare const EVENTS_MAX_BYTES: number;
+/**
+ * PURE — diff the previous fleet state against the current one.
+ *
+ * For each session in `next` we emit a transition when its status changed, and
+ * a first-sight event (`from: null`) the first time we see it. A session that
+ * DISAPPEARS from `next` emits NOTHING — we don't synthesize an `idle`/gone
+ * event, we just drop it from the returned `state` (keeps the log honest: an
+ * absent session simply stops producing events until it returns).
+ *
+ * Returns both the new events and the fresh state map to thread into the next
+ * tick. The caller stamps `ts` on the events (see {@link appendEvents}).
+ */
+export declare function diffFleet(prev: Map<string, AgentStatus>, next: Array<{
+    name: string;
+    status: AgentStatus;
+}>): {
+    events: AgentEventInit[];
+    state: Map<string, AgentStatus>;
+};
+/** PURE — whether a log of `sizeBytes` is due for rotation. */
+export declare function shouldRotate(sizeBytes: number): boolean;
+/**
+ * PURE — render one event for the human-readable `tmux-ide events` view, e.g.
+ * `12:31:07 prototyper-platform working → done`. First-sight events (from=null)
+ * render the origin as `·`. `paint` colors a status token (defaults to
+ * identity so tests get plain text); the CLI passes an ANSI painter.
+ */
+export declare function formatEventLine(ev: AgentEvent, paint?: (status: AgentStatus | null, text: string) => string): string;
+/** Absolute path to the fleet event log (under the `TMUX_IDE_HOME`-aware home). */
+export declare function eventsPath(): string;
+/**
+ * io — stamp each event with `now()` and append it to the log as JSONL.
+ *
+ * Before appending, rotates the log to `events.jsonl.1` (overwriting any prior
+ * generation) when it's grown past {@link EVENTS_MAX_BYTES}. Best-effort: a
+ * filesystem failure must never break the updater loop, so every step is
+ * guarded. No-op when there are no events.
+ */
+export declare function appendEvents(events: AgentEventInit[], now?: () => string): void;

package/packages/daemon/dist/tui/chrome/events.js

@@ -0,0 +1,94 @@
+/**
+ * Agent-state TRANSITION event log — the fleet's history layer.
+ *
+ * The chrome {@link ./updater.ts updater} sees every session's status EACH
+ * tick, but a status bar is a snapshot: it can't tell you that
+ * `prototyper-platform` went `working → done` at 12:31. This module turns the
+ * per-tick fleet into a stream of transition events and appends them to a
+ * JSONL log that `tmux-ide events` tails.
+ *
+ * Split as usual: {@link diffFleet} + {@link formatEventLine} +
+ * {@link shouldRotate} are PURE (unit-tested without a filesystem), while
+ * {@link appendEvents} is the thin io wrapper that stamps `ts`, rotates the
+ * file, and appends.
+ */
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stateHome } from "../../lib/state-home.js";
+/** Rotate the log once it grows past this many bytes (crude one-generation rotation). */
+export const EVENTS_MAX_BYTES = 1024 * 1024;
+/**
+ * PURE — diff the previous fleet state against the current one.
+ *
+ * For each session in `next` we emit a transition when its status changed, and
+ * a first-sight event (`from: null`) the first time we see it. A session that
+ * DISAPPEARS from `next` emits NOTHING — we don't synthesize an `idle`/gone
+ * event, we just drop it from the returned `state` (keeps the log honest: an
+ * absent session simply stops producing events until it returns).
+ *
+ * Returns both the new events and the fresh state map to thread into the next
+ * tick. The caller stamps `ts` on the events (see {@link appendEvents}).
+ */
+export function diffFleet(prev, next) {
+    const state = new Map();
+    const events = [];
+    for (const { name, status } of next) {
+        const before = prev.has(name) ? prev.get(name) : null;
+        state.set(name, status);
+        if (before === null) {
+            events.push({ session: name, from: null, to: status });
+        }
+        else if (before !== status) {
+            events.push({ session: name, from: before, to: status });
+        }
+    }
+    return { events, state };
+}
+/** PURE — whether a log of `sizeBytes` is due for rotation. */
+export function shouldRotate(sizeBytes) {
+    return sizeBytes > EVENTS_MAX_BYTES;
+}
+/** Extract `HH:MM:SS` from an ISO-8601 timestamp (UTC); falls back to the raw string. */
+function isoTime(ts) {
+    const m = /T(\d{2}:\d{2}:\d{2})/.exec(ts);
+    return m ? m[1] : ts;
+}
+/**
+ * PURE — render one event for the human-readable `tmux-ide events` view, e.g.
+ * `12:31:07 prototyper-platform working → done`. First-sight events (from=null)
+ * render the origin as `·`. `paint` colors a status token (defaults to
+ * identity so tests get plain text); the CLI passes an ANSI painter.
+ */
+export function formatEventLine(ev, paint = (_s, t) => t) {
+    const from = ev.from === null ? "·" : paint(ev.from, ev.from);
+    return `${isoTime(ev.ts)} ${ev.session} ${from} → ${paint(ev.to, ev.to)}`;
+}
+/** Absolute path to the fleet event log (under the `TMUX_IDE_HOME`-aware home). */
+export function eventsPath() {
+    return join(stateHome(), "events.jsonl");
+}
+/**
+ * io — stamp each event with `now()` and append it to the log as JSONL.
+ *
+ * Before appending, rotates the log to `events.jsonl.1` (overwriting any prior
+ * generation) when it's grown past {@link EVENTS_MAX_BYTES}. Best-effort: a
+ * filesystem failure must never break the updater loop, so every step is
+ * guarded. No-op when there are no events.
+ */
+export function appendEvents(events, now = () => new Date().toISOString()) {
+    if (events.length === 0)
+        return;
+    const path = eventsPath();
+    try {
+        mkdirSync(stateHome(), { recursive: true });
+        if (existsSync(path) && shouldRotate(statSync(path).size)) {
+            renameSync(path, `${path}.1`);
+        }
+        const ts = now();
+        const lines = events.map((e) => `${JSON.stringify({ ts, ...e })}\n`).join("");
+        appendFileSync(path, lines);
+    }
+    catch {
+        // Stale/failed log write just means a gap in history — never fatal.
+    }
+}

package/packages/daemon/dist/tui/chrome/front-door.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The chrome front door (M25.1) — the tiny, LEAF constants + argv builders the
+ * unified app needs to get a session watched without importing the chrome/data
+ * graph (app.tsx deliberately never imports the sync fleet-scan modules that
+ * {@link ./updater.ts} pulls in; see the FleetSession note there).
+ *
+ * "Watched" means: stamped with {@link ADOPTED_OPTION} so the background
+ * updater enumerates it (VERIFIED inert for a session that never ran `adopt` —
+ * none of adopt's status-row/border options are set, so the updater's status/
+ * chip var writes land on options nothing reads), and the updater itself
+ * ensured up. The sync twin of that flow lives in `updater.ts`
+ * (`startUpdaterIfNeeded`); the app uses these argvs with async execFile (the
+ * render-loop law).
+ */
+export { ADOPTED_OPTION, UPDATER_SESSION, adoptMarkArgv, updaterProbeArgv, updaterSpawnArgv, } from "../../lib/chrome-front-door.ts";
+export { PANE_CHROME_BORDER_FORMAT, PANE_CHROME_CHIP_OPTION as CHIP_OPTION, } from "../../lib/pane-chrome.ts";

package/packages/daemon/dist/tui/chrome/front-door.js

@@ -0,0 +1,16 @@
+/**
+ * The chrome front door (M25.1) — the tiny, LEAF constants + argv builders the
+ * unified app needs to get a session watched without importing the chrome/data
+ * graph (app.tsx deliberately never imports the sync fleet-scan modules that
+ * {@link ./updater.ts} pulls in; see the FleetSession note there).
+ *
+ * "Watched" means: stamped with {@link ADOPTED_OPTION} so the background
+ * updater enumerates it (VERIFIED inert for a session that never ran `adopt` —
+ * none of adopt's status-row/border options are set, so the updater's status/
+ * chip var writes land on options nothing reads), and the updater itself
+ * ensured up. The sync twin of that flow lives in `updater.ts`
+ * (`startUpdaterIfNeeded`); the app uses these argvs with async execFile (the
+ * render-loop law).
+ */
+export { ADOPTED_OPTION, UPDATER_SESSION, adoptMarkArgv, updaterProbeArgv, updaterSpawnArgv, } from "../../lib/chrome-front-door.js";
+export { PANE_CHROME_BORDER_FORMAT, PANE_CHROME_CHIP_OPTION as CHIP_OPTION, } from "../../lib/pane-chrome.js";

package/packages/daemon/dist/tui/chrome/kitty-keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Kitty-keyboard-protocol fallback binds for the root-table Alt keys.
+ *
+ * Claude Code enables the Kitty keyboard protocol with event-type reporting.
+ * Under it, the FOCUSED pane's terminal encodes e.g. Alt-m not as the legacy
+ * `ESC m` but as the CSI-u form `ESC[109;3:1u` (109 = 'm', 3 = the Alt modifier,
+ * `:1` = a key-PRESS event-type subparameter). tmux 3.6 does NOT normalize that
+ * `:1`-carrying full form back to `M-m`, so a root-table `bind-key -n M-m` never
+ * fires while a Claude Code pane is focused — every dock shortcut (⌥m/⌥p/⌥k/⌥b/
+ * ⌥e/⌥g/⌥,/⌥h) goes dead. Plain `ESC m` and the basic CSI-u `ESC[109;3u` both
+ * DO reach tmux as `M-m`; only the `:1` full form misses (proven live by
+ * injecting each encoding into a nested client).
+ *
+ * The fix is a tmux USER-KEY fallback per Alt bind: teach tmux the exact kitty
+ * escape as `user-keys[N]`, then bind `UserN` to the SAME action argv as the
+ * `M-…` key. tmux matches the raw escape against the user-key and fires the
+ * bind, so the shortcut works whether the focused pane speaks legacy or full
+ * kitty. Registering the fallback is harmless for panes that never send the
+ * `:1` form (nothing else emits `UserN`).
+ *
+ * Pure — tested as a table; the io (registering the binds) lives in
+ * {@link ./statusline.ts}.
+ */
+/**
+ * PURE — the full-kitty key-PRESS encoding for a single-char Alt key (`M-<c>`),
+ * or `null` for anything else (multi-char key names, non-Alt keys — they don't
+ * get a fallback). The sequence is `ESC[<code>;3:1u` where `<code>` is the code
+ * point of the (lowercased) character, `3` is the Alt modifier, and `:1` is the
+ * key-press event-type subparameter. Examples: `M-m` → `ESC[109;3:1u`, `M-h` →
+ * `ESC[104;3:1u`, `M-,` → `ESC[44;3:1u`.
+ */
+export declare function kittyEscapeFor(key: string): string | null;
+/**
+ * PURE — the tmux `user-keys` array index for the Nth Alt fallback. We claim the
+ * range `[100, …)` (offset 100) so we never clobber a user's own
+ * `user-keys[0..]` entries — anyone hand-setting `user-keys` should keep their
+ * indices below 100.
+ */
+export declare function kittyUserKeyIndex(slot: number): number;
+/** PURE — the tmux key name a `user-keys[idx]` entry surfaces as (`UserN`). */
+export declare function kittyUserKeyName(slot: number): string;

package/packages/daemon/dist/tui/chrome/kitty-keys.js

@@ -0,0 +1,54 @@
+/**
+ * Kitty-keyboard-protocol fallback binds for the root-table Alt keys.
+ *
+ * Claude Code enables the Kitty keyboard protocol with event-type reporting.
+ * Under it, the FOCUSED pane's terminal encodes e.g. Alt-m not as the legacy
+ * `ESC m` but as the CSI-u form `ESC[109;3:1u` (109 = 'm', 3 = the Alt modifier,
+ * `:1` = a key-PRESS event-type subparameter). tmux 3.6 does NOT normalize that
+ * `:1`-carrying full form back to `M-m`, so a root-table `bind-key -n M-m` never
+ * fires while a Claude Code pane is focused — every dock shortcut (⌥m/⌥p/⌥k/⌥b/
+ * ⌥e/⌥g/⌥,/⌥h) goes dead. Plain `ESC m` and the basic CSI-u `ESC[109;3u` both
+ * DO reach tmux as `M-m`; only the `:1` full form misses (proven live by
+ * injecting each encoding into a nested client).
+ *
+ * The fix is a tmux USER-KEY fallback per Alt bind: teach tmux the exact kitty
+ * escape as `user-keys[N]`, then bind `UserN` to the SAME action argv as the
+ * `M-…` key. tmux matches the raw escape against the user-key and fires the
+ * bind, so the shortcut works whether the focused pane speaks legacy or full
+ * kitty. Registering the fallback is harmless for panes that never send the
+ * `:1` form (nothing else emits `UserN`).
+ *
+ * Pure — tested as a table; the io (registering the binds) lives in
+ * {@link ./statusline.ts}.
+ */
+/**
+ * PURE — the full-kitty key-PRESS encoding for a single-char Alt key (`M-<c>`),
+ * or `null` for anything else (multi-char key names, non-Alt keys — they don't
+ * get a fallback). The sequence is `ESC[<code>;3:1u` where `<code>` is the code
+ * point of the (lowercased) character, `3` is the Alt modifier, and `:1` is the
+ * key-press event-type subparameter. Examples: `M-m` → `ESC[109;3:1u`, `M-h` →
+ * `ESC[104;3:1u`, `M-,` → `ESC[44;3:1u`.
+ */
+export function kittyEscapeFor(key) {
+    const m = /^M-(.)$/.exec(key);
+    const ch = m?.[1];
+    if (ch === undefined)
+        return null;
+    const code = ch.toLowerCase().codePointAt(0);
+    if (code === undefined)
+        return null;
+    return `\x1b[${code};3:1u`;
+}
+/**
+ * PURE — the tmux `user-keys` array index for the Nth Alt fallback. We claim the
+ * range `[100, …)` (offset 100) so we never clobber a user's own
+ * `user-keys[0..]` entries — anyone hand-setting `user-keys` should keep their
+ * indices below 100.
+ */
+export function kittyUserKeyIndex(slot) {
+    return 100 + slot;
+}
+/** PURE — the tmux key name a `user-keys[idx]` entry surfaces as (`UserN`). */
+export function kittyUserKeyName(slot) {
+    return `User${kittyUserKeyIndex(slot)}`;
+}

package/packages/daemon/dist/tui/chrome/menu.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The tmux-ide right-click actions menu — native chrome.
+ *
+ * Right-clicking the chrome row (or pressing `⌥m` on an adopted session) floats
+ * tmux's own `display-menu`: a small popup of tmux-ide actions (switch session,
+ * cheat sheet, jump to any live session, new session, kill session). tmux draws
+ * the whole thing — there is no OpenTUI/bun boot and no per-tick cost — so this
+ * module only produces the argument vector.
+ *
+ * The menu content is LIVE (the session list changes), so it can't be baked into
+ * a static bind. Instead the bind runs our CLI via `run-shell`, and the CLI
+ * rebuilds the menu args fresh and hands them to `tmux display-menu -c <client>`
+ * (see the `menu` case in bin/cli.ts). This mirrors how the switcher/cheat-sheet
+ * popups defer their content to a fresh CLI invocation.
+ *
+ * `buildMenu` and the bind/unbind command builders are PURE (tested); the CLI
+ * `menu` command wires the io (resolve the client, run display-menu).
+ */
+import { type AppTheme } from "../../lib/app-config.ts";
+import type { AgentStatus } from "../detect/classify.ts";
+import { MENU_KEY, MENU_PANE_KEY, MENU_STATUS_KEY } from "./statusline.ts";
+import type { UpdateStatus } from "../../lib/update-check.ts";
+/**
+ * Quote a session name for embedding in a tmux command string (the target of a
+ * menu item's `switch-client -t <name>`). Single-quote it and escape any embedded
+ * single quote the shell way (`'\''`) — tmux's lexer builds words like the shell,
+ * so this keeps a weird name (spaces, `;`, `#`, `$`) inert instead of leaking as
+ * extra command tokens. Verified live on tmux 3.6.
+ */
+export declare function menuQuoteName(name: string): string;
+/**
+ * PURE — the `display-menu` argument vector (everything AFTER `display-menu`,
+ * minus the runtime `-c <client>`/placement flags the CLI prepends): a
+ * `tmux-ide` title, then four groups joined by separator lines —
+ *
+ *   1. `⌂ Home cockpit` (h) → the same home popup M-h / the bar trigger opens;
+ *      `⧉ Switch session…` (s) → the same switcher popup M-p / the bar trigger
+ *      opens; `? Cheat sheet` (k) → the same cheat-sheet popup M-k opens. All
+ *      reuse the exact popup command strings so a menu pick behaves identically.
+ *   2. the widget PANELS (Files e / Changes g / Config ,) → the same floating
+ *      `display-popup` each panel's root-table key opens (see ./panels.ts).
+ *   3. up to 8 live sessions, each `«glyph» <name>` keyed 1..8 →
+ *      `switch-client -t <name>` (the name quoted so odd names stay inert). The
+ *      menu commands run in the client that opened the menu, so the switch lands
+ *      on the right client.
+ *   4. `＋ New session…` (n) → a `command-prompt` that creates + switches to a
+ *      named session; `✕ Kill this session` (x) → a confirmed `kill-session`.
+ *
+ * A separator is a single empty-string argument (tmux's display-menu convention).
+ * Empty groups (no sessions) collapse so two separators never stack.
+ */
+export declare function buildMenu(sessions: Array<{
+    name: string;
+    status: AgentStatus;
+}>, theme?: AppTheme, update?: UpdateStatus): string[];
+export { MENU_KEY, MENU_PANE_KEY, MENU_STATUS_KEY };
+/**
+ * PURE — the `display-menu` position flags (`-x <n> -y <n>`) for a click at
+ * `(x, y)`, or `[]` when either coord is absent or non-numeric (the keyboard
+ * path, or an unexpanded `#{mouse_*}` literal) so tmux falls back to centering.
+ * `-x` is the menu's LEFT edge; `-y` is the menu's BOTTOM edge on tmux 3.6, so
+ * the pointer coords put the menu just above-right of the click.
+ */
+export declare function menuPositionArgs(x: string | undefined, y: string | undefined): string[];
+/**
+ * PURE — the tmux argv that binds {@link MENU_KEY} (`M-m`, root table) to open
+ * the actions menu. Server-wide bind, mirroring the switcher's M-p — see the note
+ * on `unadoptSession`.
+ */
+export declare function menuBindCommand(menuCmd?: string, key?: string): string[];
+/**
+ * PURE — the tmux argv that binds a RIGHT-click on the chrome row
+ * ({@link MENU_STATUS_KEY}) to open the same actions menu. Unlike the left-click
+ * router this is range-independent: a right-click anywhere on the bar opens the
+ * menu, so the session-list content is what matters, not the click target.
+ */
+export declare function menuStatusBindCommand(menuCmd?: string): string[];
+/**
+ * PURE — the tmux argv that binds a RIGHT-click on ANY pane body
+ * ({@link MENU_PANE_KEY}) to open the same actions menu, so the menu is reachable
+ * everywhere, not only from the dock row. Forwards the click position (see
+ * {@link menuPaneMouseRunShellArgs}) so the menu opens at the pointer. Panes whose app
+ * captures the mouse (vim, agent TUIs) eat the event — graceful degradation,
+ * `M-m` still works there.
+ */
+export declare function menuPaneBindCommand(menuCmd?: string): string[];
+/** PURE — the tmux argv that removes the {@link MENU_KEY} binding. */
+export declare function menuUnbindCommand(key?: string): string[];
+/** PURE — the tmux argv that removes the {@link MENU_STATUS_KEY} binding. */
+export declare function menuStatusUnbindCommand(): string[];
+/** PURE — the tmux argv that removes the {@link MENU_PANE_KEY} binding. */
+export declare function menuPaneUnbindCommand(): string[];

package/packages/daemon/dist/tui/chrome/menu.js

@@ -0,0 +1,251 @@
+/**
+ * The tmux-ide right-click actions menu — native chrome.
+ *
+ * Right-clicking the chrome row (or pressing `⌥m` on an adopted session) floats
+ * tmux's own `display-menu`: a small popup of tmux-ide actions (switch session,
+ * cheat sheet, jump to any live session, new session, kill session). tmux draws
+ * the whole thing — there is no OpenTUI/bun boot and no per-tick cost — so this
+ * module only produces the argument vector.
+ *
+ * The menu content is LIVE (the session list changes), so it can't be baked into
+ * a static bind. Instead the bind runs our CLI via `run-shell`, and the CLI
+ * rebuilds the menu args fresh and hands them to `tmux display-menu -c <client>`
+ * (see the `menu` case in bin/cli.ts). This mirrors how the switcher/cheat-sheet
+ * popups defer their content to a fresh CLI invocation.
+ *
+ * `buildMenu` and the bind/unbind command builders are PURE (tested); the CLI
+ * `menu` command wires the io (resolve the client, run display-menu).
+ */
+import { DEFAULT_THEME } from "../../lib/app-config.js";
+import { switcherPopupCommand, homePopupCommand, updatePopupCommand, MENU_KEY, MENU_PANE_KEY, MENU_STATUS_KEY, } from "./statusline.js";
+import { cheatsheetPopupCommand } from "./cheatsheet.js";
+import { PANEL_POPUPS, panelPopupCommand } from "./panels.js";
+/** Single-char menu mnemonics for the panel rows (parallel to PANEL_POPUPS). */
+const PANEL_MENU_KEYS = ["e", "g", ","];
+/**
+ * PURE — glyph + tmux colour per status for the menu's session rows, from the
+ * shared theme tokens. Colours are `theme.status.*` (working amber, blocked red,
+ * done blue, idle green). `idle` uses the hollow `inactive` glyph so a quiet
+ * session reads as "nothing running" at a glance; `unknown` uses the `·` "no
+ * signal" marker; everything else the filled `active` glyph.
+ */
+function menuGlyph(status, theme) {
+    const glyph = status === "idle" ? theme.glyphs.inactive : status === "unknown" ? "·" : theme.glyphs.active;
+    return { glyph, colour: theme.status[status] };
+}
+/** Max session rows the menu lists (keys 1..8). Extra sessions are dropped. */
+const MAX_SESSION_ITEMS = 8;
+/**
+ * Quote a session name for embedding in a tmux command string (the target of a
+ * menu item's `switch-client -t <name>`). Single-quote it and escape any embedded
+ * single quote the shell way (`'\''`) — tmux's lexer builds words like the shell,
+ * so this keeps a weird name (spaces, `;`, `#`, `$`) inert instead of leaking as
+ * extra command tokens. Verified live on tmux 3.6.
+ */
+export function menuQuoteName(name) {
+    return `'${name.replace(/'/g, `'\\''`)}'`;
+}
+/** The styled `#[fg=…]glyph#[default] name` label for a session row. */
+function sessionLabel(session, theme) {
+    const g = menuGlyph(session.status, theme);
+    return `#[fg=${g.colour}]${g.glyph}#[default] ${session.name}`;
+}
+/**
+ * PURE — the `display-menu` argument vector (everything AFTER `display-menu`,
+ * minus the runtime `-c <client>`/placement flags the CLI prepends): a
+ * `tmux-ide` title, then four groups joined by separator lines —
+ *
+ *   1. `⌂ Home cockpit` (h) → the same home popup M-h / the bar trigger opens;
+ *      `⧉ Switch session…` (s) → the same switcher popup M-p / the bar trigger
+ *      opens; `? Cheat sheet` (k) → the same cheat-sheet popup M-k opens. All
+ *      reuse the exact popup command strings so a menu pick behaves identically.
+ *   2. the widget PANELS (Files e / Changes g / Config ,) → the same floating
+ *      `display-popup` each panel's root-table key opens (see ./panels.ts).
+ *   3. up to 8 live sessions, each `«glyph» <name>` keyed 1..8 →
+ *      `switch-client -t <name>` (the name quoted so odd names stay inert). The
+ *      menu commands run in the client that opened the menu, so the switch lands
+ *      on the right client.
+ *   4. `＋ New session…` (n) → a `command-prompt` that creates + switches to a
+ *      named session; `✕ Kill this session` (x) → a confirmed `kill-session`.
+ *
+ * A separator is a single empty-string argument (tmux's display-menu convention).
+ * Empty groups (no sessions) collapse so two separators never stack.
+ */
+export function buildMenu(sessions, theme = DEFAULT_THEME, update) {
+    // When an update is pending, lead with a highlighted row that opens the same
+    // update popup the dock's `⬆ v<latest>` chip does. Its own group so it reads
+    // as a callout above the navigation actions.
+    const updateItems = update?.updateAvailable && update.latest
+        ? [`#[fg=${theme.accent}]⬆ Update available (v${update.latest})`, "u", updatePopupCommand()]
+        : [];
+    const header = [
+        "⌂ Home cockpit",
+        "h",
+        homePopupCommand(),
+        "⧉ Switch session…",
+        "s",
+        switcherPopupCommand(),
+        "? Cheat sheet",
+        "k",
+        cheatsheetPopupCommand(),
+        "▏ Toggle sidebar",
+        "b",
+        // run-shell format-expands #{session_name}, so the toggle targets whatever
+        // session the opening client is viewing (bind args don't expand; run-shell
+        // does — the same trick the menu bind itself uses).
+        `run-shell "tmux-ide sidebar-toggle --session '#{session_name}'"`,
+    ];
+    // The widget panels — each row opens the same floating popup its root-table
+    // key does (esc/q closes). Menu commands run in the opening client, so the
+    // popup lands on its pane's cwd.
+    const panelItems = [];
+    PANEL_POPUPS.forEach((panel, i) => {
+        panelItems.push(panel.label, PANEL_MENU_KEYS[i] ?? "", panelPopupCommand(panel));
+    });
+    const sessionItems = [];
+    sessions.slice(0, MAX_SESSION_ITEMS).forEach((session, i) => {
+        sessionItems.push(sessionLabel(session, theme), String(i + 1), `switch-client -t ${menuQuoteName(session.name)}`);
+    });
+    const footer = [
+        "＋ New session…",
+        "n",
+        `command-prompt -p "new session name:" "new-session -d -s '%%' ; switch-client -t '%%'"`,
+        "⎇ New worktree…",
+        "w",
+        // Prompt for a branch, then create a git worktree + session for it. The
+        // command-prompt template is SINGLE-quoted so the inner run-shell arg can be
+        // DOUBLE-quoted — run-shell only format-expands #{session_name} inside double
+        // quotes (single quotes suppress it). `%%` is command-prompt's branch
+        // substitution; --session carries the current session so the CLI resolves the
+        // repo from its cwd (run-shell's own cwd is the tmux server's, not the pane's).
+        // Quoting verified live on tmux 3.6 with branch `feat/x-1`.
+        `command-prompt -p "worktree branch:" 'run-shell "tmux-ide worktree create %% --session #{session_name}"'`,
+        "✕ Kill this session",
+        "x",
+        `confirm-before -p "kill session #S? (y/n)" kill-session`,
+    ];
+    // Join non-empty groups with a single separator line between them.
+    const items = [];
+    for (const group of [updateItems, header, panelItems, sessionItems, footer]) {
+        if (group.length === 0)
+            continue;
+        if (items.length > 0)
+            items.push(""); // separator
+        items.push(...group);
+    }
+    return ["-T", "tmux-ide", ...items];
+}
+// Re-export the key constants (defined in statusline.ts alongside POPUP_KEY so
+// the cheat sheet can list them without importing this module) for callers that
+// reach for them via the menu module.
+export { MENU_KEY, MENU_PANE_KEY, MENU_STATUS_KEY };
+/**
+ * The tmux command run by every menu bind: invoke our CLI to (re)build and show
+ * the menu. `run-shell` format-expands `#{client_name}` into `--client` (bind
+ * args themselves do NOT expand; run-shell DOES — verified live on tmux 3.6), and
+ * `-b` detaches so tmux's key/mouse dispatch isn't blocked while the menu is open.
+ * The CLI resolves the client from `--client`, falling back to the
+ * most-recently-active attached client, and runs display-menu (all tmux calls
+ * time-capped so the bind can never hang).
+ */
+function menuRunShellArgs(menuCmd) {
+    return ["run-shell", "-b", `${menuCmd} --client '#{client_name}'`];
+}
+/**
+ * Like {@link menuRunShellArgs} but for a PANE mouse bind: forwards the click
+ * position, only knowable at fire time inside the mouse binding.
+ *
+ * Coordinate model (measured live on tmux 3.6):
+ *  - `#{mouse_x}`/`#{mouse_y}` are PANE-RELATIVE for pane mouse events — the
+ *    screen position is `pane_left + mouse_x` / `pane_top + mouse_y`, computed
+ *    in the bind string itself with tmux format arithmetic (`#{e|+:…}`).
+ *  - `display-menu -y` is the menu's BOTTOM edge, so passing the pointer row
+ *    opens the menu upward from the click (tmux clamps/flips near edges).
+ * Keyboard binds (M-m) deliberately stay coordless — centered is right when
+ * there's no pointer.
+ */
+function menuPaneMouseRunShellArgs(menuCmd) {
+    return [
+        "run-shell",
+        "-b",
+        `${menuCmd} --client '#{client_name}' --x '#{e|+:#{pane_left},#{mouse_x}}' --y '#{e|+:#{pane_top},#{mouse_y}}'`,
+    ];
+}
+/**
+ * Status-line (dock) variant: status mouse events carry no pane and their
+ * `#{mouse_x}` is already the screen column. The dock sits at the bottom, so
+ * `#{client_height}` as the bottom edge opens the menu directly ABOVE the dock
+ * at the clicked column.
+ */
+function menuStatusMouseRunShellArgs(menuCmd) {
+    return [
+        "run-shell",
+        "-b",
+        `${menuCmd} --client '#{client_name}' --x '#{mouse_x}' --y '#{client_height}'`,
+    ];
+}
+/**
+ * PURE — the `display-menu` position flags (`-x <n> -y <n>`) for a click at
+ * `(x, y)`, or `[]` when either coord is absent or non-numeric (the keyboard
+ * path, or an unexpanded `#{mouse_*}` literal) so tmux falls back to centering.
+ * `-x` is the menu's LEFT edge; `-y` is the menu's BOTTOM edge on tmux 3.6, so
+ * the pointer coords put the menu just above-right of the click.
+ */
+export function menuPositionArgs(x, y) {
+    const nx = parseCoord(x);
+    const ny = parseCoord(y);
+    if (nx === null || ny === null)
+        return [];
+    // One row ABOVE the pointer: -y is the menu's bottom edge, and if the pointer
+    // cell were ON the menu, the user's trailing button-release would land on the
+    // border and dismiss it instantly (even with -O — measured live). A -1 offset
+    // puts the release just BELOW the menu, which -O survives.
+    return ["-x", String(nx), "-y", String(Math.max(0, ny - 1))];
+}
+/** Parse a non-negative integer coord, or null for anything else. */
+function parseCoord(value) {
+    if (typeof value !== "string" || !/^\d+$/.test(value))
+        return null;
+    const n = Number(value);
+    return Number.isInteger(n) ? n : null;
+}
+/**
+ * PURE — the tmux argv that binds {@link MENU_KEY} (`M-m`, root table) to open
+ * the actions menu. Server-wide bind, mirroring the switcher's M-p — see the note
+ * on `unadoptSession`.
+ */
+export function menuBindCommand(menuCmd = "tmux-ide menu", key = MENU_KEY) {
+    return ["bind-key", "-n", key, ...menuRunShellArgs(menuCmd)];
+}
+/**
+ * PURE — the tmux argv that binds a RIGHT-click on the chrome row
+ * ({@link MENU_STATUS_KEY}) to open the same actions menu. Unlike the left-click
+ * router this is range-independent: a right-click anywhere on the bar opens the
+ * menu, so the session-list content is what matters, not the click target.
+ */
+export function menuStatusBindCommand(menuCmd = "tmux-ide menu") {
+    return ["bind-key", "-n", MENU_STATUS_KEY, ...menuStatusMouseRunShellArgs(menuCmd)];
+}
+/**
+ * PURE — the tmux argv that binds a RIGHT-click on ANY pane body
+ * ({@link MENU_PANE_KEY}) to open the same actions menu, so the menu is reachable
+ * everywhere, not only from the dock row. Forwards the click position (see
+ * {@link menuPaneMouseRunShellArgs}) so the menu opens at the pointer. Panes whose app
+ * captures the mouse (vim, agent TUIs) eat the event — graceful degradation,
+ * `M-m` still works there.
+ */
+export function menuPaneBindCommand(menuCmd = "tmux-ide menu") {
+    return ["bind-key", "-n", MENU_PANE_KEY, ...menuPaneMouseRunShellArgs(menuCmd)];
+}
+/** PURE — the tmux argv that removes the {@link MENU_KEY} binding. */
+export function menuUnbindCommand(key = MENU_KEY) {
+    return ["unbind-key", "-n", key];
+}
+/** PURE — the tmux argv that removes the {@link MENU_STATUS_KEY} binding. */
+export function menuStatusUnbindCommand() {
+    return ["unbind-key", "-n", MENU_STATUS_KEY];
+}
+/** PURE — the tmux argv that removes the {@link MENU_PANE_KEY} binding. */
+export function menuPaneUnbindCommand() {
+    return ["unbind-key", "-n", MENU_PANE_KEY];
+}