@yaag/tui 0.1.0

package/src/terminal-text.ts

@@ -0,0 +1,62 @@
+/**
+ * Removes terminal control sequences from untrusted event text while retaining
+ * printable Unicode and newlines used by Ask output tails.
+ *
+ * Unterminated escape sequences are discarded through the end of the value.
+ */
+export function sanitizeTerminalText(value: string): string {
+  let text = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 27) {
+      index = skipEscape(value, index);
+    } else if (code === 0x9b) {
+      index = skipCsi(value, index + 1);
+    } else if (code === 0x90 || code === 0x98 || code === 0x9d || code === 0x9e || code === 0x9f) {
+      index = skipString(value, index + 1);
+    } else if (isPrintable(code) || code === 10) {
+      text += value[index];
+    }
+  }
+  return text;
+}
+
+/**
+ * Sanitizes untrusted event text for one-line contexts: control sequences are
+ * removed and embedded newlines flatten to single spaces, so a hostile value
+ * cannot forge extra log lines or alter a rendered frame's line structure.
+ */
+export function sanitizeTerminalLine(value: string): string {
+  return sanitizeTerminalText(value).replace(/\n+/g, " ");
+}
+
+function skipEscape(value: string, index: number): number {
+  const next = value.charCodeAt(index + 1);
+  if (next === 91) return skipCsi(value, index + 2);
+  if (next === 93 || next === 80 || next === 88 || next === 94 || next === 95)
+    return skipString(value, index + 2);
+  return index + 1;
+}
+
+function skipCsi(value: string, index: number): number {
+  while (index < value.length) {
+    const code = value.charCodeAt(index);
+    if (code >= 64 && code <= 126) return index;
+    index += 1;
+  }
+  return value.length;
+}
+
+function skipString(value: string, index: number): number {
+  while (index < value.length) {
+    const code = value.charCodeAt(index);
+    if (code === 7 || code === 0x9c) return index;
+    if (code === 27 && value.charCodeAt(index + 1) === 92) return index + 1;
+    index += 1;
+  }
+  return value.length;
+}
+
+function isPrintable(code: number): boolean {
+  return code >= 32 && code !== 127 && (code < 0x80 || code > 0x9f);
+}

package/src/transcript-content.ts

@@ -0,0 +1,42 @@
+/**
+ * The content of one drill-in transcript overlay: the status header of the node's
+ * owning Agent, then that Agent's session transcript.
+ *
+ * A nested node runs with `--no-session`, so its turns live inside the owning
+ * Agent's session file; the node path stays the identity the overlay shows, and
+ * the owning Agent's session file is the read source.
+ */
+import type { AgentInfo } from "@yaag/runtime";
+import { parseTranscript } from "./session-transcript.ts";
+import { NO_TRANSCRIPT_STUB, renderTranscript, transcriptHeader } from "./transcript-render.ts";
+
+/**
+ * One transcript-content request for a single node.
+ *
+ * Contract: `nodePath` is the identity the header shows; `agent` supplies the
+ * header facts of the owning Agent; `session` is that Agent's session body.
+ * Failure mode: a null or unparsable `session` renders `NO_TRANSCRIPT_STUB`
+ * under the same header; no input makes the renderer throw.
+ */
+export interface NodeTranscriptOptions {
+  /** The node path the overlay is titled with (spec §1 node-path grammar). */
+  readonly nodePath: string;
+  /** The owning Agent's observer projection, for the header facts. */
+  readonly agent: AgentInfo;
+  /** The owning Agent's session file body, or null when it is missing. */
+  readonly session: string | null;
+}
+
+/**
+ * Renders the overlay's content lines: header, a blank separator, transcript.
+ *
+ * Never throws: a missing or unparsable session body renders
+ * `NO_TRANSCRIPT_STUB` under a header that still names the node.
+ */
+export function nodeTranscriptLines(options: NodeTranscriptOptions): readonly string[] {
+  const body =
+    options.session === null
+      ? [NO_TRANSCRIPT_STUB]
+      : renderTranscript(parseTranscript(options.session));
+  return [...transcriptHeader(options.nodePath, options.agent), "", ...body];
+}

package/src/transcript-overlay.ts

