tmux-ide 2.6.0 → 2.6.1

package/packages/daemon/src/tui/chrome/menu.ts

@@ -0,0 +1,289 @@
+/**
+ * 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, type AppTheme } from "../../lib/app-config.ts";
+import type { AgentStatus } from "../detect/classify.ts";
+import {
+  switcherPopupCommand,
+  homePopupCommand,
+  updatePopupCommand,
+  MENU_KEY,
+  MENU_PANE_KEY,
+  MENU_STATUS_KEY,
+} from "./statusline.ts";
+import type { UpdateStatus } from "../../lib/update-check.ts";
+import { cheatsheetPopupCommand } from "./cheatsheet.ts";
+import { PANEL_POPUPS, panelPopupCommand } from "./panels.ts";
+
+/** 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: AgentStatus, theme: AppTheme): { glyph: string; colour: string } {
+  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: string): string {
+  return `'${name.replace(/'/g, `'\\''`)}'`;
+}
+
+/** The styled `#[fg=…]glyph#[default] name` label for a session row. */
+function sessionLabel(session: { name: string; status: AgentStatus }, theme: AppTheme): string {
+  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: Array<{ name: string; status: AgentStatus }>,
+  theme: AppTheme = DEFAULT_THEME,
+  update?: UpdateStatus,
+): string[] {
+  // 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: string[] =
+    update?.updateAvailable && update.latest
+      ? [`#[fg=${theme.accent}]⬆ Update available (v${update.latest})`, "u", updatePopupCommand()]
+      : [];
+
+  const header: string[] = [
+    "⌂ 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: string[] = [];
+  PANEL_POPUPS.forEach((panel, i) => {
+    panelItems.push(panel.label, PANEL_MENU_KEYS[i] ?? "", panelPopupCommand(panel));
+  });
+
+  const sessionItems: string[] = [];
+  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: string[] = [
+    "＋ 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: string[] = [];
+  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: string): string[] {
+  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: string): string[] {
+  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: string): string[] {
+  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: string | undefined, y: string | undefined): string[] {
+  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: string | undefined): number | null {
+  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): string[] {
+  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"): string[] {
+  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"): string[] {
+  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): string[] {
+  return ["unbind-key", "-n", key];
+}
+
+/** PURE — the tmux argv that removes the {@link MENU_STATUS_KEY} binding. */
+export function menuStatusUnbindCommand(): string[] {
+  return ["unbind-key", "-n", MENU_STATUS_KEY];
+}
+
+/** PURE — the tmux argv that removes the {@link MENU_PANE_KEY} binding. */
+export function menuPaneUnbindCommand(): string[] {
+  return ["unbind-key", "-n", MENU_PANE_KEY];
+}

package/packages/daemon/src/tui/chrome/notify.ts

@@ -0,0 +1,195 @@
+/**
+ * The "who needs me" loop — turn fleet transitions into user-facing pings.
+ *
+ * The chrome {@link ./updater.ts updater} already sees every session's state
+ * transition each tick (via {@link ./events.ts diffFleet}). Watching the status
+ * bar for a `blocked`/`done` flip is a chore, so this module fans those two
+ * signals out to the human: a tmux toast on each attached client
+ * (`display-message -c`), and optionally a macOS notification.
+ *
+ * Split as usual: {@link decideNotifications} + {@link notificationPrefs} +
+ * {@link applyKillSwitch} + {@link parseClients} are PURE (unit-tested without a
+ * live tmux / filesystem); {@link sendToasts}, {@link sendSystemNotification},
+ * {@link listAttachedClients} and {@link readNotificationPrefs} are the thin io
+ * wrappers. Every io path is best-effort — a failed ping must never break the
+ * updater loop.
+ */
+import { execFileSync } from "node:child_process";
+import { runTmux } from "@tmux-ide/tmux-bridge";
+import { appConfigPath, loadAppConfig, parseAppConfig } from "../../lib/app-config.ts";
+import type { AgentStatus } from "../detect/classify.ts";
+
+/** A fleet transition this tick — the shape {@link ./events.ts diffFleet} emits. */
+export interface NotifyEvent {
+  session: string;
+  from: AgentStatus | null;
+  to: AgentStatus;
+}
+
+/** An attached tmux client and the session it's currently viewing. */
+export interface AttachedClient {
+  client: string;
+  session: string;
+}
+
+/** A toast destined for one client's status line. */
+export interface ToastTarget {
+  client: string;
+  message: string;
+}
+
+/** A macOS-notification payload (title is fixed by {@link sendSystemNotification}). */
+export interface SystemNotification {
+  message: string;
+}
+
+/** The verdict of {@link decideNotifications}. */
+export interface NotifyDecision {
+  toasts: ToastTarget[];
+  system: SystemNotification[];
+  /** The debounce map to thread into the next tick (a copy of the input). */
+  nextLastNotified: Map<string, number>;
+}
+
+/** The only two states worth pinging the user over. */
+const NOTIFY_STATES: ReadonlySet<AgentStatus> = new Set<AgentStatus>(["blocked", "done"]);
+/** Don't re-ping the same session+state more than once inside this window. */
+export const NOTIFY_DEBOUNCE_MS = 30_000;
+
+/** PURE — the human-readable ping text for a notifiable state. */
+function notifyMessage(session: string, to: AgentStatus): string {
+  return to === "blocked" ? `⚠ ${session} needs you (blocked)` : `✓ ${session} finished (done)`;
+}
+
+/**
+ * PURE — decide who to ping from this tick's transitions.
+ *
+ * Rules:
+ *   - only `blocked` / `done` transitions qualify (working/idle etc. are noise);
+ *   - DEBOUNCE: skip a session+state that fired within {@link NOTIFY_DEBOUNCE_MS};
+ *   - SUPPRESS the toast for any client already viewing that session (they can
+ *     see the bar flip themselves) — other clients still get toasted;
+ *   - a `system` entry is produced per qualifying, non-debounced event regardless
+ *     of clients (so the macOS path fires even with nothing attached — the
+ *     caller gates it on prefs).
+ *
+ * Returns the toasts/system to dispatch plus `nextLastNotified` (a copy of the
+ * input with fresh timestamps for the events we acted on) to thread onward.
+ */
+export function decideNotifications(
+  events: NotifyEvent[],
+  clients: AttachedClient[],
+  lastNotified: Map<string, number>,
+  nowMs: number,
+): NotifyDecision {
+  const nextLastNotified = new Map(lastNotified);
+  const toasts: ToastTarget[] = [];
+  const system: SystemNotification[] = [];
+  for (const ev of events) {
+    if (!NOTIFY_STATES.has(ev.to)) continue;
+    const key = `${ev.session}:${ev.to}`;
+    const last = nextLastNotified.get(key);
+    if (last !== undefined && nowMs - last < NOTIFY_DEBOUNCE_MS) continue;
+    nextLastNotified.set(key, nowMs);
+    const message = notifyMessage(ev.session, ev.to);
+    for (const c of clients) {
+      if (c.session === ev.session) continue; // they're already looking at it
+      toasts.push({ client: c.client, message });
+    }
+    system.push({ message });
+  }
+  return { toasts, system, nextLastNotified };
+}
+
+/** PURE — parse `list-clients -F '#{client_name}\t#{session_name}'` output. */
+export function parseClients(lines: string[]): AttachedClient[] {
+  const out: AttachedClient[] = [];
+  for (const line of lines) {
+    const [client = "", session = ""] = line.split("\t");
+    if (client && session) out.push({ client, session });
+  }
+  return out;
+}
+
+/** io — enumerate attached clients from the live tmux server. Never throws. */
+export function listAttachedClients(): AttachedClient[] {
+  try {
+    const raw = runTmux(["list-clients", "-F", "#{client_name}\t#{session_name}"])
+      .toString()
+      .trim();
+    return raw ? parseClients(raw.split("\n")) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * io — flash each toast on its client's status line (`-d 3000` = 3s; needs tmux
+ * ≥3.2). Best-effort per toast: a gone client / failed call just drops that one.
+ */
+export function sendToasts(toasts: ToastTarget[]): void {
+  for (const { client, message } of toasts) {
+    try {
+      runTmux(["display-message", "-c", client, "-d", "3000", message]);
+    } catch {
+      // client vanished or display failed — never fatal
+    }
+  }
+}
+
+/**
+ * io — fire a macOS notification via `osascript`. macOS-only (guarded), and
+ * quotes/backslashes are escaped for the AppleScript string literal. Best-effort.
+ */
+export function sendSystemNotification(message: string): void {
+  if (process.platform !== "darwin") return;
+  const escaped = message.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  try {
+    execFileSync("osascript", ["-e", `display notification "${escaped}" with title "tmux-ide"`], {
+      stdio: "ignore",
+    });
+  } catch {
+    // osascript missing / notification blocked — never fatal
+  }
+}
+
+/** User notification preferences (minimal, pre-M14). */
+export interface NotificationPrefs {
+  toast: boolean;
+  macos: boolean;
+}
+
+/** Defaults: tmux toasts on, macOS notifications off. */
+export const DEFAULT_NOTIFICATION_PREFS: NotificationPrefs = { toast: true, macos: false };
+
+/**
+ * PURE — read `{ notifications: { toast, macos } }` out of a parsed config,
+ * falling back to {@link DEFAULT_NOTIFICATION_PREFS} for anything missing or of
+ * the wrong type. Delegates to the shared {@link parseAppConfig} so notification
+ * parsing can't drift from the rest of the config.
+ */
+export function notificationPrefs(parsedConfig: unknown): NotificationPrefs {
+  return parseAppConfig(parsedConfig).notifications;
+}
+
+/** PURE — the `TMUX_IDE_NOTIFY=0` kill-switch: disables both channels. */
+export function applyKillSwitch(
+  prefs: NotificationPrefs,
+  envValue: string | undefined,
+): NotificationPrefs {
+  return envValue === "0" ? { toast: false, macos: false } : prefs;
+}
+
+/** Absolute path to the shared config (honors `TMUX_IDE_CONFIG`). */
+export function notifyConfigPath(): string {
+  return appConfigPath();
+}
+
+/**
+ * io — resolve effective prefs from the shared app config (defaults for a
+ * missing/invalid file), then apply the `TMUX_IDE_NOTIFY=0` kill-switch. Reads
+ * fresh so the env kill-switch is honored each call.
+ */
+export function readNotificationPrefs(): NotificationPrefs {
+  return applyKillSwitch(loadAppConfig().notifications, process.env.TMUX_IDE_NOTIFY);
+}

package/packages/daemon/src/tui/chrome/panels.ts

@@ -0,0 +1,111 @@
+/**
+ * The tmux-ide widget PANELS — every widget is a floating app dialog.
+ *
+ * The one-app milestone: instead of living as dedicated tmux panes, each widget
+ * opens as a `display-popup -E` over your work, one root-table keystroke away,
+ * esc/q to close (the popup exits when the widget process does). This mirrors the
+ * chrome popups (switcher `M-p` / cheat sheet `M-k`) but points each key at
+ * `tmux-ide popup <widget>`, which execs the bun widget synchronously inside the
+ * popup's PTY (see the `popup` case in bin/cli.ts).
+ *
+ * {@link PANEL_POPUPS} is the single source of truth — the widget name (the
+ * `tmux-ide popup <widget>` arg AND the `keys.panels.<widget>` config key), a
+ * menu label, and per-widget popup sizing. The status bar's adopt binds one key
+ * per entry, the cheat sheet lists them, and the actions menu opens them — all
+ * derived from this list so they never drift.
+ *
+ * Only widgets that EXIST and stand alone are here: `preview` renders whatever
+ * the explorer selected (via a shared `@preview_file` tmux option — nothing to
+ * show on its own) and `setup` is the onboarding wizard, so neither is a panel.
+ * `tasks`/`warroom`/`costs` were removed in the v2.6.0 front-end trim.
+ *
+ * Every builder here is PURE (tested); the io (running the popup) is the CLI's.
+ */
+import type { AppPanelKeys } from "../../lib/app-config.ts";
+
+/** A widget that can float as a panel popup. */
+export interface PanelPopup {
+  /** Widget name — the `tmux-ide popup <widget>` arg + `keys.panels` field. */
+  widget: "explorer" | "changes" | "config";
+  /** Human label for the actions menu row. */
+  label: string;
+  /**
+   * `display-popup` size tokens (tmux `-w`/`-h`). Sized per widget: the explorer
+   * is a tall, narrower file column; changes is a wide diff surface; config is a
+   * roomy tree editor. All large — a panel floats OVER your work, so it should
+   * dominate while open, then vanish on esc.
+   */
+  width: string;
+  height: string;
+}
+
+/**
+ * The panel registry — the widgets bound as floating popups, in menu order.
+ * Keys are configurable via `~/.tmux-ide/config.json` (`keys.panels.*`); the
+ * defaults live in {@link ../../lib/app-config.ts}. Sizing is fixed here (tuned,
+ * not configurable — a deliberate scope line).
+ */
+export const PANEL_POPUPS: PanelPopup[] = [
+  { widget: "explorer", label: "⊞ Files", width: "60%", height: "85%" },
+  { widget: "changes", label: "± Changes", width: "85%", height: "90%" },
+  { widget: "config", label: "⚙ Config", width: "80%", height: "85%" },
+];
+
+/** The widget names that `tmux-ide popup <widget>` accepts (the panel set). */
+export const POPUP_WIDGETS: string[] = PANEL_POPUPS.map((p) => p.widget);
+
+/** The CLI invocation a panel popup runs (`tmux-ide popup <widget>`). */
+export function panelPopupCli(widget: string): string {
+  return `tmux-ide popup ${widget}`;
+}
+
+/**
+ * The configured root-table key for a panel. `AppPanelKeys` fields are named
+ * for the widgets, so this is a typed lookup — the panel registry and the config
+ * shape stay in lockstep.
+ */
+export function panelKey(panel: PanelPopup, keys: AppPanelKeys): string {
+  return keys[panel.widget];
+}
+
+/**
+ * PURE — the `display-popup` command STRING that floats a panel (shared by the
+ * actions menu's Panels rows, so a menu pick opens an identical popup to the
+ * key bind). `-d '#{pane_current_path}'` opens the widget on the pane's cwd, so
+ * the explorer/changes/config land on the project you're looking at.
+ */
+export function panelPopupCommand(panel: PanelPopup, cli = panelPopupCli(panel.widget)): string {
+  return `display-popup -E -d '#{pane_current_path}' -w ${panel.width} -h ${panel.height} "${cli}"`;
+}
+
+/**
+ * PURE — the tmux argv that binds a panel's root-table key to its
+ * `display-popup`. Server-wide root-table bind (tmux has no per-session
+ * bind-key), mirroring the switcher's popup key — see the note on
+ * `unadoptSession`. Idempotent: re-binding a key overwrites it.
+ */
+export function panelPopupBindCommand(
+  panel: PanelPopup,
+  key: string,
+  cli = panelPopupCli(panel.widget),
+): string[] {
+  return [
+    "bind-key",
+    "-n",
+    key,
+    "display-popup",
+    "-E",
+    "-d",
+    "#{pane_current_path}",
+    "-w",
+    panel.width,
+    "-h",
+    panel.height,
+    cli,
+  ];
+}
+
+/** PURE — the tmux argv that removes a panel's key binding. */
+export function panelPopupUnbindCommand(key: string): string[] {
+  return ["unbind-key", "-n", key];
+}