# RFD D16: Read-Only Web UI for Conversations - **Status**: Draft - **Category**: Design - **Authors**: Jean Mertz - **Date**: 2026-04-06 ## Summary This RFD introduces a read-only web interface for browsing JP conversations from a mobile device. The server is started via `jp serve --web` and serves server-rendered HTML using Axum and Maud, with a mobile-first CSS layout that supports automatic dark mode. No JavaScript is required. ## Motivation JP conversations are currently only readable through the terminal via `jp conversation print`. This works well at a workstation but is inaccessible when away from the machine — most commonly when reading from a phone. A lightweight web UI that renders conversations as HTML solves this. It needs to be mobile-first (the primary use case is reading on a phone at night), support dark mode, and preserve the native iOS/Android text interactions (zoom, select, copy-paste) by avoiding custom JavaScript controls. ## Design ### User Experience The UI follows the standard chat-app layout: - **Conversation list** (left pane / drawer): Shows all conversations sorted by last activity, displaying title and timestamp. On mobile this is the default view; tapping a conversation navigates to the detail view. - **Conversation detail** (right pane / main view): Renders the full conversation history as a scrollable chat view. User messages and assistant responses are visually distinct. Tool calls are rendered as collapsible blocks. Markdown content is rendered to HTML with syntax-highlighted code blocks. - **Navigation**: The sidebar slides in/out on mobile via a CSS-only toggle (no JavaScript). On wider viewports, the sidebar is always visible. ### CLI Entry Point A new `serve` subcommand is added to the CLI: ``` jp serve --web # default: 127.0.0.1:3141 jp serve --web --port 8080 jp serve --web --bind 0.0.0.0 # for phone access over LAN ``` The command initializes the workspace using the standard startup pipeline, then starts an HTTP server that blocks until interrupted. The `serve` subcommand is a top-level command (not nested under `conversation`) because it will later host the `--http-api` endpoint as well. ### Configuration A new top-level `server.web` config section: ```toml [server.web] bind = "127.0.0.1" # listening address port = 3141 # listening port ``` This is added to `AppConfig` via a new `ServerConfig` struct containing a nested `WebServerConfig`. The `server` namespace is reserved for future additions like `server.http_api`. ### Routes | Route | Description | | ------------------------ | ------------------------------------------------ | | `GET /` | Redirect to `/conversations` | | `GET /conversations` | Conversation list, sorted by `last_activated_at` | | `GET /conversations/:id` | Render a single conversation's chat history | | `GET /assets/style.css` | Embedded CSS, served with cache headers | All routes return server-rendered HTML. The `:id` parameter accepts the conversation's decisecond timestamp identifier (the same format used by `jp conversation show`). ### Architecture #### New Crate: `jp_web` ``` crates/jp_web/ ├── Cargo.toml └── src/ ├── lib.rs # start_server(workspace, config) -> Result ├── state.rs # Shared application state (Arc, etc.) ├── routes.rs # Axum router and handler functions ├── views/ │ ├── layout.rs # Base HTML shell (maud) │ ├── list.rs # Conversation list page │ └── detail.rs # Conversation detail page ├── render.rs # Event rendering: ConversationStream → HTML └── style.rs # Embedded CSS via include_str!() ``` The crate depends on `jp_workspace`, `jp_conversation`, and `jp_config` for data access, and on `axum`, `maud`, `comrak`, and `syntect` for serving and rendering. #### Technology Choices **Axum** (0.8): HTTP framework built on tokio and tower. JP already depends on tokio with full features enabled, so axum reuses the existing async runtime with minimal additional dependency surface. **Maud** (0.27): Compile-time HTML macro. Generates HTML from Rust expressions with automatic escaping. The transitive dependency cost is near-zero — `maud` pulls in `itoa`, `proc-macro2`, `quote`, and `syn`, all of which are already in the dependency tree. The only net-new crate is `proc-macro2-diagnostics`. Maud is preferred over minijinja for this use case because it keeps the HTML structure co-located with the Rust rendering logic, provides compile-time type checking, and avoids runtime template registration — advantages that outweigh the minor additional dependency for a UI with only 2-3 pages. **Comrak** (existing): Already a workspace dependency. Used in HTML output mode (`markdown_to_html()`) to render conversation message content. **Syntect** (existing): Already a workspace dependency. Used to produce ``-based syntax highlighting for code blocks in HTML output (instead of the ANSI escape sequences used by the terminal renderer). #### Rendering Pipeline The web renderer mirrors the logic in `jp_cli::cmd::conversation::print` but targets HTML instead of ANSI: 1. Load conversation events via `Workspace::events(handle)`. 2. Iterate turns via `ConversationStream::iter_turns()`. 3. For each event: - `ChatRequest` → render user message bubble (markdown → HTML via comrak). - `ChatResponse::Message` → render assistant message bubble. - `ChatResponse::Reasoning` → render as a collapsible `
` block (respecting `style.reasoning.display` config). - `ChatResponse::Structured` → render as a `
` JSON block.
   - `ToolCallRequest` / `ToolCallResponse` → render as a collapsible
     `
` block showing tool name, arguments, and result.
     Hidden tools (per `conversation.tools..style.hidden`) are skipped.
   - `InquiryRequest` / `InquiryResponse` → skipped (same as terminal print).

#### CSS Strategy

A single CSS file embedded via `include_str!()` and served at
`/assets/style.css` with a content-hash ETag for cache busting.

Key properties:

- **Dark mode**: `@media (prefers-color-scheme: dark)` — follows the OS setting
  automatically, no JavaScript toggle.
- **Mobile-first**: Default layout is single-column.
  Sidebar appears as a drawer toggled via a CSS checkbox hack (`` + `