@aryasaatvik/motel 0.3.0

package/src/ui/waterfallFilter.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "bun:test"
+import type { TraceSpanItem } from "../domain.ts"
+import { computeMatchingSpanIds, findAdjacentMatch, spanMatchesFilter } from "./waterfallFilter.ts"
+
+const span = (spanId: string, operationName: string, tags: Record<string, string> = {}): TraceSpanItem => ({
+	spanId,
+	parentSpanId: null,
+	serviceName: "test",
+	scopeName: null,
+	kind: null,
+	operationName,
+	startTime: new Date(0),
+	isRunning: false,
+	durationMs: 1,
+	status: "ok",
+	depth: 0,
+	tags,
+	warnings: [],
+	events: [],
+})
+
+describe("spanMatchesFilter", () => {
+	it("matches operation name case-insensitively", () => {
+		expect(spanMatchesFilter(span("a", "ai.StreamText"), "stream")).toBe(true)
+		expect(spanMatchesFilter(span("a", "ai.StreamText"), "nope")).toBe(false)
+	})
+
+	it("matches tag values but not keys", () => {
+		expect(spanMatchesFilter(span("a", "op", { "ai.model.id": "claude" }), "claude")).toBe(true)
+		// Key-only match should not count, otherwise searching "ai" dims nothing.
+		expect(spanMatchesFilter(span("a", "op", { "ai.model.id": "claude" }), "model.id")).toBe(false)
+	})
+
+	it("returns true when the needle is empty", () => {
+		expect(spanMatchesFilter(span("a", "op"), "")).toBe(true)
+	})
+})
+
+describe("computeMatchingSpanIds", () => {
+	it("returns null for empty/whitespace filter", () => {
+		expect(computeMatchingSpanIds([span("a", "op")], "")).toBeNull()
+		expect(computeMatchingSpanIds([span("a", "op")], "   ")).toBeNull()
+	})
+
+	it("returns only matching span ids", () => {
+		const spans = [span("a", "ai.streamText"), span("b", "Agent.get"), span("c", "ai.toolCall")]
+		const ids = computeMatchingSpanIds(spans, "ai")
+		expect(ids).not.toBeNull()
+		expect(Array.from(ids!)).toEqual(["a", "c"])
+	})
+})
+
+describe("findAdjacentMatch", () => {
+	const spans = [span("a", "one"), span("b", "two"), span("c", "three"), span("d", "four")]
+	const matches = new Set(["b", "d"])
+
+	it("finds next from current selection", () => {
+		expect(findAdjacentMatch(spans, matches, 0, 1)).toBe(1)  // a -> b
+		expect(findAdjacentMatch(spans, matches, 1, 1)).toBe(3)  // b -> d
+	})
+
+	it("wraps forward past the end", () => {
+		expect(findAdjacentMatch(spans, matches, 3, 1)).toBe(1)  // d -> b (wrap)
+	})
+
+	it("finds previous from current selection", () => {
+		expect(findAdjacentMatch(spans, matches, 3, -1)).toBe(1) // d -> b
+		expect(findAdjacentMatch(spans, matches, 1, -1)).toBe(3) // b -> d (wrap)
+	})
+
+	it("starts from beginning/end when nothing is selected", () => {
+		expect(findAdjacentMatch(spans, matches, null, 1)).toBe(1)  // forward → first match
+		expect(findAdjacentMatch(spans, matches, null, -1)).toBe(3) // backward → last match
+	})
+
+	it("returns null when there are no matches", () => {
+		expect(findAdjacentMatch(spans, new Set(), 0, 1)).toBeNull()
+	})
+
+	it("handles a single match by returning it regardless of direction", () => {
+		expect(findAdjacentMatch(spans, new Set(["c"]), 0, 1)).toBe(2)
+		expect(findAdjacentMatch(spans, new Set(["c"]), 0, -1)).toBe(2)
+	})
+})

package/src/ui/waterfallFilter.ts

