tmux-ide 2.6.1 → 2.7.0

package/packages/daemon/src/tui/mirror/dialog-stack.ts

@@ -0,0 +1,354 @@
+/**
+ * The global dialog STACK (M22.4) — one overlay mount in app.tsx renders
+ * whatever is on top; everything else is state here, framework-free so it
+ * unit-tests without OpenTUI.
+ *
+ * The API is Promise-based one-shots, so multi-step flows read as sequential
+ * awaits:
+ *
+ *   const choice = await DialogSelect.show({ title, items });
+ *   if (choice && (await DialogConfirm.show({ title: "Sure?" }))) { … }
+ *
+ * `push` may be called while another dialog is open — the new one stacks on
+ * top and only IT renders/receives input; resolving it reveals the one below.
+ * Escape (and a click outside the box) pops ONE level, resolving that dialog
+ * with its cancel value (`null`, or `false` for confirms). `replace` swaps the
+ * top in place; `clear` cancels the whole stack (quit paths).
+ *
+ * INPUT while a dialog is open is fully owned here: app.tsx feeds every key to
+ * {@link dialogKey} and every pointer event to its dialog route block FIRST, so
+ * nothing leaks to panes/editor underneath. Selection changes — keyboard and
+ * mouse alike — funnel through one place, which is where a select's `onMove`
+ * live-preview hook fires (never on open) and where an armed destructive row
+ * disarms.
+ *
+ * Solid bridge: the stack is not reactive; app.tsx subscribes and bumps a
+ * `dialogRev` signal on every notification (the `editorRev` idiom).
+ */
+import {
+  filterDialogItems,
+  initialSelIndex,
+  followTop,
+  clampDialogTop,
+  DIALOG_ROWS,
+  type DialogConfirmSpec,
+  type DialogPromptSpec,
+  type DialogSelectItem,
+  type DialogSelectResult,
+  type DialogSelectSpec,
+  type DialogSpec,
+} from "./dialog-model.ts";
+
+/** Mutable interaction state of one open dialog. */
+export interface DialogEntryState {
+  /** select: the filter query. */
+  query: string;
+  /** select/confirm: the selected row (select: index into the FILTERED list). */
+  sel: number;
+  /** select: the scroll window top. */
+  top: number;
+  /** select: the armed destructive row (filtered index), disarmed on any move. */
+  armed: number | null;
+  /** prompt: the typed value. */
+  input: string;
+  /** prompt: the current validation error. */
+  error: string | null;
+  /** prompt: a busy flag the caller may set while persisting. */
+  busy: boolean;
+}
+
+/** One stack entry: the spec, its interaction state, and the pending resolver. */
+export interface DialogEntry {
+  spec: DialogSpec;
+  state: DialogEntryState;
+  resolve: (result: unknown) => void;
+}
+
+function freshState(spec: DialogSpec): DialogEntryState {
+  return {
+    query: "",
+    sel:
+      spec.kind === "select"
+        ? initialSelIndex(spec)
+        : spec.kind === "confirm" && spec.defaultNo
+          ? 1
+          : 0,
+    top: 0,
+    armed: null,
+    input: spec.kind === "prompt" ? (spec.initial ?? "") : "",
+    error: null,
+    busy: false,
+  };
+}
+
+/** The cancel value a dismissed dialog resolves with. */
+function cancelValue(spec: DialogSpec): unknown {
+  return spec.kind === "confirm" ? false : null;
+}
+
+export interface DialogStack {
+  /** The rendered/driven entry — the top of the stack, or null. */
+  top(): DialogEntry | null;
+  depth(): number;
+  /** Re-render notifications (app.tsx bumps a signal). Returns unsubscribe. */
+  subscribe(fn: () => void): () => void;
+  /** Open a dialog ON TOP; resolves when it closes. */
+  push(spec: DialogSpec): Promise<unknown>;
+  /** Swap the top dialog in place (its promise resolves with the cancel value). */
+  replace(spec: DialogSpec): Promise<unknown>;
+  /** Resolve + remove the top entry. */
+  pop(result: unknown): void;
+  /** Pop ONE level with its cancel value — what Escape and a click outside do. */
+  dismiss(): void;
+  /** Cancel every open dialog (bottom-up resolves with cancel values). */
+  clear(): void;
+  /** The top select's rows for its current query. */
+  filtered(): DialogSelectItem[];
+  /** Move the selection by delta (select/confirm) — fires onMove, follows scroll. */
+  moveSel(delta: number): void;
+  /** Set the selection to a FILTERED index (mouse motion) — fires onMove. */
+  setSel(index: number): void;
+  /** Wheel: shift the select window top by delta rows. */
+  scrollBy(delta: number): void;
+  /** Activate a filtered row (enter / click): arms danger rows first. */
+  activate(index: number): void;
+  /** Confirm: resolve option 0 (true) / 1 (false). */
+  choose(option: number): void;
+  /** Prompt: mark busy (footer shows "saving…", input ignores keys). */
+  setBusy(busy: boolean): void;
+  /** Notify subscribers after a direct state mutation (query/input edits). */
+  touch(): void;
+}
+
+export function createDialogStack(): DialogStack {
+  const stack: DialogEntry[] = [];
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const fn of listeners) fn();
+  };
+
+  const top = () => stack[stack.length - 1] ?? null;
+
+  const filtered = (): DialogSelectItem[] => {
+    const e = top();
+    if (!e || e.spec.kind !== "select") return [];
+    return filterDialogItems(e.state.query, e.spec.items);
+  };
+
+  /** Central selection change — the ONLY place `sel` moves, so onMove and the
+   *  danger disarm can't be bypassed by one of the two input paths. */
+  const applySel = (next: number) => {
+    const e = top();
+    if (!e) return;
+    if (e.spec.kind === "confirm") {
+      e.state.sel = Math.max(0, Math.min(1, next));
+      notify();
+      return;
+    }
+    if (e.spec.kind !== "select") return;
+    const rows = filtered();
+    if (rows.length === 0) return;
+    const clamped = Math.max(0, Math.min(rows.length - 1, next));
+    if (clamped === e.state.sel) return;
+    e.state.sel = clamped;
+    e.state.armed = null;
+    e.state.top = followTop(clamped, e.state.top, DIALOG_ROWS);
+    e.spec.onMove?.(rows[clamped]!);
+    notify();
+  };
+
+  const pop = (result: unknown) => {
+    const e = stack.pop();
+    if (!e) return;
+    e.resolve(result);
+    notify();
+  };
+
+  return {
+    top,
+    depth: () => stack.length,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    push(spec) {
+      return new Promise<unknown>((resolve) => {
+        stack.push({ spec, state: freshState(spec), resolve });
+        notify();
+      });
+    },
+    replace(spec) {
+      const e = stack.pop();
+      if (e) e.resolve(cancelValue(e.spec));
+      return new Promise<unknown>((resolve) => {
+        stack.push({ spec, state: freshState(spec), resolve });
+        notify();
+      });
+    },
+    pop,
+    dismiss() {
+      const e = top();
+      if (e) pop(cancelValue(e.spec));
+    },
+    clear() {
+      while (stack.length > 0) {
+        const e = stack.pop()!;
+        e.resolve(cancelValue(e.spec));
+      }
+      notify();
+    },
+    filtered,
+    moveSel(delta) {
+      const e = top();
+      if (!e) return;
+      applySel(e.state.sel + delta);
+    },
+    setSel(index) {
+      applySel(index);
+    },
+    scrollBy(delta) {
+      const e = top();
+      if (!e || e.spec.kind !== "select") return;
+      e.state.top = clampDialogTop(e.state.top + delta, filtered().length, DIALOG_ROWS);
+      notify();
+    },
+    activate(index) {
+      const e = top();
+      if (!e || e.spec.kind !== "select") return;
+      const rows = filtered();
+      const item = rows[index];
+      if (!item) return;
+      if (index !== e.state.sel) applySel(index);
+      if (item.danger && e.state.armed !== index) {
+        // Inline destructive confirm — the row itself asks again, no modal.
+        e.state.armed = index;
+        notify();
+        return;
+      }
+      pop({ item } satisfies DialogSelectResult);
+    },
+    choose(option) {
+      const e = top();
+      if (!e || e.spec.kind !== "confirm") return;
+      pop(option === 0);
+    },
+    setBusy(busy) {
+      const e = top();
+      if (!e || e.spec.kind !== "prompt") return;
+      e.state.busy = busy;
+      notify();
+    },
+    touch: notify,
+  };
+}
+
+/** THE stack — one per app process; the overlay mount and the routers all
+ *  address this instance. */
+export const dialogStack = createDialogStack();
+
+// ── One-shot façades (the exploration's API shape) ───────────────────────────
+
+export const DialogSelect = {
+  /** Open a select; resolves the chosen row (+ action key) or null on cancel. */
+  show(spec: Omit<DialogSelectSpec, "kind">, stack: DialogStack = dialogStack) {
+    return stack.push({ kind: "select", ...spec }) as Promise<DialogSelectResult | null>;
+  },
+};
+
+export const DialogPrompt = {
+  /** Open a prompt; resolves the (validated) text or null on cancel. */
+  show(spec: Omit<DialogPromptSpec, "kind">, stack: DialogStack = dialogStack) {
+    return stack.push({ kind: "prompt", ...spec }) as Promise<string | null>;
+  },
+};
+
+export const DialogConfirm = {
+  /** Open a two-option confirm; resolves true only on the affirmative. */
+  show(spec: Omit<DialogConfirmSpec, "kind">, stack: DialogStack = dialogStack) {
+    return stack.push({ kind: "confirm", ...spec }) as Promise<boolean>;
+  },
+};
+
+// ── The keyboard reducer ─────────────────────────────────────────────────────
+
+/** The key-event shape app.tsx feeds (matches its useKeyboard events). */
+export interface DialogKeyEvent {
+  name: string;
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+}
+
+/**
+ * Feed one key to the stack's top dialog. Centralized ESCAPE lives here: it
+ * pops exactly one level. The caller must treat EVERY key as consumed while
+ * `stack.depth() > 0` (input suppression — nothing forwards to panes).
+ */
+export function dialogKey(stack: DialogStack, evt: DialogKeyEvent): void {
+  const e = stack.top();
+  if (!e) return;
+  const { spec, state } = e;
+  if (evt.name === "escape") {
+    stack.dismiss();
+    return;
+  }
+  if (spec.kind === "select") {
+    if (evt.name === "up") return stack.moveSel(-1);
+    if (evt.name === "down") return stack.moveSel(1);
+    if (evt.name === "return") return stack.activate(state.sel);
+    // Per-row actions ride ctrl+<key> so they never collide with filter typing.
+    if (evt.ctrl && evt.name.length === 1) {
+      const action = (spec.actions ?? []).find((a) => a.key === evt.name);
+      const item = stack.filtered()[state.sel];
+      if (action && item) {
+        stack.pop({ item, action: action.key } satisfies DialogSelectResult);
+      }
+      return;
+    }
+    if (spec.filterable === false) return;
+    if (evt.name === "backspace") {
+      state.query = state.query.slice(0, -1);
+      state.sel = 0;
+      state.top = 0;
+      state.armed = null;
+      return stack.touch();
+    }
+    if (evt.name.length === 1 && !evt.ctrl && !evt.meta) {
+      state.query += evt.shift ? evt.name.toUpperCase() : evt.name;
+      state.sel = 0;
+      state.top = 0;
+      state.armed = null;
+      return stack.touch();
+    }
+    return;
+  }
+  if (spec.kind === "prompt") {
+    if (state.busy) return; // a persisting prompt ignores edits
+    if (evt.name === "return") {
+      const err = spec.validate?.(state.input) ?? null;
+      if (err) {
+        state.error = err;
+        return stack.touch();
+      }
+      stack.pop(state.input);
+      return;
+    }
+    if (evt.name === "backspace") {
+      state.input = state.input.slice(0, -1);
+      state.error = null;
+      return stack.touch();
+    }
+    if (evt.name.length === 1 && !evt.ctrl && !evt.meta) {
+      state.input += evt.shift ? evt.name.toUpperCase() : evt.name;
+      state.error = null;
+      return stack.touch();
+    }
+    return;
+  }
+  // confirm
+  if (evt.name === "up" || evt.name === "left") return stack.setSel(0);
+  if (evt.name === "down" || evt.name === "right") return stack.setSel(1);
+  if (evt.name === "return") return stack.choose(state.sel);
+  if (evt.name === "y") return stack.choose(0);
+  if (evt.name === "n") return stack.choose(1);
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Pure, io-free helpers for the built-in git diff panel (M18.3).
+ *
+ * Like {@link ./editor-buffer.ts}, this imports NOTHING from @opentui/core: the
+ * app runs the git subprocesses (async execFile) and reads untracked files, but
+ * the PARSING and coordinate math live here so they unit-test as tables under
+ * the Node/vitest runner while app.tsx keeps the OpenTUI wiring.
+ *
+ * Three concerns: (1) parse `git status --porcelain` into a flat, display-ready
+ * file list; (2) classify each `git diff` line so the renderer can color it; and
+ * (3) turn an untracked file's contents into an all-additions pseudo-diff (git
+ * diff prints nothing for untracked paths).
+ */
+
+/** One changed file from `git status --porcelain`, display-ready. */
+export interface StatusEntry {
+  /** Single status letter for the list: M(odified) · A(dded) · D(eleted) ·
+   *  R(enamed) · ?(untracked) · etc. Worktree state wins over index state so a
+   *  file staged-then-edited still reads as M. */
+  status: string;
+  /** Repo-relative path (the NEW path for renames). */
+  path: string;
+  /** True when the index carries a change (a staged component exists). */
+  staged: boolean;
+}
+
+/**
+ * PURE — parse porcelain v1 output. Each line is `XY<space>PATH`, where X is the
+ * index state and Y the worktree state; renames/copies render as `orig -> new`.
+ * Untracked files come through as `??`. Malformed/short lines are skipped.
+ */
+export function parseStatusPorcelain(out: string): StatusEntry[] {
+  const entries: StatusEntry[] = [];
+  for (const line of out.split("\n")) {
+    if (line.length < 4) continue;
+    const index = line[0]!;
+    const work = line[1]!;
+    let rest = line.slice(3);
+    const arrow = rest.indexOf(" -> ");
+    if (arrow !== -1) rest = rest.slice(arrow + 4);
+    const untracked = index === "?" && work === "?";
+    const status = untracked ? "?" : work !== " " ? work : index;
+    entries.push({ status, path: rest, staged: !untracked && index !== " " });
+  }
+  return entries;
+}
+
+/** How a unified-diff line renders: added / removed / hunk header / file-meta
+ *  (diff/index/+++/---/mode/rename) / plain context. */
+export type DiffLineKind = "add" | "del" | "hunk" | "meta" | "context";
+
+/** One classified diff line: its kind and its raw text (leading sigil kept). */
+export interface DiffLine {
+  kind: DiffLineKind;
+  text: string;
+}
+
+const META_PREFIXES = [
+  "diff ",
+  "index ",
+  "new file",
+  "deleted file",
+  "old mode",
+  "new mode",
+  "similarity ",
+  "dissimilarity ",
+  "rename ",
+  "copy ",
+  "Binary ",
+  "\\ No newline",
+];
+
+/**
+ * PURE — classify one raw diff line. Order matters: the `+++`/`---` file headers
+ * must be caught as meta BEFORE the bare `+`/`-` add/del checks.
+ */
+export function classifyDiffLine(line: string): DiffLineKind {
+  if (line.startsWith("@@")) return "hunk";
+  if (line.startsWith("+++") || line.startsWith("---")) return "meta";
+  for (const p of META_PREFIXES) if (line.startsWith(p)) return "meta";
+  if (line.startsWith("+")) return "add";
+  if (line.startsWith("-")) return "del";
+  return "context";
+}
+
+/**
+ * PURE — split a `git diff --no-color` blob into classified lines, dropping the
+ * single trailing empty produced by the final newline.
+ */
+export function classifyDiff(diff: string): DiffLine[] {
+  if (!diff) return [];
+  const lines = diff.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.map((text) => ({ kind: classifyDiffLine(text), text }));
+}
+
+/**
+ * PURE — render an untracked file's contents as an all-additions pseudo-diff
+ * (git diff emits nothing for untracked paths). Each content line is prefixed
+ * with `+` so {@link classifyDiff} colors it as an addition.
+ */
+export function untrackedDiffText(content: string): string {
+  const lines = content.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.map((l) => "+" + l).join("\n");
+}
+
+/** PURE — clamp a selection index into `[0, count)` (0 when the list is empty). */
+export function clampSel(sel: number, count: number): number {
+  if (count <= 0) return 0;
+  return Math.max(0, Math.min(sel, count - 1));
+}

