@kitlangton/motel 0.1.0

package/src/ui/useKeyboardNav.ts

@@ -0,0 +1,532 @@
+import { useAtom } from "@effect/atom-react"
+import { useKeyboard, useRenderer } from "@opentui/react"
+import { useLayoutEffect, useRef } from "react"
+import type { TraceItem, TraceSummaryItem } from "../domain.ts"
+import { otelServerInstructions } from "../instructions.ts"
+import { copyToClipboard, traceUiUrl, webUiUrl } from "./format.ts"
+import {
+	autoRefreshAtom,
+	collapsedSpanIdsAtom,
+	detailViewAtom,
+	filterModeAtom,
+	filterTextAtom,
+	refreshNonceAtom,
+	selectedThemeAtom,
+	selectedServiceLogIndexAtom,
+	selectedSpanIndexAtom,
+	selectedTraceIndexAtom,
+	selectedTraceServiceAtom,
+	serviceLogStateAtom,
+	showHelpAtom,
+	traceSortAtom,
+	type TraceSortMode,
+	traceStateAtom,
+} from "./state.ts"
+import { G_PREFIX_TIMEOUT_MS } from "./theme.ts"
+import { cycleThemeName, themeLabel } from "./theme.ts"
+import { getVisibleSpans } from "./Waterfall.tsx"
+import { resolveCollapseStep } from "./waterfallNav.ts"
+
+interface KeyboardNavParams {
+	selectedTrace: TraceItem | null
+	filteredTraces: readonly TraceSummaryItem[]
+	isWideLayout: boolean
+	wideBodyLines: number
+	narrowBodyLines: number
+	tracePageSize: number
+	spanPageSize: number
+	flashNotice: (message: string) => void
+}
+
+export const useKeyboardNav = (params: KeyboardNavParams) => {
+	const {
+		selectedTrace,
+		isWideLayout,
+		wideBodyLines,
+		narrowBodyLines,
+		tracePageSize,
+		spanPageSize,
+		flashNotice,
+	} = params
+	const renderer = useRenderer()
+
+	const [traceState] = useAtom(traceStateAtom)
+	const [serviceLogState] = useAtom(serviceLogStateAtom)
+	const [selectedSpanIndex, setSelectedSpanIndex] = useAtom(selectedSpanIndexAtom)
+	const [selectedServiceLogIndex, setSelectedServiceLogIndex] = useAtom(selectedServiceLogIndexAtom)
+	const [selectedTheme, setSelectedTheme] = useAtom(selectedThemeAtom)
+	const [selectedTraceIndex, setSelectedTraceIndex] = useAtom(selectedTraceIndexAtom)
+	const [selectedTraceService, setSelectedTraceService] = useAtom(selectedTraceServiceAtom)
+	const [detailView, setDetailView] = useAtom(detailViewAtom)
+	const [showHelp, setShowHelp] = useAtom(showHelpAtom)
+	const [, setRefreshNonce] = useAtom(refreshNonceAtom)
+	const [collapsedSpanIds, setCollapsedSpanIds] = useAtom(collapsedSpanIdsAtom)
+	const [autoRefresh, setAutoRefresh] = useAtom(autoRefreshAtom)
+	const [filterMode, setFilterMode] = useAtom(filterModeAtom)
+	const [filterText, setFilterText] = useAtom(filterTextAtom)
+	const [traceSort, setTraceSort] = useAtom(traceSortAtom)
+
+	const pendingGRef = useRef(false)
+	const pendingGTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+	const quittingRef = useRef(false)
+
+	const spanNavActive = detailView !== "service-logs" && selectedSpanIndex !== null
+	const serviceLogNavActive = detailView === "service-logs"
+
+	const stateRef = useRef({ traceState, serviceLogState, selectedServiceLogIndex, selectedTheme, selectedTraceIndex, selectedSpanIndex, selectedTraceService, detailView, showHelp, collapsedSpanIds, spanNavActive, serviceLogNavActive, filterMode, filterText, autoRefresh, traceSort, ...params })
+	// Keep the keyboard handler's state mirror in sync before the next paint.
+	// OpenTUI's own effect-event helper uses useLayoutEffect for this same reason:
+	// rapid repeated keypresses can otherwise observe stale selection state.
+	useLayoutEffect(() => {
+		stateRef.current = { traceState, serviceLogState, selectedServiceLogIndex, selectedTheme, selectedTraceIndex, selectedSpanIndex, selectedTraceService, detailView, showHelp, collapsedSpanIds, spanNavActive, serviceLogNavActive, filterMode, filterText, autoRefresh, traceSort, ...params }
+	})
+
+	const clearPendingG = () => {
+		pendingGRef.current = false
+		if (pendingGTimeoutRef.current !== null) {
+			clearTimeout(pendingGTimeoutRef.current)
+			pendingGTimeoutRef.current = null
+		}
+	}
+
+	const armPendingG = () => {
+		clearPendingG()
+		pendingGRef.current = true
+		pendingGTimeoutRef.current = globalThis.setTimeout(() => {
+			pendingGRef.current = false
+			pendingGTimeoutRef.current = null
+		}, G_PREFIX_TIMEOUT_MS)
+	}
+
+	const $ = () => stateRef.current
+
+	const selectFilteredTraceAt = (filteredIdx: number) => {
+		const s = $()
+		const trace = s.filteredTraces[filteredIdx]
+		if (!trace) return
+		const fullIndex = s.traceState.data.findIndex((t) => t.traceId === trace.traceId)
+		if (fullIndex >= 0) setSelectedTraceIndex(fullIndex)
+	}
+
+	const jumpToStart = () => {
+		const s = $()
+		if (s.spanNavActive && s.selectedTrace) {
+			const visibleCount = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds).length
+			setSelectedSpanIndex(visibleCount === 0 ? null : 0)
+		} else {
+			selectFilteredTraceAt(0)
+		}
+	}
+
+	const jumpToEnd = () => {
+		const s = $()
+		if (s.spanNavActive && s.selectedTrace) {
+			const visibleCount = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds).length
+			setSelectedSpanIndex(visibleCount === 0 ? null : visibleCount - 1)
+		} else {
+			selectFilteredTraceAt(s.filteredTraces.length - 1)
+		}
+	}
+
+	const moveTraceBy = (direction: -1 | 1) => {
+		const s = $()
+		const filtered = s.filteredTraces
+		if (filtered.length === 0) return
+		setSelectedTraceIndex((current) => {
+			const currentTraceId = s.traceState.data[current]?.traceId
+			const currentFilteredIdx = currentTraceId
+				? filtered.findIndex((t) => t.traceId === currentTraceId)
+				: -1
+			if (currentFilteredIdx < 0) {
+				const fallbackTrace = filtered[0]
+				if (!fallbackTrace) return current
+				const fallbackIndex = s.traceState.data.findIndex((t) => t.traceId === fallbackTrace.traceId)
+				return fallbackIndex >= 0 ? fallbackIndex : current
+			}
+			const nextFilteredIdx = Math.max(0, Math.min(currentFilteredIdx + direction, filtered.length - 1))
+			const nextTrace = filtered[nextFilteredIdx]
+			if (!nextTrace) return current
+			const fullIndex = s.traceState.data.findIndex((t) => t.traceId === nextTrace.traceId)
+			return fullIndex >= 0 ? fullIndex : current
+		})
+	}
+
+	const moveServiceLogBy = (direction: -1 | 1) => {
+		const s = $()
+		setSelectedServiceLogIndex((current) => {
+			if (s.serviceLogState.data.length === 0) return 0
+			return Math.max(0, Math.min(current + direction, s.serviceLogState.data.length - 1))
+		})
+	}
+
+	const cycleService = (direction: -1 | 1) => {
+		const s = $()
+		if (s.traceState.services.length === 0) return
+		const currentIndex = s.selectedTraceService ? s.traceState.services.indexOf(s.selectedTraceService) : -1
+		const nextIndex = currentIndex >= 0 ? (currentIndex + direction + s.traceState.services.length) % s.traceState.services.length : 0
+		setSelectedTraceService(s.traceState.services[nextIndex] ?? s.selectedTraceService)
+	}
+
+	const refresh = (message?: string) => {
+		const s = $()
+		setRefreshNonce((current) => current + 1)
+		if (message) s.flashNotice(message)
+	}
+
+	const copySelectedIds = () => {
+		const s = $()
+		if (s.serviceLogNavActive) {
+			const selectedLog = s.serviceLogState.data[s.selectedServiceLogIndex]
+			if (!selectedLog?.traceId) {
+				s.flashNotice("No trace id to copy")
+				return
+			}
+			const lines = [
+				`traceId=${selectedLog.traceId}`,
+				selectedLog.spanId ? `spanId=${selectedLog.spanId}` : null,
+			].filter((line): line is string => line !== null).join("\n")
+			void copyToClipboard(lines)
+				.then(() => {
+					s.flashNotice(selectedLog.spanId ? "Copied trace and span ids" : "Copied trace id")
+				})
+				.catch((error) => {
+					s.flashNotice(error instanceof Error ? error.message : String(error))
+				})
+			return
+		}
+
+		if (!s.selectedTrace) {
+			s.flashNotice("No trace selected")
+			return
+		}
+
+		const visibleSpans = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds)
+		const selectedSpan = s.selectedSpanIndex !== null ? visibleSpans[s.selectedSpanIndex] ?? null : null
+		const lines = [
+			`traceId=${s.selectedTrace.traceId}`,
+			selectedSpan ? `spanId=${selectedSpan.spanId}` : null,
+		].filter((line): line is string => line !== null).join("\n")
+
+		void copyToClipboard(lines)
+			.then(() => {
+				s.flashNotice(selectedSpan ? "Copied trace and span ids" : "Copied trace id")
+			})
+			.catch((error) => {
+				s.flashNotice(error instanceof Error ? error.message : String(error))
+			})
+	}
+
+	const toggleServiceLogsView = () => {
+		const s = $()
+		if (!s.selectedTraceService && !s.selectedTrace) return
+		setDetailView((current) => current === "service-logs" ? (s.selectedSpanIndex !== null ? "span-detail" : "waterfall") : "service-logs")
+	}
+
+	const pageBy = (direction: -1 | 1) => {
+		const s = $()
+		if (s.serviceLogNavActive) {
+			const serviceLogPageSize = Math.max(1, Math.floor((s.isWideLayout ? s.wideBodyLines : s.narrowBodyLines) * 0.5))
+			setSelectedServiceLogIndex((current) => {
+				if (s.serviceLogState.data.length === 0) return 0
+				return Math.max(0, Math.min(current + direction * serviceLogPageSize, s.serviceLogState.data.length - 1))
+			})
+		} else if (s.spanNavActive && s.selectedTrace) {
+			const visibleCount = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds).length
+			setSelectedSpanIndex((current) => {
+				if (visibleCount === 0) return null
+				const start = current ?? 0
+				return Math.max(0, Math.min(start + direction * s.spanPageSize, visibleCount - 1))
+			})
+		} else {
+			const filtered = s.filteredTraces
+			if (filtered.length === 0) return
+			setSelectedTraceIndex((current) => {
+				const currentTraceId = s.traceState.data[current]?.traceId
+				const currentFilteredIdx = currentTraceId
+					? filtered.findIndex((t) => t.traceId === currentTraceId)
+					: 0
+				const nextIdx = Math.max(0, Math.min(currentFilteredIdx + direction * s.tracePageSize, filtered.length - 1))
+				const nextTrace = filtered[nextIdx]
+				if (!nextTrace) return current
+				const fullIndex = s.traceState.data.findIndex((t) => t.traceId === nextTrace.traceId)
+				return fullIndex >= 0 ? fullIndex : current
+			})
+		}
+	}
+
+	useKeyboard((key) => {
+		const s = $()
+
+		// Filter mode: capture text input
+		if (s.filterMode) {
+			if (key.name === "escape") {
+				setFilterMode(false)
+				setFilterText("")
+				return
+			}
+			if (key.name === "return" || key.name === "enter") {
+				setFilterMode(false)
+				return
+			}
+			if (key.name === "backspace") {
+				setFilterText(s.filterText.slice(0, -1))
+				return
+			}
+			// Single printable character
+			if (key.name.length === 1 && !key.ctrl && !key.meta) {
+				setFilterText(s.filterText + key.name)
+				return
+			}
+			return
+		}
+		const plainG = key.name === "g" && !key.ctrl && !key.meta && !key.option && !key.shift
+		const shiftedG = key.name === "g" && key.shift
+		const questionMark = key.name === "?" || (key.name === "/" && key.shift)
+
+		if (questionMark) {
+			clearPendingG()
+			setShowHelp((current) => !current)
+			return
+		}
+
+		if (s.showHelp) {
+			if (key.name === "return" || key.name === "enter" || key.name === "escape") {
+				setShowHelp(false)
+			}
+			return
+		}
+
+		if (plainG && !key.repeated) {
+			if (pendingGRef.current) {
+				clearPendingG()
+				jumpToStart()
+			} else {
+				armPendingG()
+			}
+			return
+		}
+
+		if (shiftedG) {
+			clearPendingG()
+			jumpToEnd()
+			return
+		}
+
+		clearPendingG()
+
+		if (key.name === "q" || (key.ctrl && key.name === "c")) {
+			if (quittingRef.current) return
+			quittingRef.current = true
+			renderer.destroy()
+			return
+		}
+		if (key.name === "home") {
+			if (s.serviceLogNavActive) {
+				setSelectedServiceLogIndex(0)
+			} else {
+				jumpToStart()
+			}
+			return
+		}
+		if (key.name === "end") {
+			if (s.serviceLogNavActive) {
+				setSelectedServiceLogIndex(s.serviceLogState.data.length === 0 ? 0 : s.serviceLogState.data.length - 1)
+			} else {
+				jumpToEnd()
+			}
+			return
+		}
+		if (key.name === "pagedown" || (key.ctrl && key.name === "d")) {
+			pageBy(1)
+			return
+		}
+		if (key.name === "pageup" || (key.ctrl && key.name === "u")) {
+			pageBy(-1)
+			return
+		}
+		if (key.ctrl && key.name === "p") {
+			moveTraceBy(-1)
+			return
+		}
+		if (key.ctrl && key.name === "n") {
+			moveTraceBy(1)
+			return
+		}
+		if (key.name === "escape") {
+			if (s.showHelp) {
+				setShowHelp(false)
+				return
+			}
+			if (s.detailView === "span-detail" || s.detailView === "service-logs") {
+				setDetailView("waterfall")
+				return
+			}
+			if (s.spanNavActive) {
+				setSelectedSpanIndex(null)
+				return
+			}
+			return
+		}
+		if (key.name === "return" || key.name === "enter") {
+			if (s.detailView === "service-logs") {
+				const selectedLog = s.serviceLogState.data[s.selectedServiceLogIndex]
+				if (selectedLog?.traceId) {
+					const traceIndex = s.traceState.data.findIndex((trace) => trace.traceId === selectedLog.traceId)
+					if (traceIndex >= 0) {
+						setSelectedTraceIndex(traceIndex)
+						setDetailView("waterfall")
+						s.flashNotice(`Jumped to trace ${selectedLog.traceId.slice(-8)}`)
+					}
+				}
+				return
+			}
+			if (s.spanNavActive && s.detailView === "waterfall") {
+				setDetailView("span-detail")
+				return
+			}
+			if (!s.spanNavActive && s.selectedTrace && s.selectedTrace.spans.length > 0) {
+				setSelectedSpanIndex(0)
+				return
+			}
+			return
+		}
+		if (key.name === "r") {
+			refresh("Refreshing traces...")
+			return
+		}
+		if (key.name === "a") {
+			setAutoRefresh(!s.autoRefresh)
+			s.flashNotice(s.autoRefresh ? "Auto-refresh paused" : "Auto-refresh resumed")
+			return
+		}
+		if (key.name === "s") {
+			const modes: readonly TraceSortMode[] = ["recent", "slowest", "errors"]
+			const nextMode = modes[(modes.indexOf(s.traceSort) + 1) % modes.length] ?? "recent"
+			setTraceSort(nextMode)
+			s.flashNotice(`Sort: ${nextMode}`)
+			return
+		}
+		if (key.name === "t") {
+			const nextTheme = cycleThemeName(s.selectedTheme)
+			setSelectedTheme(nextTheme)
+			s.flashNotice(`Theme: ${themeLabel(nextTheme)}`)
+			return
+		}
+		if (key.name === "/" && !key.shift) {
+			setFilterMode(true)
+			return
+		}
+		if (key.name === "tab") {
+			toggleServiceLogsView()
+			return
+		}
+		if (key.name === "[") {
+			cycleService(-1)
+			return
+		}
+		if (key.name === "]") {
+			cycleService(1)
+			return
+		}
+		if (key.name === "up" || key.name === "k") {
+			if (s.serviceLogNavActive) {
+				moveServiceLogBy(-1)
+			} else if (s.spanNavActive && s.selectedTrace) {
+				const visibleCount = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds).length
+				setSelectedSpanIndex((current) => {
+					if (current === null || visibleCount === 0) return 0
+					return Math.max(0, current - 1)
+				})
+			} else {
+				moveTraceBy(-1)
+			}
+			return
+		}
+		if (key.name === "down" || key.name === "j") {
+			if (s.serviceLogNavActive) {
+				moveServiceLogBy(1)
+			} else if (s.spanNavActive && s.selectedTrace) {
+				const visibleCount = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds).length
+				setSelectedSpanIndex((current) => {
+					if (current === null || visibleCount === 0) return 0
+					return Math.min(current + 1, visibleCount - 1)
+				})
+			} else {
+				moveTraceBy(1)
+			}
+			return
+		}
+		if (key.name === "left" || key.name === "h") {
+			if (s.spanNavActive && s.selectedTrace) {
+				const trace = s.selectedTrace
+				setCollapsedSpanIds((currentCollapsed) => {
+					const result = resolveCollapseStep({
+						spans: trace.spans,
+						collapsed: currentCollapsed,
+						selectedIndex: s.selectedSpanIndex,
+						direction: "left",
+					})
+					if (result.selectedIndex !== s.selectedSpanIndex) {
+						setSelectedSpanIndex(result.selectedIndex)
+					}
+					return result.collapsed
+				})
+			}
+			return
+		}
+		if (key.name === "right" || key.name === "l") {
+			if (s.spanNavActive && s.selectedTrace) {
+				const trace = s.selectedTrace
+				setCollapsedSpanIds((currentCollapsed) => {
+					const result = resolveCollapseStep({
+						spans: trace.spans,
+						collapsed: currentCollapsed,
+						selectedIndex: s.selectedSpanIndex,
+						direction: "right",
+					})
+					if (result.selectedIndex !== s.selectedSpanIndex) {
+						setSelectedSpanIndex(result.selectedIndex)
+					}
+					return result.collapsed
+				})
+			} else if (!s.spanNavActive && !s.serviceLogNavActive) {
+				toggleServiceLogsView()
+			}
+			return
+		}
+		if (key.name === "o" && !key.shift) {
+			if (s.serviceLogNavActive) {
+				const selectedLog = s.serviceLogState.data[s.selectedServiceLogIndex]
+				if (selectedLog?.traceId) {
+					void Bun.spawn({ cmd: ["open", traceUiUrl(selectedLog.traceId)], stdout: "ignore", stderr: "ignore" })
+					s.flashNotice(`Opened trace ${selectedLog.traceId.slice(-8)}`)
+				}
+				return
+			}
+			if (!s.selectedTrace) return
+			void Bun.spawn({ cmd: ["open", traceUiUrl(s.selectedTrace.traceId)], stdout: "ignore", stderr: "ignore" })
+			s.flashNotice(`Opened trace ${s.selectedTrace.traceId.slice(-8)}`)
+			return
+		}
+		if (key.name === "o" && key.shift) {
+			void Bun.spawn({ cmd: ["open", webUiUrl()], stdout: "ignore", stderr: "ignore" })
+			s.flashNotice("Opened web UI")
+			return
+		}
+		if (key.name === "y" || key.name === "Y") {
+			copySelectedIds()
+			return
+		}
+		if (key.name === "c" || key.name === "C") {
+			void copyToClipboard(otelServerInstructions())
+				.then(() => {
+					s.flashNotice("Copied OTEL server details")
+				})
+				.catch((error) => {
+					s.flashNotice(error instanceof Error ? error.message : String(error))
+				})
+		}
+	})
+
+	return { spanNavActive }
+}

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.asEffect(), (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)