@kitlangton/motel 0.1.3 → 0.2.1

package/src/ui/SpanDetail.tsx

@@ -4,6 +4,50 @@ import { formatTimestamp, logSeverityColor, relevantLogAttributes, truncateText,
 import { BlankRow, PlainLine, TextLine } from "./primitives.tsx"
 import { colors, SEPARATOR } from "./theme.ts"
 
+/**
+ * Inline-vs-stacked threshold for tag rendering.
+ *
+ * A tag renders **inline** (`key  value` on one row) when:
+ *   - the key is ≤ INLINE_KEY_MAX chars AND
+ *   - the value fits in the remaining width on one line AND
+ *   - the value contains no newlines.
+ *
+ * Otherwise it **stacks** — the key gets its own row (full, no truncation)
+ * and the value is wrapped below with a leading indent. Long LLM payloads
+ * (`ai.prompt.messages`, `gen_ai.completion`, etc.) always hit the stacked
+ * path, which is what makes them readable at a glance.
+ */
+const INLINE_KEY_MAX = 24
+/** Max wrapped rows we'll spend on a single stacked value's content. */
+const VALUE_WRAP_MAX_LINES = 4
+/** Leading indent for stacked values — subtle but visible. */
+const STACK_INDENT = "  "
+
+interface TagRender {
+	readonly key: string
+	readonly value: string
+	readonly inline: boolean
+	readonly valueLines: readonly string[]
+	readonly rowCount: number
+}
+
+const planTag = (key: string, value: string, contentWidth: number, inlineKeyPad: number): TagRender => {
+	const hasNewline = value.includes("\n")
+	const inlineValueWidth = Math.max(1, contentWidth - inlineKeyPad - 2)
+	const canInline =
+		!hasNewline &&
+		key.length <= INLINE_KEY_MAX &&
+		value.length <= inlineValueWidth
+	if (canInline) {
+		return { key, value, inline: true, valueLines: [value], rowCount: 1 }
+	}
+	const wrapWidth = Math.max(16, contentWidth - STACK_INDENT.length)
+	const valueLines = wrapTextLines(value, wrapWidth, VALUE_WRAP_MAX_LINES)
+	// 1 row for the key + N rows for wrapped value (at least 1).
+	const rowCount = 1 + Math.max(1, valueLines.length)
+	return { key, value, inline: false, valueLines, rowCount }
+}
+
 export const SpanDetailView = ({
 	span,
 	logs,
@@ -16,15 +60,41 @@ export const SpanDetailView = ({
 	bodyLines: number
 }) => {
 	const tagEntries = Object.entries(span.tags)
-	const maxKeyLen = Math.min(28, tagEntries.reduce((max, [key]) => Math.max(max, key.length), 0))
+	// Column width for inline keys. We cap at INLINE_KEY_MAX so a single
+	// very-long key doesn't widen the column for everyone. Short keys still
+	// align against each other.
+	const inlineKeyPad = Math.min(
+		INLINE_KEY_MAX,
+		tagEntries.reduce((max, [key]) => (key.length <= INLINE_KEY_MAX ? Math.max(max, key.length) : max), 0),
+	)
+
 	const maxLogLines = logs.length > 0 ? Math.min(4, Math.max(1, Math.floor(bodyLines * 0.3))) : 0
 	const visibleLogs = logs.slice(0, maxLogLines)
 	const visibleWarnings = span.warnings.slice(0, visibleLogs.length > 0 ? 1 : 2)
 	const visibleEvents = span.events.slice(0, 2)
 	const reservedForWarnings = visibleWarnings.length > 0 ? visibleWarnings.length + 2 : 0
 	const reservedForEvents = visibleEvents.length > 0 ? visibleEvents.length + 2 : 0
-	const reservedForLogs = visibleLogs.length > 0 ? visibleLogs.reduce((total, log) => total + 3 + Math.min(3, wrapTextLines(log.body, Math.max(16, contentWidth - 2), 3).length), 1) : 0
-	const maxTagLines = Math.max(0, bodyLines - 4 - reservedForWarnings - reservedForEvents - reservedForLogs)
+	const reservedForLogs = visibleLogs.length > 0
+		? visibleLogs.reduce((total, log) => total + 3 + Math.min(3, wrapTextLines(log.body, Math.max(16, contentWidth - 2), 3).length), 1)
+		: 0
+	// Budget for the TAGS section: total body minus header (TAGS row + blank)
+	// minus every other section's reservation. Each stacked tag spends more
+	// rows than an inline one so we plan the full visible set up-front rather
+	// than slicing by entry count.
+	const tagBudget = Math.max(0, bodyLines - 2 - reservedForWarnings - reservedForEvents - reservedForLogs)
+
+	const planned: TagRender[] = []
+	let rowsUsed = 0
+	let skipped = 0
+	for (const [key, value] of tagEntries) {
+		const plan = planTag(key, value, contentWidth, inlineKeyPad)
+		if (rowsUsed + plan.rowCount > tagBudget) {
+			skipped = tagEntries.length - planned.length
+			break
+		}
+		planned.push(plan)
+		rowsUsed += plan.rowCount
+	}
 
 	// NOTE: op name, service, duration, lifecycle, status, and spanId are all
 	// rendered by the enclosing SpanDetailPane header (rows 0..2). Starting
@@ -37,21 +107,32 @@ export const SpanDetailView = ({
 					<TextLine>
 						<span fg={colors.accent} attributes={TextAttributes.BOLD}>TAGS</span>
 					</TextLine>
-					{tagEntries.slice(0, maxTagLines).map(([key, value]) => {
-						const keyStr = key.length > maxKeyLen ? `${key.slice(0, maxKeyLen - 1)}\u2026` : key.padEnd(maxKeyLen)
-						const valMaxWidth = Math.max(8, contentWidth - maxKeyLen - 2)
-						const valStr = value.length > valMaxWidth ? `${value.slice(0, valMaxWidth - 1)}\u2026` : value
-
-						return (
-							<TextLine key={key}>
-								<span fg={colors.count}>{keyStr}</span>
-								<span fg={colors.muted}>  </span>
-								<span fg={colors.text}>{valStr}</span>
+					{planned.map((tag) => tag.inline ? (
+						<TextLine key={tag.key}>
+							<span fg={colors.count}>{tag.key.padEnd(inlineKeyPad)}</span>
+							<span fg={colors.muted}>  </span>
+							<span fg={colors.text}>{tag.value}</span>
+						</TextLine>
+					) : (
+						<box key={tag.key} flexDirection="column">
+							<TextLine>
+								<span fg={colors.count}>{tag.key}</span>
 							</TextLine>
-						)
-					})}
-					{tagEntries.length > maxTagLines ? (
-						<PlainLine text={`  \u2026 ${tagEntries.length - maxTagLines} more`} fg={colors.muted} />
+							{tag.valueLines.length === 0 ? (
+								<TextLine>
+									<span fg={colors.muted}>{STACK_INDENT}</span>
+									<span fg={colors.muted}>(empty)</span>
+								</TextLine>
+							) : tag.valueLines.map((line, index) => (
+								<TextLine key={index}>
+									<span fg={colors.muted}>{STACK_INDENT}</span>
+									<span fg={colors.text}>{line}</span>
+								</TextLine>
+							))}
+						</box>
+					))}
+					{skipped > 0 ? (
+						<PlainLine text={`${STACK_INDENT}\u2026 ${skipped} more`} fg={colors.muted} />
 					) : null}
 				</>
 			) : (

package/src/ui/TraceDetailsPane.tsx

@@ -1,8 +1,10 @@
 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 { getVisibleSpans, WaterfallTimeline } from "./Waterfall.tsx"
+import { AlignedHeaderLine, Divider, FilterBar, PlainLine, TextLine } from "./primitives.tsx"
+import { WaterfallTimeline } from "./Waterfall.tsx"
+import { computeMatchingSpanIds } from "./waterfallFilter.ts"
+import { getVisibleSpans } from "./waterfallModel.ts"
 import type { LoadStatus, LogState } from "./state.ts"
 import { colors, SEPARATOR } from "./theme.ts"
 
@@ -30,6 +32,8 @@ export const TraceDetailsPane = ({
 	collapsedSpanIds,
 	focused = false,
 	onSelectSpan,
+	waterfallFilterMode,
+	waterfallFilterText,
 }: {
 	trace: TraceItem | null
 	traceSummary: TraceSummaryItem | null
@@ -43,6 +47,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 +68,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 +127,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 +150,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

@@ -1,81 +1,17 @@
 import { memo, useLayoutEffect, useRef, useState } from "react"
-import type { LogItem, TraceItem, TraceSpanItem } from "../domain.ts"
+import { isAiSpan, type LogItem, type TraceItem, type TraceSpanItem } from "../domain.ts"
 import { formatDuration, lifecycleLabel, splitDuration, truncateText } from "./format.ts"
 import { BlankRow, TextLine } from "./primitives.tsx"
 import { colors, waterfallColors } from "./theme.ts"
-
-/** Filter spans to only those visible given a set of collapsed span IDs. */
-export const getVisibleSpans = (spans: readonly TraceSpanItem[], collapsedIds: ReadonlySet<string>): readonly TraceSpanItem[] => {
-	if (collapsedIds.size === 0) return spans
-	const result: TraceSpanItem[] = []
-	let skipDepth = -1
-	for (const span of spans) {
-		if (skipDepth >= 0 && span.depth > skipDepth) continue
-		skipDepth = -1
-		result.push(span)
-		if (collapsedIds.has(span.spanId)) {
-			skipDepth = span.depth
-		}
-	}
-	return result
-}
-
-/** Find the index of a span's parent in the visible list. */
-export const findParentIndex = (spans: readonly TraceSpanItem[], index: number): number | null => {
-	const span = spans[index]
-	if (!span || span.depth === 0) return null
-	for (let i = index - 1; i >= 0; i--) {
-		if (spans[i]!.depth < span.depth) return i
-	}
-	return null
-}
-
-/** Find the index of a span's first child in the visible list. */
-export const findFirstChildIndex = (spans: readonly TraceSpanItem[], index: number): number | null => {
-	const span = spans[index]
-	const next = spans[index + 1]
-	if (span && next && next.depth > span.depth) return index + 1
-	return null
-}
-
-const INTERESTING_TAGS = [
-	"http.method", "http.url", "http.status_code", "http.route",
-	"db.system", "db.statement", "db.name",
-	"messaging.system", "messaging.destination",
-	"error", "error.message",
-	"net.peer.name", "net.peer.port",
-] as const
-
-const buildTreePrefix = (spans: readonly TraceSpanItem[], index: number): string => {
-	const span = spans[index]
-	if (span.depth === 0) return ""
-
-	const parts: string[] = []
-
-	const isLastChild = (spanIndex: number, depth: number): boolean => {
-		for (let i = spanIndex + 1; i < spans.length; i++) {
-			if (spans[i].depth < depth) return true
-			if (spans[i].depth === depth) return false
-		}
-		return true
-	}
-
-	parts.push(isLastChild(index, span.depth) ? "\u2514\u2500" : "\u251c\u2500")
-
-	for (let d = span.depth - 1; d >= 1; d--) {
-		let parentIndex = index
-		for (let i = index - 1; i >= 0; i--) {
-			if (spans[i].depth === d) {
-				parentIndex = i
-				break
-			}
-			if (spans[i].depth < d) break
-		}
-		parts.push(isLastChild(parentIndex, d) ? "  " : "\u2502 ")
-	}
-
-	return parts.reverse().join("")
-}
+export { getVisibleSpans } from "./waterfallModel.ts"
+import {
+	buildTreePrefix,
+	findFirstChildIndex,
+	getWaterfallLayout,
+	getWaterfallSuffixMetrics,
+	type WaterfallSuffixMetrics,
+	spanPreviewEntries,
+} from "./waterfallModel.ts"
 
 const PARTIAL_BLOCKS = ["", "\u258f", "\u258e", "\u258d", "\u258c", "\u258b", "\u258a", "\u2589", "\u2588"] as const
 const ULTRA_SHORT_MARKERS = ["\u258f", "\u258e", "\u258d", "\u258c"] as const
@@ -180,66 +116,6 @@ const durationColor = (durationMs: number) => {
 	return colors.muted
 }
 
-export const getWaterfallLayout = (contentWidth: number, suffixWidth: number) => {
-	const labelMaxWidth = Math.min(Math.floor(contentWidth * 0.4), 32)
-	// Two single-space gaps: one between label and bar, one between bar and suffix.
-	const barWidth = Math.max(6, contentWidth - labelMaxWidth - suffixWidth - 2)
-	return { labelMaxWidth, barWidth } as const
-}
-
-export type WaterfallSuffixMetrics = {
-	readonly maxDurationWidth: number
-	readonly suffixWidth: number
-}
-
-/**
- * Compute a shared suffix (duration) width from the visible viewport.
- * Reserving the width once keeps every row's duration right-aligned on the
- * same column regardless of per-row content. Log correlation lives in the
- * span detail pane, not the row suffix.
- */
-export const getWaterfallSuffixMetrics = (
-	spans: readonly { readonly durationMs: number; readonly spanId: string }[],
-): WaterfallSuffixMetrics => {
-	let maxDurationWidth = 0
-	for (const span of spans) {
-		const d = formatDuration(Math.max(0, span.durationMs)).length
-		if (d > maxDurationWidth) maxDurationWidth = d
-	}
-	return { maxDurationWidth, suffixWidth: maxDurationWidth }
-}
-
-// Retained for tests: per-row view of the shared layout.
-export const getWaterfallColumns = (
-	contentWidth: number,
-	metrics: WaterfallSuffixMetrics,
-) => {
-	const { labelMaxWidth, barWidth } = getWaterfallLayout(contentWidth, metrics.suffixWidth)
-	return { labelMaxWidth, barWidth, suffixWidth: metrics.suffixWidth } as const
-}
-
-export const spanPreviewEntries = (span: TraceSpanItem, logs: readonly LogItem[], maxEntries: number): Array<{ key: string; value: string; isWarning?: boolean }> => {
-	const entries = Object.entries(span.tags)
-	const interesting = entries.filter(([key]) =>
-		INTERESTING_TAGS.includes(key as (typeof INTERESTING_TAGS)[number]) || key.startsWith("error"),
-	)
-	const rest = entries.filter(([key]) =>
-		!INTERESTING_TAGS.includes(key as (typeof INTERESTING_TAGS)[number]) && !key.startsWith("error") && !key.startsWith("otel.") && key !== "span.kind",
-	)
-	const tagResults: Array<{ key: string; value: string; isWarning?: boolean }> = []
-	if (logs.length > 0) {
-		tagResults.push({ key: "logs", value: `${logs.length} correlated` })
-		tagResults.push({ key: "log", value: logs[0]!.body.replace(/\s+/g, " ") })
-	}
-
-	tagResults.push(...[...interesting, ...rest]
-		.slice(0, maxEntries - span.warnings.length)
-		.map(([key, value]) => ({ key, value })))
-	for (const warning of span.warnings) {
-		tagResults.push({ key: "warning", value: warning, isWarning: true })
-	}
-	return tagResults.slice(0, maxEntries)
-}
 
 const WaterfallRow = memo(({
 	span,
@@ -251,6 +127,7 @@ const WaterfallRow = memo(({
 	collapsed,
 	hasChildSpans,
 	suffixMetrics,
+	dimmed,
 	onSelect,
 }: {
 	span: TraceSpanItem
@@ -262,17 +139,37 @@ const WaterfallRow = memo(({
 	collapsed: boolean
 	hasChildSpans: boolean
 	suffixMetrics: WaterfallSuffixMetrics
+	dimmed: boolean
 	onSelect: () => void
 }) => {
 	const prefix = buildTreePrefix(spans, index)
-	// Match the trace list indicator: `!` on error, chevron on collapsible parents, `·` on leaves.
-	const indicator = span.status === "error" ? "!" : hasChildSpans ? (collapsed ? "\u25b8" : "\u25be") : "\u00b7"
+	const isAi = isAiSpan(span.tags)
+	// Indicator column: `!` on error, chevron on collapsible parents,
+	// `✦` on AI leaves (LLM payloads detected — enter drills into a
+	// specialized chat view), `·` on other leaves. AI parents keep the
+	// chevron glyph so tree structure stays readable; the accent color
+	// (applied below) carries the "AI content lives here" signal.
+	const indicator = span.status === "error" ? "!"
+		: hasChildSpans ? (collapsed ? "\u25b8" : "\u25be")
+		: isAi ? "\u2726"
+		: "\u00b7"
 	const opName = span.isRunning ? `${span.operationName} [${lifecycleLabel(span)}]` : span.operationName
 
 	const { labelMaxWidth, barWidth } = getWaterfallLayout(contentWidth, suffixMetrics.suffixWidth)
 
-	const opMaxWidth = Math.max(4, labelMaxWidth - prefix.length - 2)
-	const opTruncated = opName.length > opMaxWidth ? `${opName.slice(0, opMaxWidth - 1)}\u2026` : opName
+	// Op name budget = labelMaxWidth minus (prefix + indicator + 1 space).
+	// Never force a minimum: at very deep nesting or narrow widths the
+	// prefix + indicator may already fill the label column, in which
+	// case we render the op as an empty string (or a lone ellipsis) so
+	// the line stays within contentWidth. Previous code forced op to 4
+	// chars which could push total row width past the pane and make
+	// OpenTUI smear "..." across the right edge.
+	const opMaxWidth = Math.max(0, labelMaxWidth - prefix.length - 2)
+	const opTruncated = opMaxWidth === 0
+		? ""
+		: opName.length > opMaxWidth
+			? `${opName.slice(0, Math.max(0, opMaxWidth - 1))}\u2026`
+			: opName
 	const labelLen = prefix.length + 2 + opTruncated.length
 	const labelPad = " ".repeat(Math.max(0, labelMaxWidth - labelLen))
 
@@ -282,12 +179,28 @@ 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
+		// AI accent outranks parent/leaf color so both AI parents and AI
+		// leaves scan as "there's an LLM payload here" from across the
+		// waterfall. Error still wins because a failed AI span is first
+		// and foremost a failure.
+		: isAi ? colors.accent
+		: 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 +286,7 @@ export const WaterfallTimeline = ({
 	bodyLines,
 	selectedSpanIndex,
 	collapsedSpanIds,
+	matchingSpanIds,
 	onSelectSpan,
 }: {
 	trace: TraceItem
@@ -383,6 +297,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 +311,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 +349,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 +368,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 +381,7 @@ export const WaterfallTimeline = ({
 						collapsed={collapsedSpanIds.has(span.spanId)}
 						hasChildSpans={fullIndex >= 0 && findFirstChildIndex(trace.spans, fullIndex) !== null}
 						suffixMetrics={suffixMetrics}
+						dimmed={dimmed}
 						onSelect={() => onSelectSpan(actualIndex)}
 					/>
 				)