@kitlangton/motel 0.1.0

package/AGENTS.md

@@ -0,0 +1,142 @@
+# AGENTS.md
+
+## Commands
+- Install deps: `bun install`
+- Run the TUI: `bun run dev` or `bun run start`
+- Run the local server only: `bun run server`
+- Run tests: `bun run test`
+- Query services via CLI: `bun run cli services`
+- Query traces via CLI: `bun run cli traces <service> [limit]`
+- Query a span via CLI: `bun run cli span <span-id>`
+- Query spans for one trace: `bun run cli trace-spans <trace-id>`
+- Search spans via CLI: `bun run cli search-spans [service] [operation] [parent=<operation>] [attr.key=value ...]`
+- Search traces via CLI: `bun run cli search-traces <service> [operation] [attr.key=value ...]`
+- Query trace stats via CLI: `bun run cli trace-stats <groupBy> <agg> [service] [attr.key=value ...]`
+- Query logs via CLI: `bun run cli logs <service>`
+- Search logs via CLI: `bun run cli search-logs <service> [body] [attr.key=value ...]`
+- Query log stats via CLI: `bun run cli log-stats <groupBy> [service] [attr.key=value ...]`
+- Query logs for one trace: `bun run cli trace-logs <trace-id>`
+- Query logs for one span: `bun run cli span-logs <span-id>`
+- Query facets via CLI: `bun run cli facets <traces|logs> <field>`
+- Print Effect setup instructions: `bun run instructions`
+- Build the web UI: `bun run web:build`
+- Dev the web UI (with hot reload): `bun run web:dev`
+- Typecheck: `bun run typecheck`
+
+## Verification
+- The built-in verification step is `bun run typecheck`.
+- For runtime verification, start the TUI or server once, then query `http://127.0.0.1:27686/api/services`, `http://127.0.0.1:27686/api/spans/<span-id>`, `http://127.0.0.1:27686/openapi.json`, and `bun run cli logs motel-otel-tui`.
+- For span-centric debugging, use `http://127.0.0.1:27686/api/spans/search?...`, `http://127.0.0.1:27686/api/spans/<span-id>/logs`, and `http://127.0.0.1:27686/api/traces/<trace-id>/spans`.
+
+## API Notes
+- List and search endpoints return a `meta` object with `limit`, `lookback`, `returned`, `truncated`, and `nextCursor`.
+- `/api/traces` and `/api/traces/search` return summaries by default. Use `/api/traces/<trace-id>` for the full trace tree.
+- `/api/logs` and `/api/logs/search` support `severity` (e.g. `?severity=ERROR`), case-insensitive body search, and `attrContains.<key>=<substring>` for substring search inside attribute values.
+- `/api/spans/search` supports `traceId` to scope to one trace, `attr.<key>=<value>` for exact match, and `attrContains.<key>=<substring>` for case-insensitive substring search inside attribute values.
+- `/api/ai/calls` searches AI SDK calls (streamText, generateText, etc.) with first-class filters for `model`, `provider`, `sessionId`, `functionId`, `operation`, `status`, `text` (cross-field search), and returns compact summaries with previews and token usage.
+- `/api/ai/calls/<span-id>` returns the full detail of a single AI call including complete prompt messages, response text, tool calls, timing, and correlated logs.
+- `/api/ai/stats` aggregates AI call statistics by `provider`, `model`, `functionId`, `sessionId`, or `status` with aggregations: `count`, `avg_duration`, `p95_duration`, `total_input_tokens`, `total_output_tokens`.
+- `/api/docs` lists available documentation; `/api/docs/debug` and `/api/docs/effect` return the full skill content.
+
+## Architecture
+- `src/index.tsx` creates the OpenTUI renderer and mounts the app.
+- `src/App.tsx` composes the top-level screen: header, footer, and the
+  drill-in workspace. Heavy logic is delegated to the modules below.
+- `src/ui/app/useTraceScreenData.ts` owns the atoms and data-loading
+  effects for traces, logs, services, and cache warming.
+- `src/ui/app/useAppLayout.ts` is the single source for layout math
+  (pane widths, body lines, viewport rows, drill-in level).
+- `src/ui/app/TraceWorkspace.tsx` renders the drill-in state machine:
+  L0 (trace list), L1 (waterfall), L2 (span detail), plus the service
+  logs side mode.
+- `src/ui/app/TraceListPane.tsx` wraps `TraceList` in a scrollbox with
+  the filter bar and list header.
+- `src/ui/TraceList.tsx` renders trace rows (trace id, duration, span
+  count, relative age).
+- `src/ui/Waterfall.tsx` renders the waterfall timeline with a
+  virtualised scroll viewport; `src/ui/waterfallNav.ts` is the pure
+  collapse/expand/walk resolver (unit-tested).
+- `src/ui/TraceDetailsPane.tsx` is the L1 body: header + waterfall.
+- `src/ui/SpanDetailPane.tsx` is the L2 body; renders
+  `src/ui/SpanDetail.tsx` below a header that owns the span identity.
+- `src/ui/useKeyboardNav.ts` centralises the keyboard handlers and
+  cross-pane navigation state transitions.
+- `src/cli.ts` exposes trace and log queries through a small local CLI wrapper.
+- `src/runtime.ts` wires the Effect beta runtime and OTEL trace + log exporters.
+- `src/localServer.ts` starts the local Bun OTLP/query server.
+- `src/httpApi.ts` defines the typed Effect HttpApi surface and OpenAPI spec for the local server.
+- `src/server.ts` runs the local server without the TUI.
+- `src/instructions.ts` contains the copied setup instructions for other Effect apps.
+- `src/services/TelemetryStore.ts` persists traces and logs in SQLite and exposes indexed queries.
+- `src/services/TraceQueryService.ts` reads traces from the local store.
+- `src/services/LogQueryService.ts` reads logs from the local store.
+- `src/config.ts` is the source of truth for ports and env-driven OTEL settings.
+- `web/` is a Vite + React SPA for the browser-based UI (Tailwind CSS, `@effect/atom-react`, `AtomHttpApi`).
+- `web/src/api.ts` creates the typed `AtomHttpApi.Service` client from `src/httpApi.ts`.
+- `web/src/pages/` contains route pages: TracesPage, TraceDetailPage, LogsPage, AiCallsPage.
+- `web/src/components/` contains Waterfall and SpanDetail components.
+- The server in `src/localServer.ts` serves `web/dist/` as static files with SPA fallback for non-API routes.
+
+## Tests
+- `bun test` runs the suite. Three kinds of tests live in the repo:
+  - `src/telemetry.test.ts` exercises the SQLite TelemetryStore with
+    OTLP payloads end-to-end.
+  - `src/ui/waterfallNav.test.ts` unit-tests the pure collapse/expand
+    resolver (no UI).
+  - `src/ui/*.repro.test.ts` drive the real TUI under `tuistory` to
+    reproduce regressions; each has a sibling `*.repro.seed.ts` that
+    seeds a deterministic trace into SQLite in a child process. These
+    are auto-skipped when `tuistory` isn't installed.
+
+## Effect Observability Guidance
+- Inspect the target repo’s existing Effect runtime and observability wiring before adding anything new.
+- Prefer the repo’s existing Effect-native observability APIs if available.
+- If `effect/unstable/observability` is already the best fit, prefer it over adding `@effect/opentelemetry`.
+- Only add new OpenTelemetry SDK packages when the repo already uses them or they are clearly required.
+- Merge telemetry into the main runtime once, not per-feature.
+- Prefer structured log annotations so fields like `sessionID`, `modelID`, `providerID`, and `tool` are queryable.
+
+## Local OTEL Ports
+- Local API / UI base: `http://127.0.0.1:27686`
+- OTLP HTTP traces: `http://127.0.0.1:27686/v1/traces`
+- OTLP HTTP logs: `http://127.0.0.1:27686/v1/logs`
+- Health: `http://127.0.0.1:27686/api/health`
+
+## Env Vars
+- `MOTEL_OTEL_ENABLED`: defaults to `false` (set to `true` to emit self-traces for debugging motel itself)
+- `MOTEL_OTEL_SERVICE_NAME`: defaults to `motel-otel-tui`
+- `MOTEL_OTEL_BASE_URL`: defaults to `http://127.0.0.1:27686`
+- `MOTEL_OTEL_HOST`: defaults to `127.0.0.1`
+- `MOTEL_OTEL_PORT`: defaults to `27686`
+- `MOTEL_OTEL_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/traces`
+- `MOTEL_OTEL_LOGS_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/logs`
+- `MOTEL_OTEL_QUERY_URL`: defaults to `http://127.0.0.1:27686`
+- `MOTEL_OTEL_DB_PATH`: defaults to `.motel-data/telemetry.sqlite`
+- `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES`: defaults to `1440` (24h)
+- `MOTEL_OTEL_TRACE_LIMIT`: defaults to `100`
+- `MOTEL_OTEL_LOG_LIMIT`: defaults to `80`
+- `MOTEL_OTEL_RETENTION_HOURS`: defaults to `168` (7d)
+- `MOTEL_OTEL_MAX_DB_SIZE_MB`: defaults to `256` (size-based retention cap)
+
+## TUI Keys
+- `?`: toggle shortcut help
+- `j` / `k` or `up` / `down`: move trace or span selection
+- `h` / `left`: collapse current span, or step to parent
+- `l` / `right`: expand current span, or step to first child
+- `ctrl-n` / `ctrl-p`: switch traces while staying in the details area
+- `gg` / `home`: jump to the first trace or span
+- `G` / `end`: jump to the last trace or span
+- `ctrl-u` / `pageup`: page up
+- `ctrl-d` / `pagedown`: page down
+- `enter`: drill in one level (list → waterfall → span detail)
+- `esc`: back out one level
+- `tab`: toggle service logs view
+- `[` / `]`: switch services
+- `s`: cycle sort mode (recent → slowest → errors)
+- `/`: enter filter mode (type to match on root operation name; `:error` restricts to failing traces)
+- `a`: pause or resume auto-refresh
+- `r`: refresh now
+- `c`: copy setup instructions for another Effect app
+- `o`: open selected trace in the browser
+- `y`: copy selected trace or span id
+- `q`: quit

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kit Langton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# motel
+
+A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.
+Point your app's OTLP/HTTP exporters at the local motel server and browse
+traces, spans, and logs from a terminal or the built-in web UI.
+
+## Install
+
+```bash
+bun add -g @kitlangton/motel
+motel
+```
+
+(or `bunx @kitlangton/motel` for a one-off run without installing.)
+
+## Requirements
+
+- [Bun](https://bun.sh/) — v1.1 or newer
+
+## Install the motel-debug skill
+
+`motel` ships a companion skill that teaches agents (Claude Code, OpenCode,
+Cursor, Codex, and 40+ others) how to debug with runtime evidence by
+querying motel's local OTLP store. Install it with a one-liner via
+[`npx skills`](https://github.com/vercel-labs/skills):
+
+```bash
+# Project-local (adds to .claude/skills, .agents/skills, etc.)
+npx skills add kitlangton/motel --skill motel-debug
+
+# Globally, available in every project
+npx skills add kitlangton/motel --skill motel-debug -g
+
+# Target a specific agent only
+npx skills add kitlangton/motel --skill motel-debug -a claude-code
+```
+
+The skill lives at [`skills/motel-debug/`](skills/motel-debug/) in this repo.
+
+## Quick start
+
+```bash
+bun install
+bun run dev
+```
+
+`bun run dev` starts the local OTLP ingest server (on `http://127.0.0.1:27686`)
+and launches the TUI. Press `?` once inside for the keyboard cheat sheet, or
+`c` to copy paste-ready setup instructions for another Effect/OTEL app.
+
+If you just want the server without the TUI (for example, to run it in the
+background and browse the web UI):
+
+```bash
+bun run server
+# then in another terminal
+bun run web:dev
+```
+
+## Commands
+
+- `bun install`
+- `bun run server`
+- `bun run dev`
+- `bun run test`
+- `bun run cli services`
+- `bun run cli traces <service>`
+- `bun run cli span <span-id>`
+- `bun run cli search-traces <service> [operation]`
+- `bun run cli trace-stats <groupBy> <agg> [service]`
+- `bun run cli logs <service>`
+- `bun run cli search-logs <service> [body]`
+- `bun run cli log-stats <groupBy> [service]`
+- `bun run cli trace-logs <trace-id>`
+- `bun run cli facets <traces|logs> <field>`
+- `bun run instructions`
+- `bun run typecheck`
+
+## Local ports
+
+This repo uses one local Bun server with SQLite storage. No Docker is required.
+
+- motel local API / UI base: `http://127.0.0.1:27686`
+- OTLP HTTP traces: `http://127.0.0.1:27686/v1/traces`
+- OTLP HTTP logs: `http://127.0.0.1:27686/v1/logs`
+- health: `http://127.0.0.1:27686/api/health`
+
+Other local apps can send telemetry to:
+
+```bash
+http://127.0.0.1:27686/v1/traces
+http://127.0.0.1:27686/v1/logs
+```
+
+Agents and scripts can query traces and logs from the local API:
+
+```bash
+http://127.0.0.1:27686/api/services
+http://127.0.0.1:27686/api/traces?service=<service>&limit=20&lookback=1h
+http://127.0.0.1:27686/api/traces/search?service=<service>&operation=proxy&status=error&attr.sessionID=<session-id>
+http://127.0.0.1:27686/api/traces/stats?groupBy=operation&agg=p95_duration&service=<service>
+http://127.0.0.1:27686/api/spans/<span-id>
+http://127.0.0.1:27686/api/spans/<span-id>/logs
+http://127.0.0.1:27686/api/spans/search?service=<service>&operation=Format.file&parentOperation=Tool.write&attr.sessionID=<session-id>
+http://127.0.0.1:27686/api/traces/<trace-id>/spans
+http://127.0.0.1:27686/api/logs?service=<service>&body=proxy_request
+http://127.0.0.1:27686/api/logs?service=<service>&attr.service.name=<service>
+http://127.0.0.1:27686/api/logs/stats?groupBy=severity&agg=count&service=<service>
+http://127.0.0.1:27686/api/facets?type=logs&field=severity
+http://127.0.0.1:27686/openapi.json
+http://127.0.0.1:27686/docs
+```
+
+## TUI keys
+
+- `?`: show or hide keyboard shortcut help
+- `j` / `k` or `up` / `down`: move selection
+- `ctrl-n` / `ctrl-p`: switch traces even while in trace details
+- `gg` or `home`: jump to the first trace or first span
+- `G` or `end`: jump to the last trace or last span
+- `ctrl-u` / `pageup`: move up by one page
+- `ctrl-d` / `pagedown`: move down by one page
+- `l`: toggle service logs mode
+- `[` / `]`: switch service
+- `enter`: enter span navigation or open selected span detail
+- `esc`: leave span detail or span navigation
+- `r`: refresh
+- `c`: copy a paste-ready Effect setup prompt for another app
+- `o`: open selected trace in browser
+- `q`: quit
+
+## How It Works
+
+`motel` now has one local service process:
+
+- the local Bun server receives OTLP traces and logs on `http://127.0.0.1:27686`
+- it stores telemetry in SQLite at `.motel-data/telemetry.sqlite`
+- it exposes query endpoints on the same base URL
+
+So yes: another service has to point its OTEL exporters at this local motel instance.
+
+## Privacy Note
+
+`motel` is a local observability tool, and it can store sensitive telemetry content if the upstream app emits it.
+
+- correlated logs may include secrets, tokens, or PII if your app logs them
+- AI call data may include prompt previews, response previews, full prompt content, response text, tool metadata, and provider metadata
+- treat the local SQLite store as sensitive development data when using motel against real workloads
+
+The easiest flow is:
+
+1. Run `bun run dev` here. That starts the local server if needed and then launches the TUI.
+2. In `motel`, press `c`.
+3. Paste the copied instructions into an agent working in the other service.
+4. Have that service export OTEL traces to `http://127.0.0.1:27686/v1/traces` and OTEL logs to `http://127.0.0.1:27686/v1/logs`.
+5. Refresh `motel`, switch to that service with `[` / `]`, and use `l` or `enter` to inspect logs under a trace or span.
+
+## For Agents
+
+An agent does not need to talk to the TUI.
+
+List and search endpoints now return a `meta` object with `limit`, `lookback`, `returned`, `truncated`, and `nextCursor` so callers can page safely instead of assuming they received all results.
+
+Use one of these:
+
+1. motel HTTP API directly
+
+```bash
+curl http://127.0.0.1:27686/api/services
+curl "http://127.0.0.1:27686/api/traces?service=my-service&limit=20&lookback=1h"
+curl http://127.0.0.1:27686/api/traces/<trace-id>
+```
+
+2. The local CLI wrapper in this repo
+
+```bash
+bun run cli services
+bun run cli traces my-service 20
+bun run cli span <span-id>
+bun run cli trace-spans <trace-id>
+bun run cli search-spans my-service Format.file parent=Tool.write attr.sessionID=sess_123
+bun run cli search-traces my-service proxy attr.sessionID=sess_123
+bun run cli trace-stats operation p95_duration my-service attr.modelID=gpt-5.4
+bun run cli trace <trace-id>
+bun run cli logs my-service
+bun run cli search-logs my-service timeout attr.tool=search
+bun run cli log-stats severity my-service attr.tool=search
+bun run cli trace-logs <trace-id>
+bun run cli span-logs <span-id>
+bun run cli facets logs severity
+bun run instructions
+```
+
+Recommended shape going forward:
+
+1. Keep motel as the single ingest point for apps.
+2. Keep SQLite as the local source of truth.
+3. Keep `motel` as the interactive viewer.
+4. Keep the CLI and HTTP API as the agent/script interfaces.

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@kitlangton/motel",
+  "version": "0.1.0",
+  "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Kit Langton",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitlangton/motel.git"
+  },
+  "homepage": "https://github.com/kitlangton/motel#readme",
+  "bugs": {
+    "url": "https://github.com/kitlangton/motel/issues"
+  },
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "observability",
+    "tui",
+    "sqlite",
+    "effect",
+    "opentui"
+  ],
+  "workspaces": ["web"],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "web/dist",
+    "LICENSE",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "bin": {
+    "motel": "src/motel.ts",
+    "motel-mcp": "src/mcp.ts"
+  },
+  "scripts": {
+    "clear-motel-debug": "bun run skills/motel-debug/scripts/clear-motel-debug.ts",
+    "dev": "bun run src/motel.ts tui",
+    "start": "bun run src/motel.ts tui",
+    "daemon": "bun run src/motel.ts daemon",
+    "status": "bun run src/motel.ts status",
+    "stop": "bun run src/motel.ts stop",
+    "server": "bun run src/motel.ts server",
+    "mcp": "bun run src/mcp.ts",
+    "test": "bun test",
+    "cli": "bun run src/cli.ts",
+    "instructions": "bun run src/cli.ts instructions",
+    "services": "bun run src/cli.ts services",
+    "logs": "bun run src/cli.ts logs",
+    "trace-logs": "bun run src/cli.ts trace-logs",
+    "span-logs": "bun run src/cli.ts span-logs",
+    "span": "bun run src/cli.ts span",
+    "trace-spans": "bun run src/cli.ts trace-spans",
+    "search-spans": "bun run src/cli.ts search-spans",
+    "trace-stats": "bun run src/cli.ts trace-stats",
+    "log-stats": "bun run src/cli.ts log-stats",
+    "web:dev": "cd web && npx vite",
+    "web:build": "cd web && npx vite build",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run web:build"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.12",
+    "@types/react": "^19.2.14",
+    "typescript": "^6.0.2"
+  },
+  "dependencies": {
+    "@effect/atom-react": "^4.0.0-beta.49",
+    "@effect/opentelemetry": "^4.0.0-beta.49",
+    "@effect/platform-bun": "^4.0.0-beta.49",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.211.0",
+    "@opentelemetry/sdk-logs": "^0.214.0",
+    "@opentelemetry/sdk-node": "^0.214.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "@opentui/core": "^0.1.99",
+    "@opentui/react": "^0.1.99",
+    "effect": "^4.0.0-beta.49",
+    "react": "^19.2.5",
+    "scheduler": "^0.27.0"
+  }
+}

