@kitlangton/motel 0.1.3 → 0.2.1

package/src/ui/app/useTraceScreenData.ts

@@ -1,18 +1,27 @@
 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 type { LogItem, TraceItem, TraceSummaryItem } from "../../domain.ts"
 import {
 	activeAttrKeyAtom,
 	activeAttrValueAtom,
+	aiCallDetailStateAtom,
 	autoRefreshAtom,
+	chatDetailChunkIdAtom,
+	chatDetailScrollOffsetAtom,
 	collapsedSpanIdsAtom,
 	detailViewAtom,
+	ensureAiCallDetail,
+	ensureTraceAttributeKeys,
 	filterModeAtom,
 	filterTextAtom,
+	getCachedAiCallDetail,
+	initialAiCallDetailState,
 	initialLogState,
 	initialServiceLogState,
 	initialTraceDetailState,
+	invalidateAiCallDetailCache,
+	invalidateFacetCaches,
 	loadFilteredTraceSummaries,
 	loadRecentTraceSummaries,
 	loadServiceLogs,
@@ -22,6 +31,8 @@ import {
 	logStateAtom,
 	persistSelectedService,
 	refreshNonceAtom,
+	selectedAttrIndexAtom,
+	selectedChatChunkIdAtom,
 	selectedServiceLogIndexAtom,
 	selectedSpanIndexAtom,
 	selectedTraceIndexAtom,
@@ -29,11 +40,71 @@ import {
 	serviceLogStateAtom,
 	showHelpAtom,
 	traceDetailStateAtom,
+	type TraceSortMode,
 	traceSortAtom,
 	traceStateAtom,
 } from "../state.ts"
+import { isAiSpan } from "../../domain.ts"
+import { buildChunks, type Chunk } from "../aiChatModel.ts"
+import { parseFilterText } from "../filterParser.ts"
 import { getVisibleSpans } from "../Waterfall.tsx"
 
+const clampSelectionIndex = (index: number, length: number) => {
+	if (length === 0) return 0
+	return Math.max(0, Math.min(index, length - 1))
+}
+
+const resolveEffectiveService = (
+	services: readonly string[],
+	selectedTraceService: string | null,
+) => services.includes(selectedTraceService ?? "")
+	? selectedTraceService
+	: selectedTraceService ?? services[0] ?? config.otel.serviceName
+
+const loadTraceSummariesForService = (
+	serviceName: string | null,
+	filters: {
+		readonly activeAttrKey: string | null
+		readonly activeAttrValue: string | null
+		readonly debouncedAiText: string | null
+	},
+) => {
+	if (!serviceName) return Promise.resolve([] as readonly TraceSummaryItem[])
+	const hasAttrFilter = Boolean(filters.activeAttrKey && filters.activeAttrValue)
+	const hasAiFilter = Boolean(filters.debouncedAiText)
+	if (!hasAttrFilter && !hasAiFilter) return loadRecentTraceSummaries(serviceName)
+	return loadFilteredTraceSummaries(serviceName, {
+		attributeFilters: hasAttrFilter ? { [filters.activeAttrKey as string]: filters.activeAttrValue as string } : undefined,
+		aiText: hasAiFilter ? filters.debouncedAiText : null,
+	})
+}
+
+const applyClientTraceFilters = (
+	traces: readonly TraceSummaryItem[],
+	filterText: string,
+	parsedFilter: ReturnType<typeof parseFilterText>,
+) => filterText
+	? traces.filter((trace) => {
+		if (parsedFilter.errorOnly && trace.errorCount === 0) return false
+		if (parsedFilter.operationNeedle && !trace.rootOperationName.toLowerCase().includes(parsedFilter.operationNeedle)) return false
+		return true
+	})
+	: traces
+
+const sortTraceSummaries = (traces: readonly TraceSummaryItem[], traceSort: TraceSortMode) => {
+	if (traceSort === "recent") return traces
+	return [...traces].sort((a, b) => {
+		if (traceSort === "slowest") return b.durationMs - a.durationMs
+		if (traceSort === "errors") return b.errorCount - a.errorCount || b.startedAt.getTime() - a.startedAt.getTime()
+		return 0
+	})
+}
+
+const getSelectedVisibleSpan = (
+	spans: readonly TraceItem["spans"][number][],
+	selectedSpanIndex: number | null,
+) => selectedSpanIndex === null ? null : spans[selectedSpanIndex] ?? null
+
 export const useTraceScreenData = () => {
 	const [traceState, setTraceState] = useAtom(traceStateAtom)
 	const [traceDetailState, setTraceDetailState] = useAtom(traceDetailStateAtom)
@@ -44,6 +115,11 @@ export const useTraceScreenData = () => {
 	const [selectedTraceService, setSelectedTraceService] = useAtom(selectedTraceServiceAtom)
 	const [refreshNonce, setRefreshNonce] = useAtom(refreshNonceAtom)
 	const [selectedSpanIndex, setSelectedSpanIndex] = useAtom(selectedSpanIndexAtom)
+	const [, setSelectedAttrIndex] = useAtom(selectedAttrIndexAtom)
+	const [, setChatDetailChunkId] = useAtom(chatDetailChunkIdAtom)
+	const [, setChatDetailScrollOffset] = useAtom(chatDetailScrollOffsetAtom)
+	const [selectedChatChunkId, setSelectedChatChunkId] = useAtom(selectedChatChunkIdAtom)
+	const [aiCallDetailState, setAiCallDetailState] = useAtom(aiCallDetailStateAtom)
 	const [detailView, setDetailView] = useAtom(detailViewAtom)
 	const [showHelp, setShowHelp] = useAtom(showHelpAtom)
 	const [collapsedSpanIds, setCollapsedSpanIds] = useAtom(collapsedSpanIdsAtom)
@@ -54,6 +130,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 }>())
@@ -79,8 +166,18 @@ export const useTraceScreenData = () => {
 		serviceLogCacheRef.current.clear()
 		traceDetailInflightRef.current.clear()
 		traceLogInflightRef.current.clear()
+		invalidateFacetCaches()
+		invalidateAiCallDetailCache()
 	}, [refreshNonce])
 
+	// Pre-warm the attribute picker facet keys for the currently-selected
+	// service so pressing `f` feels instant. Fire-and-forget; errors are
+	// surfaced when the user actually opens the picker.
+	useEffect(() => {
+		if (!selectedTraceService) return
+		void ensureTraceAttributeKeys(selectedTraceService).catch(() => {})
+	}, [selectedTraceService, refreshNonce])
+
 	useEffect(() => {
 		let cancelled = false
 
@@ -91,19 +188,17 @@ export const useTraceScreenData = () => {
 				const services = await loadTraceServices()
 				if (cancelled) return
 
-				const effectiveService = services.includes(selectedTraceService ?? "")
-					? selectedTraceService
-					: selectedTraceService ?? services[0] ?? config.otel.serviceName
+				const effectiveService = resolveEffectiveService(services, selectedTraceService)
 
 				if (effectiveService !== selectedTraceService) {
 					setSelectedTraceService(effectiveService)
 				}
 
-				const traces = effectiveService
-					? (activeAttrKey && activeAttrValue
-						? await loadFilteredTraceSummaries(effectiveService, { [activeAttrKey]: activeAttrValue })
-						: await loadRecentTraceSummaries(effectiveService))
-					: []
+				const traces = await loadTraceSummariesForService(effectiveService, {
+					activeAttrKey,
+					activeAttrValue,
+					debouncedAiText,
+				})
 				if (cancelled) return
 
 				const prevTraceId = selectedTraceRef.current
@@ -126,18 +221,22 @@ export const useTraceScreenData = () => {
 		return () => {
 			cancelled = true
 		}
-	}, [refreshNonce, selectedTraceService, activeAttrKey, activeAttrValue, setSelectedTraceIndex, setSelectedTraceService, setTraceState])
+	}, [refreshNonce, selectedTraceService, activeAttrKey, activeAttrValue, debouncedAiText, setSelectedTraceIndex, setSelectedTraceService, setTraceState])
 
 	useEffect(() => {
 		setSelectedTraceIndex((current) => {
-			if (traceState.data.length === 0) return 0
-			return Math.max(0, Math.min(current, traceState.data.length - 1))
+			return clampSelectionIndex(current, traceState.data.length)
 		})
 	}, [traceState.data.length, setSelectedTraceIndex])
 
 	const selectedTraceSummary = traceState.data[selectedTraceIndex] ?? null
 	const selectedTraceId = selectedTraceSummary?.traceId ?? null
 	const selectedTrace = traceDetailState.traceId === selectedTraceId ? traceDetailState.data : null
+	const selectedVisibleSpans = useMemo(
+		() => selectedTrace ? getVisibleSpans(selectedTrace.spans, collapsedSpanIds) : [],
+		[selectedTrace, collapsedSpanIds],
+	)
+	const selectedVisibleSpan = getSelectedVisibleSpan(selectedVisibleSpans, selectedSpanIndex)
 	selectedTraceRef.current = selectedTraceId
 
 	const warmTraceDetail = useCallback((traceId: string, hydrateSelection: boolean) => {
@@ -274,6 +373,72 @@ export const useTraceScreenData = () => {
 		setSelectedSpanIndex(null)
 	}, [selectedTraceId, setCollapsedSpanIds, setSelectedSpanIndex])
 
+	// Reset the attribute cursor whenever the span selection moves. Without
+	// this, drilling from span A (with 34 tags) to span B (with 3 tags)
+	// would leave the cursor pointing past the end of B's tag list until
+	// the user hit `j`/`k` again.
+	useEffect(() => {
+		setSelectedAttrIndex(0)
+		setChatDetailChunkId(null)
+		setChatDetailScrollOffset(0)
+		// New span → drop chunk selection and any open detail modal.
+		// The effect below will re-select the first chunk once the
+		// detail loads.
+		setSelectedChatChunkId(null)
+	}, [selectedSpanIndex, selectedTraceId, setSelectedAttrIndex, setChatDetailChunkId, setChatDetailScrollOffset, setSelectedChatChunkId])
+
+	// Load the parsed AI call detail for the currently-selected span when
+	// it's an AI span and the user is drilled into L2. Cached module-level
+	// so re-entering the chat view for a span we already loaded is free.
+	const selectedSpanId = selectedVisibleSpan?.spanId ?? null
+	const shouldLoadAiDetail = detailView === "span-detail" && selectedVisibleSpan !== null && isAiSpan(selectedVisibleSpan.tags)
+
+	useEffect(() => {
+		if (!shouldLoadAiDetail || !selectedSpanId) {
+			setAiCallDetailState(initialAiCallDetailState)
+			return
+		}
+		const cached = getCachedAiCallDetail(selectedSpanId)
+		if (cached !== undefined) {
+			setAiCallDetailState({ status: "ready", spanId: selectedSpanId, data: cached, error: null })
+			return
+		}
+		setAiCallDetailState({ status: "loading", spanId: selectedSpanId, data: null, error: null })
+		let cancelled = false
+		ensureAiCallDetail(selectedSpanId)
+			.then((data) => {
+				if (cancelled) return
+				setAiCallDetailState({ status: "ready", spanId: selectedSpanId, data, error: null })
+			})
+			.catch((err) => {
+				if (cancelled) return
+				setAiCallDetailState({
+					status: "error",
+					spanId: selectedSpanId,
+					data: null,
+					error: err instanceof Error ? err.message : String(err),
+				})
+			})
+		return () => { cancelled = true }
+	}, [shouldLoadAiDetail, selectedSpanId, setAiCallDetailState])
+
+	// Chunk model — rebuilt whenever the detail payload changes.
+	// Width-independent, so this lives here instead of in the view.
+	const aiChatChunks = useMemo<readonly Chunk[]>(() => {
+		if (!shouldLoadAiDetail || !aiCallDetailState.data) return []
+		return buildChunks(aiCallDetailState.data)
+	}, [shouldLoadAiDetail, aiCallDetailState.data])
+
+	// Once chunks are available, pin selection to the first chunk unless
+	// the user has already chosen one. Also handles the "chunk list
+	// changed and the previous selection disappeared" case.
+	useEffect(() => {
+		if (aiChatChunks.length === 0) return
+		const stillValid = selectedChatChunkId !== null
+			&& aiChatChunks.some((c) => c.id === selectedChatChunkId)
+		if (!stillValid) setSelectedChatChunkId(aiChatChunks[0]!.id)
+	}, [aiChatChunks, selectedChatChunkId, setSelectedChatChunkId])
+
 	useEffect(() => {
 		if (selectedSpanIndex === null) return
 		if (!selectedTrace || selectedTrace.spans.length === 0) {
@@ -281,11 +446,11 @@ export const useTraceScreenData = () => {
 			setDetailView("waterfall")
 			return
 		}
-		const visibleCount = getVisibleSpans(selectedTrace.spans, collapsedSpanIds).length
+		const visibleCount = selectedVisibleSpans.length
 		if (selectedSpanIndex >= visibleCount) {
 			setSelectedSpanIndex(visibleCount - 1)
 		}
-	}, [selectedTrace, selectedSpanIndex, collapsedSpanIds, setDetailView, setSelectedSpanIndex])
+	}, [selectedTrace, selectedSpanIndex, selectedVisibleSpans.length, setDetailView, setSelectedSpanIndex])
 
 	useEffect(() => {
 		const traceId = selectedTraceId
@@ -354,29 +519,18 @@ export const useTraceScreenData = () => {
 
 	useEffect(() => {
 		setSelectedServiceLogIndex((current) => {
-			if (serviceLogState.data.length === 0) return 0
-			return Math.max(0, Math.min(current, serviceLogState.data.length - 1))
+			return clampSelectionIndex(current, serviceLogState.data.length)
 		})
 	}, [serviceLogState.data.length, setSelectedServiceLogIndex])
 
-	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
-			return true
-		})
-		: traceState.data
-
-	const filteredTraces = traceSort === "recent"
-		? preFilterTraces
-		: [...preFilterTraces].sort((a, b) => {
-			if (traceSort === "slowest") return b.durationMs - a.durationMs
-			if (traceSort === "errors") return b.errorCount - a.errorCount || b.startedAt.getTime() - a.startedAt.getTime()
-			return 0
-		})
+	// 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 filteredTraces = useMemo(() => {
+		const preFiltered = applyClientTraceFilters(traceState.data, filterText, parsedFilter)
+		return sortTraceSummaries(preFiltered, traceSort)
+	}, [filterText, parsedFilter, traceSort, traceState.data])
 
 	useEffect(() => {
 		if (!selectedTraceId || filteredTraces.length === 0) return
@@ -418,5 +572,7 @@ export const useTraceScreenData = () => {
 		selectedTrace,
 		selectedTraceId,
 		filteredTraces,
+		aiCallDetailState,
+		aiChatChunks,
 	} as const
 }

package/src/ui/atoms.ts

@@ -0,0 +1,131 @@
+import * as Atom from "effect/unstable/reactivity/Atom"
+import { config } from "../config.ts"
+import type { LogItem, TraceItem, TraceSummaryItem } from "../domain.ts"
+import type { ThemeName } from "./theme.ts"
+import { readLastService, readLastTheme } from "./persistence.ts"
+
+export type LoadStatus = "loading" | "ready" | "error"
+export type DetailView = "waterfall" | "span-detail" | "service-logs"
+
+export interface TraceState {
+	readonly status: LoadStatus
+	readonly services: readonly string[]
+	readonly data: readonly TraceSummaryItem[]
+	readonly error: string | null
+	readonly fetchedAt: Date | null
+}
+
+export interface TraceDetailState {
+	readonly status: LoadStatus
+	readonly traceId: string | null
+	readonly data: TraceItem | null
+	readonly error: string | null
+	readonly fetchedAt: Date | null
+}
+
+export interface LogState {
+	readonly status: LoadStatus
+	readonly traceId: string | null
+	readonly data: readonly LogItem[]
+	readonly error: string | null
+	readonly fetchedAt: Date | null
+}
+
+export interface ServiceLogState {
+	readonly status: LoadStatus
+	readonly serviceName: string | null
+	readonly data: readonly LogItem[]
+	readonly error: string | null
+	readonly fetchedAt: Date | null
+}
+
+export const initialTraceState: TraceState = {
+	status: "loading",
+	services: [],
+	data: [],
+	error: null,
+	fetchedAt: null,
+}
+
+export const initialLogState: LogState = {
+	status: "ready",
+	traceId: null,
+	data: [],
+	error: null,
+	fetchedAt: null,
+}
+
+export const initialTraceDetailState: TraceDetailState = {
+	status: "ready",
+	traceId: null,
+	data: null,
+	error: null,
+	fetchedAt: null,
+}
+
+export const initialServiceLogState: ServiceLogState = {
+	status: "ready",
+	serviceName: null,
+	data: [],
+	error: null,
+	fetchedAt: null,
+}
+
+export const traceStateAtom = Atom.make(initialTraceState).pipe(Atom.keepAlive)
+export const traceDetailStateAtom = Atom.make(initialTraceDetailState).pipe(Atom.keepAlive)
+export const logStateAtom = Atom.make(initialLogState).pipe(Atom.keepAlive)
+export const serviceLogStateAtom = Atom.make(initialServiceLogState).pipe(Atom.keepAlive)
+export const selectedServiceLogIndexAtom = Atom.make(0).pipe(Atom.keepAlive)
+export const selectedTraceIndexAtom = Atom.make(0).pipe(Atom.keepAlive)
+export const selectedTraceServiceAtom = Atom.make<string | null>(readLastService() ?? config.otel.serviceName).pipe(Atom.keepAlive)
+export const refreshNonceAtom = Atom.make(0).pipe(Atom.keepAlive)
+export const noticeAtom = Atom.make<string | null>(null).pipe(Atom.keepAlive)
+export const selectedSpanIndexAtom = Atom.make<number | null>(null).pipe(Atom.keepAlive)
+// Cursor inside the full-screen span content view (detailView === "span-detail").
+// Tracks which span tag is currently selected for copy / drill-in. Reset to 0
+// on each new span so the cursor doesn't point past a shorter tag list.
+export const selectedAttrIndexAtom = Atom.make(0).pipe(Atom.keepAlive)
+export const detailViewAtom = Atom.make<DetailView>("waterfall").pipe(Atom.keepAlive)
+export const showHelpAtom = Atom.make(false).pipe(Atom.keepAlive)
+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)
+export const attrPickerInputAtom = Atom.make("").pipe(Atom.keepAlive)
+export const attrPickerIndexAtom = Atom.make(0).pipe(Atom.keepAlive)
+
+export interface AttrFacetState {
+	readonly status: LoadStatus
+	readonly key: string | null
+	readonly data: readonly { readonly value: string; readonly count: number }[]
+	readonly error: string | null
+}
+
+export const initialAttrFacetState: AttrFacetState = {
+	status: "ready",
+	key: null,
+	data: [],
+	error: null,
+}
+
+export const attrFacetStateAtom = Atom.make(initialAttrFacetState).pipe(Atom.keepAlive)
+
+// Applied filter (drives trace list query)
+export const activeAttrKeyAtom = Atom.make<string | null>(null).pipe(Atom.keepAlive)
+export const activeAttrValueAtom = Atom.make<string | null>(null).pipe(Atom.keepAlive)
+
+export const selectedThemeAtom = Atom.make<ThemeName>(readLastTheme()).pipe(Atom.keepAlive)
+
+export type TraceSortMode = "recent" | "slowest" | "errors"
+export const traceSortAtom = Atom.make<TraceSortMode>("recent").pipe(Atom.keepAlive)
+export const collapsedSpanIdsAtom = Atom.make(new Set<string>() as ReadonlySet<string>).pipe(Atom.keepAlive)

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