@@ -0,0 +1,42 @@
+/**
+ * The read-only transcript overlay drawn over the Run tree (spec §1).
+ *
+ * Pure: two calls with the same content and scroll return equal arrays. It holds
+ * no clock and no I/O, so a host refreshes a tailed session file by re-rendering.
+ */
+
+import { renderFramedBox } from "./overlay-frame.ts";
+import { resolveOffset, type Scroll } from "./overlay-scroll.ts";
+
+const FOOTER = " ↑↓ scroll  c copy path  esc back";
+
+/**
+ * One transcript-overlay render request.
+ *
+ * Contract: `content` and `scroll` decide the visible slice; `rows` is the
+ * content row budget; `width` is the exact visible width of every returned
+ * line. Failure mode: empty `content`, a `rows` of zero or less, and a scroll
+ * offset past the end all draw a valid frame instead of throwing.
+ */
+export interface TranscriptOverlayOptions {
+  /** The node path the overlay is titled with (spec §1 node-path grammar). */
+  readonly nodePath: string;
+  /** Already-rendered content lines, from `nodeTranscriptLines`. */
+  readonly content: readonly string[];
+  readonly scroll: Scroll;
+  /** Content rows the overlay may draw; a zero or negative value draws one. */
+  readonly rows: number;
+  readonly width: number;
+}
+
+/** Draws the framed, scrolled overlay for one node's transcript. */
+export function renderTranscriptOverlay(options: TranscriptOverlayOptions): readonly string[] {
+  const rows = Math.max(1, Math.floor(options.rows));
+  const offset = resolveOffset(options.scroll, options.content.length, rows);
+  return renderFramedBox({
+    title: `${options.nodePath} ─ transcript`,
+    lines: options.content.slice(offset, offset + rows),
+    footer: `${FOOTER}  ${options.scroll.following ? "following" : "paused"}`,
+    width: options.width,
+  });
+}

package/src/transcript-render.ts

@@ -0,0 +1,115 @@
+/**
+ * Renders one Agent's Peek: a status header folded from its Summary record, then
+ * its transcript with every item truncated to a few lines. Pure string work — no
+ * clock, no I/O — so the viewer can re-render a tailed session file on a timer.
+ */
+import type { AgentInfo } from "@yaag/runtime";
+import type { TranscriptItem } from "./session-transcript.ts";
+
+/** Shown in place of the transcript when no session file backs an Agent. */
+export const NO_TRANSCRIPT_STUB =
+  "(no transcript available — this Agent has no readable session file)";
+
+export interface TranscriptViewOptions {
+  /** Lines kept per transcript item before an elision marker; defaults to 4. */
+  readonly maxLinesPerItem?: number;
+}
+
+const DEFAULT_MAX_LINES = 4;
+
+/** A one-line-per-fact status header for an Agent, from its Summary projection. */
+export function transcriptHeader(name: string, agent: AgentInfo): readonly string[] {
+  return [
+    `Agent ${name} — ${agent.state}${activitySuffix(agent)}`,
+    `  ask: ${askLabel(agent)}`,
+    `  usage: ${usageLabel(agent)}`,
+  ];
+}
+
+/**
+ * Renders transcript items, each labelled and truncated to `maxLinesPerItem`.
+ *
+ * An empty item list renders the `NO_TRANSCRIPT_STUB` line, so a Cassette-playback
+ * Agent or an unreadable file is labelled rather than hidden.
+ */
+export function renderTranscript(
+  items: readonly TranscriptItem[],
+  options: TranscriptViewOptions = {},
+): readonly string[] {
+  if (items.length === 0) return [NO_TRANSCRIPT_STUB];
+  const max = options.maxLinesPerItem ?? DEFAULT_MAX_LINES;
+  const lines: string[] = [];
+  for (const item of items) {
+    lines.push(label(item));
+    lines.push(...truncate(bodyText(item), max));
+  }
+  return lines;
+}
+
+function label(item: TranscriptItem): string {
+  switch (item.kind) {
+    case "user":
+      return "▶ user";
+    case "assistant":
+      return "◀ assistant";
+    case "thinking":
+      return "· thinking";
+    case "tool-call":
+      return `⚙ tool → ${item.name}(${item.args})`;
+    case "tool-result":
+      return `⚑ result ← ${item.name}${item.isError ? " [error]" : ""}`;
+    default: {
+      const never: never = item;
+      throw new Error(`unhandled transcript item: ${JSON.stringify(never)}`);
+    }
+  }
+}
+
+function bodyText(item: TranscriptItem): string {
+  switch (item.kind) {
+    case "user":
+    case "assistant":
+    case "thinking":
+      return item.text;
+    case "tool-call":
+      return "";
+    case "tool-result":
+      return item.text;
+    default: {
+      const never: never = item;
+      throw new Error(`unhandled transcript item: ${JSON.stringify(never)}`);
+    }
+  }
+}
+
+function truncate(text: string, max: number): readonly string[] {
+  if (text === "") return [];
+  const all = text.split("\n").map((line) => `    ${line}`);
+  if (all.length <= max) return all;
+  return [...all.slice(0, max), `    … (${all.length - max} more lines)`];
+}
+
+function activitySuffix(agent: AgentInfo): string {
+  const activity = agent.activity;
+  if (activity === null) return "";
+  switch (activity.type) {
+    case "tool":
+      return ` · ${activity.name}`;
+    case "retrying":
+      return ` · retrying ${activity.attempt}/${activity.max}`;
+    default:
+      return ` · ${activity.type}`;
+  }
+}
+
+function askLabel(agent: AgentInfo): string {
+  if (agent.state === "asking") return `#${agent.askIndex} ${agent.promptGist}`;
+  if (agent.askIndex === null) return "none yet";
+  return `#${agent.askIndex} (settled)`;
+}
+
+function usageLabel(agent: AgentInfo): string {
+  const cost = agent.cost === null ? "unknown" : `$${agent.cost.toFixed(4)}`;
+  const total = agent.tokens === null ? "unknown" : `${agent.tokens.total} tok`;
+  return `${total}, ${cost}${agent.incomplete ? " (floor)" : ""}`;
+}

