tmux-ide 2.7.0 → 2.8.0

package/packages/daemon/src/tui/mirror/file-tree.ts

@@ -1,8 +1,10 @@
 /**
- * Pure model for the Files tab's one-level-expandable file list (M18.4). Like
- * {@link ./diff-model.ts}, the io (async `fs.readdir`) stays in app.tsx; the
- * ORDERING and the flat-tree splice/prune math live here so they unit-test as
- * tables.
+ * Pure model for the Files tab's expandable file list (M18.4, uplifted M24.6).
+ * Like {@link ./diff-model.ts}, the io (async `fs.readdir`, git subprocesses,
+ * the `ignore` matcher fed from .gitignore) stays in app.tsx; the ORDERING, the
+ * flat-tree splice/prune math, the ignore/hidden FILTERING, the git-status
+ * DECORATION merge, the changed-file WALK for `[`/`]`, the `/` FILTER view and
+ * the expansion-preserving REBUILD all live here so they unit-test as tables.
  *
  * The list is a FLAT array of {@link FileNode}s carrying a `depth`; a directory
  * "expands" by splicing its freshly-read children in right after it and
@@ -11,21 +13,69 @@
  * a file manager does.
  */
 
+/** Names that are NEVER listed, whatever the toggles say (the explorer
+ *  widget's battle-tested list — build artifacts and VCS internals that would
+ *  only bury the code). */
+export const ALWAYS_IGNORE: ReadonlySet<string> = new Set([
+  "node_modules",
+  ".git",
+  ".svn",
+  ".hg",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".turbo",
+  ".cache",
+  "__pycache__",
+  "coverage",
+  ".nyc_output",
+  "target",
+  "vendor",
+  "bower_components",
+]);
+
 /** One row in the flat file list. `path` is absolute; `depth` is the indent
- *  level (0 = the context dir's immediate children). */
+ *  level (0 = the context dir's immediate children). `ignored` marks a
+ *  gitignored entry — visible only when the I toggle shows them, dimmed. */
 export interface FileNode {
   name: string;
   path: string;
   isDir: boolean;
   depth: number;
   expanded: boolean;
+  ignored: boolean;
 }
 
 /** A raw `fs.readdir(..., { withFileTypes: true })` entry, reduced to what we
- *  need (kept minimal so callers can map Dirent → this trivially). */
+ *  need (kept minimal so callers can map Dirent → this trivially). `ignored`
+ *  is stamped by the caller's gitignore matcher (io stays outside). */
 export interface RawEntry {
   name: string;
   isDir: boolean;
+  ignored?: boolean;
+}
+
+/** The two Files-surface visibility toggles (both default OFF = filtered). */
+export interface ListFilter {
+  /** Show dotfiles (H). */
+  showHidden: boolean;
+  /** Show gitignored entries (I) — they render dimmed. */
+  showIgnored: boolean;
+}
+
+/**
+ * PURE — drop the entries the current toggles hide: {@link ALWAYS_IGNORE}
+ * names always, dotfiles unless `showHidden`, gitignored entries (as stamped
+ * by the caller) unless `showIgnored`.
+ */
+export function filterEntries(entries: readonly RawEntry[], filter: ListFilter): RawEntry[] {
+  return entries.filter((e) => {
+    if (ALWAYS_IGNORE.has(e.name)) return false;
+    if (!filter.showHidden && e.name.startsWith(".")) return false;
+    if (!filter.showIgnored && e.ignored) return false;
+    return true;
+  });
 }
 
 /**
@@ -57,6 +107,7 @@ export function buildNodes(dir: string, entries: RawEntry[], depth: number): Fil
     isDir: e.isDir,
     depth,
     expanded: false,
+    ignored: e.ignored ?? false,
   }));
 }
 
@@ -95,3 +146,177 @@ export function removeSubtreeAt(list: FileNode[], index: number): FileNode[] {
   next[index] = { ...parent, expanded: false };
   return next;
 }
+
+// ── M24.6 — decoration, changed walk, filter view, rebuild ──────────────────
+
+/** PURE — `abs` relative to `root` ("" when equal or not under root). Both are
+ *  plain string paths; a trailing slash on root is tolerated. */
+export function relPath(root: string, abs: string): string {
+  const base = root.endsWith("/") ? root.slice(0, -1) : root;
+  if (abs === base) return "";
+  return abs.startsWith(base + "/") ? abs.slice(base.length + 1) : "";
+}
+
+/** PURE — every ancestor DIRECTORY of a repo-relative path, outermost first:
+ *  `a/b/c.ts` → `["a", "a/b"]`. A top-level path has none. */
+export function ancestorDirs(rel: string): string[] {
+  const out: string[] = [];
+  let idx = rel.indexOf("/");
+  while (idx !== -1) {
+    out.push(rel.slice(0, idx));
+    idx = rel.indexOf("/", idx + 1);
+  }
+  return out;
+}
+
+/**
+ * PURE — the per-path git status map from parsed porcelain entries
+ * (repo-relative `path` + one-letter `status`), with the explorer widget's
+ * parent-dir propagation: every ancestor directory inherits the FIRST child
+ * status seen, so a collapsed dir still shows that something changed inside.
+ */
+export function statusMapFromEntries(
+  entries: readonly { path: string; status: string }[],
+): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const file of entries) {
+    map.set(file.path, file.status);
+    let parent = file.path;
+    while (parent.includes("/")) {
+      parent = parent.slice(0, parent.lastIndexOf("/"));
+      if (!map.has(parent)) map.set(parent, file.status);
+    }
+  }
+  return map;
+}
+
+/** PURE — compare two repo-relative paths in TREE DISPLAY order: walk the
+ *  segments; where they diverge, a directory component (more segments follow)
+ *  sorts before a terminal file segment — matching {@link sortEntries}'
+ *  dirs-first, case-insensitive ordering. */
+export function treePathCompare(a: string, b: string): number {
+  const as = a.split("/");
+  const bs = b.split("/");
+  const n = Math.min(as.length, bs.length);
+  for (let i = 0; i < n; i++) {
+    const aDir = i < as.length - 1;
+    const bDir = i < bs.length - 1;
+    const av = as[i]!;
+    const bv = bs[i]!;
+    if (av === bv && aDir && bDir) continue;
+    // At the divergence point a directory component sorts before a file
+    // segment, regardless of name (dirs-first display order).
+    if (aDir !== bDir) return aDir ? -1 : 1;
+    const al = av.toLowerCase();
+    const bl = bv.toLowerCase();
+    if (al !== bl) return al < bl ? -1 : 1;
+    if (av !== bv) return av < bv ? -1 : 1;
+  }
+  return as.length - bs.length;
+}
+
+/**
+ * PURE — the ordered changed-FILE walk for `[`/`]`: the porcelain entries'
+ * paths, deduped, minus anything the surface can never show (a DELETED file
+ * has no row at all, an {@link ALWAYS_IGNORE} segment or a dot segment while
+ * hidden files are off is filtered out — hopping to an unrevealable row would
+ * strand the selection and wedge the chain), sorted in tree display order.
+ */
+export function changedFileWalk(
+  entries: readonly { path: string; status?: string }[],
+  opts: { showHidden: boolean },
+): string[] {
+  const seen = new Set<string>();
+  for (const e of entries) {
+    if (!e.path) continue;
+    if (e.status === "D") continue;
+    const segs = e.path.split("/");
+    if (segs.some((s) => ALWAYS_IGNORE.has(s))) continue;
+    if (!opts.showHidden && segs.some((s) => s.startsWith("."))) continue;
+    seen.add(e.path);
+  }
+  return [...seen].sort(treePathCompare);
+}
+
+/**
+ * PURE — the next/previous changed path from `current` (repo-relative, or null
+ * when the selection is nowhere useful), wrapping around. `current` need not
+ * be IN the walk — the step lands on the nearest entry in walk order, so a hop
+ * from an unchanged file between two changed ones does the right thing.
+ */
+export function nextChangedPath(
+  walk: readonly string[],
+  current: string | null,
+  dir: 1 | -1,
+): string | null {
+  if (walk.length === 0) return null;
+  if (current === null) return dir === 1 ? walk[0]! : walk[walk.length - 1]!;
+  if (dir === 1) {
+    for (const p of walk) if (treePathCompare(p, current) > 0) return p;
+    return walk[0]!;
+  }
+  for (let i = walk.length - 1; i >= 0; i--) {
+    if (treePathCompare(walk[i]!, current) < 0) return walk[i]!;
+  }
+  return walk[walk.length - 1]!;
+}
+
+/** One visible row of the `/`-filtered tree: the node plus its index into the
+ *  UNDERLYING flat list (so activation/expansion math still applies there). */
+export interface FilteredRow {
+  node: FileNode;
+  index: number;
+}
+
+/**
+ * PURE — the `/` filter view over the flat list: rows whose NAME contains the
+ * query case-insensitively, each carrying its underlying index. A null or
+ * empty query is "filter off" — every row, in order. The list itself is never
+ * touched, so expanded state trivially survives the filter.
+ */
+export function filterView(list: readonly FileNode[], query: string | null): FilteredRow[] {
+  if (!query) return list.map((node, index) => ({ node, index }));
+  const q = query.toLowerCase();
+  const out: FilteredRow[] = [];
+  for (let index = 0; index < list.length; index++) {
+    const node = list[index]!;
+    if (node.name.toLowerCase().includes(q)) out.push({ node, index });
+  }
+  return out;
+}
+
+/** PURE — the index of `path` in the flat list, or -1. */
+export function indexOfPath(list: readonly FileNode[], path: string): number {
+  for (let i = 0; i < list.length; i++) if (list[i]!.path === path) return i;
+  return -1;
+}
+
+/**
+ * PURE — rebuild the whole flat tree from fresh directory listings while
+ * PRESERVING expansion: `listing` maps a directory's absolute path → its
+ * fresh (already filtered/annotated) entries, `expanded` is the set of dir
+ * paths that were expanded before the refresh. A dir stays expanded only when
+ * it survived the refresh AND its fresh listing was provided; a vanished or
+ * newly-hidden dir simply drops out. Keys must be the exact `FileNode.path`
+ * strings (and the root exactly as passed).
+ */
+export function rebuildTree(
+  rootDir: string,
+  listing: ReadonlyMap<string, readonly RawEntry[]>,
+  expanded: ReadonlySet<string>,
+): FileNode[] {
+  const walk = (dir: string, depth: number): FileNode[] => {
+    const ents = listing.get(dir);
+    if (!ents) return [];
+    const out: FileNode[] = [];
+    for (const node of buildNodes(dir, [...ents], depth)) {
+      if (node.isDir && expanded.has(node.path) && listing.has(node.path)) {
+        out.push({ ...node, expanded: true }, ...walk(node.path, depth + 1));
+      } else {
+        out.push(node);
+      }
+    }
+    return out;
+  };
+  return walk(rootDir, 0);
+}

