@kitlangton/motel 0.1.3 → 0.2.0

package/AGENTS.md

@@ -146,7 +146,12 @@
 - `[` / `]`: switch services
 - `s`: cycle sort mode (recent → slowest → errors)
 - `t`: cycle theme (motel-default → tokyo-night → catppuccin)
-- `/`: enter filter mode (type to match on root operation name; `:error` restricts to failing traces)
+- `/`: enter filter mode.
+  - **In the trace list (L0)** the input matches against the root operation name. Composable modifiers:
+    - `:error` — restrict to traces with at least one failed span (client-side)
+    - `:ai <query>` — FTS5-backed search against LLM prompt/response/tool content (`AI_FTS_KEYS`) across every span in the trace. Tokens are prefix-matched and implicitly AND'd. Debounced 250ms.
+    - Modifiers compose: `/ :ai rate limit :error`
+  - **In the waterfall (L1/L2)** the input runs a client-side substring match against each span's operation name and tag values. Non-matching spans are dimmed; the filter bar shows the live match count. `enter` commits (dim persists while you navigate); `esc` clears.
 - `f`: open attribute filter picker (browse span-attribute keys → values for the current service; `backspace` walks back to keys; `esc` in the trace list clears the active filter)
 - `a`: pause or resume auto-refresh
 - `r`: refresh now

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitlangton/motel",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
   "type": "module",
   "license": "MIT",

package/src/App.tsx

@@ -15,6 +15,8 @@ import {
 	noticeAtom,
 	persistSelectedTheme,
 	selectedThemeAtom,
+	waterfallFilterModeAtom,
+	waterfallFilterTextAtom,
 } from "./ui/state.ts"
 import { applyTheme, colors, SEPARATOR, themeLabel } from "./ui/theme.ts"
 import { getVisibleSpans } from "./ui/Waterfall.tsx"