package/src/tree-cursor.ts

@@ -0,0 +1,75 @@
+import { type FoldState, visibleRows } from "./tree-fold.ts";
+import type { TreeNode } from "./tree-node.ts";
+
+/**
+ * The ancestor chain of one node, root first and the node itself last, or null
+ * when no node carries the path.
+ *
+ * Ancestry is walked, never parsed out of the path string: a roll-up row's
+ * `agent#pruned` path is outside the node-path grammar (spec §1).
+ */
+export function nodeChain(tree: readonly TreeNode[], path: string): readonly TreeNode[] | null {
+  for (const node of tree) {
+    if (node.path === path) return [node];
+    const below = nodeChain(node.children, path);
+    if (below !== null) return [node, ...below];
+  }
+  return null;
+}
+
+/** The node at one path, or undefined when no node carries it. */
+export function nodeAt(tree: readonly TreeNode[], path: string): TreeNode | undefined {
+  return nodeChain(tree, path)?.at(-1);
+}
+
+/** The parent of one path; undefined for a root node or an unknown path. */
+export function parentOf(tree: readonly TreeNode[], path: string): TreeNode | undefined {
+  return nodeChain(tree, path)?.at(-2);
+}
+
+/**
+ * The visible node the cursor rests on.
+ *
+ * A cursor over a node the current fold hides resolves to its deepest visible
+ * ancestor. This covers both a user fold and the default policy collapsing a
+ * branch on its own once the nested work settles (spec §1). An unknown path,
+ * or none, resolves to the first visible row, so the cursor never disappears.
+ * Returns undefined only for an empty tree.
+ */
+export function resolveSelection(
+  tree: readonly TreeNode[],
+  fold: FoldState,
+  path: string | undefined,
+): string | undefined {
+  const visible = visibleRows(tree, fold);
+  const first = visible[0]?.node.path;
+  if (path === undefined) return first;
+  const chain = nodeChain(tree, path);
+  if (chain === null) return first;
+  const drawn = new Set(visible.map((row) => row.node.path));
+  for (const node of [...chain].reverse()) {
+    if (drawn.has(node.path)) return node.path;
+  }
+  return first;
+}
+
+/**
+ * Moves the cursor `delta` visible rows from where it currently resolves.
+ *
+ * The result clamps to the first and the last visible row — the cursor does
+ * not wrap. Returns undefined only for an empty tree.
+ */
+export function moveSelection(
+  tree: readonly TreeNode[],
+  fold: FoldState,
+  path: string | undefined,
+  delta: number,
+): string | undefined {
+  const visible = visibleRows(tree, fold);
+  if (visible.length === 0) return undefined;
+  const current = resolveSelection(tree, fold, path);
+  const at = visible.findIndex((row) => row.node.path === current);
+  if (at === -1) return visible[0]?.node.path;
+  const next = Math.min(visible.length - 1, Math.max(0, at + delta));
+  return visible[next]?.node.path;
+}

package/src/tree-fold.ts