package/packages/daemon/src/tui/mirror/host-terminal.ts

@@ -0,0 +1,49 @@
+/**
+ * Host-terminal modes owned by the unified app.
+ *
+ * OpenTUI renders each changed row as ANSI runs. With DECAWM (host autowrap)
+ * enabled, a wide/right-edge run can physically wrap into column 1 of the next
+ * row while OpenTUI's shadow records the intended cells. That strands pane text
+ * over the left sidebar until an outer full repaint. The app never relies on
+ * host autowrap—it positions runs absolutely—so disable it for the app's
+ * lifetime and restore it exactly once on every exit path.
+ */
+
+export const HOST_AUTOWRAP_DISABLE = "\x1b[?7l";
+export const HOST_AUTOWRAP_ENABLE = "\x1b[?7h";
+
+export interface HostTerminalExitLifecycle {
+  onExit(listener: () => void): void;
+  offExit(listener: () => void): void;
+}
+
+export interface HostAutowrapGuard {
+  restore(): void;
+}
+
+/**
+ * Disable host autowrap immediately and arm an exit fallback. `restore` is
+ * idempotent and removes the fallback before writing the enable sequence, so a
+ * normal renderer teardown followed by process exit cannot double-write it.
+ *
+ * The caller supplies a synchronous writer: process `exit` listeners cannot
+ * rely on queued/asynchronous stdout writes being flushed.
+ */
+export function installHostAutowrapGuard(
+  write: (sequence: string) => void,
+  lifecycle: HostTerminalExitLifecycle,
+): HostAutowrapGuard {
+  let restored = false;
+
+  const restore = () => {
+    if (restored) return;
+    restored = true;
+    lifecycle.offExit(restore);
+    write(HOST_AUTOWRAP_ENABLE);
+  };
+
+  write(HOST_AUTOWRAP_DISABLE);
+  lifecycle.onExit(restore);
+
+  return { restore };
+}

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

