@kitlangton/motel 0.1.2 → 0.2.0

package/src/ui/useKeyboardNav.ts

@@ -1,6 +1,6 @@
 import { useAtom } from "@effect/atom-react"
 import { useKeyboard, useRenderer } from "@opentui/react"
-import { useLayoutEffect, useRef } from "react"
+import { useEffect, useLayoutEffect, useRef } from "react"
 import type { TraceItem, TraceSummaryItem } from "../domain.ts"
 import { otelServerInstructions } from "../instructions.ts"
 import { copyToClipboard, traceUiUrl, webUiUrl } from "./format.ts"
@@ -27,13 +27,47 @@ 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 { getVisibleSpans } from "./Waterfall.tsx"
+import { computeMatchingSpanIds, findAdjacentMatch } from "./waterfallFilter.ts"
 import { resolveCollapseStep } from "./waterfallNav.ts"
 
+/**
+ * Pull a printable string out of a key event. Handles two cases:
+ *
+ * 1. A plain printable key (1 char) — returns the char.
+ * 2. A multi-char sequence that arrived as one event (common when the
+ *    terminal has bracketed paste disabled but the user pasted quickly and
+ *    opentui's parser returned the whole buffer as one key). Returns the
+ *    sanitised sequence with control bytes stripped.
+ *
+ * Returns `null` for non-printable events (function keys, modifiers, etc.)
+ * so callers can skip them.
+ */
+const extractPrintable = (key: {
+	readonly name: string
+	readonly sequence?: string
+	readonly ctrl: boolean
+	readonly meta: boolean
+}): 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
+	// control byte means this was a function / navigation key.
+	if (seq.length > 1 && !/[\x00-\x1f\x7f]/.test(seq)) return seq
+	return null
+}
+
 interface KeyboardNavParams {
 	selectedTrace: TraceItem | null
 	filteredTraces: readonly TraceSummaryItem[]
@@ -78,6 +112,8 @@ 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 pendingGRef = useRef(false)
 	const pendingGTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
@@ -86,12 +122,50 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 	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, pickerMode, pickerInput, pickerIndex, attrFacets, activeAttrKey, activeAttrValue, ...params })
+	// Bracketed paste: when the terminal has bracketed paste enabled, opentui
+	// surfaces the full pasted text as a single "paste" event on keyInput.
+	// Route it into whichever input is currently open. We also enable the
+	// mode ourselves (`\x1b[?2004h`) in case the host terminal didn't — it's
+	// a no-op on terminals that already had it on.
+	useEffect(() => {
+		const keyInput = (renderer as unknown as { keyInput?: { on: (event: string, handler: (e: unknown) => void) => void; off: (event: string, handler: (e: unknown) => void) => void } }).keyInput
+		if (!keyInput) return
+		try {
+			process.stdout.write("\x1b[?2004h")
+		} catch {
+			// Best effort — some test environments don't have a real TTY.
+		}
+		const handler = (event: unknown) => {
+			const bytes = (event as { bytes?: Uint8Array }).bytes
+			if (!bytes || bytes.length === 0) return
+			const text = Buffer.from(bytes).toString("utf8").replace(/[\x00-\x1f\x7f]+/g, (match) => match === "\n" ? " " : "")
+			if (!text) return
+			const s = stateRef.current
+			if (s.pickerMode !== "off") {
+				setPickerInput((current) => current + text)
+				setPickerIndex(0)
+				return
+			}
+			if (s.filterMode) {
+				setFilterText((current) => current + text)
+				return
+			}
+		}
+		keyInput.on("paste", handler)
+		return () => {
+			keyInput.off("paste", handler)
+			try {
+				process.stdout.write("\x1b[?2004l")
+			} catch {}
+		}
+	}, [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, waterfallFilterMode, waterfallFilterText, ...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, pickerMode, pickerInput, pickerIndex, attrFacets, activeAttrKey, activeAttrValue, ...params }
+		stateRef.current = { traceState, serviceLogState, selectedServiceLogIndex, selectedTheme, selectedTraceIndex, selectedSpanIndex, selectedTraceService, detailView, showHelp, collapsedSpanIds, spanNavActive, serviceLogNavActive, filterMode, filterText, autoRefresh, traceSort, pickerMode, pickerInput, pickerIndex, attrFacets, activeAttrKey, activeAttrValue, waterfallFilterMode, waterfallFilterText, ...params }
 	})
 
 	const clearPendingG = () => {
@@ -285,6 +359,17 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 				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 }
@@ -323,8 +408,14 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 				}
 				return
 			}
