@kitlangton/motel 0.1.3 → 0.2.1

package/src/ui/useKeyboardNav.ts

@@ -1,8 +1,9 @@
 import { useAtom } from "@effect/atom-react"
 import { useKeyboard, useRenderer } from "@opentui/react"
 import { useEffect, useLayoutEffect, useRef } from "react"
-import type { TraceItem, TraceSummaryItem } from "../domain.ts"
+import { isAiSpan, type TraceItem, type TraceSummaryItem } from "../domain.ts"
 import { otelServerInstructions } from "../instructions.ts"
+import { renderChunkDetailLines, type Chunk } from "./aiChatModel.ts"
 import { copyToClipboard, traceUiUrl, webUiUrl } from "./format.ts"
 import {
 	activeAttrKeyAtom,
@@ -12,11 +13,15 @@ import {
 	attrPickerInputAtom,
 	attrPickerModeAtom,
 	autoRefreshAtom,
+	chatDetailChunkIdAtom,
+	chatDetailScrollOffsetAtom,
 	collapsedSpanIdsAtom,
 	detailViewAtom,
 	filterModeAtom,
 	filterTextAtom,
 	refreshNonceAtom,
+	selectedAttrIndexAtom,
+	selectedChatChunkIdAtom,
 	selectedThemeAtom,
 	selectedServiceLogIndexAtom,
 	selectedSpanIndexAtom,
@@ -27,10 +32,13 @@ import {
 	traceSortAtom,
 	type TraceSortMode,
 	traceStateAtom,
+	waterfallFilterModeAtom,
+	waterfallFilterTextAtom,
 } from "./state.ts"
 import { filterFacets } from "./AttrFilterModal.tsx"
 import { G_PREFIX_TIMEOUT_MS } from "./theme.ts"
 import { cycleThemeName, themeLabel } from "./theme.ts"
+import { computeMatchingSpanIds, findAdjacentMatch } from "./waterfallFilter.ts"
 import { getVisibleSpans } from "./Waterfall.tsx"
 import { resolveCollapseStep } from "./waterfallNav.ts"
 
@@ -46,13 +54,22 @@ import { resolveCollapseStep } from "./waterfallNav.ts"
  * Returns `null` for non-printable events (function keys, modifiers, etc.)
  * so callers can skip them.
  */
-const extractPrintable = (key: {
+interface KeyboardKey {
 	readonly name: string
 	readonly sequence?: string
 	readonly ctrl: boolean
 	readonly meta: boolean
-}): string | null => {
+	readonly option?: boolean
+	readonly shift?: boolean
+	readonly repeated?: boolean
+}
+
+const extractPrintable = (key: KeyboardKey): string | null => {
 	if (key.ctrl || key.meta) return null
+	// Space arrives as `key.name === "space"` with a 1-char sequence. We
+	// handle it explicitly because the generic "length > 1" branch below
+	// only catches multi-char paste sequences, not a lone " ".
+	if (key.name === "space") return " "
 	if (key.name.length === 1) return key.name
 	const seq = key.sequence ?? ""
 	// Only accept sequences that are pure printable text. Any escape or
@@ -64,6 +81,7 @@ const extractPrintable = (key: {
 interface KeyboardNavParams {
 	selectedTrace: TraceItem | null
 	filteredTraces: readonly TraceSummaryItem[]
+	aiChatChunks: readonly Chunk[]
 	isWideLayout: boolean
 	wideBodyLines: number
 	narrowBodyLines: number
@@ -72,6 +90,11 @@ interface KeyboardNavParams {
 	flashNotice: (message: string) => void
 }
 
+const findTraceIndexById = (traces: readonly TraceSummaryItem[], traceId: string | null) =>
+	traceId === null ? -1 : traces.findIndex((trace) => trace.traceId === traceId)
+
+const clamp = (n: number, min: number, max: number) => Math.max(min, Math.min(max, n))
+
 export const useKeyboardNav = (params: KeyboardNavParams) => {
 	const {
 		selectedTrace,
@@ -105,6 +128,12 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 	const [attrFacets] = useAtom(attrFacetStateAtom)
 	const [activeAttrKey, setActiveAttrKey] = useAtom(activeAttrKeyAtom)
 	const [activeAttrValue, setActiveAttrValue] = useAtom(activeAttrValueAtom)
+	const [waterfallFilterMode, setWaterfallFilterMode] = useAtom(waterfallFilterModeAtom)
+	const [waterfallFilterText, setWaterfallFilterText] = useAtom(waterfallFilterTextAtom)
+	const [selectedAttrIndex, setSelectedAttrIndex] = useAtom(selectedAttrIndexAtom)
+	const [chatDetailChunkId, setChatDetailChunkId] = useAtom(chatDetailChunkIdAtom)
+	const [chatDetailScrollOffset, setChatDetailScrollOffset] = useAtom(chatDetailScrollOffsetAtom)
+	const [selectedChatChunkId, setSelectedChatChunkId] = useAtom(selectedChatChunkIdAtom)
 
 	const pendingGRef = useRef(false)
 	const pendingGTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
@@ -112,6 +141,19 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 
 	const spanNavActive = detailView !== "service-logs" && selectedSpanIndex !== null
 	const serviceLogNavActive = detailView === "service-logs"
+	// L2 (full-screen content view): j/k/y/gg/G operate on the tag list
+	// instead of the waterfall or trace list. Enter drilled us here from
+	// L1; esc drills back.
+	const attrNavActive = detailView === "span-detail" && selectedSpanIndex !== null
+	// L2 specialisation: when drilled into an AI-flagged span we render
+	// the chat transcript view instead of the attribute dump. j/k scroll
+	// the transcript by a line, ctrl-d/u page by half the viewport, y
+	// falls back to copying trace/span ids (the individual message
+	// copying can come later; line-level is rarely what you want).
+	const selectedSpanForAi = selectedTrace && selectedSpanIndex !== null
+		? getVisibleSpans(selectedTrace.spans, collapsedSpanIds)[selectedSpanIndex] ?? null
+		: null
+	const chatNavActive = attrNavActive && selectedSpanForAi !== null && isAiSpan(selectedSpanForAi.tags)
 
 	// Bracketed paste: when the terminal has bracketed paste enabled, opentui
 	// surfaces the full pasted text as a single "paste" event on keyInput.
@@ -151,12 +193,46 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 		}
 	}, [renderer, setFilterText, setPickerInput, setPickerIndex])
 
-	const stateRef = useRef({ traceState, serviceLogState, selectedServiceLogIndex, selectedTheme, selectedTraceIndex, selectedSpanIndex, selectedTraceService, detailView, showHelp, collapsedSpanIds, spanNavActive, serviceLogNavActive, filterMode, filterText, autoRefresh, traceSort, pickerMode, pickerInput, pickerIndex, attrFacets, activeAttrKey, activeAttrValue, ...params })
+	const buildStateSnapshot = () => ({
+		traceState,
+		serviceLogState,
+		selectedServiceLogIndex,
+		selectedTheme,
+		selectedTraceIndex,
+		selectedSpanIndex,
+		selectedTraceService,
+		detailView,
+		showHelp,
+		collapsedSpanIds,
+		spanNavActive,
+		serviceLogNavActive,
+		attrNavActive,
+		chatNavActive,
+		selectedAttrIndex,
+		chatDetailChunkId,
+		chatDetailScrollOffset,
+		selectedChatChunkId,
+		filterMode,
+		filterText,
+		autoRefresh,
+		traceSort,
+		pickerMode,
+		pickerInput,
+		pickerIndex,
+		attrFacets,
+		activeAttrKey,
+		activeAttrValue,
+		waterfallFilterMode,
+		waterfallFilterText,
+		...params,
+	})
+
+	const stateRef = useRef(buildStateSnapshot())
 	// 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, pickerMode, pickerInput, pickerIndex, attrFacets, activeAttrKey, activeAttrValue, ...params }
+		stateRef.current = buildStateSnapshot()
 	})
 
 	const clearPendingG = () => {
@@ -178,18 +254,114 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 
 	const $ = () => stateRef.current
 
+	const resetPicker = () => {
+		setPickerInput("")
+		setPickerIndex(0)
+	}
+
+	const closePicker = () => {
+		setPickerMode("off")
+		resetPicker()
+	}
+
+	const getVisibleSelectedSpans = () => {
+		const s = $()
+		return s.selectedTrace ? getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds) : []
+	}
+
+	const getSelectedVisibleSpan = () => {
+		const s = $()
+		if (s.selectedSpanIndex === null) return null
+		return getVisibleSelectedSpans()[s.selectedSpanIndex] ?? null
+	}
+
 	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)
+		const fullIndex = findTraceIndexById(s.traceState.data, trace.traceId)
 		if (fullIndex >= 0) setSelectedTraceIndex(fullIndex)
 	}
 
+	const currentFilteredTraceIndex = () => {
+		const s = $()
+		const selectedTraceId = s.traceState.data[s.selectedTraceIndex]?.traceId ?? null
+		return findTraceIndexById(s.filteredTraces, selectedTraceId)
+	}
+
+	const attrCountForSelectedSpan = () => {
+		const span = getSelectedVisibleSpan()
+		return span ? Object.keys(span.tags).length : 0
+	}
+
+	const moveTraceBy = (delta: number) => {
+		const s = $()
+		if (s.filteredTraces.length === 0) return
+		const currentIndex = currentFilteredTraceIndex()
+		const nextIndex = currentIndex < 0
+			? 0
+			: Math.max(0, Math.min(currentIndex + delta, s.filteredTraces.length - 1))
+		selectFilteredTraceAt(nextIndex)
+	}
+
+	const moveServiceLogBy = (delta: number) => {
+		const s = $()
+		if (s.serviceLogState.data.length === 0) {
+			setSelectedServiceLogIndex(0)
+			return
+		}
+		setSelectedServiceLogIndex(Math.max(0, Math.min(s.selectedServiceLogIndex + delta, s.serviceLogState.data.length - 1)))
+	}
+
+	const moveSpanBy = (delta: number) => {
+		const s = $()
+		if (!s.selectedTrace) return
+		const visibleCount = getVisibleSelectedSpans().length
+		if (visibleCount === 0) {
+			setSelectedSpanIndex(null)
+			return
+		}
+		const current = s.selectedSpanIndex ?? 0
+		setSelectedSpanIndex(Math.max(0, Math.min(current + delta, visibleCount - 1)))
+	}
+
+	const moveAttrBy = (delta: number) => {
+		const count = attrCountForSelectedSpan()
+		if (count === 0) return
+		const s = $()
+		setSelectedAttrIndex(Math.max(0, Math.min(s.selectedAttrIndex + delta, count - 1)))
+	}
+
+	const moveChatChunkBy = (direction: -1 | 1) => {
+		const s = $()
+		const chunks = s.aiChatChunks
+		if (chunks.length === 0) return
+		if (s.chatDetailChunkId) return
+		const currentIdx = s.selectedChatChunkId
+			? chunks.findIndex((c) => c.id === s.selectedChatChunkId)
+			: 0
+		const nextIdx = Math.max(0, Math.min(currentIdx + direction, chunks.length - 1))
+		const next = chunks[nextIdx]
+		if (next) setSelectedChatChunkId(next.id)
+	}
+
 	const jumpToStart = () => {
 		const s = $()
+		if (s.chatNavActive) {
+			if (s.chatDetailChunkId) {
+				setChatDetailScrollOffset(0)
+				return
+			}
+			const first = s.aiChatChunks[0]
+			if (first) setSelectedChatChunkId(first.id)
+			return
+		}
+		if (s.attrNavActive) {
+			setSelectedAttrIndex(0)
+			return
+		}
 		if (s.spanNavActive && s.selectedTrace) {
-			const visibleCount = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds).length
+			const visibleCount = getVisibleSelectedSpans().length
 			setSelectedSpanIndex(visibleCount === 0 ? null : 0)
 		} else {
 			selectFilteredTraceAt(0)
@@ -198,45 +370,32 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 
 	const jumpToEnd = () => {
 		const s = $()
+		if (s.chatNavActive) {
+			if (s.chatDetailChunkId) {
+				const openChunk = s.aiChatChunks.find((c) => c.id === s.chatDetailChunkId)
+				if (!openChunk) return
+				const lines = renderChunkDetailLines(openChunk, 80)
+				const pageSize = Math.max(4, Math.floor((s.isWideLayout ? s.wideBodyLines : s.narrowBodyLines) * 0.75))
+				setChatDetailScrollOffset(Math.max(0, lines.length - pageSize))
+				return
+			}
+			const last = s.aiChatChunks[s.aiChatChunks.length - 1]
+			if (last) setSelectedChatChunkId(last.id)
+			return
+		}
+		if (s.attrNavActive) {
+			const count = attrCountForSelectedSpan()
+			setSelectedAttrIndex(Math.max(0, count - 1))
+			return
+		}
 		if (s.spanNavActive && s.selectedTrace) {
-			const visibleCount = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds).length
+			const visibleCount = getVisibleSelectedSpans().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
@@ -251,6 +410,46 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 		if (message) s.flashNotice(message)
 	}
 
+	const copySelectedAttrValue = () => {
+		const s = $()
+		const span = getSelectedVisibleSpan()
+		if (!span) return
+		const entries = Object.entries(span.tags)
+		const entry = entries[s.selectedAttrIndex] ?? entries[0]
+		if (!entry) {
+			s.flashNotice("No tag to copy")
+			return
+		}
+		const [key, value] = entry
+		void copyToClipboard(value)
+			.then(() => {
+				const preview = value.length > 40 ? `${value.slice(0, 39)}\u2026` : value
+				s.flashNotice(`Copied ${key}: ${preview}`)
+			})
+			.catch((error) => {
+				s.flashNotice(error instanceof Error ? error.message : String(error))
+			})
+	}
+
+	const copySelectedChatChunk = () => {
+		const s = $()
+		const chunkId = s.chatDetailChunkId ?? s.selectedChatChunkId
+		const chunk = s.aiChatChunks.find((c) => c.id === chunkId)
+		if (!chunk) {
+			s.flashNotice("No chunk selected")
+			return
+		}
+		const payload = chunk.body.length > 0 ? chunk.body : chunk.header
+		void copyToClipboard(payload)
+			.then(() => {
+				const label = chunk.toolName ?? chunk.kind
+				s.flashNotice(`Copied ${label} (${payload.length} chars)`)
+			})
+			.catch((error) => {
+				s.flashNotice(error instanceof Error ? error.message : String(error))
+			})
+	}
+
 	const copySelectedIds = () => {
 		const s = $()
 		if (s.serviceLogNavActive) {
@@ -278,8 +477,7 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 			return
 		}
 
-		const visibleSpans = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds)
-		const selectedSpan = s.selectedSpanIndex !== null ? visibleSpans[s.selectedSpanIndex] ?? null : null
+		const selectedSpan = getSelectedVisibleSpan()
 		const lines = [
 			`traceId=${s.selectedTrace.traceId}`,
 			selectedSpan ? `spanId=${selectedSpan.spanId}` : null,
@@ -302,167 +500,199 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 
 	const pageBy = (direction: -1 | 1) => {
 		const s = $()
+		if (s.chatNavActive) {
+			if (s.chatDetailChunkId) {
+				const openChunk = s.aiChatChunks.find((c) => c.id === s.chatDetailChunkId)
+				if (!openChunk) return
+				const pageSize = Math.max(1, Math.floor((s.isWideLayout ? s.wideBodyLines : s.narrowBodyLines) / 2))
+				const detailLines = renderChunkDetailLines(openChunk, 80)
+				const maxOffset = Math.max(0, detailLines.length - pageSize)
+				setChatDetailScrollOffset((current) => clamp(current + direction * pageSize, 0, maxOffset))
+				return
+			}
+			// Page-by-half in chunk units.
+			const pageSize = Math.max(1, Math.floor(s.aiChatChunks.length / 4))
+			const chunks = s.aiChatChunks
+			const currentIdx = s.selectedChatChunkId
+				? chunks.findIndex((c) => c.id === s.selectedChatChunkId)
+				: 0
+			const nextIdx = Math.max(0, Math.min(currentIdx + direction * pageSize, chunks.length - 1))
+			const next = chunks[nextIdx]
+			if (next) setSelectedChatChunkId(next.id)
+			return
+		}
+		if (s.attrNavActive) {
+			const count = attrCountForSelectedSpan()
+			if (count === 0) return
+			// Attr page size: ~half the viewport in "blocks", not rows.
+			// Attributes are variable height so measuring in blocks keeps
+			// the jump feeling consistent regardless of value length.
+			const pageSize = Math.max(1, Math.floor((s.isWideLayout ? s.wideBodyLines : s.narrowBodyLines) / 4))
+			setSelectedAttrIndex((current) =>
+				Math.max(0, Math.min(current + direction * pageSize, count - 1)),
+			)
+			return
+		}
 		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))
-			})
+			moveServiceLogBy(direction * serviceLogPageSize)
 		} else if (s.spanNavActive) {
-			if (!s.selectedTrace) return
-			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))
-			})
+			moveSpanBy(direction * s.spanPageSize)
 		} 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