@@ -0,0 +1,79 @@
+import type { TreeNode } from "./tree-node.ts";
+
+/** Explicit user folds, layered over the default policy (ticket 03 writes here). */
+export interface FoldState {
+  readonly overrides: ReadonlyMap<string, boolean>;
+}
+
+/** The fold state before the user folds anything. */
+export function emptyFold(): FoldState {
+  return { overrides: new Map() };
+}
+
+/**
+ * Whether one node draws its children.
+ *
+ * Default policy: the tree collapses to Agent level, except the paths that
+ * lead to live nested work, so running Nested Nodes are always visible
+ * (spec §1). An Agent with no running Nested Node below it stays collapsed,
+ * even when it is settled or asking. A user override for the node's path wins
+ * over the default.
+ */
+export function isExpanded(node: TreeNode, fold: FoldState): boolean {
+  const override = fold.overrides.get(node.path);
+  if (override !== undefined) return override;
+  if (node.children.length === 0) return false;
+  return leadsToRunningNested(node);
+}
+
+/** One visible row: the node plus the depth and ancestry the renderer draws. */
+export interface VisibleRow {
+  readonly node: TreeNode;
+  readonly depth: number;
+  readonly expanded: boolean;
+  readonly hasChildren: boolean;
+  /** True for the last child at each ancestor level, for `│`/`└` prefixes. */
+  readonly lastAtDepth: readonly boolean[];
+}
+
+/**
+ * Flattens the tree into the rows the renderer draws, in depth-first order.
+ *
+ * A collapsed node contributes its own row only. The row order and the
+ * `lastAtDepth` flags are a pure function of the tree and the fold state.
+ */
+export function visibleRows(tree: readonly TreeNode[], fold: FoldState): readonly VisibleRow[] {
+  const rows: VisibleRow[] = [];
+  collect(tree, fold, 0, [], rows);
+  return rows;
+}
+
+function collect(
+  nodes: readonly TreeNode[],
+  fold: FoldState,
+  depth: number,
+  ancestry: readonly boolean[],
+  rows: VisibleRow[],
+): void {
+  for (const [position, node] of nodes.entries()) {
+    const last = position === nodes.length - 1;
+    const lastAtDepth = [...ancestry, last];
+    const expanded = isExpanded(node, fold);
+    rows.push({
+      node,
+      depth,
+      expanded,
+      hasChildren: node.children.length > 0,
+      lastAtDepth,
+    });
+    if (expanded) collect(node.children, fold, depth + 1, lastAtDepth, rows);
+  }
+}
+
+function leadsToRunningNested(node: TreeNode): boolean {
+  for (const child of node.children) {
+    if (child.kind === "nested" && child.state === "running") return true;
+    if (leadsToRunningNested(child)) return true;
+  }
+  return false;
+}

package/src/tree-glyphs.ts

@@ -0,0 +1,33 @@
+import type { TreeNodeState } from "./tree-node.ts";
+
+/** The glyphs the normative tree mockup uses (`.scratch/run-tree-tui/assets`). */
+export const GLYPHS = {
+  expanded: "▾",
+  collapsed: "▸",
+  running: "●",
+  ok: "✔",
+  failed: "✖",
+  idle: "○",
+  branch: "└",
+  trunk: "│",
+} as const;
+
+/** The state glyph one tree row draws before its label. */
+export function stateGlyph(state: TreeNodeState): string {
+  switch (state) {
+    case "running":
+      return GLYPHS.running;
+    case "exited":
+      return GLYPHS.ok;
+    case "failed":
+      return GLYPHS.failed;
+    case "idle":
+      return GLYPHS.idle;
+  }
+}
+
+/** The fold glyph one tree row draws: expanded, collapsed, or nothing for a leaf. */
+export function foldGlyph(hasChildren: boolean, expanded: boolean): string {
+  if (!hasChildren) return " ";
+  return expanded ? GLYPHS.expanded : GLYPHS.collapsed;
+}

package/src/tree-keys.ts