@@ -57,6 +59,8 @@ export const App = () => {
 	const [pickerInput] = useAtom(attrPickerInputAtom)
 	const [pickerIndex] = useAtom(attrPickerIndexAtom)
 	const [attrFacets] = useAtom(attrFacetStateAtom)
+	const [waterfallFilterMode] = useAtom(waterfallFilterModeAtom)
+	const [waterfallFilterText] = useAtom(waterfallFilterTextAtom)
 	useAttrFilterPicker(activeAttrKey)
 
 	const layout = useAppLayout({ width, height, notice, detailView, selectedSpanIndex })
@@ -179,6 +183,8 @@ export const App = () => {
 				detailView={detailView}
 				filterMode={filterMode}
 				filterText={filterText}
+				waterfallFilterMode={waterfallFilterMode}
+				waterfallFilterText={waterfallFilterText}
 				traceListProps={traceListProps}
 				selectedTraceService={selectedTraceService}
 				serviceLogState={serviceLogState}

package/src/domain.ts

@@ -145,14 +145,56 @@ export const AI_ATTR_MAP = {
 	responseTimestamp: "ai.response.timestamp",
 } as const
 
-/** Attribute keys to search across when using the `text` filter */
-export const AI_TEXT_SEARCH_KEYS = [
-	"ai.prompt.messages",
+/**
+ * Attribute keys that carry LLM prompt/response content and should be
+ * indexed in the span-attribute FTS table. These are the keys emitted by
+ * well-known LLM instrumentation conventions:
+ *
+ * - **Vercel AI SDK** (`ai.*`): rich, SDK-specific attributes captured by
+ *   `experimental_telemetry` on `generateText` / `streamText` / `generateObject`.
+ * - **OpenTelemetry GenAI semantic conventions** (`gen_ai.*`): the
+ *   cross-vendor standard. The singular `prompt`/`completion` attrs are
+ *   deprecated in favor of event-based capture but are still emitted by
+ *   most instrumentations, so we keep them.
+ * - **OpenInference** (`input.value` / `output.value`): Arize Phoenix /
+ *   LangChain-style normalized input/output.
+ *
+ * Keys here trigger FTS indexing on insert via a trigger in TelemetryStore.
+ * Adding a key requires a one-time backfill; removing one leaves orphan
+ * FTS entries that get cleaned up on next retention pass.
+ */
+export const AI_FTS_KEYS = [
+	// Vercel AI SDK
 	"ai.prompt",
-	"ai.response.text",
+	"ai.prompt.messages",
 	"ai.prompt.tools",
+	"ai.prompt.toolChoice",
+	"ai.response.text",
+	"ai.response.toolCalls",
+	"ai.response.reasoning",
+	"ai.response.object",
+	"ai.toolCall.args",
+	"ai.toolCall.result",
+	// OpenTelemetry GenAI semantic conventions
+	"gen_ai.prompt",
+	"gen_ai.completion",
+	"gen_ai.input.messages",
+	"gen_ai.output.messages",
+	"gen_ai.system_instructions",
+	"gen_ai.tool.definitions",
+	"gen_ai.tool.message.content",
+	// OpenInference (Phoenix, LangChain, etc.)
+	"input.value",
+	"output.value",
 ] as const
 
+/**
+ * Back-compat alias. The `text` filter on `/api/ai/calls` historically
+ * LIKE-searched these four keys; now FTS indexes the broader AI_FTS_KEYS
+ * set so the filter transparently covers more content.
+ */
+export const AI_TEXT_SEARCH_KEYS = AI_FTS_KEYS
+
 const PREVIEW_LENGTH = 200
 
 export const truncatePreview = (value: string | null | undefined): string | null => {

package/src/httpApi.ts

@@ -121,6 +121,9 @@ export const MotelHttpApi = HttpApi.make("MotelTelemetry")
 						minDurationMs: Schema.optionalKey(Schema.Number).pipe(
 							Schema.annotateKey({ description: "Only return traces slower than this threshold (milliseconds)" }),
 						),
+						aiText: Schema.optionalKey(Schema.String).pipe(
+							Schema.annotateKey({ description: "FTS match against AI prompt/response/tool content across all spans in the trace. Tokens are prefix-matched and implicitly AND'd." }),
+						),
 						lookback: LookbackParam,
 						limit: LimitParam,
 						cursor: CursorParam,
@@ -128,7 +131,7 @@ export const MotelHttpApi = HttpApi.make("MotelTelemetry")
 					success: TraceSummaryList,
 				})
 					.annotate(OpenApi.Summary, "Search traces with filters")
-					.annotate(OpenApi.Description, "Search compact trace summaries with filters. Use /api/traces/{traceId} for full details. Supports cursor pagination and attr.<key> filters in the query string."),
+					.annotate(OpenApi.Description, "Search compact trace summaries with filters. Use /api/traces/{traceId} for full details. Supports cursor pagination, attr.<key> filters in the query string, and aiText for full-text search across LLM prompt/response content."),
 
 				HttpApiEndpoint.get("traceStats", "/api/traces/stats", {
 					query: {

package/src/localServer.ts

@@ -335,6 +335,7 @@ const TelemetryGroupLive = HttpApiBuilder.group(
 							status: (url.searchParams.get("status") as "ok" | "error" | null) ?? null,
 							minDurationMs: url.searchParams.get("minDurationMs") ? Number.parseFloat(url.searchParams.get("minDurationMs") ?? "") : null,
 							attributeFilters,
+							aiText: url.searchParams.get("aiText"),
 							limit: limit + 1,
 							lookbackMinutes,
 							cursorStartedAtMs: cursor?.kind === "trace" ? cursor.startedAt : undefined,

package/src/services/TelemetryStore.ts

@@ -4,7 +4,7 @@ import { dirname } from "node:path"
 import { Clock, Effect, Layer, Schedule, Context } from "effect"
 import { config } from "../config.js"
 import type { AiCallDetail, AiCallSummary, FacetItem, LogItem, SpanItem, StatsItem, TraceItem, TraceSummaryItem, TraceSpanEvent, TraceSpanItem } from "../domain.js"
-import { AI_ATTR_MAP, AI_TEXT_SEARCH_KEYS, truncatePreview } from "../domain.js"
+import { AI_ATTR_MAP, AI_FTS_KEYS, AI_TEXT_SEARCH_KEYS, truncatePreview } from "../domain.js"
 import { attributeMap, nanosToMilliseconds, parseAnyValue, spanKindLabel, spanStatusLabel, stringifyValue, type OtlpLogExportRequest, type OtlpTraceExportRequest } from "../otlp.js"
 
 interface SpanRow {
@@ -57,6 +57,13 @@ interface TraceSearch {
 	readonly status?: "ok" | "error" | null
 	readonly minDurationMs?: number | null
 	readonly attributeFilters?: Readonly<Record<string, string>>
+	/**
+	 * Full-text match against the AI prompt/response/tool attribute values
+	 * on any span in the trace (see AI_FTS_KEYS). When set, traces are
+	 * filtered to those containing at least one span whose indexed LLM
+	 * content matches. Powered by span_attr_fts (FTS5).
+	 */
+	readonly aiText?: string | null
 	readonly lookbackMinutes?: number
 	readonly limit?: number
 	readonly cursorStartedAtMs?: number
@@ -571,6 +578,66 @@ export const TelemetryStoreLive = Layer.effect(
 			// FTS is optional; queries will fall back to LIKE if unavailable.
 		}
 
+		// External-content FTS5 over the subset of span_attributes.value rows
+		// whose key is in AI_FTS_KEYS (LLM prompts, responses, tool calls,
+		// etc.). External content means the inverted index is the only
+		// FTS storage — the value text itself continues to live once in
+		// span_attributes, not duplicated into the FTS table. On a 2 GB DB
+		// with 270 MB of prompt JSON this typically adds ~50-120 MB of
+		// index, turning a 500-800ms LIKE scan into a <50ms MATCH.
+		//
+		// Keys are inlined into the trigger DDL rather than looked up in a
+		// side table so the `WHEN` guard stays constant-cost (a subquery
+		// would run on every span_attributes insert — ~60/span).
+		let hasAttrFts = hasFts
+		if (hasFts) {
+			try {
+				const keyList = AI_FTS_KEYS.map((k) => `'${k.replace(/'/g, "''")}'`).join(", ")
+				db.exec(`
+					CREATE VIRTUAL TABLE IF NOT EXISTS span_attr_fts USING fts5(
+						value,
+						content='span_attributes',
+						content_rowid='rowid',
+						tokenize='unicode61 remove_diacritics 2'
+					);
+
+					-- Mirror inserts into FTS when the key carries LLM content.
+					-- NOTE: triggers MUST use fully-qualified name (new.rowid,
+					-- new.value) and emit rowid so external-content FTS can
+					-- fetch the value back via span_attributes.rowid.
+					CREATE TRIGGER IF NOT EXISTS span_attr_fts_ai AFTER INSERT ON span_attributes
+					WHEN new.key IN (${keyList})
+					BEGIN
+						INSERT INTO span_attr_fts(rowid, value) VALUES (new.rowid, new.value);
+					END;
+
+					-- Delete with the same guard so retention & re-ingest stay
+					-- in sync. External-content 'delete' command needs the
+					-- original value to remove from the inverted index.
+					CREATE TRIGGER IF NOT EXISTS span_attr_fts_ad AFTER DELETE ON span_attributes
+					WHEN old.key IN (${keyList})
+					BEGIN
+						INSERT INTO span_attr_fts(span_attr_fts, rowid, value)
+						VALUES ('delete', old.rowid, old.value);
+					END;
+
+					-- Handle in-place updates (rare; re-ingest usually goes
+					-- DELETE then INSERT but belt-and-braces).
+					CREATE TRIGGER IF NOT EXISTS span_attr_fts_au AFTER UPDATE ON span_attributes
+					WHEN old.key IN (${keyList}) OR new.key IN (${keyList})
+					BEGIN
+						INSERT INTO span_attr_fts(span_attr_fts, rowid, value)
+						VALUES ('delete', old.rowid, old.value);
+						INSERT INTO span_attr_fts(rowid, value)
+						SELECT new.rowid, new.value
+						WHERE new.key IN (${keyList});
+					END;
+				`)
+			} catch {
+				hasAttrFts = false
+			}
+		}
+
 		try {
 			db.exec(`ALTER TABLE trace_summaries ADD COLUMN active_span_count INTEGER NOT NULL DEFAULT 0`)
 		} catch {
@@ -741,6 +808,37 @@ export const TelemetryStoreLive = Layer.effect(
 		})
 		yield* Effect.forkScoped(Effect.repeat(refreshPlannerStats, Schedule.spaced("15 minutes")))
 
+		// One-time backfill for existing DBs: if span_attr_fts is empty but
+		// span_attributes has rows with AI_FTS_KEYS, populate the index.
+		// Runs forked so server startup isn't blocked; queries hitting the
+		// FTS will just return empty until the fill lands. On a 2 GB DB with
+		// ~400 matching rows this takes ~3-8 seconds.
+		if (hasAttrFts) {
+			const backfillAttrFts = Effect.sync(() => {
+				try {
+					const ftsCount = (db.query(`SELECT COUNT(*) AS c FROM span_attr_fts`).get() as { c: number }).c
+					if (ftsCount > 0) return
+					const keyList = AI_FTS_KEYS.map((k) => `'${k.replace(/'/g, "''")}'`).join(", ")
+					const attrCount = (db.query(
+						`SELECT COUNT(*) AS c FROM span_attributes WHERE key IN (${keyList})`,
+					).get() as { c: number }).c
+					if (attrCount === 0) return
+					// Single INSERT..SELECT is atomic and fast; FTS5 batches
+					// its internal segment writes. No transaction wrapper
+					// needed — it runs as one statement.
+					db.exec(`
+						INSERT INTO span_attr_fts(rowid, value)
+						SELECT rowid, value FROM span_attributes WHERE key IN (${keyList})
+					`)
+				} catch {
+					// Backfill failure is never fatal — new ingests still
+					// populate FTS via the trigger, and queries fall back to
+					// LIKE when FTS lookups return empty.
+				}
+			})
+			yield* Effect.forkScoped(backfillAttrFts)
+		}
+
 		const ingestTraces = Effect.fn("motel/TelemetryStore.ingestTraces")(function* (payload: OtlpTraceExportRequest) {
 			return yield* Effect.sync(() => {
 				let insertedSpans = 0
@@ -965,6 +1063,25 @@ export const TelemetryStoreLive = Layer.effect(
 					params.push(...exactAttrMatch.params)
 				}
 
+				// `:ai <query>` — FTS match against LLM content keys. Joins
+				// span_attr_fts back to span_attributes to collect trace_ids
+				// whose spans carry matching prompt/response content. Falls
+				// through to no-op when the query tokenizes empty (e.g. only
+				// stopwords or operator-chars) so users don't get a silently
+				// empty list.
+				if (input.aiText) {
+					const aiFtsQuery = toFtsMatchQuery(input.aiText)
+					if (hasAttrFts && aiFtsQuery) {
+						clauses.push(`trace_id IN (
+							SELECT DISTINCT sa.trace_id
+							FROM span_attr_fts fts
+							JOIN span_attributes sa ON sa.rowid = fts.rowid
+							WHERE fts.value MATCH ?
+						)`)
+						params.push(aiFtsQuery)
+					}
+				}
+
 				const rows = db.query(`
 					SELECT trace_id, service_name, root_operation_name, started_at_ms, ended_at_ms, active_span_count, duration_ms, span_count, error_count
 					FROM trace_summaries
@@ -1624,11 +1741,27 @@ export const TelemetryStoreLive = Layer.effect(
 				params.push(key, value)
 			}
 
-			// Text search across prompt/response/tool attribute values
+			// Text search across prompt/response/tool attribute values via
+			// FTS5. Prefers the external-content span_attr_fts index when
+			// available, falls back to case-insensitive LIKE so old DBs
+			// without FTS still work. FTS turns ~500ms full scans of 3 MB
+			// prompt JSON into <50ms MATCH lookups.
 			if ("text" in input && input.text) {
-				const textKeys = AI_TEXT_SEARCH_KEYS.map(() => "?").join(", ")
-				clauses.push(`EXISTS (SELECT 1 FROM span_attributes WHERE span_attributes.trace_id = s.trace_id AND span_attributes.span_id = s.span_id AND key IN (${textKeys}) AND value LIKE ? COLLATE NOCASE)`)
-				params.push(...AI_TEXT_SEARCH_KEYS, `%${input.text}%`)
+				const ftsQuery = toFtsMatchQuery(input.text)
+				if (hasAttrFts && ftsQuery) {
+					clauses.push(`EXISTS (
+						SELECT 1 FROM span_attr_fts fts
+						JOIN span_attributes sa ON sa.rowid = fts.rowid
+						WHERE sa.trace_id = s.trace_id
+						AND sa.span_id = s.span_id
+						AND fts.value MATCH ?
+					)`)
+					params.push(ftsQuery)
+				} else {
+					const textKeys = AI_TEXT_SEARCH_KEYS.map(() => "?").join(", ")
+					clauses.push(`EXISTS (SELECT 1 FROM span_attributes WHERE span_attributes.trace_id = s.trace_id AND span_attributes.span_id = s.span_id AND key IN (${textKeys}) AND value LIKE ? COLLATE NOCASE)`)
+					params.push(...AI_TEXT_SEARCH_KEYS, `%${input.text}%`)
+				}
 			}
 
 			return { clauses, params }

package/src/services/TraceQueryService.ts

@@ -8,7 +8,7 @@ export class TraceQueryService extends Context.Service<
 		readonly listServices: Effect.Effect<readonly string[], Error>
 		readonly listRecentTraces: (serviceName: string, options?: { readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly TraceItem[], Error>
 		readonly listTraceSummaries: (serviceName: string, options?: { readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly TraceSummaryItem[], Error>
-		readonly searchTraceSummaries: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly TraceSummaryItem[], Error>
+		readonly searchTraceSummaries: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>>; readonly aiText?: string | null }) => Effect.Effect<readonly TraceSummaryItem[], Error>
 		readonly listFacets: (input: { readonly type: "traces" | "logs"; readonly field: string; readonly serviceName?: string | null; readonly key?: string | null; readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly { readonly value: string; readonly count: number }[], Error>
 		readonly searchTraces: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly TraceItem[], Error>
 		readonly traceStats: (input: { readonly groupBy: string; readonly agg: "count" | "avg_duration" | "p95_duration" | "error_rate"; readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly { readonly group: string; readonly value: number; readonly count: number }[], Error>

package/src/telemetry.test.ts

@@ -651,6 +651,39 @@ describe("motel telemetry store", () => {
 		expect(result[0]?.spanId).toBe("ai-stream-1")
 	})
 
+	it("matches AI calls via words in the response text", async () => {
+		// Verifies FTS indexes ai.response.text, not just ai.prompt*. The
+		// seeded ai-stream-2 has response "Error: rate limited".
+		const result = await storeRuntime.runPromise(
+			Effect.flatMap(TelemetryStore.asEffect(), (store) =>
+				store.searchAiCalls({ text: "rate limited" }),
+			).pipe(Effect.provideService(References.MinimumLogLevel, "None")),
+		)
+		expect(result.map((r) => r.spanId)).toContain("ai-stream-2")
+	})
+
+	it("matches AI calls case-insensitively and with partial words", async () => {
+		// unicode61 tokenizer is case-insensitive by default; prefix `*`
+		// handles partial terms like `"PROG"` matching `"programming"`.
+		const result = await storeRuntime.runPromise(
+			Effect.flatMap(TelemetryStore.asEffect(), (store) =>
+				store.searchAiCalls({ text: "PROG" }),
+			).pipe(Effect.provideService(References.MinimumLogLevel, "None")),
+		)
+		expect(result.map((r) => r.spanId)).toContain("ai-stream-1")
+	})
+
+	it("ignores FTS special characters without syntax errors", async () => {
+		// FTS5 treats `"`, `*`, `-`, `:` as operators; toFtsQuery must
+		// strip them so raw user input never crashes the query.
+		const result = await storeRuntime.runPromise(
+			Effect.flatMap(TelemetryStore.asEffect(), (store) =>
+				store.searchAiCalls({ text: `"joke" - about:programming*` }),
+			).pipe(Effect.provideService(References.MinimumLogLevel, "None")),
+		)
+		expect(result.map((r) => r.spanId)).toContain("ai-stream-1")
+	})
+
 	it("filters AI calls by operation type", async () => {
 		const result = await storeRuntime.runPromise(
 			Effect.flatMap(TelemetryStore.asEffect(), (store) =>

package/src/ui/TraceDetailsPane.tsx

@@ -1,8 +1,9 @@
 import { useMemo } from "react"
 import type { TraceItem, TraceSummaryItem } from "../domain.ts"
 import { formatDuration, formatShortDate, formatTimestamp } from "./format.ts"
-import { AlignedHeaderLine, Divider, PlainLine, TextLine } from "./primitives.tsx"
+import { AlignedHeaderLine, Divider, FilterBar, PlainLine, TextLine } from "./primitives.tsx"
 import { getVisibleSpans, WaterfallTimeline } from "./Waterfall.tsx"
+import { computeMatchingSpanIds } from "./waterfallFilter.ts"
 import type { LoadStatus, LogState } from "./state.ts"
 import { colors, SEPARATOR } from "./theme.ts"
 
@@ -30,6 +31,8 @@ export const TraceDetailsPane = ({
 	collapsedSpanIds,
 	focused = false,
 	onSelectSpan,
+	waterfallFilterMode,
+	waterfallFilterText,
 }: {
 	trace: TraceItem | null
 	traceSummary: TraceSummaryItem | null
@@ -43,6 +46,8 @@ export const TraceDetailsPane = ({
 	collapsedSpanIds: ReadonlySet<string>
 	focused?: boolean
 	onSelectSpan: (index: number) => void
+	waterfallFilterMode: boolean
+	waterfallFilterText: string
 }) => {
 	const filteredSpans = useMemo(
 		() => trace ? getVisibleSpans(trace.spans, collapsedSpanIds) : [],
@@ -62,6 +67,15 @@ export const TraceDetailsPane = ({
 		() => selectedSpan ? traceLogsState.data.filter((log) => log.spanId === selectedSpan.spanId) : [],
 		[selectedSpan, traceLogsState.data],
 	)
+	const matchingSpanIds = useMemo(
+		() => trace ? computeMatchingSpanIds(trace.spans, waterfallFilterText) : null,
+		[trace, waterfallFilterText],
+	)
+	const matchCount = matchingSpanIds?.size ?? 0
+	// Reserve 1 row for the filter bar when it's being shown so the
+	// waterfall doesn't spill into the footer.
+	const showFilterBar = waterfallFilterMode || waterfallFilterText.length > 0
+	const waterfallBodyLines = showFilterBar ? Math.max(1, bodyLines - 1) : bodyLines
 
 	const traceMeta = trace ?? traceSummary
 	const hasTraceSelection = traceSummary !== null
@@ -112,6 +126,22 @@ export const TraceDetailsPane = ({
 						</TextLine>
 					</box>
 					<Divider width={paneWidth} />
+					{showFilterBar ? (
+						<box paddingLeft={1} paddingRight={1}>
+							{waterfallFilterMode ? (
+								<FilterBar text={waterfallFilterText} width={contentWidth} />
+							) : (
+								<TextLine>
+									<span fg={colors.muted}>{"/"}</span>
+									<span fg={colors.text}>{waterfallFilterText}</span>
+									<span fg={colors.separator}>{SEPARATOR}</span>
+									<span fg={colors.count}>{matchCount} match{matchCount === 1 ? "" : "es"}</span>
+									<span fg={colors.separator}>{SEPARATOR}</span>
+									<span fg={colors.muted}>esc clear</span>
+								</TextLine>
+							)}
+						</box>
+					) : null}
 					<box flexDirection="column" paddingLeft={1} paddingRight={1}>
 						<WaterfallTimeline
 							trace={trace}
@@ -119,9 +149,10 @@ export const TraceDetailsPane = ({
 							spanLogCounts={spanLogCounts}
 							selectedSpanLogs={selectedSpanLogs}
 							contentWidth={contentWidth}
-							bodyLines={bodyLines}
+							bodyLines={waterfallBodyLines}
 							selectedSpanIndex={selectedSpanIndex}
 							collapsedSpanIds={collapsedSpanIds}
+							matchingSpanIds={matchingSpanIds}
 							onSelectSpan={onSelectSpan}
 						/>
 					</box>

package/src/ui/Waterfall.tsx

@@ -251,6 +251,7 @@ const WaterfallRow = memo(({
 	collapsed,
 	hasChildSpans,
 	suffixMetrics,
+	dimmed,
 	onSelect,
 }: {
 	span: TraceSpanItem
@@ -262,6 +263,7 @@ const WaterfallRow = memo(({
 	collapsed: boolean
 	hasChildSpans: boolean
 	suffixMetrics: WaterfallSuffixMetrics
+	dimmed: boolean
 	onSelect: () => void
 }) => {
 	const prefix = buildTreePrefix(spans, index)
@@ -282,12 +284,23 @@ const WaterfallRow = memo(({
 	const rowBg = selected ? colors.selectedBg : colors.screenBg
 	const { segments } = renderWaterfallBar(span, trace, barWidth, barColor, laneColor, rowBg)
 	const bg = selected ? colors.selectedBg : undefined
-	const treeColor = selected ? colors.separator : colors.treeLine
-	const indicatorColor = isError ? colors.error : hasChildSpans ? (selected ? colors.selectedText : colors.muted) : colors.passing
-	const opColor = selected ? colors.selectedText : span.isRunning ? colors.warning : colors.text
-
-	const durationFg = durationColor(span.durationMs)
-	const unitFg = colors.muted
+	// Dimmed rows (non-matching under an active waterfall filter) collapse
+	// their palette to the muted separator color so matches stand out.
+	// Selection always wins — the selected row keeps its full brightness
+	// so you can still see where the cursor is while scanning.
+	const treeColor = selected ? colors.separator : dimmed ? colors.separator : colors.treeLine
+	const indicatorColor = selected ? colors.selectedText
+		: dimmed ? colors.separator
+		: isError ? colors.error
+		: hasChildSpans ? colors.muted
+		: colors.passing
+	const opColor = selected ? colors.selectedText
+		: dimmed ? colors.separator
+		: span.isRunning ? colors.warning
+		: colors.text
+
+	const durationFg = selected ? colors.selectedText : dimmed ? colors.separator : durationColor(span.durationMs)
+	const unitFg = dimmed && !selected ? colors.separator : colors.muted
 
 	// Split the duration so the unit (s/ms) renders dimmer than the number.
 	const { number: durNumber, unit: durUnit } = splitDuration(Math.max(0, span.durationMs))
@@ -373,6 +386,7 @@ export const WaterfallTimeline = ({
 	bodyLines,
 	selectedSpanIndex,
 	collapsedSpanIds,
+	matchingSpanIds,
 	onSelectSpan,
 }: {
 	trace: TraceItem
@@ -383,6 +397,11 @@ export const WaterfallTimeline = ({
 	bodyLines: number
 	selectedSpanIndex: number | null
 	collapsedSpanIds: ReadonlySet<string>
+	/**
+	 * When set, spans whose spanId is NOT in this set are dimmed. Null
+	 * means no filter active — skip the per-row lookup entirely.
+	 */
+	matchingSpanIds?: ReadonlySet<string> | null
 	onSelectSpan: (index: number) => void
 }) => {
 	const selectedSpan = selectedSpanIndex !== null ? filteredSpans[selectedSpanIndex] ?? null : null
@@ -392,29 +411,37 @@ export const WaterfallTimeline = ({
 		spanIndexById.set(trace.spans[i].spanId, i)
 	}
 
-	// Virtual windowing: only render visible rows, shift window only when
-	// the selection would go out of view (no jerkiness).
+	// Virtual windowing: only render visible rows. We track scroll offset
+	// as state so the mouse wheel can scroll the window INDEPENDENTLY of
+	// the selected span (mirrors TraceList behavior). Selection still
+	// follows: if the user moves selection off-screen via j/k, we nudge
+	// the window to keep it visible — but wheel-scrolling never changes
+	// selection, only clicking a row does.
 	const viewportSize = Math.max(1, bodyLines)
-	const scrollOffsetRef = useRef(0)
+	const maxOffset = Math.max(0, filteredSpans.length - viewportSize)
+	const [scrollOffset, setScrollOffset] = useState(0)
 	const lastTraceIdRef = useRef<string | null>(null)
 
-	// Reset scroll offset when the trace changes
+	// Reset scroll offset when the trace changes.
 	if (trace.traceId !== lastTraceIdRef.current) {
-		scrollOffsetRef.current = 0
+		setScrollOffset(0)
 		lastTraceIdRef.current = trace.traceId
 	}
 
-	// Only shift the window when the selection would be outside it
-	if (selectedSpanIndex !== null) {
-		if (selectedSpanIndex < scrollOffsetRef.current) {
-			scrollOffsetRef.current = selectedSpanIndex
-		} else if (selectedSpanIndex >= scrollOffsetRef.current + viewportSize) {
-			scrollOffsetRef.current = selectedSpanIndex - viewportSize + 1
-		}
-	}
-	scrollOffsetRef.current = Math.max(0, Math.min(scrollOffsetRef.current, Math.max(0, filteredSpans.length - viewportSize)))
-
-	const windowStart = scrollOffsetRef.current
+	// Auto-follow selection: only if the selected span would be hidden
+	// by the current window, shift just enough to bring it back. Runs in
+	// layout effect so the visible window is accurate on the same paint
+	// that the selection changed.
+	useLayoutEffect(() => {
+		if (selectedSpanIndex === null) return
+		setScrollOffset((current) => {
+			if (selectedSpanIndex < current) return selectedSpanIndex
+			if (selectedSpanIndex >= current + viewportSize) return selectedSpanIndex - viewportSize + 1
+			return current
+		})
+	}, [selectedSpanIndex, viewportSize])
+
+	const windowStart = Math.max(0, Math.min(scrollOffset, maxOffset))
 	const windowSpans = filteredSpans.slice(windowStart, windowStart + viewportSize)
 	const blankCount = Math.max(0, viewportSize - windowSpans.length)
 
@@ -422,19 +449,17 @@ export const WaterfallTimeline = ({
 	// row's duration cell lines up on the same right-edge column.
 	const suffixMetrics = getWaterfallSuffixMetrics(windowSpans)
 
-	// Mouse wheel moves the span selection by the scroll delta. The waterfall
-	// uses virtual windowing (not a scrollbox) so native scroll does nothing;
-	// we convert wheel events into selection moves, which the windowing code
-	// already translates into visible-viewport shifts.
+	// Mouse wheel scrolls the window without touching selection — matches
+	// the trace list, so the user can browse ahead of their cursor freely
+	// and click a row to commit. Delta is scaled 1:1 with opentui's wheel
+	// reporting (1 notch ≈ 3 rows on most terminals).
 	const handleWheel = (event: { scroll?: { direction: string; delta: number }; stopPropagation?: () => void }) => {
 		const info = event.scroll
 		if (!info || filteredSpans.length === 0) return
 		const magnitude = Math.max(1, Math.round(info.delta))
 		const signed = info.direction === "up" ? -magnitude : info.direction === "down" ? magnitude : 0
 		if (signed === 0) return
-		const start = selectedSpanIndex ?? 0
-		const next = Math.max(0, Math.min(start + signed, filteredSpans.length - 1))
-		if (next !== selectedSpanIndex) onSelectSpan(next)
+		setScrollOffset((current) => Math.max(0, Math.min(current + signed, maxOffset)))
 		event.stopPropagation?.()
 	}
 
@@ -443,6 +468,7 @@ export const WaterfallTimeline = ({
 			{windowSpans.map((span, index) => {
 				const actualIndex = windowStart + index
 				const fullIndex = spanIndexById.get(span.spanId) ?? -1
+				const dimmed = matchingSpanIds != null && !matchingSpanIds.has(span.spanId)
 				return (
 					<WaterfallRow
 						key={`${trace.traceId}-${span.spanId}`}
@@ -455,6 +481,7 @@ export const WaterfallTimeline = ({
 						collapsed={collapsedSpanIds.has(span.spanId)}
 						hasChildSpans={fullIndex >= 0 && findFirstChildIndex(trace.spans, fullIndex) !== null}
 						suffixMetrics={suffixMetrics}
+						dimmed={dimmed}
 						onSelect={() => onSelectSpan(actualIndex)}
 					/>
 				)