@kitlangton/motel 0.1.0

package/src/ui/waterfallNav.repro.test.ts

@@ -0,0 +1,263 @@
+/**
+ * End-to-end reproducer for the waterfall collapse/expand bug.
+ *
+ * Strategy:
+ * 1. Seed a deterministic trace with a parent span and three leaf children
+ *    into a fresh SQLite database.
+ * 2. Launch the motel TUI under tuistory pointing at that database.
+ * 3. Drive keys to navigate onto the parent span, capture a baseline snapshot.
+ * 4. Press `h` (collapse) then `l` (expand). Capture again.
+ * 5. Assert: the visible waterfall body before === after. Today this fails
+ *    because the first child silently disappears from the visible list after
+ *    a collapse/expand cycle.
+ *
+ * Skipped automatically when `tuistory` is not installed.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "bun:test"
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+const TUISTORY_BIN = "tuistory"
+const SESSION = `motel-repro-${Date.now()}`
+
+// ---------------------------------------------------------------------------
+// tuistory wrappers
+// ---------------------------------------------------------------------------
+
+const hasTuistory = async () => {
+	try {
+		const proc = Bun.spawn({ cmd: ["which", TUISTORY_BIN], stdout: "pipe", stderr: "ignore" })
+		const code = await proc.exited
+		return code === 0
+	} catch {
+		return false
+	}
+}
+
+const tui = async (args: readonly string[]): Promise<{ code: number; stdout: string; stderr: string }> => {
+	const proc = Bun.spawn({ cmd: [TUISTORY_BIN, ...args], stdout: "pipe", stderr: "pipe" })
+	const [stdout, stderr] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+	])
+	const code = await proc.exited
+	return { code, stdout, stderr }
+}
+
+const snapshot = async () => (await tui(["snapshot", "--session", SESSION])).stdout
+
+const press = async (...keys: string[]) => {
+	await tui(["press", "--session", SESSION, ...keys])
+	// small settle so the next snapshot reflects the keypress
+	await Bun.sleep(120)
+}
+
+// Slice out just the waterfall body region from a snapshot. The waterfall
+// always sits between the last two horizontal dividers (the one just below
+// the trace meta / pane header, and the one above the footer). Using the
+// *last* pair makes the helper robust to layout changes that add or remove
+// header dividers (breadcrumbs, split-divider junctions, etc.).
+//
+// In wide (side-by-side) mode each line also contains the trace list on the
+// left half separated by `│`. The list renders relative ages like "6s / 7s"
+// that drift between snapshots; strip everything left of the first `│` so
+// only the waterfall contributes to the comparison.
+const waterfallBody = (snap: string): readonly string[] => {
+	const lines = snap.split("\n")
+	const dividerIdxs: number[] = []
+	for (let i = 0; i < lines.length; i++) {
+		if (lines[i]!.startsWith("─")) dividerIdxs.push(i)
+	}
+	if (dividerIdxs.length < 2) return []
+	const start = dividerIdxs[dividerIdxs.length - 2]! + 1
+	const end = dividerIdxs[dividerIdxs.length - 1]!
+	return lines.slice(start, end).map((line) => {
+		const barIdx = line.indexOf("\u2502")
+		const sliced = barIdx >= 0 ? line.slice(barIdx) : line
+		return sliced.replace(/\s+$/g, "")
+	})
+}
+
+// ---------------------------------------------------------------------------
+// Test fixture: temp DB with a deterministic trace
+// ---------------------------------------------------------------------------
+
+// Structure (kept in sync with src/ui/waterfallNav.repro.seed.ts):
+//   root.op
+//   ├─ siblingBefore.op
+//   ├─ parent.op            <- the one we collapse / expand
+//   │  ├─ childA.op (1st)   <- the one that used to disappear after a cycle
+//   │  ├─ childB.op
+//   │  ├─ childC.op
+//   │  ├─ childD.op
+//   │  ├─ childE.op
+//   │  └─ childF.op
+//   ├─ siblingAfter.op
+//   └─ tail.op
+//      └─ tailChild.op
+//         └─ tailGrandchild.op
+const SERVICE_NAME = "waterfall-repro"
+
+describe("waterfall collapse/expand (end-to-end TUI)", () => {
+	const tempDir = mkdtempSync(join(tmpdir(), "motel-repro-"))
+	const dbPath = join(tempDir, "telemetry.sqlite")
+	const lastServicePath = join(tempDir, "last-service.txt")
+	let canRun = false
+
+	beforeAll(async () => {
+		canRun = await hasTuistory()
+		if (!canRun) return
+
+		// Pin selected service so the TUI lands on our seeded trace immediately.
+		writeFileSync(lastServicePath, SERVICE_NAME)
+
+		// Seed the DB in a child process. Doing it in-process collides with
+		// other tests that imported config.ts first (databasePath is captured at
+		// module load time and ESM cache busts on the runtime entry alone do not
+		// invalidate the transitively cached config module).
+		const seed = Bun.spawn({
+			cmd: ["bun", "run", "src/ui/waterfallNav.repro.seed.ts"],
+			cwd: process.cwd(),
+			env: {
+				...process.env,
+				MOTEL_OTEL_DB_PATH: dbPath,
+				MOTEL_OTEL_RETENTION_HOURS: "24",
+				MOTEL_OTEL_ENABLED: "false",
+			},
+			stdout: "pipe",
+			stderr: "pipe",
+		})
+		const seedCode = await seed.exited
+		if (seedCode !== 0) {
+			const [out, err] = await Promise.all([
+				new Response(seed.stdout).text(),
+				new Response(seed.stderr).text(),
+			])
+			throw new Error(`Seed subprocess failed (${seedCode})\nstdout: ${out}\nstderr: ${err}`)
+		}
+
+		// Make sure no stale session is hanging around with the same name.
+		await tui(["close", "--session", SESSION])
+
+		// Launch the TUI. We use a dedicated entry point (src/index.tsx) and a
+		// generous viewport so the waterfall isn't truncated.
+		const launch = await tui([
+			"launch",
+			"bun run src/index.tsx",
+			"--session", SESSION,
+			"--cols", "160",
+			"--rows", "40",
+			"--cwd", process.cwd(),
+			"--env", `MOTEL_OTEL_DB_PATH=${dbPath}`,
+			"--env", "MOTEL_OTEL_ENABLED=false",
+			"--timeout", "15000",
+		])
+		if (launch.code !== 0) {
+			throw new Error(`tuistory launch failed: ${launch.stderr || launch.stdout}`)
+		}
+
+		// Wait for the trace row to appear.
+		const waitResult = await tui(["wait", "root.op", "--session", SESSION, "--timeout", "10000"])
+		if (waitResult.code !== 0) {
+			const snap = (await tui(["snapshot", "--session", SESSION])).stdout
+			throw new Error(`Trace did not appear in TUI after seed.\nstderr: ${waitResult.stderr}\nstdout: ${waitResult.stdout}\nSnapshot:\n${snap}`)
+		}
+		await tui(["wait-idle", "--session", SESSION, "--timeout", "5000"])
+	}, 60_000)
+
+	afterAll(async () => {
+		if (canRun) {
+			await tui(["close", "--session", SESSION])
+		}
+		try {
+			rmSync(tempDir, { recursive: true, force: true })
+		} catch {}
+	})
+
+	it("collapse → expand cycle preserves the visible span list", async () => {
+		if (!canRun) return // tuistory unavailable: skip
+
+		// Enter the span navigation pane.
+		await press("return")
+		// Visible order: root, siblingBefore, parent, childA..F, siblingAfter, tail, tailChild, tailGrandchild
+		// Move down to parent.op (index 2): two j presses.
+		await press("j")
+		await press("j")
+
+		const before = waterfallBody(await snapshot())
+		const beforeText = before.join("\n")
+		// Sanity: every operation should be visible.
+		for (const op of [
+			"parent.op", "childA.op", "childB.op", "childC.op",
+			"childD.op", "childE.op", "childF.op",
+			"siblingBefore.op", "siblingAfter.op",
+			"tail.op", "tailChild.op", "tailGrandchild.op",
+		]) {
+			expect(beforeText).toContain(op)
+		}
+
+		// Collapse parent.op
+		await press("h")
+		const collapsedText = waterfallBody(await snapshot()).join("\n")
+		expect(collapsedText).toContain("parent.op")
+		for (const child of ["childA.op", "childB.op", "childC.op", "childD.op", "childE.op", "childF.op"]) {
+			expect(collapsedText).not.toContain(child)
+		}
+
+		// Expand parent.op
+		await press("l")
+		const after = waterfallBody(await snapshot())
+		const afterText = after.join("\n")
+
+		// Every child must reappear after expand.
+		for (const child of ["childA.op", "childB.op", "childC.op", "childD.op", "childE.op", "childF.op"]) {
+			expect(afterText).toContain(child)
+		}
+		// Sibling structure must remain intact.
+		expect(afterText).toContain("siblingBefore.op")
+		expect(afterText).toContain("siblingAfter.op")
+		expect(afterText).toContain("tailGrandchild.op")
+
+		// And the waterfall body should be byte-identical to baseline.
+		expect(after).toEqual(before)
+	}, 60_000)
+
+	it("a SINGLE collapse/expand cycle does not drift the visible list", async () => {
+		if (!canRun) return
+
+		await press("escape")
+		await press("escape")
+		await press("return")
+		await press("j")
+		await press("j")
+
+		const baseline = waterfallBody(await snapshot())
+		await press("h")
+		await press("l")
+		const after = waterfallBody(await snapshot())
+		expect(after).toEqual(baseline)
+	}, 60_000)
+
+	it("repeated h/l cycles do not drift the visible list", async () => {
+		if (!canRun) return
+
+		// Reset by re-entering nav: esc out of any sub-mode then re-enter.
+		await press("escape")
+		await press("escape")
+		await press("return")
+		await press("j") // siblingBefore
+		await press("j") // parent
+
+		const baseline = waterfallBody(await snapshot())
+
+		for (let i = 0; i < 5; i++) {
+			await press("h")
+			await press("l")
+		}
+
+		const after = waterfallBody(await snapshot())
+		expect(after).toEqual(baseline)
+	}, 60_000)
+})

package/src/ui/waterfallNav.test.ts

@@ -0,0 +1,422 @@
+import { describe, expect, it } from "bun:test"
+import type { TraceSpanItem } from "../domain.ts"
+import {
+	findFirstChildIndex,
+	findParentIndex,
+	getWaterfallColumns,
+	getVisibleSpans,
+} from "./Waterfall.tsx"
+import { resolveCollapseStep } from "./waterfallNav.ts"
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+const mkSpan = (spanId: string, depth: number, parentSpanId: string | null): TraceSpanItem => ({
+	spanId,
+	parentSpanId,
+	serviceName: "svc",
+	scopeName: null,
+	kind: null,
+	operationName: spanId,
+	startTime: new Date(0),
+	isRunning: false,
+	durationMs: 1,
+	status: "ok",
+	depth,
+	tags: {},
+	warnings: [],
+	events: [],
+})
+
+/**
+ * A reusable, depth-first ordered span tree.
+ *
+ *  root        (0)
+ *  ├─ a        (1)
+ *  │  ├─ a1   (2)
+ *  │  └─ a2   (2)
+ *  ├─ b        (1)
+ *  │  └─ b1   (2)
+ *  │     └─ b1a (3)
+ *  └─ c        (1)
+ */
+const buildTree = (): readonly TraceSpanItem[] => [
+	mkSpan("root", 0, null),
+	mkSpan("a", 1, "root"),
+	mkSpan("a1", 2, "a"),
+	mkSpan("a2", 2, "a"),
+	mkSpan("b", 1, "root"),
+	mkSpan("b1", 2, "b"),
+	mkSpan("b1a", 3, "b1"),
+	mkSpan("c", 1, "root"),
+]
+
+const idsOf = (spans: readonly TraceSpanItem[]) => spans.map((s) => s.spanId)
+const indexOfId = (spans: readonly TraceSpanItem[], id: string) => spans.findIndex((s) => s.spanId === id)
+
+// Convenience: run resolveCollapseStep with the selection identified by spanId.
+const step = (
+	spans: readonly TraceSpanItem[],
+	collapsed: ReadonlySet<string>,
+	selectedSpanId: string | null,
+	direction: "left" | "right",
+) => {
+	const visible = getVisibleSpans(spans, collapsed)
+	const selectedIndex = selectedSpanId === null ? -1 : visible.findIndex((s) => s.spanId === selectedSpanId)
+	const out = resolveCollapseStep({
+		spans,
+		collapsed,
+		selectedIndex: selectedIndex < 0 ? null : selectedIndex,
+		direction,
+	})
+	const newVisible = getVisibleSpans(spans, out.collapsed)
+	return {
+		collapsed: out.collapsed,
+		selectedIndex: out.selectedIndex,
+		selectedSpanId: out.selectedIndex !== null ? newVisible[out.selectedIndex]?.spanId ?? null : null,
+		visibleIds: idsOf(newVisible),
+	}
+}
+
+// ---------------------------------------------------------------------------
+// getVisibleSpans
+// ---------------------------------------------------------------------------
+
+describe("getVisibleSpans", () => {
+	it("returns the full list when nothing is collapsed", () => {
+		const spans = buildTree()
+		expect(idsOf(getVisibleSpans(spans, new Set()))).toEqual([
+			"root", "a", "a1", "a2", "b", "b1", "b1a", "c",
+		])
+	})
+
+	it("hides direct children of a collapsed node", () => {
+		const spans = buildTree()
+		expect(idsOf(getVisibleSpans(spans, new Set(["a"])))).toEqual([
+			"root", "a", "b", "b1", "b1a", "c",
+		])
+	})
+
+	it("hides transitive descendants of a collapsed node", () => {
+		const spans = buildTree()
+		expect(idsOf(getVisibleSpans(spans, new Set(["b"])))).toEqual([
+			"root", "a", "a1", "a2", "b", "c",
+		])
+	})
+
+	it("collapsing a leaf changes nothing visually (no children to hide)", () => {
+		const spans = buildTree()
+		expect(idsOf(getVisibleSpans(spans, new Set(["c"])))).toEqual(idsOf(spans))
+	})
+
+	it("handles multiple collapsed sibling subtrees", () => {
+		const spans = buildTree()
+		expect(idsOf(getVisibleSpans(spans, new Set(["a", "b"])))).toEqual([
+			"root", "a", "b", "c",
+		])
+	})
+
+	it("collapsing root hides everything but root", () => {
+		const spans = buildTree()
+		expect(idsOf(getVisibleSpans(spans, new Set(["root"])))).toEqual(["root"])
+	})
+
+	it("collapsing a node and its descendant is idempotent", () => {
+		const spans = buildTree()
+		expect(idsOf(getVisibleSpans(spans, new Set(["b", "b1"])))).toEqual([
+			"root", "a", "a1", "a2", "b", "c",
+		])
+	})
+})
+
+describe("getWaterfallColumns", () => {
+	it("pads duration and log columns to fill the reserved width", () => {
+		const contentWidth = 72
+		const columns = getWaterfallColumns(contentWidth, 153_000, 1, 0)
+		expect(columns.durationCell.length).toBe(columns.durationWidth)
+		expect(columns.logCell.length).toBe(columns.logWidth)
+		expect(columns.labelMaxWidth + 1 + columns.barWidth + 1 + columns.durationCell.length + columns.logCell.length).toBe(contentWidth)
+	})
+})
+
+// ---------------------------------------------------------------------------
+// findParentIndex
+// ---------------------------------------------------------------------------
+
+describe("findParentIndex", () => {
+	it("returns null for the root span", () => {
+		const spans = buildTree()
+		expect(findParentIndex(spans, indexOfId(spans, "root"))).toBeNull()
+	})
+
+	it("returns the immediate parent index in the same list", () => {
+		const spans = buildTree()
+		expect(findParentIndex(spans, indexOfId(spans, "a1"))).toBe(indexOfId(spans, "a"))
+		expect(findParentIndex(spans, indexOfId(spans, "b1a"))).toBe(indexOfId(spans, "b1"))
+		expect(findParentIndex(spans, indexOfId(spans, "c"))).toBe(indexOfId(spans, "root"))
+	})
+
+	it("works against a filtered (visible) list — parent is the nearest shallower ancestor before index", () => {
+		const spans = buildTree()
+		const visible = getVisibleSpans(spans, new Set(["b1"]))
+		// visible: root, a, a1, a2, b, b1, c
+		expect(findParentIndex(visible, indexOfId(visible, "b1"))).toBe(indexOfId(visible, "b"))
+	})
+
+	it("returns null on out-of-range index instead of crashing", () => {
+		const spans = buildTree()
+		expect(findParentIndex(spans, 999)).toBeNull()
+		expect(findParentIndex(spans, -1)).toBeNull()
+	})
+
+	it("returns null on empty input", () => {
+		expect(findParentIndex([], 0)).toBeNull()
+	})
+})
+
+// ---------------------------------------------------------------------------
+// findFirstChildIndex
+// ---------------------------------------------------------------------------
+
+describe("findFirstChildIndex", () => {
+	it("returns next index when the next span is deeper", () => {
+		const spans = buildTree()
+		expect(findFirstChildIndex(spans, indexOfId(spans, "a"))).toBe(indexOfId(spans, "a1"))
+		expect(findFirstChildIndex(spans, indexOfId(spans, "b1"))).toBe(indexOfId(spans, "b1a"))
+		expect(findFirstChildIndex(spans, indexOfId(spans, "root"))).toBe(indexOfId(spans, "a"))
+	})
+
+	it("returns null for leaf spans", () => {
+		const spans = buildTree()
+		expect(findFirstChildIndex(spans, indexOfId(spans, "a1"))).toBeNull()
+		expect(findFirstChildIndex(spans, indexOfId(spans, "c"))).toBeNull()
+	})
+
+	it("returns null on out-of-range index", () => {
+		const spans = buildTree()
+		expect(findFirstChildIndex(spans, 999)).toBeNull()
+		expect(findFirstChildIndex(spans, -1)).toBeNull()
+	})
+
+	it("returns null on empty input", () => {
+		expect(findFirstChildIndex([], 0)).toBeNull()
+	})
+})
+
+// ---------------------------------------------------------------------------
+// resolveCollapseStep — the heart of the keyboard logic
+// ---------------------------------------------------------------------------
+
+describe("resolveCollapseStep — `right` (l / expand-or-into)", () => {
+	it("expanding a collapsed node keeps the same span selected", () => {
+		const spans = buildTree()
+		const collapsed = new Set(["a"])
+		const r = step(spans, collapsed, "a", "right")
+		expect(r.collapsed.has("a")).toBe(false)
+		expect(r.selectedSpanId).toBe("a")
+		expect(r.visibleIds).toEqual(["root", "a", "a1", "a2", "b", "b1", "b1a", "c"])
+	})
+
+	it("on an expanded parent, walks selection into its first visible child", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), "a", "right")
+		expect(r.collapsed.size).toBe(0)
+		expect(r.selectedSpanId).toBe("a1")
+	})
+
+	it("on a leaf, is a no-op", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), "a1", "right")
+		expect(r.collapsed.size).toBe(0)
+		expect(r.selectedSpanId).toBe("a1")
+	})
+
+	it("on root (expanded with children) walks into first child", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), "root", "right")
+		expect(r.selectedSpanId).toBe("a")
+	})
+
+	it("on root (collapsed) expands it", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(["root"]), "root", "right")
+		expect(r.collapsed.has("root")).toBe(false)
+		expect(r.selectedSpanId).toBe("root")
+	})
+
+	it("when nothing is selected, is a no-op", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), null, "right")
+		expect(r.selectedSpanId).toBeNull()
+		expect(r.collapsed.size).toBe(0)
+	})
+
+	it("when index is stale (past visible end), is a no-op rather than crashing", () => {
+		const spans = buildTree()
+		const out = resolveCollapseStep({ spans, collapsed: new Set(), selectedIndex: 999, direction: "right" })
+		expect(out.selectedIndex).toBe(999)
+		expect(out.collapsed.size).toBe(0)
+	})
+})
+
+describe("resolveCollapseStep — `left` (h / collapse-or-up)", () => {
+	it("collapsing an expanded parent keeps the same span selected", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), "a", "left")
+		expect(r.collapsed.has("a")).toBe(true)
+		expect(r.selectedSpanId).toBe("a")
+		expect(r.visibleIds).toEqual(["root", "a", "b", "b1", "b1a", "c"])
+	})
+
+	it("on a leaf, walks to its parent", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), "a1", "left")
+		expect(r.selectedSpanId).toBe("a")
+		expect(r.collapsed.size).toBe(0)
+	})
+
+	it("on a deep leaf, walks to its immediate parent (not all the way to root)", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), "b1a", "left")
+		expect(r.selectedSpanId).toBe("b1")
+	})
+
+	it("on a collapsed parent, walks to its parent (since it has no expanded kids to collapse)", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(["a"]), "a", "left")
+		expect(r.selectedSpanId).toBe("root")
+		expect(r.collapsed.has("a")).toBe(true) // staying collapsed
+	})
+
+	it("on root, is a no-op", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(["root"]), "root", "left")
+		expect(r.selectedSpanId).toBe("root")
+	})
+
+	it("when nothing is selected, is a no-op", () => {
+		const spans = buildTree()
+		const r = step(spans, new Set(), null, "left")
+		expect(r.selectedSpanId).toBeNull()
+		expect(r.collapsed.size).toBe(0)
+	})
+})
+
+describe("resolveCollapseStep — sequences (real bug scenarios)", () => {
+	it("press l then l: navigates root → a → a1 (no double-collapse)", () => {
+		const spans = buildTree()
+		const r1 = step(spans, new Set(), "root", "right")
+		expect(r1.selectedSpanId).toBe("a")
+		const r2 = step(spans, r1.collapsed, r1.selectedSpanId!, "right")
+		expect(r2.selectedSpanId).toBe("a1")
+	})
+
+	it("h-then-h-then-h on a leaf reaches root via collapse-then-walk pattern", () => {
+		const spans = buildTree()
+		// b1a -> h -> b1 (walk parent)
+		const r1 = step(spans, new Set(), "b1a", "left")
+		expect(r1.selectedSpanId).toBe("b1")
+		// b1 -> h -> collapse b1
+		const r2 = step(spans, r1.collapsed, r1.selectedSpanId!, "left")
+		expect(r2.collapsed.has("b1")).toBe(true)
+		expect(r2.selectedSpanId).toBe("b1")
+		// b1 (collapsed) -> h -> walk to parent b
+		const r3 = step(spans, r2.collapsed, r2.selectedSpanId!, "left")
+		expect(r3.selectedSpanId).toBe("b")
+	})
+
+	it("rapid collapse/expand on the same node converges to the original state", () => {
+		const spans = buildTree()
+		let st: { collapsed: ReadonlySet<string>; selectedSpanId: string } = {
+			collapsed: new Set(),
+			selectedSpanId: "a",
+		}
+		for (let i = 0; i < 10; i++) {
+			const dir = i % 2 === 0 ? "left" : "right"
+			const r = step(spans, st.collapsed, st.selectedSpanId, dir)
+			st = { collapsed: r.collapsed, selectedSpanId: r.selectedSpanId! }
+		}
+		expect([...st.collapsed]).toEqual([])
+		expect(st.selectedSpanId).toBe("a")
+	})
+
+	it("walking right past a leaf is idempotent (no crash, no state change)", () => {
+		const spans = buildTree()
+		const r1 = step(spans, new Set(), "a1", "right")
+		const r2 = step(spans, r1.collapsed, r1.selectedSpanId!, "right")
+		const r3 = step(spans, r2.collapsed, r2.selectedSpanId!, "right")
+		expect(r1.selectedSpanId).toBe("a1")
+		expect(r2.selectedSpanId).toBe("a1")
+		expect(r3.selectedSpanId).toBe("a1")
+	})
+
+	it("walking left past root is idempotent", () => {
+		const spans = buildTree()
+		const r1 = step(spans, new Set(["root"]), "root", "left")
+		const r2 = step(spans, r1.collapsed, r1.selectedSpanId!, "left")
+		expect(r1.selectedSpanId).toBe("root")
+		expect(r2.selectedSpanId).toBe("root")
+	})
+
+	it("collapse then move to another span then expand: state stays consistent", () => {
+		const spans = buildTree()
+		// Collapse `a` while on it.
+		const r1 = step(spans, new Set(), "a", "left")
+		expect(r1.collapsed.has("a")).toBe(true)
+		// Visible: root, a, b, b1, b1a, c
+		// Pretend user clicks `b1a` (so selection moves there).
+		// Now press h on b1a.
+		const r2 = step(spans, r1.collapsed, "b1a", "left")
+		expect(r2.selectedSpanId).toBe("b1")
+		expect(r2.collapsed.has("a")).toBe(true) // a stays collapsed
+	})
+})
+
+describe("resolveCollapseStep — invariants", () => {
+	it("never returns a selectedIndex that is out of the new visible range", () => {
+		const spans = buildTree()
+		// Try every (selectedSpanId, direction, collapsed-state) combination we care about.
+		const interesting: ReadonlyArray<{ collapsed: ReadonlySet<string>; selectedSpanId: string }> = [
+			{ collapsed: new Set(), selectedSpanId: "root" },
+			{ collapsed: new Set(), selectedSpanId: "a" },
+			{ collapsed: new Set(), selectedSpanId: "a2" },
+			{ collapsed: new Set(), selectedSpanId: "b1a" },
+			{ collapsed: new Set(["a"]), selectedSpanId: "a" },
+			{ collapsed: new Set(["a"]), selectedSpanId: "b" },
+			{ collapsed: new Set(["b"]), selectedSpanId: "b" },
+			{ collapsed: new Set(["root"]), selectedSpanId: "root" },
+		]
+		for (const { collapsed, selectedSpanId } of interesting) {
+			for (const direction of ["left", "right"] as const) {
+				const r = step(spans, collapsed, selectedSpanId, direction)
+				if (r.selectedIndex !== null) {
+					expect(r.selectedIndex).toBeGreaterThanOrEqual(0)
+					expect(r.selectedIndex).toBeLessThan(r.visibleIds.length)
+				}
+			}
+		}
+	})
+
+	it("collapsing then expanding the same node restores the original state", () => {
+		const spans = buildTree()
+		const a = step(spans, new Set(), "a", "left")           // collapse a
+		const b = step(spans, a.collapsed, a.selectedSpanId!, "right") // expand a
+		expect([...b.collapsed]).toEqual([])
+		expect(b.selectedSpanId).toBe("a")
+		expect(b.visibleIds).toEqual(idsOf(spans))
+	})
+
+	it("collapsing an ancestor of the currently selected span keeps the ancestor visible (selection moves up)", () => {
+		// Start: selected = b1a (depth 3). Collapse `b` (its grandparent).
+		const spans = buildTree()
+		// We collapse `b` while `b1a` is selected. The keyboard handler only collapses
+		// the currently selected span, so we simulate the click-to-collapse path by
+		// asserting the helper handles a selection that became invisible afterward.
+		const collapsed = new Set(["b"])
+		const visible = getVisibleSpans(spans, collapsed)
+		// `b1a` is no longer visible. Its nearest visible ancestor is `b`.
+		expect(visible.some((s) => s.spanId === "b1a")).toBe(false)
+		expect(visible.some((s) => s.spanId === "b")).toBe(true)
+	})
+})