@@ -0,0 +1,45 @@
+import { getKeybindings } from "@earendil-works/pi-tui";
+import { type KeyBinding, type NamedKeybindings, routeKey } from "./key-router.ts";
+
+/** One navigation gesture the tree consumes (spec §2). */
+export type TreeAction = "selectUp" | "selectDown" | "collapse" | "expand";
+
+/** One row of the tree key table. */
+export type TreeKeyBinding = KeyBinding<TreeAction>;
+
+/**
+ * The one key table the Host Session view and the standalone CLI both route
+ * through (spec §2).
+ *
+ * Named entries come first, so a user who remaps `tui.select.down` onto an
+ * arrow still gets the move rather than the fold.
+ */
+export const TREE_KEY_TABLE: readonly TreeKeyBinding[] = [
+  { action: "selectUp", named: "tui.select.up", vim: ["k"] },
+  { action: "selectDown", named: "tui.select.down", vim: ["j"] },
+  { action: "collapse", keys: ["left"], vim: ["h"] },
+  { action: "expand", keys: ["right"], vim: ["l"] },
+];
+
+/**
+ * Resolves one input byte string to a tree action.
+ *
+ * Returns undefined when the table binds nothing for the input, so the tree
+ * consumes only its own keys and shadows no other pi default binding.
+ */
+export function routeTreeKey(data: string, keybindings: NamedKeybindings): TreeAction | undefined {
+  return routeKey(data, keybindings, TREE_KEY_TABLE);
+}
+
+/**
+ * The standalone CLI's matcher: pi-tui's process-global keybindings manager,
+ * which already carries the user's `keybindings.json` overrides.
+ *
+ * The Host Session path passes pi's injected manager instead — the global is
+ * per pi-tui instance, so a component must never reach for it itself.
+ */
+export function cliKeybindings(): NamedKeybindings {
+  return getKeybindings();
+}
+
+export type { NamedKeybindings } from "./key-router.ts";

package/src/tree-model.ts

@@ -0,0 +1,107 @@
+import type { AgentInfo } from "@yaag/runtime";
+import { costText, tokensText } from "./accounting-text.ts";
+import { activityText } from "./activity-text.ts";
+import type { AskRow } from "./ask-ledger.ts";
+import { durationText } from "./duration-text.ts";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { graftNestedNodes } from "./tree-nested.ts";
+import type { TreeNode } from "./tree-node.ts";
+import type { TreeState } from "./tree-state.ts";
+
+/** Render-time inputs the model needs; `now` keeps every builder clock-free. */
+export interface TreeModelOptions {
+  readonly now: number;
+}
+
+/**
+ * Builds the Run's node tree from the folded state.
+ *
+ * Pure: the same state and options always build the same tree. Agents come in
+ * first-observed order, each Agent's children are its Ask rows, and each Ask's
+ * children are the Nested Nodes grafted under it by path. Pruned rows become
+ * one trailing "and N more finished" roll-up node.
+ */
+export function buildTree(state: TreeState, options: TreeModelOptions): readonly TreeNode[] {
+  const nodes: TreeNode[] = [];
+  for (const name of state.agentOrder) {
+    const agent = state.summary.agents[name];
+    if (agent === undefined) continue;
+    nodes.push(agentNode(state, name, agent, options.now));
+  }
+  return nodes;
+}
+
+function agentNode(state: TreeState, name: string, agent: AgentInfo, now: number): TreeNode {
+  const ledger = state.ledger(name);
+  const nested = graftNestedNodes(name, agent.nodes, now);
+  const gist = agent.activity === null ? null : activityText(agent.activity);
+  const children: TreeNode[] = ledger.rows.map((row) =>
+    askNode(name, row, nested.get(row.index) ?? [], now, gist),
+  );
+  const finished = agent.finishedNodesPruned + ledger.settledPruned;
+  if (finished > 0) children.push(rollup(`${name}#pruned`, `and ${finished} more finished`));
+  return {
+    path: sanitizeTerminalLine(name),
+    kind: "agent",
+    label: sanitizeTerminalLine(name),
+    state: agentState(agent),
+    facts: agentFacts(agent, state.settledAsks(name), now),
+    children,
+    activityGist: gist,
+    startedAt: agent.stateChangedAt,
+  };
+}
+
+function askNode(
+  agent: string,
+  row: AskRow,
+  children: readonly TreeNode[],
+  now: number,
+  activityGist: string | null,
+): TreeNode {
+  const live = row.endedAt === null;
+  const dwell = live ? now - (row.startedAt ?? now) : row.endedAt - (row.startedAt ?? row.endedAt);
+  const facts = [durationText(dwell)];
+  if (row.replayed) facts.push("replayed");
+  return {
+    path: `${sanitizeTerminalLine(agent)}:${row.index}`,
+    kind: "ask",
+    label: `ask #${row.index + 1}${row.promptGist === "" ? "" : `  “${row.promptGist}”`}`,
+    state: live ? "running" : row.ok === false ? "failed" : "exited",
+    facts,
+    children,
+    activityGist: live ? activityGist : null,
+    startedAt: row.startedAt,
+  };
+}
+
+function rollup(path: string, label: string): TreeNode {
+  return {
+    path,
+    kind: "rollup",
+    label,
+    state: "idle",
+    facts: [],
+    children: [],
+    activityGist: null,
+    startedAt: null,
+  };
+}
+
+function agentState(agent: AgentInfo): TreeNode["state"] {
+  if (agent.state === "exited") return "exited";
+  return agent.state === "asking" ? "running" : "idle";
+}
+
+function agentFacts(agent: AgentInfo, settled: number, now: number): readonly string[] {
+  const facts: string[] = [];
+  if (agent.state === "asking")
+    facts.push(`ask #${agent.askIndex + 1} · ${durationText(now - (agent.askStartedAt ?? now))}`);
+  else if (agent.state === "exited")
+    facts.push(`exited · ${settled} ask${settled === 1 ? "" : "s"}`);
+  else facts.push(`idle · ${durationText(now - (agent.stateChangedAt ?? now))}`);
+  facts.push(
+    `${costText(agent.cost, agent.incomplete)} · ${tokensText(agent.tokens?.total ?? null)}`,
+  );
+  return facts;
+}