@@ -0,0 +1,59 @@
+import type { TraceSpanItem } from "../domain.ts"
+
+/**
+ * Case-insensitive substring match against a span's operation name and
+ * any of its tag values. Keys aren't checked — they're dotted
+ * identifiers the user never types, so matching them just creates false
+ * positives on bare tokens like "ai" or "response".
+ */
+export const spanMatchesFilter = (span: TraceSpanItem, needle: string): boolean => {
+	if (!needle) return true
+	if (span.operationName.toLowerCase().includes(needle)) return true
+	for (const value of Object.values(span.tags)) {
+		if (typeof value === "string" && value.toLowerCase().includes(needle)) return true
+	}
+	return false
+}
+
+/**
+ * Compute the set of span IDs that match the given filter text. Returns
+ * null when the filter is empty so callers can skip dimming entirely
+ * (hot path during waterfall scrolling).
+ */
+export const computeMatchingSpanIds = (
+	spans: readonly TraceSpanItem[],
+	filterText: string,
+): ReadonlySet<string> | null => {
+	const needle = filterText.trim().toLowerCase()
+	if (!needle) return null
+	const matches = new Set<string>()
+	for (const span of spans) {
+		if (spanMatchesFilter(span, needle)) matches.add(span.spanId)
+	}
+	return matches
+}
+
+/**
+ * Find the next (direction=1) or previous (direction=-1) matching span
+ * index in `filteredSpans` relative to `currentIndex`. Wraps around the
+ * ends. Returns `null` when the list has no matches at all. When
+ * `currentIndex` is null (nothing selected), starts from either end
+ * based on direction.
+ */
+export const findAdjacentMatch = (
+	filteredSpans: readonly TraceSpanItem[],
+	matchingSpanIds: ReadonlySet<string>,
+	currentIndex: number | null,
+	direction: 1 | -1,
+): number | null => {
+	if (filteredSpans.length === 0 || matchingSpanIds.size === 0) return null
+	const start = currentIndex ?? (direction === 1 ? -1 : filteredSpans.length)
+	const n = filteredSpans.length
+	// Walk the ring exactly once so we wrap but never loop forever.
+	for (let step = 1; step <= n; step++) {
+		const idx = ((start + direction * step) % n + n) % n
+		const span = filteredSpans[idx]
+		if (span && matchingSpanIds.has(span.spanId)) return idx
+	}
+	return null
+}

package/src/ui/waterfallModel.ts

