tmux-ide 2.6.0 → 2.7.0

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;
+}

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);
+}