-			if (key.name.length === 1 && !key.ctrl && !key.meta) {
-				setPickerInput(s.pickerInput + key.name)
+			// 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)
 				setPickerIndex(0)
 				return
 			}
@@ -338,17 +429,65 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 				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(s.filterText.slice(0, -1))
+				setFilterText((current) => current.slice(0, -1))
 				return
 			}
-			// Single printable character
-			if (key.name.length === 1 && !key.ctrl && !key.meta) {
-				setFilterText(s.filterText + key.name)
+			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
+		}
+
+		// Waterfall filter mode: text-capture scoped to the current
+		// trace's spans.
+		// - enter  → commit: close input but keep text so dimming persists
+		//            while the user navigates. `/` can be pressed again
+		//            to edit.
+		// - esc    → cancel: clear text + exit input entirely.
+		// - ctrl-c → clear input if non-empty, otherwise exit.
+		if (s.waterfallFilterMode) {
+			if (key.name === "escape") {
+				setWaterfallFilterMode(false)
+				setWaterfallFilterText("")
+				return
+			}
+			if (key.ctrl && key.name === "c") {
+				if (s.waterfallFilterText.length > 0) {
+					setWaterfallFilterText("")
+				} else {
+					setWaterfallFilterMode(false)
+				}
+				return
+			}
+			if (key.name === "return" || key.name === "enter") {
+				setWaterfallFilterMode(false)
+				return
+			}
+			if (key.name === "backspace") {
+				setWaterfallFilterText((current) => current.slice(0, -1))
+				return
+			}
+			const printable = extractPrintable(key)
+			if (printable) {
+				setWaterfallFilterText((current) => current + printable)
 				return
 			}
 			return
@@ -431,6 +570,14 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 				setShowHelp(false)
 				return
 			}
+			// Committed waterfall filter outranks drill-back: hitting esc
+			// should clear the dim before jumping you out of the span
+			// detail pane. That keeps a single `esc` predictable whether
+			// the filter was applied by typing or left over from before.
+			if (s.waterfallFilterText.length > 0) {
+				setWaterfallFilterText("")
+				return
+			}
 			if (s.detailView === "span-detail" || s.detailView === "service-logs") {
 				setDetailView("waterfall")
 				return
@@ -495,8 +642,42 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 			s.flashNotice(`Theme: ${themeLabel(nextTheme)}`)
 			return
 		}
+		// `n` / `N`: jump between matches of the committed waterfall filter.
+		// Only active when drilled into a trace AND the filter has text
+		// (committed or live — either way, there's a dim/highlight we can
+		// step through). Wraps at the ends like vim's /n. Plain `n` forward,
+		// shift-n (`N`) backward.
+		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 = getVisibleSpans(s.selectedTrace.spans, s.collapsedSpanIds)
+				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
+			}
+			// Fall through when not in a trace detail view — reserves `n`
+			// for other future bindings without shadowing them globally.
+		}
+
 		if (key.name === "/" && !key.shift) {
-			setFilterMode(true)
+			// When drilled into a trace (viewLevel >= 1 — waterfall or
+			// span detail is the dominant pane), `/` opens a filter scoped
+			// to the current trace's spans instead of the trace list.
+			// Drill level here is inferred from selectedSpanIndex/detailView
+			// the same way useAppLayout does it.
+			const inWaterfall = s.detailView === "span-detail" || s.selectedSpanIndex !== null
+			if (inWaterfall) {
+				setWaterfallFilterMode(true)
+			} else {
+				setFilterMode(true)
+			}
 			return
 		}
 		if ((key.name === "f" || key.name === "F") && !key.ctrl && !key.meta) {

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
+}