@@ -0,0 +1,130 @@
+import type { LogItem, TraceSpanItem } from "../domain.ts"
+import { formatDuration } from "./format.ts"
+
+/** Filter spans to only those visible given a set of collapsed span IDs. */
+export const getVisibleSpans = (spans: readonly TraceSpanItem[], collapsedIds: ReadonlySet<string>): readonly TraceSpanItem[] => {
+	if (collapsedIds.size === 0) return spans
+	const result: TraceSpanItem[] = []
+	let skipDepth = -1
+	for (const span of spans) {
+		if (skipDepth >= 0 && span.depth > skipDepth) continue
+		skipDepth = -1
+		result.push(span)
+		if (collapsedIds.has(span.spanId)) {
+			skipDepth = span.depth
+		}
+	}
+	return result
+}
+
+/** Find the index of a span's parent in the visible list. */
+export const findParentIndex = (spans: readonly TraceSpanItem[], index: number): number | null => {
+	const span = spans[index]
+	if (!span || span.depth === 0) return null
+	for (let i = index - 1; i >= 0; i--) {
+		if (spans[i]!.depth < span.depth) return i
+	}
+	return null
+}
+
+/** Find the index of a span's first child in the visible list. */
+export const findFirstChildIndex = (spans: readonly TraceSpanItem[], index: number): number | null => {
+	const span = spans[index]
+	const next = spans[index + 1]
+	if (span && next && next.depth > span.depth) return index + 1
+	return null
+}
+
+export const buildTreePrefix = (spans: readonly TraceSpanItem[], index: number): string => {
+	const span = spans[index]
+	if (span.depth === 0) return ""
+
+	const parts: string[] = []
+
+	const isLastChild = (spanIndex: number, depth: number): boolean => {
+		for (let i = spanIndex + 1; i < spans.length; i++) {
+			if (spans[i].depth < depth) return true
+			if (spans[i].depth === depth) return false
+		}
+		return true
+	}
+
+	parts.push(isLastChild(index, span.depth) ? "\u2514\u2500" : "\u251c\u2500")
+
+	for (let d = span.depth - 1; d >= 1; d--) {
+		let parentIndex = index
+		for (let i = index - 1; i >= 0; i--) {
+			if (spans[i].depth === d) {
+				parentIndex = i
+				break
+			}
+			if (spans[i].depth < d) break
+		}
+		parts.push(isLastChild(parentIndex, d) ? "  " : "\u2502 ")
+	}
+
+	return parts.reverse().join("")
+}
+
+const INTERESTING_TAGS = [
+	"http.method", "http.url", "http.status_code", "http.route",
+	"db.system", "db.statement", "db.name",
+	"messaging.system", "messaging.destination",
+	"error", "error.message",
+	"net.peer.name", "net.peer.port",
+] as const
+
+export const getWaterfallLayout = (contentWidth: number, suffixWidth: number) => {
+	const gapsAndSuffix = suffixWidth + 2
+	const remaining = Math.max(4, contentWidth - gapsAndSuffix)
+	const labelMaxWidth = Math.max(4, Math.min(Math.floor(remaining * 0.5), 32))
+	const barWidth = Math.max(1, contentWidth - labelMaxWidth - gapsAndSuffix)
+	return { labelMaxWidth, barWidth } as const
+}
+
+export type WaterfallSuffixMetrics = {
+	readonly maxDurationWidth: number
+	readonly suffixWidth: number
+}
+
+export const getWaterfallSuffixMetrics = (
+	spans: readonly { readonly durationMs: number; readonly spanId: string }[],
+): WaterfallSuffixMetrics => {
+	let maxDurationWidth = 0
+	for (const span of spans) {
+		const d = formatDuration(Math.max(0, span.durationMs)).length
+		if (d > maxDurationWidth) maxDurationWidth = d
+	}
+	return { maxDurationWidth, suffixWidth: maxDurationWidth }
+}
+
+export const getWaterfallColumns = (
+	contentWidth: number,
+	metrics: WaterfallSuffixMetrics,
+) => {
+	const { labelMaxWidth, barWidth } = getWaterfallLayout(contentWidth, metrics.suffixWidth)
+	return { labelMaxWidth, barWidth, suffixWidth: metrics.suffixWidth } as const
+}
+
+export const spanPreviewEntries = (span: TraceSpanItem, logs: readonly LogItem[], maxEntries: number): Array<{ key: string; value: string; isWarning?: boolean }> => {
+	const entries = Object.entries(span.tags)
+	const interesting = entries.filter(([key]) =>
+		INTERESTING_TAGS.includes(key as (typeof INTERESTING_TAGS)[number]) || key.startsWith("error"),
+	)
+	const rest = entries.filter(([key]) =>
+		!INTERESTING_TAGS.includes(key as (typeof INTERESTING_TAGS)[number]) && !key.startsWith("error") && !key.startsWith("otel.") && key !== "span.kind",
+	)
+	const tagResults: Array<{ key: string; value: string; isWarning?: boolean }> = []
+	if (logs.length > 0) {
+		tagResults.push({ key: "logs", value: `${logs.length} correlated` })
+		tagResults.push({ key: "log", value: logs[0]!.body.replace(/\s+/g, " ") })
+	}
+
+	tagResults.push(...[...interesting, ...rest]
+		.slice(0, maxEntries - span.warnings.length)
+		.map(([key, value]) => ({ key, value })))
+	for (const warning of span.warnings) {
+		tagResults.push({ key: "warning", value: warning, isWarning: true })
+	}
+	return tagResults.slice(0, maxEntries)
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Seed a deterministic trace into the SQLite store. Invoked as a child process
+ * by the reproducer test so it gets a fresh module graph (config.ts caches the
+ * DB path at module-load time).
+ *
+ * Usage:
+ *   bun run src/ui/waterfallNav.repro.seed.ts
+ *
+ * Reads MOTEL_OTEL_DB_PATH from the environment.
+ */
+
+import { Effect } from "effect"
+import { storeRuntime } from "../runtime.ts"
+import { TelemetryStore } from "../services/TelemetryStore.ts"
+
+const SERVICE_NAME = "waterfall-repro"
+const TRACE_ID = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+const ROOT = "1111111111111111"
+const SIB_BEFORE = "2222222222222222"
+const PARENT = "3333333333333333"
+const CHILD_A = "aaaaaaaaaaaaaaaa"
+const CHILD_B = "bbbbbbbbbbbbbbbb"
+const CHILD_C = "cccccccccccccccc"
+const CHILD_D = "dddddddddddddddd"
+const CHILD_E = "eeeeeeeeeeeeeeee"
+const CHILD_F = "ffffffffffffffff"
+const SIB_AFTER = "4444444444444444"
+const TAIL = "5555555555555555"
+const TAIL_CHILD = "6666666666666666"
+const TAIL_GRAND = "7777777777777777"
+
+const nowNanos = BigInt(Date.now()) * 1_000_000n
+const ms = (n: number) => String(nowNanos + BigInt(n) * 1_000_000n)
+
+const span = (
+	spanId: string,
+	parent: string | null,
+	name: string,
+	startMs: number,
+	endMs: number,
+) => ({
+	traceId: TRACE_ID,
+	spanId,
+	parentSpanId: parent ?? undefined,
+	name,
+	kind: 1,
+	startTimeUnixNano: ms(startMs),
+	endTimeUnixNano: ms(endMs),
+})
+
+const program = Effect.flatMap(TelemetryStore, (store) =>
+	store.ingestTraces({
+		resourceSpans: [
+			{
+				resource: {
+					attributes: [
+						{ key: "service.name", value: { stringValue: SERVICE_NAME } },
+					],
+				},
+				scopeSpans: [
+					{
+						scope: { name: "test-scope" },
+						spans: [
+							span(ROOT, null, "root.op", 0, 100),
+							span(SIB_BEFORE, ROOT, "siblingBefore.op", 1, 2),
+							span(PARENT, ROOT, "parent.op", 5, 60),
+							span(CHILD_A, PARENT, "childA.op", 6, 8),
+							span(CHILD_B, PARENT, "childB.op", 10, 12),
+							span(CHILD_C, PARENT, "childC.op", 14, 18),
+							span(CHILD_D, PARENT, "childD.op", 20, 25),
+							span(CHILD_E, PARENT, "childE.op", 28, 35),
+							span(CHILD_F, PARENT, "childF.op", 40, 55),
+							span(SIB_AFTER, ROOT, "siblingAfter.op", 65, 68),
+							span(TAIL, ROOT, "tail.op", 70, 95),
+							span(TAIL_CHILD, TAIL, "tailChild.op", 72, 90),
+							span(TAIL_GRAND, TAIL_CHILD, "tailGrandchild.op", 75, 85),
+						],
+					},
+				],
+			},
+		],
+	}),
+)
+
+await storeRuntime.runPromise(program)
+process.exit(0)

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

@@ -0,0 +1,271 @@
+/**
+ * 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 level-1 mode the waterfall is rendered in the left pane and span
+// detail is rendered on the right. Determine the pane separator from the
+// stable header line rather than mistaking tree branch glyphs for it.
+const waterfallBody = (snap: string): readonly string[] => {
+	const lines = snap.split("\n")
+	const header = lines.find((line) => line.includes("TRACE DETAILS") && line.includes("SPAN"))
+	const paneSeparator = header?.indexOf("\u2502") ?? -1
+	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 sliced = paneSeparator >= 0 ? line.slice(0, paneSeparator) : 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 port = 40_000 + Math.floor(Math.random() * 5_000)
+	const daemonEnv = { MOTEL_RUNTIME_DIR: tempDir, MOTEL_OTEL_DB_PATH: dbPath, MOTEL_OTEL_BASE_URL: `http://127.0.0.1:${port}`, MOTEL_OTEL_QUERY_URL: `http://127.0.0.1:${port}`, MOTEL_OTEL_PORT: String(port) }
+	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,
+				...daemonEnv,
+				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 wide enough to exercise the waterfall + span-detail split.
+		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_RUNTIME_DIR=${tempDir}`,
+			"--env", `MOTEL_OTEL_BASE_URL=${daemonEnv.MOTEL_OTEL_BASE_URL}`,
+			"--env", `MOTEL_OTEL_QUERY_URL=${daemonEnv.MOTEL_OTEL_QUERY_URL}`,
+			"--env", `MOTEL_OTEL_PORT=${port}`,
+			"--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])
+			const stop = Bun.spawn({ cmd: ["bun", "run", "src/motel.ts", "stop"], cwd: process.cwd(), env: { ...process.env, ...daemonEnv }, stdout: "ignore", stderr: "ignore" })
+			await stop.exited
+		}
+		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)
+})