-			})
+			moveTraceBy(direction * s.tracePageSize)
 		}
 	}
 
-	useKeyboard((key) => {
+	const handlePickerMode = (key: KeyboardKey) => {
 		const s = $()
+		if (s.pickerMode === "off") return false
 
-		// Attribute picker modal owns the keyboard while open.
-		if (s.pickerMode !== "off") {
-			const rows = filterFacets(s.attrFacets.data, s.pickerInput)
-			const clampedIndex = rows.length === 0 ? 0 : Math.max(0, Math.min(s.pickerIndex, rows.length - 1))
-			const move = (delta: number) => {
-				if (rows.length === 0) return
-				setPickerIndex(Math.max(0, Math.min(clampedIndex + delta, rows.length - 1)))
-			}
-			if (key.name === "escape") {
+		const rows = filterFacets(s.attrFacets.data, s.pickerInput)
+		const clampedIndex = rows.length === 0 ? 0 : Math.max(0, Math.min(s.pickerIndex, rows.length - 1))
+		const move = (delta: number) => {
+			if (rows.length === 0) return
+			setPickerIndex(Math.max(0, Math.min(clampedIndex + delta, rows.length - 1)))
+		}
+
+		if (key.name === "escape") {
+			closePicker()
+			return true
+		}
+		if (key.ctrl && key.name === "c") {
+			if (s.pickerInput.length > 0) {
+				resetPicker()
+			} else {
 				setPickerMode("off")
-				setPickerInput("")
 				setPickerIndex(0)
-				return
-			}
-			// Ctrl-C: clear input, or close the picker if already empty.
-			if (key.ctrl && key.name === "c") {
-				if (s.pickerInput.length > 0) {
-					setPickerInput("")
-					setPickerIndex(0)
-				} else {
-					setPickerMode("off")
-					setPickerIndex(0)
-				}
-				return
 			}
-			if (key.name === "up" || (key.ctrl && key.name === "p")) { move(-1); return }
-			if (key.name === "down" || (key.ctrl && key.name === "n")) { move(1); return }
-			if (key.name === "pageup") { move(-10); return }
-			if (key.name === "pagedown") { move(10); return }
-			if (key.name === "return" || key.name === "enter") {
-				const row = rows[clampedIndex]
-				if (!row) return
-				if (s.pickerMode === "keys") {
-					// Drill from keys → values for this key.
-					setActiveAttrKey(row.value)
-					setPickerMode("values")
-					setPickerInput("")
-					setPickerIndex(0)
-				} else {
-					// Apply: activeAttrKey is already set, now pin the value.
-					setActiveAttrValue(row.value)
-					setPickerMode("off")
-					setPickerInput("")
-					setPickerIndex(0)
-					s.flashNotice(`Filter: ${s.activeAttrKey}=${row.value}`)
-				}
-				return
+			return true
+		}
+		if (key.name === "up" || (key.ctrl && key.name === "p")) {
+			move(-1)
+			return true
+		}
+		if (key.name === "down" || (key.ctrl && key.name === "n")) {
+			move(1)
+			return true
+		}
+		if (key.name === "pageup") {
+			move(-10)
+			return true
+		}
+		if (key.name === "pagedown") {
+			move(10)
+			return true
+		}
+		if (key.name === "return" || key.name === "enter") {
+			const row = rows[clampedIndex]
+			if (!row) return true
+			if (s.pickerMode === "keys") {
+				setActiveAttrKey(row.value)
+				setPickerMode("values")
+				resetPicker()
+			} else {
+				setActiveAttrValue(row.value)
+				closePicker()
+				s.flashNotice(`Filter: ${s.activeAttrKey}=${row.value}`)
 			}
-			if (key.name === "backspace") {
-				if (s.pickerInput.length > 0) {
-					setPickerInput(s.pickerInput.slice(0, -1))
-					setPickerIndex(0)
-					return
-				}
-				// At empty input in values mode, backspace walks back to keys.
-				if (s.pickerMode === "values") {
-					setPickerMode("keys")
-					setActiveAttrKey(null)
-					setPickerIndex(0)
-					return
-				}
-				return
+			return true
+		}
+		if (key.name === "backspace") {
+			if (s.pickerInput.length > 0) {
+				setPickerInput(s.pickerInput.slice(0, -1))
+				setPickerIndex(0)
+				return true
 			}
-			// Prefer key.sequence over key.name so multi-char paste events that
-			// slip through as a single raw sequence still get inserted in full.
-			const printable = extractPrintable(key)
-			if (printable) {
-				// Functional setState — multiple key events in the same tick would
-				// otherwise all read a stale stateRef.current.pickerInput and
-				// clobber each other, losing all but the last char of a paste.
-				setPickerInput((current) => current + printable)
+			if (s.pickerMode === "values") {
+				setPickerMode("keys")
+				setActiveAttrKey(null)
 				setPickerIndex(0)
-				return
+				return true
 			}
-			return
+			return true
 		}
 
-		// Filter mode: capture text input
-		if (s.filterMode) {
-			if (key.name === "escape") {
-				setFilterMode(false)
-				setFilterText("")
-				return
-			}
-			// Ctrl-C: clear the input, or exit filter mode if already empty.
-			if (key.ctrl && key.name === "c") {
-				if (s.filterText.length > 0) {
-					setFilterText("")
-				} else {
-					setFilterMode(false)
-				}
-				return
-			}
-			if (key.name === "return" || key.name === "enter") {
-				setFilterMode(false)
-				return
-			}
-			if (key.name === "backspace") {
-				setFilterText((current) => current.slice(0, -1))
-				return
-			}
-			const printable = extractPrintable(key)
-			if (printable) {
-				// Functional setState so rapid keystrokes / pastes don't clobber
-				// each other via a stale stateRef.current.filterText closure.
-				setFilterText((current) => current + printable)
-				return
-			}
-			return
+		const printable = extractPrintable(key)
+		if (printable) {
+			setPickerInput((current) => current + printable)
+			setPickerIndex(0)
 		}
-		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)
+		return true
+	}
 
-		if (questionMark) {
-			clearPendingG()
-			setShowHelp((current) => !current)
-			return
+	const handleTraceFilterMode = (key: KeyboardKey) => {
+		const s = $()
+		if (!s.filterMode) return false
+
+		if (key.name === "escape") {
+			setFilterMode(false)
+			setFilterText("")
+			return true
+		}
+		if (key.ctrl && key.name === "c") {
+			if (s.filterText.length > 0) setFilterText("")
+			else setFilterMode(false)
+			return true
+		}
+		if (key.name === "return" || key.name === "enter") {
+			setFilterMode(false)
+			return true
+		}
+		if (key.name === "backspace") {
+			setFilterText((current) => current.slice(0, -1))
+			return true
 		}
 
-		if (s.showHelp) {
-			if (key.name === "return" || key.name === "enter" || key.name === "escape") {
-				setShowHelp(false)
-			}
-			return
+		const printable = extractPrintable(key)
+		if (printable) setFilterText((current) => current + printable)
+		return true
+	}
+
+	const handleWaterfallFilterMode = (key: KeyboardKey) => {
+		const s = $()
+		if (!s.waterfallFilterMode) return false
+
+		if (key.name === "escape") {
+			setWaterfallFilterMode(false)
+			setWaterfallFilterText("")
+			return true
 		}
+		if (key.ctrl && key.name === "c") {
+			if (s.waterfallFilterText.length > 0) setWaterfallFilterText("")
+			else setWaterfallFilterMode(false)
+			return true
+		}
+		if (key.name === "return" || key.name === "enter") {
+			setWaterfallFilterMode(false)
+			return true
+		}
+		if (key.name === "backspace") {
+			setWaterfallFilterText((current) => current.slice(0, -1))
+			return true
+		}
+
+		const printable = extractPrintable(key)
+		if (printable) setWaterfallFilterText((current) => current + printable)
+		return true
+	}
+
+	const handleQuestionMarkKey = (key: KeyboardKey) => {
+		const questionMark = key.name === "?" || (key.name === "/" && key.shift)
+		if (!questionMark) return false
+		clearPendingG()
+		setShowHelp((current) => !current)
+		return true
+	}
+
+	const handleHelpModalKey = (key: KeyboardKey) => {
+		if (!$().showHelp) return false
+		if (key.name === "return" || key.name === "enter" || key.name === "escape") setShowHelp(false)
+		return true
+	}
 
+	const handleJumpKeys = (key: KeyboardKey) => {
+		const plainG = key.name === "g" && !key.ctrl && !key.meta && !key.option && !key.shift
+		const shiftedG = key.name === "g" && key.shift
 		if (plainG && !key.repeated) {
 			if (pendingGRef.current) {
 				clearPendingG()
@@ -470,183 +700,206 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 			} else {
 				armPendingG()
 			}
-			return
+			return true
 		}
-
 		if (shiftedG) {
 			clearPendingG()
 			jumpToEnd()
-			return
+			return true
 		}
+		return false
+	}
 
-		clearPendingG()
-
+	const handleSystemKeys = (key: KeyboardKey) => {
+		const s = $()
 		if (key.name === "q" || (key.ctrl && key.name === "c")) {
-			if (quittingRef.current) return
+			if (quittingRef.current) return true
 			quittingRef.current = true
 			renderer.destroy()
-			return
+			return true
 		}
 		if (key.name === "home") {
-			if (s.serviceLogNavActive) {
-				setSelectedServiceLogIndex(0)
-			} else {
-				jumpToStart()
-			}
-			return
+			if (s.serviceLogNavActive) setSelectedServiceLogIndex(0)
+			else jumpToStart()
+			return true
 		}
 		if (key.name === "end") {
-			if (s.serviceLogNavActive) {
-				setSelectedServiceLogIndex(s.serviceLogState.data.length === 0 ? 0 : s.serviceLogState.data.length - 1)
-			} else {
-				jumpToEnd()
-			}
-			return
+			if (s.serviceLogNavActive) setSelectedServiceLogIndex(s.serviceLogState.data.length === 0 ? 0 : s.serviceLogState.data.length - 1)
+			else jumpToEnd()
+			return true
 		}
 		if (key.name === "pagedown" || (key.ctrl && key.name === "d")) {
 			pageBy(1)
-			return
+			return true
 		}
 		if (key.name === "pageup" || (key.ctrl && key.name === "u")) {
 			pageBy(-1)
-			return
+			return true
 		}
 		if (key.ctrl && key.name === "p") {
 			moveTraceBy(-1)
-			return
+			return true
 		}
 		if (key.ctrl && key.name === "n") {
 			moveTraceBy(1)
-			return
+			return true
 		}
-		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
-			}
-			// At the trace list, `esc` clears any applied attribute filter so
-			// there's a clean way back to the unfiltered list without hunting
-			// for the picker key.
-			if (s.activeAttrKey || s.activeAttrValue) {
-				setActiveAttrKey(null)
-				setActiveAttrValue(null)
-				s.flashNotice("Cleared attribute filter")
-				return
+		return false
+	}
+
+	const handleEscapeKey = (key: KeyboardKey) => {
+		if (key.name !== "escape") return false
+		const s = $()
+		if (s.chatDetailChunkId) {
+			setChatDetailChunkId(null)
+			setChatDetailScrollOffset(0)
+			return true
+		}
+		if (s.waterfallFilterText.length > 0) {
+			setWaterfallFilterText("")
+			return true
+		}
+		if (s.detailView === "span-detail" || s.detailView === "service-logs") {
+			setDetailView("waterfall")
+			return true
+		}
+		if (s.spanNavActive) {
+			setSelectedSpanIndex(null)
+			return true
+		}
+		if (s.activeAttrKey || s.activeAttrValue) {
+			setActiveAttrKey(null)
+			setActiveAttrValue(null)
+			s.flashNotice("Cleared attribute filter")
+			return true
+		}
+		return true
+	}
+
+	const handleEnterKey = (key: KeyboardKey) => {
+		if (key.name !== "return" && key.name !== "enter") return false
+		const s = $()
+		if (s.chatNavActive) {
+			const chunk = s.aiChatChunks.find((c) => c.id === s.selectedChatChunkId)
+			if (chunk) {
+				setChatDetailChunkId(chunk.id)
+				setChatDetailScrollOffset(0)
 			}
-			return
+			return true
 		}
-		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)}`)
-					}
+		if (s.detailView === "service-logs") {
+			const selectedLog = s.serviceLogState.data[s.selectedServiceLogIndex]
+			if (selectedLog?.traceId) {
+				const traceIndex = findTraceIndexById(s.traceState.data, 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
+			return true
+		}
+		if (s.spanNavActive && s.detailView === "waterfall") {
+			setDetailView("span-detail")
+			return true
 		}
+		if (!s.spanNavActive && s.selectedTrace && s.selectedTrace.spans.length > 0) {
+			setSelectedSpanIndex(0)
+			return true
+		}
+		return true
+	}
+
+	const handleToolbarKeys = (key: KeyboardKey) => {
+		const s = $()
 		if (key.name === "r") {
 			refresh("Refreshing traces...")
-			return
+			return true
 		}
 		if (key.name === "a") {
 			setAutoRefresh(!s.autoRefresh)
 			s.flashNotice(s.autoRefresh ? "Auto-refresh paused" : "Auto-refresh resumed")
-			return
+			return true
 		}
 		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
+			return true
 		}
 		if (key.name === "t") {
 			const nextTheme = cycleThemeName(s.selectedTheme)
 			setSelectedTheme(nextTheme)
 			s.flashNotice(`Theme: ${themeLabel(nextTheme)}`)
-			return
+			return true
+		}
+		if ((key.name === "n" || key.name === "N") && !key.ctrl && !key.meta) {
+			const inWaterfall = s.detailView === "span-detail" || s.selectedSpanIndex !== null
+			if (inWaterfall && s.waterfallFilterText.length > 0 && s.selectedTrace) {
+				const visibleSpans = getVisibleSelectedSpans()
+				const matchingIds = computeMatchingSpanIds(visibleSpans, s.waterfallFilterText)
+				if (matchingIds && matchingIds.size > 0) {
+					const direction = key.name === "N" ? -1 : 1
+					const next = findAdjacentMatch(visibleSpans, matchingIds, s.selectedSpanIndex, direction)
+					if (next !== null) setSelectedSpanIndex(next)
+					else s.flashNotice("No matches")
+				} else {
+					s.flashNotice("No matches")
+				}
+				return true
+			}
 		}
 		if (key.name === "/" && !key.shift) {
-			setFilterMode(true)
-			return
+			const inWaterfall = s.detailView === "span-detail" || s.selectedSpanIndex !== null
+			if (inWaterfall) setWaterfallFilterMode(true)
+			else setFilterMode(true)
+			return true
 		}
 		if ((key.name === "f" || key.name === "F") && !key.ctrl && !key.meta) {
-			// Open attribute picker at the keys step. If a filter is already
-			// applied, reopening lets the user refine or switch.
 			setPickerMode("keys")
-			setPickerInput("")
-			setPickerIndex(0)
+			resetPicker()
 			setActiveAttrKey(null)
-			return
+			return true
 		}
 		if (key.name === "tab") {
 			toggleServiceLogsView()
-			return
+			return true
 		}
 		if (key.name === "[") {
 			cycleService(-1)
-			return
+			return true
 		}
 		if (key.name === "]") {
 			cycleService(1)
-			return
+			return true
 		}
+		return false
+	}
+
+	const handleMovementKeys = (key: KeyboardKey) => {
+		const s = $()
 		if (key.name === "up" || key.name === "k") {
-			if (s.serviceLogNavActive) {
-				moveServiceLogBy(-1)
-			} else if (s.spanNavActive) {
-				// Locked to span nav; never fall through to trace-list nav while
-				// drilled in. If the trace detail is still loading, swallow the
-				// key instead of silently leaking it to the trace list.
-				if (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)
+			if (s.chatNavActive) {
+				moveChatChunkBy(-1)
+				return true
 			}
-			return
+			if (s.attrNavActive) { moveAttrBy(-1); return true }
+			if (s.serviceLogNavActive) { moveServiceLogBy(-1); return true }
+			if (s.spanNavActive) { moveSpanBy(-1); return true }
+			moveTraceBy(-1)
+			return true
 		}
 		if (key.name === "down" || key.name === "j") {
-			if (s.serviceLogNavActive) {
-				moveServiceLogBy(1)
-			} else if (s.spanNavActive) {
-				if (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)
+			if (s.chatNavActive) {
+				moveChatChunkBy(1)
+				return true
 			}
-			return
+			if (s.attrNavActive) { moveAttrBy(1); return true }
+			if (s.serviceLogNavActive) { moveServiceLogBy(1); return true }
+			if (s.spanNavActive) { moveSpanBy(1); return true }
+			moveTraceBy(1)
+			return true
 		}
 		if (key.name === "left" || key.name === "h") {
 			if (s.spanNavActive && s.selectedTrace) {
@@ -658,13 +911,11 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 						selectedIndex: s.selectedSpanIndex,
 						direction: "left",
 					})
-					if (result.selectedIndex !== s.selectedSpanIndex) {
-						setSelectedSpanIndex(result.selectedIndex)
-					}
+					if (result.selectedIndex !== s.selectedSpanIndex) setSelectedSpanIndex(result.selectedIndex)
 					return result.collapsed
 				})
 			}
-			return
+			return true
 		}
 		if (key.name === "right" || key.name === "l") {
 			if (s.spanNavActive && s.selectedTrace) {
@@ -676,16 +927,19 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 						selectedIndex: s.selectedSpanIndex,
 						direction: "right",
 					})
-					if (result.selectedIndex !== s.selectedSpanIndex) {
-						setSelectedSpanIndex(result.selectedIndex)
-					}
+					if (result.selectedIndex !== s.selectedSpanIndex) setSelectedSpanIndex(result.selectedIndex)
 					return result.collapsed
 				})
 			} else if (!s.spanNavActive && !s.serviceLogNavActive) {
 				toggleServiceLogsView()
 			}
-			return
+			return true
 		}
+		return false
+	}
+
+	const handleOpenCopyKeys = (key: KeyboardKey) => {
+		const s = $()
 		if (key.name === "o" && !key.shift) {
 			if (s.serviceLogNavActive) {
 				const selectedLog = s.serviceLogState.data[s.selectedServiceLogIndex]
@@ -693,21 +947,23 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 					void Bun.spawn({ cmd: ["open", traceUiUrl(selectedLog.traceId)], stdout: "ignore", stderr: "ignore" })
 					s.flashNotice(`Opened trace ${selectedLog.traceId.slice(-8)}`)
 				}
-				return
+				return true
 			}
-			if (!s.selectedTrace) return
+			if (!s.selectedTrace) return true
 			void Bun.spawn({ cmd: ["open", traceUiUrl(s.selectedTrace.traceId)], stdout: "ignore", stderr: "ignore" })
 			s.flashNotice(`Opened trace ${s.selectedTrace.traceId.slice(-8)}`)
-			return
+			return true
 		}
 		if (key.name === "o" && key.shift) {
 			void Bun.spawn({ cmd: ["open", webUiUrl()], stdout: "ignore", stderr: "ignore" })
 			s.flashNotice("Opened web UI")
-			return
+			return true
 		}
 		if (key.name === "y" || key.name === "Y") {
-			copySelectedIds()
-			return
+			if (s.chatNavActive) copySelectedChatChunk()
+			else if (s.attrNavActive) copySelectedAttrValue()
+			else copySelectedIds()
+			return true
 		}
 		if (key.name === "c" || key.name === "C") {
 			void copyToClipboard(otelServerInstructions())
@@ -717,7 +973,27 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 				.catch((error) => {
 					s.flashNotice(error instanceof Error ? error.message : String(error))
 				})
+			return true
 		}
+		return false
+	}
+
+	useKeyboard((key: KeyboardKey) => {
+		if (handlePickerMode(key)) return
+		if (handleTraceFilterMode(key)) return
+		if (handleWaterfallFilterMode(key)) return
+		if (handleQuestionMarkKey(key)) return
+		if (handleHelpModalKey(key)) return
+		if (handleJumpKeys(key)) return
+
+		clearPendingG()
+
+		if (handleSystemKeys(key)) return
+		if (handleEscapeKey(key)) return
+		if (handleEnterKey(key)) return
+		if (handleToolbarKeys(key)) return
+		if (handleMovementKeys(key)) return
+		handleOpenCopyKeys(key)
 	})
 
 	return { spanNavActive }