@@ -0,0 +1,205 @@
+/**
+ * The detachable cockpit (M23.2) — tmux keeps the app itself alive.
+ *
+ * `tmux-ide app --detachable` (alias `--hosted`) doesn't run the app in the
+ * invoking terminal: it ensures an internal `_tmux-ide-app` session exists
+ * running the app full-screen, then attaches the terminal to it. ^q under
+ * hosting DETACHES the client (the app keeps running); re-invocation from any
+ * terminal — including a phone over ssh — reattaches the SAME cockpit with
+ * scroll positions, dialogs, and workspace context intact.
+ *
+ * These are the PURE pieces of that contract: the entry decision, the tmux
+ * argv builders, and the shell quoting for the host pane's command line. The
+ * io (spawning tmux, resolving bun vs the compiled binary) stays in the CLI;
+ * the app side only reads {@link HOSTED_ENV} to flip ^q from quit to detach.
+ */
+
+/** The internal host session. `_`-prefixed so every fleet surface (team --json,
+ *  sidebar, home) and the snapshot/restore path already filter it out. */
+export const APP_HOST_SESSION = "_tmux-ide-app";
+
+/** The env marker the launcher sets on the hosted app process. The app flips
+ *  ^q from "quit" to "detach the client" when it sees `=1`; the CLI treats it
+ *  as a recursion guard (a hosted app never re-hosts). */
+export const HOSTED_ENV = "TMUX_IDE_HOSTED";
+
+/** Everything the entry decision reads — flags, config, and the guard. */
+export interface HostedEntryInput {
+  /** `--detachable` (the primary flag). */
+  flagDetachable: boolean;
+  /** `--hosted` (the alias). */
+  flagHosted: boolean;
+  /** `app.detachable` from the typed config — makes bare `tmux-ide app` (and
+   *  the frontDoor entry) hosted without the flag. */
+  configDetachable: boolean;
+  /** Whether WE are already the hosted app ({@link HOSTED_ENV} set). */
+  hostedEnv: boolean;
+}
+
+/**
+ * PURE — should this `tmux-ide app` invocation run hosted? Flags and config
+ * both opt in; the env marker vetoes everything (the app inside the host
+ * session must launch plain, or it would try to attach to itself).
+ */
+export function wantsHostedApp(input: HostedEntryInput): boolean {
+  if (input.hostedEnv) return false;
+  return input.flagDetachable || input.flagHosted || input.configDetachable;
+}
+
+/**
+ * PURE — POSIX single-quote a word for a tmux `new-session` shell command
+ * (tmux hands the string to `sh -c`). Single quotes pass everything literally;
+ * an embedded `'` closes, escapes, and reopens.
+ */
+export function shellQuote(word: string): string {
+  return `'${word.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * PURE — the env vars the host pane's app process needs, assembled for the
+ * command line rather than tmux's session environment: the tmux server may
+ * have been started elsewhere with a different environment, so nothing can be
+ * assumed to inherit. PATH rides along for the same reason (the `bun` launch
+ * mode resolves the binary by name).
+ */
+export function hostedEnvVars(base: {
+  /** The user's real invocation dir (in-app prompts default here). */
+  cwd: string;
+  /** The node-runnable CLI path (`TMUX_IDE_CLI`) for in-app subprocesses. */
+  cli: string;
+  /** The invoking shell's PATH. */
+  path?: string;
+  /** `TMUX_IDE_HOME` / `TMUX_IDE_CONFIG` / `TMUX_IDE_TUI_BIN` pass-throughs
+   *  (set in test rigs; must reach the hosted app or it reads real state). */
+  home?: string;
+  config?: string;
+  tuiBin?: string;
+}): Record<string, string> {
+  const env: Record<string, string> = {
+    [HOSTED_ENV]: "1",
+    TMUX_IDE_CWD: base.cwd,
+    TMUX_IDE_CLI: base.cli,
+  };
+  if (base.path) env.PATH = base.path;
+  if (base.home) env.TMUX_IDE_HOME = base.home;
+  if (base.config) env.TMUX_IDE_CONFIG = base.config;
+  if (base.tuiBin) env.TMUX_IDE_TUI_BIN = base.tuiBin;
+  return env;
+}
+
+/**
+ * PURE — the shell command the host pane runs: `exec env K=V… bin args…`,
+ * every value quoted. `exec` replaces the pane's shell with the app so a quit
+ * (the palette verb) ends the pane — and with it the single-window session.
+ */
+export function hostedCommandLine(
+  bin: string,
+  argv: readonly string[],
+  env: Record<string, string>,
+): string {
+  const assigns = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
+  return ["exec", "env", ...assigns, shellQuote(bin), ...argv.map(shellQuote)].join(" ");
+}
+
+/** PURE — exact-match existence probe (`=` prefix: `has-session -t` would
+ *  otherwise PREFIX-match, e.g. a user session named `_tmux-ide-app-notes`). */
+export function hostExistsArgv(): string[] {
+  return ["has-session", "-t", `=${APP_HOST_SESSION}`];
+}
+
+/** PURE — create the detached host session running the app command line. */
+export function hostCreateArgv(opts: { cwd: string; commandLine: string }): string[] {
+  return ["new-session", "-d", "-s", APP_HOST_SESSION, "-c", opts.cwd, opts.commandLine];
+}
+
+/**
+ * The client events that re-assert `window-size latest` on the host (M25.5).
+ * Each hook's effect was MEASURED on tmux 3.7b in an isolated two-client rig
+ * (220x60 local + 120x40 ssh-sim):
+ *
+ * - `client-attached` / `client-focus-in` / `client-session-changed`: tmux
+ *   3.7b already re-adopts the event client's size natively on all of these
+ *   (attach ~8ms, focus-in ~17ms, switch-client ~17ms — window-resized hook
+ *   timestamps; detach of the latest client also re-adopts natively, ~13ms).
+ *   The hooks are NOT what makes those paths work; they are the SELF-HEAL for
+ *   the one measured way the host gets permanently stuck: any `resize-window`
+ *   against it (a stray tool or user command) flips `window-size` to manual —
+ *   after which NO client event re-adopts, ever (measured: a fresh 220x60
+ *   attach left a manually-80x24 host at 80x24). Re-asserting the option is
+ *   the heal (measured: instant re-adopt) — and it is safe to fire
+ *   redundantly: setting `window-size latest` when it is already latest just
+ *   recomputes the same size. Fire counts are bounded and linear (measured:
+ *   10 rapid focus alternations → exactly 20 focus-in fires; 10 attach cycles
+ *   → 10 attached + 10 session-changed fires — attach fires both — each a
+ *   single in-server set-option, no storm).
+ *
+ * NO `client-detached` hook: measured on 3.7b it never fires as a SESSION
+ * hook (the detaching client has already left the session when hooks are
+ * resolved — 0 fires across 10 detach cycles while the same rig's global
+ * hook logged every one), and the native detach re-adopt covers the path.
+ *
+ * Deliberately NOT `resize-window -a`: per the tmux manual, EVERY
+ * resize-window form — -a included — "will automatically set window-size to
+ * manual", i.e. it would cause the exact stuck state it is meant to fix. And
+ * no `run-shell`: these are tmux-native commands executed in-server
+ * (run-shell hooks serialize the server — prior measurement).
+ */
+export const HOST_RESIZE_HOOKS = [
+  "client-attached",
+  "client-focus-in",
+  "client-session-changed",
+] as const;
+
+/**
+ * PURE — the post-create/ensure session setup: status OFF so the app owns
+ * every row (under `status on` the host steals the bottom row and the app
+ * renders one short), and `window-size latest` pinned explicitly so the most
+ * recently active client dictates the size — a smaller second client
+ * letterboxes the larger one (tmux's own dot-fill), which is the documented
+ * behavior.
+ *
+ * M25.5 additions (each measured on 3.7b — see {@link HOST_RESIZE_HOOKS}):
+ *
+ * - `focus-events on` (server option — the ONE non-session-scoped line, and
+ *   the load-bearing one): it defaults OFF, so real terminals are never asked
+ *   for focus reporting and `client-focus-in` never fires. With it on, coming
+ *   BACK to a terminal that stayed attached re-adopts that client's size on
+ *   the focus event alone (measured: focus-in → client-active →
+ *   window-resized in ~17ms) — no keystroke needed. This is the user's exact
+ *   "reopen it on my computer locally" moment when the local client never
+ *   detached. Side effect is the widely-recommended one (panes that request
+ *   focus, e.g. editors, start receiving it).
+ * - the {@link HOST_RESIZE_HOOKS} self-heal hooks, session-scoped to the host
+ *   (zero effect on user sessions).
+ *
+ * The whole list is idempotent — the CLI applies it on EVERY ensure, not just
+ * create, so upgrading tmux-ide fixes an already-running cockpit on its next
+ * `tmux-ide app` (and un-sticks a manually-resized host).
+ *
+ * No `=` exact-match prefix here: tmux (measured on 3.7b) rejects it on
+ * `set-option` session targets ("no such session") even though has-session
+ * and attach accept it. Plain names are safe in THIS builder only because
+ * setup runs right after the exists-probe/create — the exact session exists,
+ * and tmux prefers an exact match over a prefix match when one does.
+ */
+export function hostSetupArgvs(): string[][] {
+  const heal = `set-option -w -t ${APP_HOST_SESSION}: window-size latest`;
+  return [
+    ["set-option", "-t", APP_HOST_SESSION, "status", "off"],
+    ["set-option", "-w", "-t", `${APP_HOST_SESSION}:`, "window-size", "latest"],
+    ["set-option", "-s", "focus-events", "on"],
+    ...HOST_RESIZE_HOOKS.map((hook) => ["set-hook", "-t", APP_HOST_SESSION, hook, heal]),
+  ];
+}
+
+/**
+ * PURE — how the invoking terminal reaches the cockpit: inside tmux the
+ * client is already attached to a server, so `switch-client` moves it (a
+ * nested `attach` would complain and double-render); a plain terminal
+ * attaches. Both exact-match the host name.
+ */
+export function hostAttachArgv(insideTmux: boolean): string[] {
+  return insideTmux
+    ? ["switch-client", "-t", `=${APP_HOST_SESSION}`]
+    : ["attach-session", "-t", `=${APP_HOST_SESSION}`];
+}

package/packages/daemon/src/tui/mirror/layout-parse.ts

@@ -0,0 +1,154 @@
+/**
+ * PURE — tmux layout-string and control-notification parsing (M23.5).
+ *
+ * `%layout-change` arrives sub-millisecond after the server applies a layout
+ * and ALWAYS precedes the first new-size `%output` (measured on tmux 3.7b:
+ * the follow-up output can trail by as little as 0.2ms). The mirror therefore
+ * derives pane geometry from the notification PAYLOAD itself instead of a
+ * debounced `list-panes` round-trip — these parsers are that push path.
+ *
+ * The layout grammar mirrors tmux's `layout_parse.c`: a 4-hex-digit checksum,
+ * a comma, then a cell. A cell is `WxH,X,Y` followed by either `,<paneId>`
+ * (a leaf; the numeric pane id sans `%`), `{…}` (horizontal split) or `[…]`
+ * (vertical split) with comma-separated child cells. The ROOT cell's WxH is
+ * the authoritative window size. Parse the VISIBLE layout — the THIRD field
+ * of `%layout-change @win <layout> <visible-layout> <flags>` — because zoom
+ * collapses it to the single zoomed pane (`*Z` in flags = zoomed); the second
+ * field keeps reporting the saved multi-pane layout.
+ *
+ * Everything here is unit-tested against layout strings captured from a real
+ * tmux 3.7b server (splits, zoom, storms) — no tmux at test time.
+ */
+
+/** One visible pane rectangle, in window cells. `id` is `%`-prefixed. */
+export interface LayoutLeaf {
+  id: string;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** A parsed (visible) layout: the window size + the leaves in layout order. */
+export interface ParsedLayout {
+  /** The root cell's WxH — the authoritative window size. */
+  width: number;
+  height: number;
+  leaves: LayoutLeaf[];
+}
+
+/** Parse a tmux layout string (`csum,WxH,X,Y…`). Null on any malformed input
+ *  (the caller falls back to the slow list-panes path — never throw here). */
+export function parseLayout(layout: string): ParsedLayout | null {
+  if (!/^[0-9a-fA-F]{4},/.test(layout)) return null;
+  const s = layout.slice(5);
+  const leaves: LayoutLeaf[] = [];
+  const root = parseCell(s, 0, leaves);
+  if (!root || root.pos !== s.length) return null;
+  return { width: root.width, height: root.height, leaves };
+}
+
+/** Recursive-descent cell parse from `pos`; appends leaves in layout order. */
+function parseCell(
+  s: string,
+  pos: number,
+  leaves: LayoutLeaf[],
+): { width: number; height: number; pos: number } | null {
+  const dims = readDims(s, pos);
+  if (!dims) return null;
+  const { width, height, left, top } = dims;
+  pos = dims.pos;
+  const ch = s[pos];
+  if (ch === ",") {
+    // Leaf: the numeric pane id.
+    const id = readInt(s, pos + 1);
+    if (!id) return null;
+    leaves.push({ id: `%${id.value}`, left, top, width, height });
+    return { width, height, pos: id.pos };
+  }
+  if (ch === "{" || ch === "[") {
+    const close = ch === "{" ? "}" : "]";
+    pos++;
+    for (;;) {
+      const child = parseCell(s, pos, leaves);
+      if (!child) return null;
+      pos = child.pos;
+      if (s[pos] === ",") {
+        pos++;
+        continue;
+      }
+      if (s[pos] === close) return { width, height, pos: pos + 1 };
+      return null;
+    }
+  }
+  // A bare root leaf ends the string (`…,0,0,445`): ch is undefined only when
+  // the leaf id was consumed above, so anything else here is malformed.
+  return null;
+}
+
+/** Read `WxH,X,Y` at `pos`. */
+function readDims(
+  s: string,
+  pos: number,
+): { width: number; height: number; left: number; top: number; pos: number } | null {
+  const w = readInt(s, pos);
+  if (!w || s[w.pos] !== "x") return null;
+  const h = readInt(s, w.pos + 1);
+  if (!h || s[h.pos] !== ",") return null;
+  const x = readInt(s, h.pos + 1);
+  if (!x || s[x.pos] !== ",") return null;
+  const y = readInt(s, x.pos + 1);
+  if (!y) return null;
+  return { width: w.value, height: h.value, left: x.value, top: y.value, pos: y.pos };
+}
+
+/** Read a decimal integer at `pos` (at least one digit). */
+function readInt(s: string, pos: number): { value: number; pos: number } | null {
+  let end = pos;
+  while (end < s.length && s.charCodeAt(end) >= 0x30 && s.charCodeAt(end) <= 0x39) end++;
+  if (end === pos) return null;
+  return { value: Number(s.slice(pos, end)), pos: end };
+}
+
+/** A parsed `%layout-change` notification body. */
+export interface LayoutChange {
+  windowId: string;
+  /** The saved (full) layout — kept for debugging; geometry uses `visible`. */
+  layout: string;
+  /** The VISIBLE layout — collapses to the single zoomed pane under zoom. */
+  visible: string;
+  /** `Z` present in the flags field (`*Z`). */
+  zoomed: boolean;
+}
+
+/** Parse the body after `%layout-change ` (tmux 3.7b:
+ *  `@387 <layout> <visible-layout> *Z`). Null when the shape is off. */
+export function parseLayoutChange(rest: string): LayoutChange | null {
+  const parts = rest.trim().split(/\s+/);
+  const [windowId = "", layout = "", visible = "", flags = ""] = parts;
+  if (parts.length < 3 || !windowId.startsWith("@")) return null;
+  return { windowId, layout, visible, zoomed: flags.includes("Z") };
+}
+
+/** Parse the body after `%window-pane-changed ` (`@387 %443`). */
+export function parseWindowPaneChanged(rest: string): { windowId: string; paneId: string } | null {
+  const [windowId = "", paneId = ""] = rest.trim().split(/\s+/);
+  if (!windowId.startsWith("@") || !paneId.startsWith("%")) return null;
+  return { windowId, paneId };
+}
+
+/** Parse the body after `%session-window-changed ` (`$353 @388`). */
+export function parseSessionWindowChanged(rest: string): { windowId: string } | null {
+  const [, windowId = ""] = rest.trim().split(/\s+/);
+  if (!windowId.startsWith("@")) return null;
+  return { windowId };
+}
+
+/** Parse the body after `%subscription-changed ` for the mirror's `mouse`
+ *  subscription (tmux 3.7b: `mouse $353 @387 0 %445 : 1`). Null for other
+ *  subscription names or an off shape. */
+export function parseMouseSubscription(rest: string): { paneId: string; on: boolean } | null {
+  const m = /^mouse\s+\$\S+\s+@\S+\s+\S+\s+(%\S+)\s*:\s*(.*)$/.exec(rest.trim());
+  if (!m) return null;
+  return { paneId: m[1]!, on: m[2]!.trim() === "1" };
+}