package/src/tree-navigation.ts

@@ -0,0 +1,76 @@
+import { moveSelection, nodeAt, parentOf, resolveSelection } from "./tree-cursor.ts";
+import { emptyFold, type FoldState, isExpanded } from "./tree-fold.ts";
+import type { TreeAction } from "./tree-keys.ts";
+import type { TreeNode } from "./tree-node.ts";
+
+/** Where the cursor rests, and which nodes the user folded by hand. */
+export interface TreeView {
+  readonly selectedPath?: string;
+  readonly fold: FoldState;
+}
+
+/** The view before the user moves or folds anything. */
+export function emptyView(): TreeView {
+  return { fold: emptyFold() };
+}
+
+/**
+ * Applies one navigation action and returns the next view.
+ *
+ * Pure: it copies the fold overrides rather than writing through them, so a
+ * caller keeping an earlier view keeps an unchanged one. `collapse` on an
+ * expanded node folds it; on a collapsed node or a leaf it moves the cursor to
+ * the parent instead (spec §2). `expand` on a leaf changes nothing.
+ */
+export function applyTreeAction(
+  tree: readonly TreeNode[],
+  view: TreeView,
+  action: TreeAction,
+): TreeView {
+  const selected = resolveSelection(tree, view.fold, view.selectedPath);
+  switch (action) {
+    case "selectUp":
+      return { ...view, selectedPath: moveSelection(tree, view.fold, selected, -1) };
+    case "selectDown":
+      return { ...view, selectedPath: moveSelection(tree, view.fold, selected, 1) };
+    case "collapse":
+      return collapse(tree, view, selected);
+    case "expand":
+      return expand(tree, view, selected);
+    default: {
+      const never: never = action;
+      throw new Error(`unhandled tree action: ${JSON.stringify(never)}`);
+    }
+  }
+}
+
+function collapse(
+  tree: readonly TreeNode[],
+  view: TreeView,
+  selected: string | undefined,
+): TreeView {
+  const node = selectedNode(tree, selected);
+  if (node === undefined) return { ...view, selectedPath: selected };
+  if (node.children.length > 0 && isExpanded(node, view.fold))
+    return { selectedPath: node.path, fold: withOverride(view.fold, node.path, false) };
+  return { ...view, selectedPath: parentOf(tree, node.path)?.path ?? node.path };
+}
+
+function expand(tree: readonly TreeNode[], view: TreeView, selected: string | undefined): TreeView {
+  const node = selectedNode(tree, selected);
+  if (node === undefined || node.children.length === 0) return { ...view, selectedPath: selected };
+  return { selectedPath: node.path, fold: withOverride(view.fold, node.path, true) };
+}
+
+function selectedNode(
+  tree: readonly TreeNode[],
+  selected: string | undefined,
+): TreeNode | undefined {
+  return selected === undefined ? undefined : nodeAt(tree, selected);
+}
+
+function withOverride(fold: FoldState, path: string, expanded: boolean): FoldState {
+  const overrides = new Map(fold.overrides);
+  overrides.set(path, expanded);
+  return { overrides };
+}