@kitlangton/motel 0.2.0 → 0.2.1

package/src/services/AsyncIngest.ts

@@ -0,0 +1,52 @@
+/**
+ * Main-thread client for the telemetry worker's ingest RPCs.
+ *
+ * The HTTP handlers for POST /v1/traces and POST /v1/logs call into
+ * this service instead of `TelemetryStore.ingestTraces/Logs`. Each
+ * method sends a typed message to the worker, awaits the reply, and
+ * returns the worker's result as an Effect. While the worker is
+ * serialising a big batch into SQLite, the main thread's event loop
+ * is FREE to answer /api/* queries — that's the whole point of the
+ * offload. Without this, /api/health and friends queued behind long
+ * ingests and reported p95 latencies of 3-5 seconds; after, they
+ * stay responsive regardless of ingest load.
+ *
+ * The worker is spawned as a scope'd resource inside the layer. The
+ * protocol pool is sized at 1 because SQLite only supports a single
+ * writer at a time anyway — running N concurrent workers would just
+ * queue them on SQLite's lock. When the outer scope closes (server
+ * shutdown), `BunWorker.layer`'s finalizer sends a close message and
+ * terminates the worker if it doesn't exit gracefully in 5s.
+ */
+
+import * as BunWorker from "@effect/platform-bun/BunWorker"
+import { Context, Layer } from "effect"
+import * as RpcClient from "effect/unstable/rpc/RpcClient"
+import type { RpcClientError } from "effect/unstable/rpc/RpcClientError"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+import { IngestRpcs } from "./ingestRpc.ts"
+
+// RpcClient.make always surfaces RpcClientError in addition to the
+// group's declared errors (transport failures, worker crashes, etc.),
+// so the service shape has to mirror that. Without the explicit error
+// type param, TS treats the declared and observed client types as
+// unrelated structural mismatches.
+export class AsyncIngest extends Context.Service<
+	AsyncIngest,
+	RpcClient.FromGroup<typeof IngestRpcs, RpcClientError>
+>()("@motel/AsyncIngest") {}
+
+// Protocol: RpcClient.layerProtocolWorker manages a worker pool and
+// speaks msgpack over structured-clone messages. `size: 1` matches
+// SQLite's single-writer constraint.
+const WorkerProtocol = RpcClient.layerProtocolWorker({ size: 1 }).pipe(
+	Layer.provide(RpcSerialization.layerMsgPack),
+	Layer.provide(
+		BunWorker.layer(() => new Worker(new URL("./telemetryWorker.ts", import.meta.url))),
+	),
+)
+
+export const AsyncIngestLive = Layer.effect(
+	AsyncIngest,
+	RpcClient.make(IngestRpcs),
+).pipe(Layer.provide(WorkerProtocol))

package/src/services/TelemetryStore.ts

@@ -447,26 +447,74 @@ export class TelemetryStore extends Context.Service<
 >()("motel/TelemetryStore") {}
 
 
