@aryasaatvik/motel 0.3.0

package/src/services/TraceQueryService.ts

@@ -0,0 +1,43 @@
+import { Effect, Layer, Context } from "effect"
+import type { AiCallDetail, SpanItem, TraceItem, TraceSummaryItem } from "../domain.js"
+import { TelemetryStore } from "./TelemetryStore.js"
+
+/**
+ * Compatibility adapter for consumers importing the historical trace query module.
+ * New internal callers should use TelemetryStoreReadonly directly.
+ */
+export class TraceQueryService extends Context.Service<
+	TraceQueryService,
+	{
+		readonly listServices: Effect.Effect<readonly string[], Error>
+		readonly listRecentTraces: (serviceName: string, options?: { readonly lookbackMinutes?: number; readonly limit?: number; readonly cursorStartedAtMs?: number; readonly cursorTraceId?: string }) => Effect.Effect<readonly TraceItem[], Error>
+		readonly listTraceSummaries: (serviceName: string | null, options?: { readonly lookbackMinutes?: number; readonly limit?: number; readonly cursorStartedAtMs?: number; readonly cursorTraceId?: string }) => Effect.Effect<readonly TraceSummaryItem[], Error>
+		readonly searchTraceSummaries: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>>; readonly aiText?: string | null; readonly cursorStartedAtMs?: number; readonly cursorTraceId?: string }) => Effect.Effect<readonly TraceSummaryItem[], Error>
+		readonly listFacets: (input: { readonly type: "traces" | "logs"; readonly field: string; readonly serviceName?: string | null; readonly key?: string | null; readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly { readonly value: string; readonly count: number }[], Error>
+		readonly searchTraces: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly TraceItem[], Error>
+		readonly traceStats: (input: { readonly groupBy: string; readonly agg: "count" | "avg_duration" | "p95_duration" | "error_rate"; readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly { readonly group: string; readonly value: number; readonly count: number }[], Error>
+		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 traceId?: 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>>; readonly attributeContainsFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly SpanItem[], Error>
+	}
+>()("motel/TraceQueryService") {}
+
+export const TraceQueryServiceLive = Layer.effect(
+	TraceQueryService,
+	Effect.map(TelemetryStore, (store) => TraceQueryService.of({
+		listServices: store.listServices,
+		listRecentTraces: store.listRecentTraces,
+		listTraceSummaries: store.listTraceSummaries,
+		searchTraceSummaries: store.searchTraceSummaries,
+		listFacets: store.listFacets,
+		searchTraces: store.searchTraces,
+		traceStats: store.traceStats,
+		getTrace: store.getTrace,
+		getSpan: store.getSpan,
+		getAiCall: store.getAiCall,
+		listTraceSpans: store.listTraceSpans,
+		searchSpans: store.searchSpans,
+	})),
+)

package/src/services/ingestRpc.ts

@@ -0,0 +1,39 @@
+/**
+ * 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. Read-only TelemetryStore methods use the separate
+ * query RPC worker so no synchronous SQLite call runs on the HTTP thread.
+ *
+ * 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/queryRpc.ts

@@ -0,0 +1,15 @@
+import { Schema } from "effect"
+import * as Rpc from "effect/unstable/rpc/Rpc"
+import * as RpcGroup from "effect/unstable/rpc/RpcGroup"
+
+export class QueryError extends Schema.TaggedErrorClass<QueryError>()("QueryError", {
+	message: Schema.String,
+}) {}
+
+export const QueryRpcs = RpcGroup.make(
+	Rpc.make("query", {
+		payload: { method: Schema.String, args: Schema.Array(Schema.Unknown) },
+		success: Schema.Any,
+		error: QueryError,
+	}),
+)

package/src/services/telemetryQueryWorker.ts

@@ -0,0 +1,32 @@
+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 { TelemetryStoreQueryWorkerLive, TelemetryStoreReadonly, type TelemetryStoreReader } from "./TelemetryStore.js"
+import { QueryError, QueryRpcs } from "./queryRpc.js"
+
+type QueryMethod = keyof TelemetryStoreReader
+
+const QueryHandlers = QueryRpcs.toLayer(Effect.gen(function*() {
+	const store = yield* TelemetryStoreReadonly
+	return {
+		query: ({ method, args }) => {
+			const member = Reflect.get(store, method as QueryMethod) as unknown
+			const result = typeof member === "function" ? Reflect.apply(member, store, args) : member
+			return (result as Effect.Effect<unknown, Error>).pipe(
+				Effect.mapError((error) => new QueryError({ message: String(error) })),
+			)
+		},
+	}
+}))
+
+const WorkerLive = RpcServer.layer(QueryRpcs).pipe(
+	Layer.provide(QueryHandlers),
+	Layer.provide(TelemetryStoreQueryWorkerLive),
+	Layer.provide(RpcServer.layerProtocolWorkerRunner),
+	Layer.provide(RpcSerialization.layerMsgPack),
+	Layer.provide(BunWorkerRunner.layer),
+)
+
+Layer.launch(WorkerLive).pipe(BunRuntime.runMain)

package/src/services/telemetryWorker.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 writer and query-worker connections coexist against the same
+ * `.sqlite` file without blocking the HTTP event loop.
+ *
+ * The worker exposes only `ingestTraces` / `ingestLogs` (see ingestRpc.ts)
+ * and owns writer maintenance. Read queries run in telemetryQueryWorker.ts;
+ * neither path can block the HTTP event loop.
+ */
+
+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/startupBench.ts

@@ -0,0 +1,19 @@
+const EPOCH_KEY = "__motelStartupEpoch"
+
+type GlobalWithStartupEpoch = typeof globalThis & {
+	[EPOCH_KEY]?: number
+}
+
+const globalWithEpoch = globalThis as GlobalWithStartupEpoch
+
+if (globalWithEpoch[EPOCH_KEY] === undefined) {
+	globalWithEpoch[EPOCH_KEY] = performance.now()
+}
+
+export const startupBenchEnabled = process.env.MOTEL_BENCH_STARTUP_PHASES === "1"
+
+export const startupBenchMark = (phase: string) => {
+	if (!startupBenchEnabled) return
+	const elapsedMs = performance.now() - (globalWithEpoch[EPOCH_KEY] ?? performance.now())
+	process.stderr.write(`[motel-startup] ${phase} ${elapsedMs.toFixed(3)}ms\n`)
+}

package/src/startupLifecycle.ts

@@ -0,0 +1,57 @@
+import { Effect } from "effect"
+import { createDaemonManager, type DaemonStatus } from "./daemon.js"
+import { createLaunchAgentManager, createMotelLifecycle, usesLaunchAgentRuntime, type LaunchAgentManager, type MotelLifecycle } from "./launchAgent.js"
+import { MOTEL_SERVICE_ID } from "./registry.js"
+
+export type ConflictStatus = DaemonStatus & {
+	readonly service: typeof MOTEL_SERVICE_ID
+	readonly pid: number
+	readonly workdir: string
+	readonly reason: string
+}
+
+export const startDaemon = (lifecycle: MotelLifecycle = createMotelLifecycle()) => Effect.runPromise(lifecycle.start)
+
+const parsePort = (url: string) => {
+	try {
+		const port = Number(new URL(url).port)
+		return Number.isFinite(port) && port > 0 ? port : undefined
+	} catch {
+		return undefined
+	}
+}
+
+export const stopConflictingDaemon = async (
+	status: ConflictStatus,
+	options: {
+		readonly service?: LaunchAgentManager
+		readonly createManager?: typeof createDaemonManager
+	} = {},
+) => {
+	const service = options.service ?? createLaunchAgentManager()
+	if (usesLaunchAgentRuntime() && service.available) {
+		const serviceStatus = await Effect.runPromise(service.status).catch((error) => {
+			throw new Error(`Refusing detached recovery until Motel LaunchAgent ownership can be inspected: ${error instanceof Error ? error.message : String(error)}`)
+		})
+		if (serviceStatus?.manager === "loaded" && serviceStatus.health.pid === status.pid) {
+			await Effect.runPromise(service.stop)
+			return
+		}
+		if (serviceStatus?.manager === "loaded") {
+			throw new Error("Refusing detached recovery while Motel LaunchAgent is loaded for a different process.")
+		}
+		if (serviceStatus?.manager === "unknown") {
+			throw new Error("Refusing detached recovery until Motel LaunchAgent ownership can be inspected reliably.")
+		}
+		if (serviceStatus?.configuration !== "missing") {
+			throw new Error("Refusing detached recovery while a Motel LaunchAgent definition is present.")
+		}
+	}
+	const port = parsePort(status.url)
+	const manager = (options.createManager ?? createDaemonManager)({
+		workdir: status.workdir ?? undefined,
+		databasePath: status.databasePath,
+		port,
+	})
+	await Effect.runPromise(manager.stop)
+}

package/src/storybook/aiChatStory.tsx

@@ -0,0 +1,244 @@
+// 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/aiState.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}
+			/>
+			<Divider width={contentWidth} />
+			<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>,
+)

package/src/storybook/fixtures/errorState.ts

@@ -0,0 +1,44 @@
+import { type ChatFixture, makeDetail, makeSpan } from "./index.ts"
+
+// A tool-call that errored mid-stream: finishReason === "error" and a
+// tool-result whose output shape is irregular (object without the
+// expected `type: "text"` wrapper). Covers graceful-degrade rendering.
+export const errorFixture: ChatFixture = {
+	id: "error",
+	label: "error",
+	span: makeSpan({ status: "error", durationMs: 820 }),
+	detail: makeDetail({
+		status: "error",
+		finishReason: "error",
+		durationMs: 820,
+		promptMessages: {
+			messages: [
+				{ role: "user", content: [{ type: "text", text: "Grab the latest commits from main." }] },
+				{
+					role: "assistant",
+					content: [
+						{ type: "tool-call", toolCallId: "tc-1", toolName: "bash", input: { command: "git fetch origin main && git log --oneline -5 origin/main" } },
+					],
+				},
+				{
+					role: "tool",
+					content: [
+						{
+							type: "tool-result",
+							toolCallId: "tc-1",
+							toolName: "bash",
+							output: { error: "HTTP 429 rate limited", code: 429, retryable: true },
+						},
+					],
+				},
+				{
+					role: "assistant",
+					content: [
+						{ type: "text", text: "The request was rate-limited. I'll retry after a delay — or you can rerun manually." },
+					],
+				},
+			],
+		},
+		responseText: null,
+	}),
+}

package/src/storybook/fixtures/imagePaste.ts

@@ -0,0 +1,34 @@
+import { type ChatFixture, makeDetail, makeSpan } from "./index.ts"
+
+// User pastes an image as a data URL alongside text. The renderer
+// should replace the base64 blob with a compact `[data:image/png
+// base64 NNk]` marker and leave the prose readable. Regression case
+// for the "screen filled with base64" bug.
+const base64Chunk = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAD".repeat(1000)
+
+export const imagePasteFixture: ChatFixture = {
+	id: "image-paste",
+	label: "image",
+	span: makeSpan(),
+	detail: makeDetail({
+		promptMessages: {
+			messages: [
+				{ role: "system", content: "You are a code review assistant." },
+				{
+					role: "user",
+					content: [
+						{ type: "text", text: `I captured this screenshot of the bug: data:image/png;base64,${base64Chunk}\n\nCan you tell me what's off about the formatting here?` },
+					],
+				},
+				{
+					role: "assistant",
+					content: [
+						{ type: "text", text: "Based on the image, the top padding looks inconsistent between rows. Let me open the component to check." },
+						{ type: "tool-call", toolCallId: "tc-1", toolName: "read", input: { filePath: "/src/ui/Row.tsx" } },
+					],
+				},
+			],
+		},
+		responseText: "The padding comes from two different tokens; we should unify them.",
+	}),
+}

package/src/storybook/fixtures/index.ts

@@ -0,0 +1,62 @@
+// Shared fixture type for the AI-chat storybook. Each fixture is a
+// label + a synthetic span + a synthetic AI call detail, in the same
+// shape the real server returns. Prefer hand-crafted minimal examples
+// over real captures — they exercise renderer cases deliberately and
+// don't leak session content into the repo.
+
+import type { AiCallDetail, TraceSpanItem } from "../../domain.ts"
+
+export interface ChatFixture {
+	readonly id: string
+	readonly label: string
+	readonly span: TraceSpanItem
+	readonly detail: AiCallDetail
+}
+
+export const makeSpan = (overrides: Partial<TraceSpanItem> = {}): TraceSpanItem => ({
+	spanId: "fixture-span-0000",
+	parentSpanId: null,
+	operationName: "ai.streamText",
+	serviceName: "storybook",
+	scopeName: "ai",
+	kind: "internal",
+	status: "ok",
+	startTime: new Date(),
+	durationMs: 2400,
+	isRunning: false,
+	depth: 0,
+	tags: {
+		"ai.operationId": "ai.streamText",
+		"ai.model.id": "claude-opus-4-7",
+		"ai.model.provider": "anthropic",
+		"ai.prompt.messages": "[]",
+	},
+	warnings: [],
+	events: [],
+	...overrides,
+})
+
+export const makeDetail = (overrides: Partial<AiCallDetail> = {}): AiCallDetail => ({
+	traceId: "fixture-trace-0000",
+	spanId: "fixture-span-0000",
+	operation: "streamText",
+	service: "storybook",
+	functionId: "story.demo",
+	provider: "anthropic",
+	model: "claude-opus-4-7",
+	status: "ok",
+	startedAt: new Date().toISOString(),
+	durationMs: 2400,
+	sessionId: "ses_fixture",
+	userId: "kit",
+	finishReason: "stop",
+	promptMessages: null,
+	responseText: null,
+	toolCalls: [],
+	toolsAvailable: null,
+	providerMetadata: null,
+	usage: { inputTokens: 1234, outputTokens: 321, totalTokens: 1555, cachedInputTokens: 0, reasoningTokens: null },
+	timing: { msToFirstChunk: null, msToFinish: null, avgOutputTokensPerSecond: null },
+	logs: [],
+	...overrides,
+})