package/src/App.tsx

@@ -0,0 +1,217 @@
+import { RGBA, TextAttributes, type ScrollBoxRenderable } from "@opentui/core"
+import { useAtom } from "@effect/atom-react"
+import { useTerminalDimensions } from "@opentui/react"
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react"
+import { formatTimestamp, traceRowId } from "./ui/format.ts"
+import { Divider, FooterHints, HelpModal, PlainLine, SplitDivider, TextLine } from "./ui/primitives.tsx"
+import { useAppLayout } from "./ui/app/useAppLayout.ts"
+import { useTraceScreenData } from "./ui/app/useTraceScreenData.ts"
+import { TraceWorkspace } from "./ui/app/TraceWorkspace.tsx"
+import { noticeAtom, persistSelectedTheme, selectedThemeAtom } from "./ui/state.ts"
+import { applyTheme, colors, SEPARATOR, themeLabel } from "./ui/theme.ts"
+import { getVisibleSpans } from "./ui/Waterfall.tsx"
+import { useKeyboardNav } from "./ui/useKeyboardNav.ts"
+
+export const App = () => {
+	const { width, height } = useTerminalDimensions()
+	const [notice, setNotice] = useAtom(noticeAtom)
+	const [selectedTheme] = useAtom(selectedThemeAtom)
+	applyTheme(selectedTheme)
+	const {
+		traceState,
+		traceDetailState,
+		logState,
+		serviceLogState,
+		selectedServiceLogIndex,
+		setSelectedServiceLogIndex,
+		selectedTraceIndex,
+		setSelectedTraceIndex,
+		selectedTraceService,
+		selectedSpanIndex,
+		setSelectedSpanIndex,
+		detailView,
+		showHelp,
+		setShowHelp,
+		collapsedSpanIds,
+		autoRefresh,
+		filterMode,
+		filterText,
+		traceSort,
+		selectedTraceSummary,
+		selectedTrace,
+		filteredTraces,
+	} = useTraceScreenData()
+
+	const layout = useAppLayout({ width, height, notice, detailView, selectedSpanIndex })
+	const {
+		contentWidth,
+		isWideLayout,
+		viewLevel,
+		footerNotice,
+		footerHeight,
+		leftPaneWidth,
+		rightPaneWidth,
+		leftContentWidth,
+		headerFooterWidth,
+		wideBodyLines,
+		narrowBodyLines,
+		traceViewportRows,
+		tracePageSize,
+		spanPageSize,
+	} = layout
+
+	const noticeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+	const traceListScrollRef = useRef<ScrollBoxRenderable | null>(null)
+
+	const flashNotice = (message: string) => {
+		if (noticeTimeoutRef.current !== null) {
+			clearTimeout(noticeTimeoutRef.current)
+		}
+		setNotice(message)
+		noticeTimeoutRef.current = globalThis.setTimeout(() => {
+			setNotice((current) => (current === message ? null : current))
+		}, 2500)
+	}
+
+	useEffect(() => () => {
+		if (noticeTimeoutRef.current !== null) {
+			clearTimeout(noticeTimeoutRef.current)
+		}
+	}, [setNotice])
+
+	useEffect(() => {
+		persistSelectedTheme(selectedTheme)
+	}, [selectedTheme])
+
+	useLayoutEffect(() => {
+		const box = traceListScrollRef.current
+		const traceId = selectedTraceSummary?.traceId
+		if (!box || !traceId) return
+		const indexInList = filteredTraces.findIndex((trace) => trace.traceId === traceId)
+		if (indexInList < 0) return
+		const currentTop = box.scrollTop
+		const viewportRows = Math.max(1, traceViewportRows)
+		let nextTop = currentTop
+		if (indexInList < currentTop) {
+			nextTop = indexInList
+		} else if (indexInList >= currentTop + viewportRows) {
+			nextTop = indexInList - viewportRows + 1
+		}
+		const maxTop = Math.max(0, filteredTraces.length - viewportRows)
+		nextTop = Math.max(0, Math.min(nextTop, maxTop))
+		if (nextTop !== currentTop) {
+			box.scrollTop = nextTop
+		}
+	}, [filteredTraces, selectedTraceIndex, selectedTraceSummary?.traceId, traceSort, traceViewportRows])
+
+	const { spanNavActive } = useKeyboardNav({
+		selectedTrace,
+		filteredTraces,
+		isWideLayout,
+		wideBodyLines,
+		narrowBodyLines,
+		tracePageSize,
+		spanPageSize,
+		flashNotice,
+	})
+
+	const headerServiceLabel = selectedTraceService ?? "none"
+	const autoLabel = autoRefresh ? "● live" : "○ paused"
+	const headerRight = traceState.fetchedAt
+		? `${autoLabel}  ${formatTimestamp(traceState.fetchedAt)}`
+		: traceState.status === "loading"
+			? "loading traces..."
+			: ""
+	const headerLeftLen = "MOTEL".length + SEPARATOR.length + headerServiceLabel.length
+	const headerGap = Math.max(2, headerFooterWidth - headerLeftLen - headerRight.length)
+	const visibleFooterNotice = footerNotice
+
+	const selectTraceById = useCallback((traceId: string) => {
+		const index = traceState.data.findIndex((trace) => trace.traceId === traceId)
+		if (index >= 0) setSelectedTraceIndex(index)
+	}, [setSelectedTraceIndex, traceState.data])
+
+	const selectSpan = useCallback((index: number) => {
+		if (!selectedTrace) return
+		const visibleCount = getVisibleSpans(selectedTrace.spans, collapsedSpanIds).length
+		setSelectedSpanIndex(Math.max(0, Math.min(index, visibleCount - 1)))
+	}, [collapsedSpanIds, selectedTrace, setSelectedSpanIndex])
+
+	const traceListProps = useMemo(() => ({
+		traces: filteredTraces,
+		selectedTraceId: selectedTraceSummary?.traceId ?? null,
+		status: traceState.status,
+		error: traceState.error,
+		contentWidth: leftContentWidth,
+		services: traceState.services,
+		selectedService: selectedTraceService,
+		focused: !spanNavActive,
+		filterText: filterText || undefined,
+		sortMode: traceSort,
+		totalCount: filterText ? traceState.data.length : undefined,
+		onSelectTrace: selectTraceById,
+	} as const), [filteredTraces, selectedTraceSummary?.traceId, traceState.status, traceState.error, leftContentWidth, traceState.services, selectedTraceService, spanNavActive, filterText, traceSort, traceState.data.length, selectTraceById])
+
+	const filteredSpans = selectedTrace ? getVisibleSpans(selectedTrace.spans, collapsedSpanIds) : []
+	const selectedSpan = selectedSpanIndex !== null ? filteredSpans[selectedSpanIndex] ?? null : null
+	const selectedSpanLogs = useMemo(
+		() => selectedSpan ? logState.data.filter((log) => log.spanId === selectedSpan.spanId) : [],
+		[selectedSpan, logState.data],
+	)
+
+	const showSplit = isWideLayout
+
+	return (
+		<box width={width ?? 100} height={height ?? 24} flexGrow={1} flexDirection="column" backgroundColor={RGBA.fromHex(colors.screenBg)}>
+			<box paddingLeft={1} paddingRight={1} flexDirection="column">
+				<TextLine>
+					<span fg={colors.muted} attributes={TextAttributes.BOLD}>MOTEL</span>
+					<span fg={colors.separator}>{SEPARATOR}</span>
+					<span fg={colors.muted}>{headerServiceLabel}</span>
+					<span fg={colors.muted}>{" ".repeat(headerGap)}</span>
+					<span fg={colors.muted} attributes={TextAttributes.BOLD}>{headerRight}</span>
+				</TextLine>
+			</box>
+			{showSplit
+				? <SplitDivider leftWidth={leftPaneWidth} junction={"┬"} rightWidth={rightPaneWidth} />
+				: <Divider width={contentWidth} />}
+			<TraceWorkspace
+				layout={layout}
+				detailView={detailView}
+				filterMode={filterMode}
+				filterText={filterText}
+				traceListProps={traceListProps}
+				traceListScrollRef={traceListScrollRef}
+				selectedTraceService={selectedTraceService}
+				serviceLogState={serviceLogState}
+				selectedServiceLogIndex={selectedServiceLogIndex}
+				setSelectedServiceLogIndex={setSelectedServiceLogIndex}
+				traceDetailState={traceDetailState}
+				selectedTrace={selectedTrace}
+				selectedTraceSummary={selectedTraceSummary}
+				logState={logState}
+				selectedSpanIndex={selectedSpanIndex}
+				collapsedSpanIds={collapsedSpanIds}
+				viewLevel={viewLevel}
+				selectedSpan={selectedSpan}
+				selectedSpanLogs={selectedSpanLogs}
+				selectSpan={selectSpan}
+			/>
+			{footerHeight > 0 ? (
+				<>
+					{showSplit
+						? <SplitDivider leftWidth={leftPaneWidth} junction={"┴"} rightWidth={rightPaneWidth} />
+						: <Divider width={contentWidth} />}
+					<box paddingLeft={1} paddingRight={1} flexDirection="column" height={footerHeight}>
+						{visibleFooterNotice ? (
+							<PlainLine text={visibleFooterNotice} fg={colors.count} />
+						) : (
+							<FooterHints spanNavActive={spanNavActive} detailView={detailView} autoRefresh={autoRefresh} width={headerFooterWidth} />
+						)}
+					</box>
+				</>
+			) : null}
+			{showHelp ? <HelpModal width={width ?? 100} height={height ?? 24} autoRefresh={autoRefresh} themeLabel={themeLabel(selectedTheme)} onClose={() => setShowHelp(false)} /> : null}
+		</box>
+	)
+}