-export const TelemetryStoreLive = Layer.effect(
+/**
+ * How this TelemetryStore instance behaves:
+ *
+ * - `readonly` — opens the SQLite connection read-only and skips every
+ *   DDL/DML initialisation. Use this from the TUI (and anywhere else
+ *   that only queries); it avoids the "database is locked" race that
+ *   happens when a TUI process races a daemon's writer for the schema
+ *   pragmas on startup. Writes through the service interface become
+ *   runtime errors — but readers don't call them.
+ *
+ * - `runRetention` — fork the background cleanup loop (age + size cap
+ *   eviction, WAL checkpoint). Only one process should own this at a
+ *   time. Currently the main daemon (localServer) does; the ingest
+ *   worker and the TUI skip it.
+ */
+export interface TelemetryStoreOptions {
+	readonly readonly: boolean
+	readonly runRetention: boolean
+}
+
+export const makeTelemetryStoreLayer = (opts: TelemetryStoreOptions) => Layer.effect(
 	TelemetryStore,
 	Effect.gen(function* () {
 		mkdirSync(dirname(config.otel.databasePath), { recursive: true })
 		const db = yield* Effect.acquireRelease(
-			Effect.sync(() => new Database(config.otel.databasePath, { create: true })),
+			Effect.sync(() => new Database(config.otel.databasePath, {
+				create: !opts.readonly,
+				readonly: opts.readonly,
+			})),
 			(db) => Effect.sync(() => {
-				// `PRAGMA optimize` at close persists any stats SQLite gathered
-				// during the session, so the next process start gets an accurate
-				// query planner on the first query instead of a 3-second cold
-				// run. Cheap: it skips work unless stats have drifted.
-				try { db.exec(`PRAGMA optimize;`) } catch { /* nothing */ }
+				if (!opts.readonly) {
+					// `PRAGMA optimize` at close persists any stats SQLite gathered
+					// during the session, so the next process start gets an accurate
+					// query planner on the first query instead of a 3-second cold
+					// run. Cheap: it skips work unless stats have drifted.
+					try { db.exec(`PRAGMA optimize;`) } catch { /* nothing */ }
+				}
 				db.close()
 			}),
 		)
+		if (opts.readonly) {
+			// Readonly connections skip schema init entirely — the schema
+			// already exists (a writer created it) and any `CREATE TABLE IF
+			// NOT EXISTS` / `PRAGMA journal_mode = WAL` statement would
+			// attempt a write and fight the daemon for the write lock.
+			// `query_only = 1` logically blocks any DML the app might
+			// accidentally send; still bump cache + mmap since those are
+			// safe and keep queries fast.
+			db.exec(`
+				PRAGMA query_only = 1;
+				PRAGMA busy_timeout = 15000;
+				PRAGMA cache_size = -65536;
+				PRAGMA mmap_size = 268435456;
+			`)
+		} else {
 		db.exec(`
 			PRAGMA journal_mode = WAL;
 			PRAGMA synchronous = NORMAL;
 			PRAGMA temp_store = MEMORY;
-			PRAGMA busy_timeout = 5000;
+			-- Longer busy timeout: the ingest worker holds the write lock
+			-- for up to a few seconds during big OTLP batches, and the main
+			-- daemon's retention passes can do the same. 15s gives either
+			-- side enough slack to serialise instead of erroring.
+			PRAGMA busy_timeout = 15000;
+			-- WAL checkpoint automatically when it grows past ~16MB. Without
+			-- this the WAL happily runs into the hundreds of MB and queries
+			-- start paying the cost of walking the WAL on every read.
+			PRAGMA wal_autocheckpoint = 4000;
 			-- Bump cache above the 2MB default. 64MB fits most hot index pages
 			-- (trace_summaries, spans, span_attributes indexes) in RAM even on
 			-- multi-GB databases, cutting cold-read latency meaningfully on
@@ -556,8 +604,26 @@ export const TelemetryStoreLive = Layer.effect(
 			CREATE INDEX IF NOT EXISTS idx_log_attributes_key_value ON log_attributes(key, value, log_id);
 			CREATE INDEX IF NOT EXISTS idx_log_attributes_log_id ON log_attributes(log_id);
 		`)
+		}
 
+		// Tables detected at runtime. For writer connections these flags are
+		// set by the FTS `CREATE VIRTUAL TABLE IF NOT EXISTS` try/catch; for
+		// readonly connections we probe `sqlite_master` and set them based on
+		// what the writer has already provisioned.
 		let hasFts = true
+		let hasAttrFts = true
+		if (opts.readonly) {
+			try {
+				const row = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name='span_operation_fts'`).get()
+				hasFts = row !== null
+			} catch { hasFts = false }
+			try {
+				const row = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name='span_attr_fts'`).get()
+				hasAttrFts = row !== null
+			} catch { hasAttrFts = false }
+		}
+
+		if (!opts.readonly) {
 		try {
 			db.exec(`
 				CREATE VIRTUAL TABLE IF NOT EXISTS span_operation_fts USING fts5(
@@ -589,7 +655,6 @@ export const TelemetryStoreLive = Layer.effect(
 		// 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(", ")
@@ -661,6 +726,7 @@ export const TelemetryStoreLive = Layer.effect(
 			// ANALYZE / optimize failures are never fatal — queries still work,
 			// they just run with default row estimates.
 		}
+		} // end: if (!opts.readonly) writer init
 
 		const insertSpan = db.query(`
 			INSERT INTO spans (
@@ -708,8 +774,14 @@ export const TelemetryStoreLive = Layer.effect(
 			GROUP BY trace_id
 		`)
 
-		db.query(`DELETE FROM trace_summaries`).run()
-		rebuildTraceSummaries.run()
+		// One-time full rebuild of the trace_summaries table at open so
+		// any drift from interrupted ingests gets reconciled. Writer-only
+		// because the DELETE + INSERT would fail on a readonly connection
+		// (and would fight the daemon's writer for the lock anyway).
+		if (!opts.readonly) {
+			db.query(`DELETE FROM trace_summaries`).run()
+			rebuildTraceSummaries.run()
+		}
 
 		const deleteSpanAttributes = db.query(`DELETE FROM span_attributes WHERE trace_id = ? AND span_id = ?`)
 		const insertSpanAttribute = db.query(`INSERT INTO span_attributes (trace_id, span_id, key, value) VALUES (?, ?, ?, ?)`)
@@ -792,28 +864,55 @@ export const TelemetryStoreLive = Layer.effect(
 				} catch {
 					// FTS table may not exist on old DBs.
 				}
+
+				// Truncate the WAL after a big delete pass. Without this the
+				// WAL keeps growing (observed: 640MB) because wal_autocheckpoint
+				// only triggers when WAL pages exceed the threshold during
+				// writes — a retention pass that evicts millions of rows can
+				// blow far past that before the auto-checkpoint fires. Using
+				// PASSIVE so active readers aren't interrupted; if the WAL
+				// can't be fully reclaimed right now, we'll try again next
+				// cycle.
+				try { db.exec(`PRAGMA wal_checkpoint(PASSIVE);`) } catch { /* ignore */ }
+
+				// Incremental vacuum reclaims some of the freed pages back
+				// to the OS so the file size actually shrinks over time
+				// instead of just growing the freelist. Bounded to 2000
+				// pages per pass (≈8MB) to avoid a long-running transaction.
+				try { db.exec(`PRAGMA incremental_vacuum(2000);`) } catch { /* ignore */ }
 			})
 		})
 
-		// Run cleanup every 60 seconds in the background, tied to the layer's scope
-		yield* Effect.forkScoped(Effect.repeat(cleanupExpired(), Schedule.spaced("60 seconds")))
-
-		// Periodically refresh query planner stats. `PRAGMA optimize` is a
-		// no-op when nothing has changed, so this is essentially free on idle
-		// servers and keeps facet/search planner estimates accurate as data
-		// grows. 15 minutes is slower than ingestion rates we care about but
-		// frequent enough that the attribute picker stays snappy.
-		const refreshPlannerStats = Effect.sync(() => {
-			try { db.exec(`PRAGMA optimize;`) } catch { /* ignore */ }
-		})
-		yield* Effect.forkScoped(Effect.repeat(refreshPlannerStats, Schedule.spaced("15 minutes")))
+		// Retention only runs in processes that opt in (currently the main
+		// daemon). The ingest worker and TUI skip it to avoid two writers
+		// competing for the write lock with overlapping DELETE passes.
+		if (opts.runRetention) {
+			// Enable incremental vacuum so retention can reclaim freed
+			// pages over time instead of needing a stop-the-world VACUUM.
+			// Idempotent: repeat calls after the first are no-ops.
+			try { db.exec(`PRAGMA auto_vacuum = INCREMENTAL;`) } catch { /* ignore */ }
+
+			// Run cleanup every 60 seconds in the background, tied to the layer's scope
+			yield* Effect.forkScoped(Effect.repeat(cleanupExpired(), Schedule.spaced("60 seconds")))
+
+			// Periodically refresh query planner stats. `PRAGMA optimize` is a
+			// no-op when nothing has changed, so this is essentially free on idle
+			// servers and keeps facet/search planner estimates accurate as data
+			// grows. 15 minutes is slower than ingestion rates we care about but
+			// frequent enough that the attribute picker stays snappy.
+			const refreshPlannerStats = Effect.sync(() => {
+				try { db.exec(`PRAGMA optimize;`) } catch { /* ignore */ }
+			})
+			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) {
+		// ~400 matching rows this takes ~3-8 seconds. Writer-only because
+		// it does INSERT INTO ... — readonly connections would error.
+		if (hasAttrFts && !opts.readonly) {
 			const backfillAttrFts = Effect.sync(() => {
 				try {
 					const ftsCount = (db.query(`SELECT COUNT(*) AS c FROM span_attr_fts`).get() as { c: number }).c
@@ -1705,7 +1804,11 @@ export const TelemetryStoreLive = Layer.effect(
 
 		/** Builds WHERE clauses for AI call search against the spans table (aliased as s) */
 		const buildAiWhereClauses = (input: AiCallSearch | AiCallStatsSearch, cutoff: number) => {
-			const clauses: string[] = ["s.operation_name LIKE 'ai.%'", "s.start_time_ms >= ?"]
+			const clauses: string[] = [
+				"s.operation_name LIKE 'ai.%'",
+				"s.operation_name NOT LIKE 'ai.%.do%'",
+				"s.start_time_ms >= ?",
+			]
 			const params: Array<string | number> = [cutoff]
 
 			if (input.service) {
@@ -2094,3 +2197,25 @@ export const TelemetryStoreLive = Layer.effect(
 		})
 	}),
 )
+
+/**
+ * Default writer instance: the main daemon uses this. Owns schema
+ * migrations, FTS backfill, and the retention loop.
+ */
+export const TelemetryStoreLive = makeTelemetryStoreLayer({ readonly: false, runRetention: true })
+
+/**
+ * Writer instance that SKIPS retention. The ingest worker uses this
+ * so the daemon and the worker aren't both running DELETE passes at
+ * the same time (they'd just serialise behind the write lock and
+ * duplicate work).
+ */
+export const TelemetryStoreWorkerLive = makeTelemetryStoreLayer({ readonly: false, runRetention: false })
+
+/**
+ * Read-only instance for query-only processes (currently the TUI).
+ * Skips every DDL/DML statement at startup so the connection can be
+ * opened while a writer is mid-transaction without racing for the
+ * write lock. Writes through the service interface will throw.
+ */
+export const TelemetryStoreReadonlyLive = makeTelemetryStoreLayer({ readonly: true, runRetention: false })

package/src/services/TraceQueryService.ts

@@ -1,5 +1,5 @@
 import { Effect, Layer, Context } from "effect"
-import type { SpanItem, TraceItem, TraceSummaryItem } from "../domain.js"
+import type { AiCallDetail, SpanItem, TraceItem, TraceSummaryItem } from "../domain.js"
 import { TelemetryStore } from "./TelemetryStore.js"
 
 export class TraceQueryService extends Context.Service<
@@ -14,6 +14,7 @@ export class TraceQueryService extends Context.Service<
 		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>
 		readonly getTrace: (traceId: string) => Effect.Effect<TraceItem | null, Error>
 		readonly getSpan: (spanId: string) => Effect.Effect<SpanItem | null, Error>
+		readonly getAiCall: (spanId: string) => Effect.Effect<AiCallDetail | null, Error>
 		readonly listTraceSpans: (traceId: string) => Effect.Effect<readonly SpanItem[], Error>
 		readonly searchSpans: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly parentOperation?: string | null; readonly status?: "ok" | "error" | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly SpanItem[], Error>
 	}
@@ -68,6 +69,7 @@ export const TraceQueryServiceLive = Layer.effect(
 			traceStats: store.traceStats,
 			getTrace,
 			getSpan,
+			getAiCall: store.getAiCall,
 			listTraceSpans: store.listTraceSpans,
 			searchSpans: store.searchSpans,
 		})

package/src/services/ingestRpc.ts

@@ -0,0 +1,41 @@
+/**
+ * RPC contract for OTLP ingest. Lives in its own file so both the
+ * main thread (client) and the telemetry worker (server) can import
+ * the schema without pulling in each other's runtime code.
+ *
+ * Only ingestTraces and ingestLogs run through RPC — those are the
+ * methods whose SQLite writes used to block the main event loop for
+ * seconds at a time. Every other TelemetryStore method stays on the
+ * main thread with its own direct DB connection; SQLite's WAL mode
+ * lets the reader (main) and writer (worker) hold independent
+ * connections to the same file concurrently without contention.
+ *
+ * Payloads are typed as Schema.Unknown because OTLP's protobuf-JSON
+ * shape is enormous and nested — the store validates structurally
+ * during the actual insert loop, and serialising a schema through
+ * the worker boundary would add overhead that beats the purpose of
+ * the offload. If a payload is malformed we surface it as an
+ * IngestError rather than a RpcSchemaError, which keeps the failure
+ * mode consistent with the old direct-call behaviour.
+ */
+
+import { Schema } from "effect"
+import * as Rpc from "effect/unstable/rpc/Rpc"
+import * as RpcGroup from "effect/unstable/rpc/RpcGroup"
+
+export class IngestError extends Schema.TaggedErrorClass<IngestError>()("IngestError", {
+	message: Schema.String,
+}) {}
+
+export const IngestRpcs = RpcGroup.make(
+	Rpc.make("ingestTraces", {
+		payload: { payload: Schema.Unknown },
+		success: Schema.Struct({ insertedSpans: Schema.Number }),
+		error: IngestError,
+	}),
+	Rpc.make("ingestLogs", {
+		payload: { payload: Schema.Unknown },
+		success: Schema.Struct({ insertedLogs: Schema.Number }),
+		error: IngestError,
+	}),
+)

package/src/services/telemetryWorker.ts

@@ -0,0 +1,62 @@
+/**
+ * Worker-thread entry point for OTLP ingest.
+ *
+ * Spawned by the main process via `new Worker(new URL("./telemetryWorker.ts", import.meta.url))`.
+ * This file runs inside a Bun Worker, so anything it imports is
+ * evaluated in a FRESH module graph on the worker side. In particular
+ * `TelemetryStoreWorkerLive` opens its own SQLite connection here — the main
+ * thread's store connection is unrelated. SQLite's WAL journal mode
+ * lets both connections coexist against the same `.sqlite` file: the
+ * worker writes, the main thread reads, and neither blocks the other.
+ *
+ * The worker only exposes `ingestTraces` / `ingestLogs` (see
+ * ingestRpc.ts). Query methods stay on the main thread because they're
+ * already fast (1-14ms) and round-tripping them through structured-
+ * clone would add more overhead than it saves. This is a deliberately
+ * narrow interface — the payoff is that main-thread HTTP queries
+ * never queue behind a heavy OTLP batch again.
+ */
+
+import { BunRuntime } from "@effect/platform-bun"
+import * as BunWorkerRunner from "@effect/platform-bun/BunWorkerRunner"
+import { Effect, Layer } from "effect"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+import * as RpcServer from "effect/unstable/rpc/RpcServer"
+import type { OtlpLogExportRequest, OtlpTraceExportRequest } from "../otlp.ts"
+import { IngestError, IngestRpcs } from "./ingestRpc.ts"
+import { TelemetryStore, TelemetryStoreWorkerLive } from "./TelemetryStore.ts"
+
+// Wire the two RPC methods to the existing TelemetryStore service.
+// The store's ingest methods already carry their own Effect.fn spans,
+// so the worker-side traces show up correctly attributed — the RPC
+// framework also auto-spans each incoming request with method +
+// payload-size attributes, giving us visibility into how ingest is
+// splitting its time across the queue / wire / SQL stages.
+const IngestHandlers = IngestRpcs.toLayer(
+	Effect.gen(function*() {
+		const store = yield* TelemetryStore
+		return {
+			ingestTraces: ({ payload }) =>
+				store.ingestTraces(payload as OtlpTraceExportRequest).pipe(
+					Effect.mapError((cause) => new IngestError({ message: String(cause) })),
+				),
+			ingestLogs: ({ payload }) =>
+				store.ingestLogs(payload as OtlpLogExportRequest).pipe(
+					Effect.mapError((cause) => new IngestError({ message: String(cause) })),
+				),
+		}
+	}),
+)
+
+const WorkerLive = RpcServer.layer(IngestRpcs).pipe(
+	Layer.provide(IngestHandlers),
+	Layer.provide(TelemetryStoreWorkerLive),
+	Layer.provide(RpcServer.layerProtocolWorkerRunner),
+	Layer.provide(RpcSerialization.layerMsgPack),
+	Layer.provide(BunWorkerRunner.layer),
+)
+
+// BunRuntime.runMain installs signal handlers so the scope closes
+// cleanly on termination; the BunHttpServer layer pattern from the
+// main server carries over here.
+Layer.launch(WorkerLive).pipe(BunRuntime.runMain)

package/src/storybook/aiChatStory.tsx

@@ -0,0 +1,243 @@
+// Storybook-style preview for AiChatView. Renders the component
+// against a menu of fixtures so we can iterate on the rendering
+// without needing real LLM traffic captured.
+//
+// Run it: `bun run story:chat`
+// Keys:
+//   1..N      switch fixture
+//   j / k     scroll down / up (1 line)
+//   ctrl-d/u  half-page
+//   gg / G    jump to top / bottom
+//   r         force re-render with a fresh date (to sanity-check headers)
+//   q / ^c    quit
+
+import { RegistryProvider } from "@effect/atom-react"
+import { RGBA, TextAttributes, createCliRenderer } from "@opentui/core"
+import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
+import { useEffect, useMemo, useRef, useState } from "react"
+import { buildChunks, type Chunk } from "../ui/aiChatModel.ts"
+import { AiChatView } from "../ui/AiChatView.tsx"
+import { Divider, TextLine } from "../ui/primitives.tsx"
+import type { AiCallDetailState } from "../ui/state.ts"
+import { applyTheme, colors, SEPARATOR } from "../ui/theme.ts"
+import type { ChatFixture } from "./fixtures/index.ts"
+import { errorFixture } from "./fixtures/errorState.ts"
+import { imagePasteFixture } from "./fixtures/imagePaste.ts"
+import { kitchenSinkFixture } from "./fixtures/kitchenSink.ts"
+import { rawPromptFixture } from "./fixtures/rawPrompt.ts"
+import { shortFixture } from "./fixtures/short.ts"
+import { toolHeavyFixture } from "./fixtures/toolHeavy.ts"
+
+// Kitchen-sink first so launching the story lands on something that
+// shows every rendering branch at once. The other fixtures exercise
+// one case at a time for regression testing.
+const FIXTURES: readonly ChatFixture[] = [
+	kitchenSinkFixture,
+	shortFixture,
+	toolHeavyFixture,
+	imagePasteFixture,
+	rawPromptFixture,
+	errorFixture,
+]
+
+const HEADER_ROWS = 2
+const FOOTER_ROWS = 1
+
+const StoryApp = () => {
+	applyTheme("motel-default")
+	const renderer = useRenderer()
+	const { width, height } = useTerminalDimensions()
+	const w = width ?? 120
+	const h = height ?? 32
+	const [fixtureIdx, setFixtureIdx] = useState(0)
+	const [selectedChunkId, setSelectedChunkId] = useState<string | null>(null)
+	const [detailChunkId, setDetailChunkId] = useState<string | null>(null)
+	const [detailScrollOffset, setDetailScrollOffset] = useState(0)
+	const pendingGRef = useRef(false)
+	const quittingRef = useRef(false)
+
+	const fixture = FIXTURES[fixtureIdx] ?? FIXTURES[0]!
+
+	const detailState: AiCallDetailState = useMemo(() => ({
+		status: "ready",
+		spanId: fixture.span.spanId,
+		data: fixture.detail,
+		error: null,
+	}), [fixture])
+
+	const chunks = useMemo<readonly Chunk[]>(() => buildChunks(fixture.detail), [fixture])
+
+	// Reset selection + expansion whenever fixture changes.
+	useEffect(() => {
+		setSelectedChunkId(chunks[0]?.id ?? null)
+		setDetailChunkId(null)
+		setDetailScrollOffset(0)
+	}, [fixtureIdx, chunks])
+
+	const move = (delta: number) => {
+		if (chunks.length === 0) return
+		const idx = selectedChunkId ? chunks.findIndex((c) => c.id === selectedChunkId) : 0
+		const next = chunks[Math.max(0, Math.min(idx + delta, chunks.length - 1))]
+		if (next) setSelectedChunkId(next.id)
+	}
+
+	useKeyboard((key) => {
+		if (key.name === "q" || (key.ctrl && key.name === "c")) {
+			// renderer.destroy() runs the opentui teardown (disables
+			// mouse tracking / kitty keyboard / bracketed paste / alt
+			// screen) before onDestroy exits the process. Bypassing it
+			// with a raw process.exit leaks those escape sequences into
+			// the host shell.
+			if (quittingRef.current) return
+			quittingRef.current = true
+			renderer.destroy()
+			return
+		}
+		if (/^[1-9]$/.test(key.name) && !key.ctrl && !key.meta) {
+			const idx = parseInt(key.name, 10) - 1
+			if (idx < FIXTURES.length) setFixtureIdx(idx)
+			return
+		}
+		if (key.name === "j" || key.name === "down") {
+			if (detailChunkId) setDetailScrollOffset((current) => current + 1)
+			else move(1)
+			return
+		}
+		if (key.name === "k" || key.name === "up") {
+			if (detailChunkId) setDetailScrollOffset((current) => Math.max(0, current - 1))
+			else move(-1)
+			return
+		}
+		if (key.name === "pagedown" || (key.ctrl && key.name === "d")) {
+			if (detailChunkId) setDetailScrollOffset((current) => current + Math.max(1, Math.floor(bodyLines / 2)))
+			else move(Math.max(1, Math.floor(chunks.length / 4)))
+			return
+		}
+		if (key.name === "pageup" || (key.ctrl && key.name === "u")) {
+			if (detailChunkId) setDetailScrollOffset((current) => Math.max(0, current - Math.max(1, Math.floor(bodyLines / 2))))
+			else move(-Math.max(1, Math.floor(chunks.length / 4)))
+			return
+		}
+		if (key.name === "g" && !key.shift) {
+			if (detailChunkId) {
+				if (pendingGRef.current) {
+					setDetailScrollOffset(0)
+					pendingGRef.current = false
+				} else {
+					pendingGRef.current = true
+					setTimeout(() => { pendingGRef.current = false }, 500)
+				}
+				return
+			}
+			if (pendingGRef.current) {
+				if (chunks[0]) setSelectedChunkId(chunks[0].id)
+				pendingGRef.current = false
+			} else {
+				pendingGRef.current = true
+				setTimeout(() => { pendingGRef.current = false }, 500)
+			}
+			return
+		}
+		if (key.name === "g" && key.shift) {
+			if (detailChunkId) setDetailScrollOffset(999999)
+			else {
+				const last = chunks[chunks.length - 1]
+				if (last) setSelectedChunkId(last.id)
+			}
+			return
+		}
+		if (key.name === "escape") {
+			setDetailChunkId(null)
+			setDetailScrollOffset(0)
+			return
+		}
+		if (key.name === "return" || key.name === "enter") {
+			const chunk = chunks.find((c) => c.id === selectedChunkId)
+			if (chunk) {
+				setDetailChunkId(chunk.id)
+				setDetailScrollOffset(0)
+			}
+			return
+		}
+	})
+
+	const bodyLines = Math.max(4, h - HEADER_ROWS - FOOTER_ROWS - 4 /* AI_CHAT_HEADER_ROWS */)
+
+	// Short compact labels — a single TextLine truncates with "..." if
+	// it overflows the padded content width, so we keep labels tight and
+	// use a single separator between items.
+	const fixtureList = FIXTURES.map((f, i) => (
+		<span key={f.id}>
+			<span fg={i === fixtureIdx ? colors.accent : colors.muted} attributes={i === fixtureIdx ? TextAttributes.BOLD : undefined}>
+				{`${i + 1} ${f.label}`}
+			</span>
+			{i < FIXTURES.length - 1 ? <span fg={colors.separator}>{" \u00b7 "}</span> : null}
+		</span>
+	))
+
+	// Header + divider live inside a paddingLeft/Right={1} box, so the
+	// real content width is `w - 2`. Divider must match or we get a
+	// mid-line "..." truncation.
+	const contentWidth = Math.max(8, w - 2)
+
+	return (
+		<box width={w} height={h} flexDirection="column" backgroundColor={RGBA.fromHex(colors.screenBg)}>
+			<box paddingLeft={1} paddingRight={1} height={HEADER_ROWS} flexDirection="column">
+				<TextLine>
+					<span fg={colors.muted} attributes={TextAttributes.BOLD}>AI CHAT</span>
+					<span fg={colors.separator}>{" \u00b7 "}</span>
+					{fixtureList}
+				</TextLine>
+				<Divider width={contentWidth} />
+			</box>
+			<AiChatView
+				span={fixture.span}
+				detailState={detailState}
+				chunks={chunks}
+				selectedChunkId={selectedChunkId}
+				onSelectChunk={(chunkId) => setSelectedChunkId(chunkId)}
+				detailChunkId={detailChunkId}
+				onOpenDetail={(chunkId) => {
+					setSelectedChunkId(chunkId)
+					setDetailChunkId(chunkId)
+					setDetailScrollOffset(0)
+				}}
+				onCloseDetail={() => {
+					setDetailChunkId(null)
+					setDetailScrollOffset(0)
+				}}
+				detailScrollOffset={detailScrollOffset}
+				onSetDetailScrollOffset={(updater) => setDetailScrollOffset(updater)}
+				contentWidth={Math.max(24, w - 2)}
+				bodyLines={bodyLines}
+				paneWidth={w}
+			/>
+			<box paddingLeft={1} paddingRight={1} height={FOOTER_ROWS}>
+				<TextLine>
+					<span fg={colors.count} attributes={TextAttributes.BOLD}>1-9</span>
+					<span fg={colors.muted}>{" fixture  "}</span>
+					<span fg={colors.count} attributes={TextAttributes.BOLD}>j/k</span>
+					<span fg={colors.muted}>{" move  "}</span>
+					<span fg={colors.count} attributes={TextAttributes.BOLD}>enter</span>
+					<span fg={colors.muted}>{" detail  "}</span>
+					<span fg={colors.count} attributes={TextAttributes.BOLD}>gg/G</span>
+					<span fg={colors.muted}>{" top/bottom  "}</span>
+					<span fg={colors.count} attributes={TextAttributes.BOLD}>q</span>
+					<span fg={colors.muted}>{" quit"}</span>
+				</TextLine>
+			</box>
+		</box>
+	)
+}
+
+const renderer = await createCliRenderer({
+	exitOnCtrlC: false,
+	screenMode: "alternate-screen",
+	onDestroy: () => { process.exit(0) },
+})
+
+createRoot(renderer).render(
+	<RegistryProvider>
+		<StoryApp />
+	</RegistryProvider>,
+)