@kitlangton/motel 0.1.2 → 0.2.0

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)}
 					/>
 				)

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) =>