@kitlangton/motel 0.1.3 → 0.2.0

package/src/ui/app/TraceWorkspace.tsx

@@ -18,6 +18,8 @@ interface TraceWorkspaceProps {
 	readonly detailView: DetailView
 	readonly filterMode: boolean
 	readonly filterText: string
+	readonly waterfallFilterMode: boolean
+	readonly waterfallFilterText: string
 	readonly traceListProps: TraceListProps
 	readonly selectedTraceService: string | null
 	readonly serviceLogState: ServiceLogState
@@ -40,6 +42,8 @@ export const TraceWorkspace = ({
 	detailView,
 	filterMode,
 	filterText,
+	waterfallFilterMode,
+	waterfallFilterText,
 	traceListProps,
 	selectedTraceService,
 	serviceLogState,
@@ -132,7 +136,7 @@ export const TraceWorkspace = ({
 							selectedSpanIndex={selectedSpanIndex}
 							collapsedSpanIds={collapsedSpanIds}
 							focused={false}
-							onSelectSpan={selectSpan}
+							waterfallFilterMode={waterfallFilterMode} waterfallFilterText={waterfallFilterText} onSelectSpan={selectSpan}
 						/>
 					</box>
 				</box>
@@ -159,7 +163,7 @@ export const TraceWorkspace = ({
 							selectedSpanIndex={selectedSpanIndex}
 							collapsedSpanIds={collapsedSpanIds}
 							focused={true}
-							onSelectSpan={selectSpan}
+							waterfallFilterMode={waterfallFilterMode} waterfallFilterText={waterfallFilterText} onSelectSpan={selectSpan}
 						/>
 					</box>
 				</box>
@@ -182,7 +186,7 @@ export const TraceWorkspace = ({
 						selectedSpanIndex={selectedSpanIndex}
 						collapsedSpanIds={collapsedSpanIds}
 						focused={false}
-						onSelectSpan={selectSpan}
+						waterfallFilterMode={waterfallFilterMode} waterfallFilterText={waterfallFilterText} onSelectSpan={selectSpan}
 					/>
 				</box>
 				<SeparatorColumn height={wideBodyHeight} junctionChars={separatorCrossChars} />
@@ -226,7 +230,7 @@ export const TraceWorkspace = ({
 					selectedSpanIndex={selectedSpanIndex}
 					collapsedSpanIds={collapsedSpanIds}
 					focused={false}
-					onSelectSpan={selectSpan}
+					waterfallFilterMode={waterfallFilterMode} waterfallFilterText={waterfallFilterText} onSelectSpan={selectSpan}
 				/>
 			</>
 		)
@@ -265,7 +269,7 @@ export const TraceWorkspace = ({
 					selectedSpanIndex={selectedSpanIndex}
 					collapsedSpanIds={collapsedSpanIds}
 					focused={true}
-					onSelectSpan={selectSpan}
+					waterfallFilterMode={waterfallFilterMode} waterfallFilterText={waterfallFilterText} onSelectSpan={selectSpan}
 				/>
 			) : (
 				<SpanDetailPane

package/src/ui/app/useTraceScreenData.ts

@@ -1,5 +1,5 @@
 import { useAtom } from "@effect/atom-react"
-import { useCallback, useEffect, useMemo, useRef } from "react"
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
 import { config } from "../../config.js"
 import type { LogItem, TraceItem } from "../../domain.ts"
 import {
@@ -32,6 +32,7 @@ import {
 	traceSortAtom,
 	traceStateAtom,
 } from "../state.ts"
+import { parseFilterText } from "../filterParser.ts"
 import { getVisibleSpans } from "../Waterfall.tsx"
 
 export const useTraceScreenData = () => {
@@ -54,6 +55,17 @@ export const useTraceScreenData = () => {
 	const [activeAttrValue] = useAtom(activeAttrValueAtom)
 	const [traceSort] = useAtom(traceSortAtom)
 
+	// `:ai <query>` is parsed out of the filter text and debounced so
+	// typing doesn't hammer FTS. The other modifiers (:error, operation
+	// needle) stay client-side since we already have those on trace
+	// summaries. 250ms feels responsive without firing on every keystroke.
+	const parsedFilter = useMemo(() => parseFilterText(filterText), [filterText])
+	const [debouncedAiText, setDebouncedAiText] = useState<string | null>(parsedFilter.aiText)
+	useEffect(() => {
+		const handle = setTimeout(() => setDebouncedAiText(parsedFilter.aiText), 250)
+		return () => clearTimeout(handle)
+	}, [parsedFilter.aiText])
+
 	const selectedTraceRef = useRef<string | null>(null)
 	const cacheEpochRef = useRef(0)
 	const traceDetailCacheRef = useRef(new Map<string, { data: TraceItem | null; fetchedAt: Date }>())
@@ -99,9 +111,18 @@ export const useTraceScreenData = () => {
 					setSelectedTraceService(effectiveService)
 				}
 
+				// Branch on whether any server-side filter is active. `:ai`
+				// (debouncedAiText) and the attr picker compose; either
+				// alone also uses the filtered loader. Unfiltered falls
+				// back to the fast recent-summaries path.
+				const hasAttrFilter = Boolean(activeAttrKey && activeAttrValue)
+				const hasAiFilter = Boolean(debouncedAiText)
 				const traces = effectiveService
-					? (activeAttrKey && activeAttrValue
-						? await loadFilteredTraceSummaries(effectiveService, { [activeAttrKey]: activeAttrValue })
+					? (hasAttrFilter || hasAiFilter
+						? await loadFilteredTraceSummaries(effectiveService, {
+							attributeFilters: hasAttrFilter ? { [activeAttrKey as string]: activeAttrValue as string } : undefined,
+							aiText: hasAiFilter ? debouncedAiText : null,
+						})
 						: await loadRecentTraceSummaries(effectiveService))
 					: []
 				if (cancelled) return
@@ -126,7 +147,7 @@ export const useTraceScreenData = () => {
 		return () => {
 			cancelled = true
 		}
-	}, [refreshNonce, selectedTraceService, activeAttrKey, activeAttrValue, setSelectedTraceIndex, setSelectedTraceService, setTraceState])
+	}, [refreshNonce, selectedTraceService, activeAttrKey, activeAttrValue, debouncedAiText, setSelectedTraceIndex, setSelectedTraceService, setTraceState])
 
 	useEffect(() => {
 		setSelectedTraceIndex((current) => {
@@ -359,13 +380,14 @@ export const useTraceScreenData = () => {
 		})
 	}, [serviceLogState.data.length, setSelectedServiceLogIndex])
 
+	// Client-side filters: `:error` + operation-name needle both run
+	// against already-loaded summaries (no server round-trip). The `:ai`
+	// query, by contrast, is applied server-side in the load effect
+	// above so we don't need to re-filter it here.
 	const preFilterTraces = filterText
 		? traceState.data.filter((trace) => {
-			const needle = filterText.toLowerCase()
-			const errorOnly = needle.includes(":error")
-			const textNeedle = needle.replace(":error", "").trim()
-			if (errorOnly && trace.errorCount === 0) return false
-			if (textNeedle && !trace.rootOperationName.toLowerCase().includes(textNeedle)) return false
+			if (parsedFilter.errorOnly && trace.errorCount === 0) return false
+			if (parsedFilter.operationNeedle && !trace.rootOperationName.toLowerCase().includes(parsedFilter.operationNeedle)) return false
 			return true
 		})
 		: traceState.data

package/src/ui/filterParser.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "bun:test"
+import { parseFilterText } from "./filterParser.ts"
+
+describe("parseFilterText", () => {
+	it("returns empty state for empty input", () => {
+		expect(parseFilterText("")).toEqual({ aiText: null, errorOnly: false, operationNeedle: "" })
+	})
+
+	it("extracts a bare operation-name needle", () => {
+		expect(parseFilterText("streamText")).toEqual({
+			aiText: null, errorOnly: false, operationNeedle: "streamtext",
+		})
+	})
+
+	it("recognizes :error modifier", () => {
+		expect(parseFilterText(":error")).toEqual({
+			aiText: null, errorOnly: true, operationNeedle: "",
+		})
+	})
+
+	it("composes :error with an operation needle", () => {
+		expect(parseFilterText("llm :error")).toEqual({
+			aiText: null, errorOnly: true, operationNeedle: "llm",
+		})
+	})
+
+	it("extracts :ai query up to end of string", () => {
+		expect(parseFilterText(":ai rate limit")).toEqual({
+			aiText: "rate limit", errorOnly: false, operationNeedle: "",
+		})
+	})
+
+	it("extracts :ai query stopping at the next modifier", () => {
+		expect(parseFilterText(":ai tool_use :error")).toEqual({
+			aiText: "tool_use", errorOnly: true, operationNeedle: "",
+		})
+	})
+
+	it("composes operation needle + :ai + :error", () => {
+		expect(parseFilterText("stream :ai rate :error")).toEqual({
+			aiText: "rate", errorOnly: true, operationNeedle: "stream",
+		})
+	})
+
+	it("ignores :ai with empty query", () => {
+		expect(parseFilterText(":ai ")).toEqual({
+			aiText: null, errorOnly: false, operationNeedle: "",
+		})
+	})
+
+	it("is case-insensitive for modifiers", () => {
+		expect(parseFilterText(":AI foo :ERROR")).toEqual({
+			aiText: "foo", errorOnly: true, operationNeedle: "",
+		})
+	})
+})

package/src/ui/filterParser.ts

@@ -0,0 +1,45 @@
+/**
+ * Parses the `/` filter input in the trace list into its component
+ * modifiers. Supports composable tokens:
+ *
+ * - `:error`           — restricts to traces with at least one failed span
+ * - `:ai <query...>`   — FTS-backed search against LLM prompt/response
+ *                        content (AI_FTS_KEYS) across every span in the
+ *                        trace. The query runs up to the next `:modifier`
+ *                        or end of input, so `"/ :ai rate limit :error"`
+ *                        passes `"rate limit"` as the aiText and also
+ *                        sets errorOnly.
+ * - bare text          — case-insensitive substring match against the
+ *                        trace's root operation name (client-side)
+ *
+ * Keep this a pure function: it's unit-tested separately and the React
+ * hook just calls it per render.
+ */
+export interface ParsedFilter {
+	readonly aiText: string | null
+	readonly errorOnly: boolean
+	readonly operationNeedle: string
+}
+
+export const parseFilterText = (raw: string): ParsedFilter => {
+	const text = raw ?? ""
+
+	// `:ai <query>` — greedy up to the next `:` modifier or end. The
+	// leading `(^|\s)` guard prevents matching a stray `:ai` glued to
+	// non-space characters (shouldn't happen in practice but cheap).
+	const aiMatch = text.match(/(?:^|\s):ai\s+([^:]*?)(?=\s:|$)/i)
+	const aiText = aiMatch?.[1]?.trim() || null
+
+	const errorOnly = /(?:^|\s):error(?=\s|$)/i.test(text)
+
+	// Whatever remains after removing the recognized modifiers becomes the
+	// operation-name needle. Lowercased here so the call site can do a
+	// plain includes() without re-lowercasing.
+	const operationNeedle = text
+		.replace(/(?:^|\s):ai\s+[^:]*?(?=\s:|$)/i, " ")
+		.replace(/(?:^|\s):error(?=\s|$)/i, " ")
+		.trim()
+		.toLowerCase()
+
+	return { aiText, errorOnly, operationNeedle }
+}

package/src/ui/primitives.tsx

@@ -80,13 +80,25 @@ export const SeparatorColumn = ({ height, junctionChars }: { height: number; jun
 	)
 }
 
-export const FilterBar = ({ text, width }: { text: string; width: number }) => (
-	<TextLine fg={colors.accent}>
-		<span fg={colors.muted}>{"/"}</span>
-		<span fg={colors.text}>{fitCell(text, width - 2)}</span>
-		<span fg={colors.accent}>{"\u2588"}</span>
-	</TextLine>
-)
+export const FilterBar = ({ text, width }: { text: string; width: number }) => {
+	// Layout: "/<text>█  op name · :error · :ai <query>"
+	// Cursor block sits immediately after the typed text (no padding —
+	// fitCell would pad the empty string to fill the available width and
+	// push the cursor to the far right, which looked like a bug). The
+	// hint only renders while the input is empty so real typing never
+	// collides with it.
+	const hint = text.length === 0 ? "  op name · :error · :ai <query>" : ""
+	const textMaxWidth = Math.max(1, width - 2 - hint.length)
+	const displayText = text.length > textMaxWidth ? text.slice(text.length - textMaxWidth) : text
+	return (
+		<TextLine fg={colors.accent}>
+			<span fg={colors.muted}>{"/"}</span>
+			<span fg={colors.text}>{displayText}</span>
+			<span fg={colors.accent}>{"\u2588"}</span>
+			{hint ? <span fg={colors.muted}>{hint}</span> : null}
+		</TextLine>
+	)
+}
 
 const FooterKey = ({ label }: { label: string }) => <span fg={colors.count} attributes={TextAttributes.BOLD}>{label}</span>
 
@@ -118,7 +130,7 @@ export const HelpModal = ({ width, height, autoRefresh, themeLabel, onClose }: {
 					{row("t", `cycle theme (${themeLabel})`)}
 					{row("tab", "toggle service logs")}
 					{row("[ ]", "switch service")}
-					{row("/", "filter by root operation")}
+					{row("/", "filter by root operation (\u2003:error, :ai <query>)")}
 					{row("f", "filter traces by span attribute")}
 					{row("s", "cycle sort mode")}
 					{row("a", `auto refresh ${autoRefresh ? "on" : "off"}`)}

package/src/ui/state.ts

@@ -106,6 +106,13 @@ export const autoRefreshAtom = Atom.make(false).pipe(Atom.keepAlive)
 export const filterModeAtom = Atom.make(false).pipe(Atom.keepAlive)
 export const filterTextAtom = Atom.make("").pipe(Atom.keepAlive)
 
+// Waterfall-scoped filter: the `/` key while drilled into a trace
+// (viewLevel >= 1) opens this filter instead of the trace-list one.
+// Purely client-side — dims spans whose operation name and attribute
+// values don't contain the needle.
+export const waterfallFilterModeAtom = Atom.make(false).pipe(Atom.keepAlive)
+export const waterfallFilterTextAtom = Atom.make("").pipe(Atom.keepAlive)
+
 // Attribute filter (F key): pick a span-attribute key + exact value to restrict the trace list.
 export type AttrPickerMode = "off" | "keys" | "values"
 export const attrPickerModeAtom = Atom.make<AttrPickerMode>("off").pipe(Atom.keepAlive)
@@ -158,8 +165,31 @@ export const collapsedSpanIdsAtom = Atom.make(new Set<string>() as ReadonlySet<s
 
 export const loadTraceServices = () => queryRuntime.runPromise(Effect.flatMap(TraceQueryService.asEffect(), (service) => service.listServices))
 export const loadRecentTraceSummaries = (serviceName: string) => queryRuntime.runPromise(Effect.flatMap(TraceQueryService.asEffect(), (service) => service.listTraceSummaries(serviceName)))
-export const loadFilteredTraceSummaries = (serviceName: string, attributeFilters: Readonly<Record<string, string>>) =>
-	queryRuntime.runPromise(Effect.flatMap(TraceQueryService.asEffect(), (service) => service.searchTraceSummaries({ serviceName, attributeFilters, limit: config.otel.traceFetchLimit })))
+/**
+ * Server-side trace summary search. Accepts any combination of:
+ *
+ * - `attributeFilters` — exact-match span attributes (from the `f` picker)
+ * - `aiText`           — FTS5-backed search across LLM prompt/response
+ *                        content (AI_FTS_KEYS), from the `:ai <query>`
+ *                        modifier in the `/` filter
+ *
+ * Both filters compose: when both are set, a trace must match both. When
+ * neither is set, callers should prefer `loadRecentTraceSummaries` so
+ * the server can skip the search path entirely.
+ */
+export const loadFilteredTraceSummaries = (
+	serviceName: string,
+	options: {
+		readonly attributeFilters?: Readonly<Record<string, string>>
+		readonly aiText?: string | null
+	},
+) =>
+	queryRuntime.runPromise(Effect.flatMap(TraceQueryService.asEffect(), (service) => service.searchTraceSummaries({
+		serviceName,
+		attributeFilters: options.attributeFilters,
+		aiText: options.aiText ?? null,
+		limit: config.otel.traceFetchLimit,
+	})))
 export const loadTraceAttributeKeys = (serviceName: string) =>
 	queryRuntime.runPromise(Effect.flatMap(TraceQueryService.asEffect(), (service) => service.listFacets({ type: "traces", field: "attribute_keys", serviceName, limit: 200 })))
 export const loadTraceAttributeValues = (serviceName: string, key: string) =>

package/src/ui/useKeyboardNav.ts

@@ -27,11 +27,14 @@ 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"
 
 /**
@@ -53,6 +56,10 @@ const extractPrintable = (key: {
 	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
@@ -105,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)
@@ -151,12 +160,12 @@ 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 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 = () => {
@@ -446,6 +455,43 @@ export const useKeyboardNav = (params: KeyboardNavParams) => {
 			}
 			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
+		}
 		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)
@@ -524,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
@@ -588,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
+}