package/packages/daemon/src/tui/mirror/editor-buffer.ts

@@ -0,0 +1,117 @@
+/**
+ * Pure, io-free helpers for the built-in file editor panel (M18.2).
+ *
+ * Deliberately imports NOTHING from @opentui/core: the editing ENGINE is a
+ * native `EditBuffer` (bun:ffi), which cannot load under Node/vitest. Everything
+ * that can be unit-tested — binary sniffing, read-only classification, the
+ * line-number gutter, viewport slicing, and click→cursor coordinate math —
+ * lives here so it runs green under the Node test runner while app.tsx keeps
+ * the bun-only EditBuffer wiring.
+ */
+
+/** Files at or above this byte length open read-only (no full-buffer edits on
+ *  the render loop). */
+export const MAX_EDITABLE_BYTES = 1_000_000;
+/** How many leading bytes we sniff for a NUL before calling a file binary. */
+export const BINARY_SNIFF_BYTES = 8000;
+
+/** NUL-byte sniff: a single 0x00 in the leading window means "not text". */
+export function isBinary(bytes: Uint8Array): boolean {
+  const n = Math.min(bytes.length, BINARY_SNIFF_BYTES);
+  for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;
+  return false;
+}
+
+export type ReadOnlyReason = "binary" | "large" | null;
+
+/** Decide whether a freshly-read file is editable, and why not. */
+export function classifyFile(byteLength: number, binary: boolean): ReadOnlyReason {
+  if (binary) return "binary";
+  if (byteLength >= MAX_EDITABLE_BYTES) return "large";
+  return null;
+}
+
+/** Human banner for a read-only reason (null = editable, no banner). */
+export function readOnlyBanner(reason: ReadOnlyReason): string | null {
+  if (reason === "binary") return "read-only · binary file (null byte detected)";
+  if (reason === "large") return `read-only · file ≥ ${MAX_EDITABLE_BYTES / 1_000_000} MB`;
+  return null;
+}
+
+/** Render a binary/undisplayable buffer as a safe ASCII preview: control and
+ *  high bytes become "·" so the rope never carries NULs and the panel stays
+ *  legible. Newlines/tabs are preserved so line structure survives. */
+export function sanitizeForDisplay(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i]!;
+    if (b === 0x09 || b === 0x0a || b === 0x0d || (b >= 0x20 && b <= 0x7e)) {
+      out += String.fromCharCode(b);
+    } else {
+      out += "·";
+    }
+  }
+  return out;
+}
+
+/** Total width of the line-number gutter, including its trailing space. */
+export function gutterWidth(totalLines: number): number {
+  return Math.max(3, String(Math.max(1, totalLines)).length) + 1;
+}
+
+/** Right-aligned line number filling `width` (last column is the separator). */
+export function formatGutter(lineNumber: number, width: number): string {
+  return String(lineNumber).padStart(width - 1, " ") + " ";
+}
+
+/** Clamp the top (first-visible) line so the viewport never scrolls past the
+ *  last screenful. `rows` is the number of text rows on screen. */
+export function clampTop(top: number, totalLines: number, rows: number): number {
+  const max = Math.max(0, totalLines - rows);
+  if (top < 0) return 0;
+  if (top > max) return max;
+  return top;
+}
+
+/** The [start,end) line range visible for a given scroll position. */
+export function visibleRange(
+  totalLines: number,
+  top: number,
+  rows: number,
+): { start: number; end: number } {
+  const start = clampTop(top, totalLines, rows);
+  return { start, end: Math.min(totalLines, start + rows) };
+}
+
+/** Ensure the cursor line sits inside [top, top+rows); returns the new top. */
+export function scrollToCursor(
+  cursorLine: number,
+  top: number,
+  rows: number,
+  totalLines: number,
+): number {
+  let next = top;
+  if (cursorLine < top) next = cursorLine;
+  else if (cursorLine >= top + rows) next = cursorLine - rows + 1;
+  return clampTop(next, totalLines, rows);
+}
+
+/**
+ * Map a click at content-relative coordinates to a buffer (line, col).
+ * `contentY` is rows below the editor header; `cx` is columns right of the
+ * sidebar (gutter included). Both results are clamped to the buffer.
+ */
+export function clickToCursor(params: {
+  cx: number;
+  contentY: number;
+  gutterW: number;
+  top: number;
+  lines: string[];
+}): { line: number; col: number } {
+  const { cx, contentY, gutterW, top, lines } = params;
+  const total = Math.max(1, lines.length);
+  const line = Math.max(0, Math.min(total - 1, top + contentY));
+  const lineText = lines[line] ?? "";
+  const col = Math.max(0, Math.min(lineText.length, cx - gutterW));
+  return { line, col };
+}

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

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ *
+ * 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
+ * "collapses" by removing the contiguous run of deeper rows. Dirs sort before
+ * files, each group alphabetical (case-insensitive), so the tree reads the way
+ * a file manager does.
+ */
+
+/** One row in the flat file list. `path` is absolute; `depth` is the indent
+ *  level (0 = the context dir's immediate children). */
+export interface FileNode {
+  name: string;
+  path: string;
+  isDir: boolean;
+  depth: number;
+  expanded: boolean;
+}
+
+/** A raw `fs.readdir(..., { withFileTypes: true })` entry, reduced to what we
+ *  need (kept minimal so callers can map Dirent → this trivially). */
+export interface RawEntry {
+  name: string;
+  isDir: boolean;
+}
+
+/**
+ * PURE — sort raw entries into display order: directories first, then files,
+ * each group alphabetical case-insensitively (ties broken by raw name for
+ * determinism). Dotfiles are kept (a hidden `.env` still matters to editing).
+ */
+export function sortEntries(entries: RawEntry[]): RawEntry[] {
+  return [...entries].sort((a, b) => {
+    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+    const an = a.name.toLowerCase();
+    const bn = b.name.toLowerCase();
+    if (an < bn) return -1;
+    if (an > bn) return 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+}
+
+/**
+ * PURE — build the flat node list for a directory's `entries` at `depth`,
+ * joining each name onto `dir` with a "/" (absolute-path aware; no node:path
+ * dependency so this stays trivially testable).
+ */
+export function buildNodes(dir: string, entries: RawEntry[], depth: number): FileNode[] {
+  const base = dir.endsWith("/") ? dir.slice(0, -1) : dir;
+  return sortEntries(entries).map((e) => ({
+    name: e.name,
+    path: `${base}/${e.name}`,
+    isDir: e.isDir,
+    depth,
+    expanded: false,
+  }));
+}
+
+/**
+ * PURE — expand the directory at `index` by marking it expanded and splicing
+ * its `children` (already built at the parent's depth+1) in right after it.
+ * A no-op (returns the list unchanged) when the row is missing, is not a
+ * directory, or is already expanded.
+ */
+export function insertChildrenAt(
+  list: FileNode[],
+  index: number,
+  children: FileNode[],
+): FileNode[] {
+  const parent = list[index];
+  if (!parent || !parent.isDir || parent.expanded) return list;
+  const next = [...list];
+  next[index] = { ...parent, expanded: true };
+  next.splice(index + 1, 0, ...children);
+  return next;
+}
+
+/**
+ * PURE — collapse the directory at `index` by marking it un-expanded and
+ * removing the contiguous run of rows deeper than it (its whole subtree,
+ * however many levels were expanded). A no-op when the row is missing, is not a
+ * directory, or is not expanded.
+ */
+export function removeSubtreeAt(list: FileNode[], index: number): FileNode[] {
+  const parent = list[index];
+  if (!parent || !parent.isDir || !parent.expanded) return list;
+  let end = index + 1;
+  while (end < list.length && list[end]!.depth > parent.depth) end++;
+  const next = [...list];
+  next.splice(index + 1, end - (index + 1));
+  next[index] = { ...parent, expanded: false };
+  return next;
+}