tmux-ide 2.6.1 → 2.8.0

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

@@ -0,0 +1,322 @@
+/**
+ * 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
+ * "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.
+ */
+
+/** 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). `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). `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;
+  });
+}
+
+/**
+ * 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,
+    ignored: e.ignored ?? 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;
+}
+
+// ── 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/focus-border.ts

@@ -0,0 +1,57 @@
+/**
+ * Focus-border geometry (M22.7): the accent strips drawn in the canvas GUTTER
+ * cells around the focused pane, so focus is pane-level obvious without
+ * consuming any terminal cells (a real box border would shrink the grid).
+ *
+ * Strips exist only where the pane has a neighboring gutter INSIDE the canvas —
+ * a pane flush to a canvas edge has no room on that side (tmux gives edge panes
+ * flush edges), and a single-pane window renders no strips at all (there is no
+ * ambiguity to resolve, and no gutters to paint). Horizontal strips extend one
+ * cell into the adjacent vertical gutters so the corners fill.
+ *
+ * PURE — rect math only; the app renders each strip as one background-tinted
+ * box, and the strips are handler-less so gutter presses still bubble to the
+ * central router (border drags keep working).
+ */
+
+export interface PaneRectLike {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface FocusStrip {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * The gutter strips around `pane` within a `cols`×`rows` canvas — empty when
+ * the window has a single pane (`paneCount < 2`) or the rect is degenerate.
+ */
+export function focusStrips(
+  pane: PaneRectLike,
+  cols: number,
+  rows: number,
+  paneCount: number,
+): FocusStrip[] {
+  if (paneCount < 2) return [];
+  if (pane.width <= 0 || pane.height <= 0) return [];
+  const strips: FocusStrip[] = [];
+  const hasLeft = pane.left > 0;
+  const hasRight = pane.left + pane.width < cols;
+  const hasTop = pane.top > 0;
+  const hasBottom = pane.top + pane.height < rows;
+  // Horizontal strips reach into the side gutters so corners fill.
+  const hx = hasLeft ? pane.left - 1 : pane.left;
+  const hw = pane.width + (hasLeft ? 1 : 0) + (hasRight ? 1 : 0);
+  if (hasTop) strips.push({ left: hx, top: pane.top - 1, width: hw, height: 1 });
+  if (hasBottom) strips.push({ left: hx, top: pane.top + pane.height, width: hw, height: 1 });
+  if (hasLeft) strips.push({ left: pane.left - 1, top: pane.top, width: 1, height: pane.height });
+  if (hasRight)
+    strips.push({ left: pane.left + pane.width, top: pane.top, width: 1, height: pane.height });
+  return strips;
+}

package/packages/daemon/src/tui/mirror/folder-picker.ts

@@ -0,0 +1,124 @@
+/**
+ * The "open a folder" picker's PURE model (M22.5) — the filesystem browser
+ * behind the home screen's non-technical entry point. The picker is a
+ * {@link ../mirror/dialog-stack.ts} DialogSelect flow: app.tsx does the async
+ * `readdir`/`stat` (the header's async-only fs law) and drives the browse loop;
+ * everything here — how a directory's entries become rows, how the breadcrumb
+ * reads, how a typed path expands, how an invalid path is explained — is pure so
+ * it unit-tests without OpenTUI or a filesystem.
+ *
+ * Row id scheme (what a chosen row dispatches on):
+ *   picker:open            → open the folder we are browsing
+ *   picker:hidden          → toggle whether dot-leading folders show
+ *   picker:up              → ascend to the parent
+ *   picker:type            → the "type a path…" escape hatch (a DialogPrompt)
+ *   picker:dir:<name>      → descend into <name>
+ *
+ * The hidden-folders toggle is a ROW (not a ctrl chord): terminal-native,
+ * `ctrl+h` is byte-identical to Backspace, so a chord can't carry it — and a
+ * row is mouse-clickable and keyboard-selectable, which suits the audience.
+ */
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import type { DialogSelectItem } from "./dialog-model.ts";
+
+export const PICKER_OPEN_ID = "picker:open";
+export const PICKER_HIDDEN_ID = "picker:hidden";
+export const PICKER_UP_ID = "picker:up";
+export const PICKER_TYPE_ID = "picker:type";
+export const PICKER_DIR_PREFIX = "picker:dir:";
+
+/** How many breadcrumb segments the title keeps before eliding the front with
+ *  an ellipsis (deep paths stay one readable line). */
+const BREADCRUMB_MAX_SEGMENTS = 4;
+
+/** PURE — expand a user-typed path: a leading `~` (or `~/…`) becomes `home`,
+ *  then relative paths resolve against `base`. An absolute path is returned as
+ *  given (normalized). Blank input resolves to `base`. */
+export function expandUserPath(input: string, home: string, base: string): string {
+  const raw = input.trim();
+  if (raw.length === 0) return base;
+  if (raw === "~") return home;
+  if (raw.startsWith("~/")) return join(home, raw.slice(2));
+  if (isAbsolute(raw)) return resolve(raw);
+  return resolve(base, raw);
+}
+
+/** PURE — the parent directory, stopping at the filesystem root (dirname of
+ *  `/` is `/`). */
+export function pickerParent(dir: string): string {
+  return dirname(dir);
+}
+
+/** PURE — whether `dir` is the filesystem root (no higher parent). */
+export function isPickerRoot(dir: string): boolean {
+  return dirname(dir) === dir;
+}
+
+/** PURE — the subdirectory names to show: hidden (dot-leading) folders are
+ *  dropped unless `showHidden`, `.`/`..` never appear, and the rest sort
+ *  case-insensitively so the list reads like a file manager. */
+export function filterDirs(names: readonly string[], showHidden: boolean): string[] {
+  return names
+    .filter((n) => n !== "." && n !== "..")
+    .filter((n) => showHidden || !n.startsWith("."))
+    .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+}
+
+/** PURE — a compact breadcrumb for the dialog title: the home prefix collapses
+ *  to `~`, segments join with ` › `, and a path deeper than
+ *  {@link BREADCRUMB_MAX_SEGMENTS} elides its front with `…`. The root shows as
+ *  `/`. */
+export function pickerBreadcrumb(dir: string, home: string): string {
+  let rest = dir;
+  let head = "";
+  if (home.length > 0 && (dir === home || dir.startsWith(`${home}/`))) {
+    head = "~";
+    rest = dir.slice(home.length);
+  }
+  const segs = rest.split("/").filter(Boolean);
+  const parts = head ? [head, ...segs] : segs;
+  if (parts.length === 0) return "/";
+  if (parts.length <= BREADCRUMB_MAX_SEGMENTS) return parts.join(" › ");
+  return ["…", ...parts.slice(parts.length - BREADCRUMB_MAX_SEGMENTS)].join(" › ");
+}
+
+/** PURE — the picker rows for a directory: an explicit "open this folder" row
+ *  first, then the hidden-folders toggle, the ascend row (unless at the root),
+ *  the subdirectories (already filtered/sorted by {@link filterDirs}), and the
+ *  "type a path…" escape hatch last. Descending happens on a `picker:dir:*` /
+ *  `picker:up` row; opening on `picker:open`; the toggle flips `showHidden`. */
+export function pickerRows(
+  dir: string,
+  subdirs: readonly string[],
+  showHidden: boolean,
+): DialogSelectItem[] {
+  const rows: DialogSelectItem[] = [
+    { id: PICKER_OPEN_ID, label: "＋ Open this folder", detail: basename(dir) || dir },
+    {
+      id: PICKER_HIDDEN_ID,
+      label: showHidden ? "Hide hidden folders" : "Show hidden folders",
+      detail: showHidden ? "on" : "off",
+    },
+  ];
+  if (!isPickerRoot(dir)) rows.push({ id: PICKER_UP_ID, label: "..", detail: "up a level" });
+  for (const name of subdirs) rows.push({ id: `${PICKER_DIR_PREFIX}${name}`, label: `${name}/` });
+  rows.push({ id: PICKER_TYPE_ID, label: "Type a path…", detail: "enter a folder path" });
+  return rows;
+}
+
+/** PURE — the subdirectory name a `picker:dir:*` row descends into, or null for
+ *  any other id. */
+export function pickerDirName(id: string): string | null {
+  return id.startsWith(PICKER_DIR_PREFIX) ? id.slice(PICKER_DIR_PREFIX.length) : null;
+}
+
+/** The three outcomes of stat-ing a typed path. */
+export type PathKind = "dir" | "file" | "missing";
+
+/** PURE — the plain-language footer error for a typed path that isn't a folder
+ *  (never called for `"dir"` — that path is accepted). */
+export function pathKindHint(kind: "file" | "missing"): string {
+  return kind === "file"
+    ? "That's a file, not a folder — pick a directory"
+    : "No folder there — check the path and try again";
+}

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

@@ -0,0 +1,174 @@
+/**
+ * The HOME panel's row model (M21.9) — PURE so it unit-tests without OpenTUI.
+ *
+ * Home used to be a flat list of live sessions; now it is a list of ITEMS:
+ * every live session (unchanged, first), then — when the project registry has
+ * projects with no live session — a section header followed by one launchable
+ * row per registered-but-not-running project. That surfaces the registry as a
+ * mouse-first "open project" affordance: clicking (or pressing enter on) a
+ * project row launches a detached session in its dir and opens it as the
+ * workspace.
+ *
+ * The item list is what the render walks AND what the router's `gy - 2` row
+ * math indexes, so selection/hover/click all share one geometry. Headers are
+ * not selectable; the step/clamp helpers keep the keyboard selection on real
+ * rows without the app hand-rolling skip loops.
+ */
+import { basename } from "node:path";
+import type { AgentStatus } from "../detect/classify.ts";
+import type { AppKeys } from "../../lib/app-config.ts";
+import { prefixTwinFor } from "./settings-model.ts";
+
+/** A live tmux session row — click/enter opens it as the workspace. */
+export interface HomeSessionItem {
+  kind: "session";
+  session: string;
+  project: string;
+  status: AgentStatus;
+  windows: number;
+  dir: string | null;
+}
+/** A registered project with no live session — click/enter launches it. */
+export interface HomeProjectItem {
+  kind: "project";
+  name: string;
+  dir: string | null;
+}
+/** A recently-opened folder with no live session or registry entry (M22.5) —
+ *  click/enter re-opens it (create-or-attach a session in `dir`). */
+export interface HomeRecentItem {
+  kind: "recent";
+  name: string;
+  dir: string;
+}
+/** A non-selectable section label between the sessions and the registry. */
+export interface HomeHeaderItem {
+  kind: "header";
+  label: string;
+}
+export type HomeItem = HomeSessionItem | HomeProjectItem | HomeRecentItem | HomeHeaderItem;
+
+/** The slice of the `tmux-ide team --json` payload this model reads (kept
+ *  structural so the app's locally-declared fleet shape satisfies it). */
+export interface HomeFleetProject {
+  name: string;
+  dir: string | null;
+  registered: boolean;
+  running: boolean;
+  sessions: Array<{
+    name: string;
+    status: AgentStatus;
+    windows: Array<unknown>;
+  }>;
+}
+
+export const REGISTRY_HEADER_LABEL = "registered projects — not running";
+export const RECENTS_HEADER_LABEL = "recently opened";
+
+/** PURE — the ordered home items: every project's live sessions first (the
+ *  exact rows home always showed), then a header + one row per registered
+ *  project that has no live session, then (M22.5) a "recently opened" section.
+ *  Recents dedupe against the REGISTRY (registry wins) — a folder you saved as
+ *  a project shows only as its project row, never doubled as a recent. Recents
+ *  are NOT deduped against live sessions: opening a folder spins up a session,
+ *  yet the folder still belongs in "recent" for one-click reopen later. */
+export function buildHomeItems(
+  projects: readonly HomeFleetProject[],
+  recents: readonly string[] = [],
+): HomeItem[] {
+  const items: HomeItem[] = [];
+  for (const p of projects) {
+    for (const s of p.sessions) {
+      items.push({
+        kind: "session",
+        session: s.name,
+        project: p.name,
+        status: s.status,
+        windows: s.windows.length,
+        dir: p.dir,
+      });
+    }
+  }
+  const idle = projects.filter((p) => p.registered && !p.running);
+  if (idle.length > 0) {
+    items.push({ kind: "header", label: REGISTRY_HEADER_LABEL });
+    for (const p of idle) items.push({ kind: "project", name: p.name, dir: p.dir });
+  }
+  // A folder already saved as a registered project is not repeated under
+  // "recent" (registry wins the dedupe).
+  const registeredDirs = new Set<string>();
+  for (const p of projects) if (p.dir && p.registered) registeredDirs.add(p.dir);
+  const freshRecents = recents.filter((d) => d.length > 0 && !registeredDirs.has(d));
+  if (freshRecents.length > 0) {
+    items.push({ kind: "header", label: RECENTS_HEADER_LABEL });
+    for (const dir of freshRecents) {
+      items.push({ kind: "recent", name: basename(dir) || dir, dir });
+    }
+  }
+  return items;
+}
+
+/** PURE — first-run when the fleet has no live sessions AND no registered
+ *  projects (M22.5). Recently-opened folders alone do NOT count — the welcome
+ *  still greets someone who has only browsed folders, and hides the moment a
+ *  session or project exists. */
+export function isFirstRun(projects: readonly HomeFleetProject[]): boolean {
+  const hasSession = projects.some((p) => p.sessions.length > 0);
+  const hasProject = projects.some((p) => p.registered);
+  return !hasSession && !hasProject;
+}
+
+/** PURE — the one-line first-run tip built from the USER'S ACTUAL keybindings
+ *  (M22.5): the reliable `prefix <letter>` twin for each action, falling back
+ *  to the raw Alt key when a letter is claimed by a stock tmux bind. */
+export function firstRunTip(keys: AppKeys): string {
+  const k = (alt: string): string => {
+    const twin = prefixTwinFor(alt);
+    return twin ? `prefix ${twin}` : alt;
+  };
+  return `Your keys: ${k(keys.home)} home · ${k(keys.popup)} switch sessions · ${k(keys.menu)} actions`;
+}
+
+/** PURE — the leading-space padding that horizontally centers a `len`-wide run
+ *  in a `width`-wide area (never negative). Shared by the welcome render and
+ *  the click router so a centered clickable lands where it is drawn. */
+export function centerPad(width: number, len: number): number {
+  return Math.max(0, Math.floor((width - len) / 2));
+}
+
+/** PURE — whether an item takes selection / clicks as a row. */
+export function isSelectable(item: HomeItem | undefined): boolean {
+  return item !== undefined && item.kind !== "header";
+}
+
+/** PURE — clamp a selection index onto a selectable item: into range first,
+ *  then the nearest selectable at-or-above, falling back downward. Returns 0
+ *  for an empty list (matching the old `Math.min(sel, len - 1)` behavior). */
+export function clampSelectable(items: readonly HomeItem[], sel: number): number {
+  if (items.length === 0) return 0;
+  const start = Math.max(0, Math.min(sel, items.length - 1));
+  for (let i = start; i < items.length; i++) if (isSelectable(items[i])) return i;
+  for (let i = start - 1; i >= 0; i--) if (isSelectable(items[i])) return i;
+  return 0;
+}
+
+/** PURE — move the selection one selectable row in `delta`'s direction (±1),
+ *  skipping headers; stays put at either end. */
+export function stepSelectable(items: readonly HomeItem[], from: number, delta: 1 | -1): number {
+  for (let i = from + delta; i >= 0 && i < items.length; i += delta) {
+    if (isSelectable(items[i])) return i;
+  }
+  return from;
+}
+
+/** PURE — a tmux-legal session name for a project: tmux forbids `:` and `.`
+ *  in session names (target syntax), and spaces only invite quoting bugs —
+ *  all collapse to `-`. */
+export function sessionNameFor(project: string): string {
+  return project.replace(/[.:\s]+/g, "-");
+}
+
+/** PURE — whether a user-typed session name is directly usable. */
+export function isValidSessionName(name: string): boolean {
+  return name.length > 0 && !/[.:\s]/.test(name);
+}