# Frontend

## HTTP Server

Axum router assembled in `src/frontend/server.rs` (`WebServer::build_router_with_plugins`):

- `/api/*` — the app's HTTP handlers (`State<Arc<Skald>>`), plus per-plugin routers nested under `/api/plugin/<id>/`.
- `/data/*` — the on-disk `data/` directory (served via `tower_http::services::ServeDir`, so e.g. `/data/gmail_attachments/...` resolves to a file URL).
- Static fallback — the `web.static_dir` directory (`ServeDir`), i.e. the SPA assets.

**Compression.** A global `tower_http::compression::CompressionLayer` (gzip + brotli, enabled via the `compression-gzip` / `compression-br` features) wraps the whole router. Encoding is negotiated from the client's `Accept-Encoding` (no-op for clients that don't advertise one and for already-compressed media). The main motivation is the **mobile relay path**: the native WebView's HTTP traffic is reverse-proxied byte-for-byte over a relay pipe (`http-local-proxy`), so shrinking text assets (JS/CSS/HTML) ~70-90% means far fewer bytes cross the slow link. Desktop browsers benefit the same way.

**Caching.** Static responses (SPA assets + `/data/*`) carry `Cache-Control: no-cache` (applied via a `tower_http::set_header::SetResponseHeaderLayer` on the two `ServeDir`s). The browser may store the asset but **must revalidate before use** — so after a self-rewrite/restart the client never serves a stale asset (no heuristic caching), and revalidation yields cheap `304`s (`ETag`/`Last-Modified` from `ServeDir`). `/api/*` is deliberately left without the header (dynamic data, not cached). Note: because the mobile loopback proxy listens on an OS-assigned port, WKWebView's URLCache is keyed by a port that changes across app/tab restarts — so cross-session cache hits depend on that port being stable (tracked as a separate, app-side follow-up).

## WebSocket Endpoint

`GET /api/ws?source=<string>`

`source` identifies the conversation: `web` (default, desktop copilot), `mobile` (mobile chat page), or `project-{id}` (a project's interactive chat — see below). The same endpoint serves all; ChatHub maintains one independent, persistent session per source.

One connection per source. The connection is upgraded by Axum's WS handler in `src/frontend/api/ws.rs`. The client sends one `ClientMessage`, receives a stream of `ServerEvent`s, then can send additional messages (cancel, approval) while events are in flight.

History for a source: `GET /api/<source>/messages` (or the legacy alias `/api/web/messages`).

### Project chats

A project's chat is a persistent session bound to source `project-{id}` and driven by the
`project-coordinator` agent. `POST /api/projects/{id}/session` provisions (or resumes) it,
seeding the session's `RunContext` with the project's working directory, fs-write grants, and
context — then returns `{ source, session_id }`. The frontend connects the WS to that source.
Because the session is **not** ephemeral and ChatHub reuses the existing session for a source,
the conversation persists and is resumed on reopen. Resetting it (`POST /api/sessions?source=project-{id}`)
recreates it with the coordinator agent, not `main` (the handler resolves agent + RunContext per
source via `provisioning_for_source`).

In the desktop copilot these appear as browser-style **tabs**: `General` (the `web` source, always
present, not closable) plus one tab per open project chat. The board's **Open Chat** button
dispatches a `project-chat-open` window event (`{source, label}`); the copilot adds/focuses the tab
and switches the live connection via `ChatSession._switchSource(source)`. Closing a project tab is
UI-only — the session persists and can be reopened from the board.

---

## ClientMessage Fields

| Field | Type | Description |
|---|---|---|
| `content` | `String` | The user's prompt text |
| `client` | `Option<String>` | Named LLM model override (or `"auto"`) |
| `attachments` | `Attachment[]` | Files uploaded beforehand via `POST /api/{source}/uploads`; each `{ path, name, mimetype?, filesize? }`. See [Attachments](#attachments) |

---

## ServerEvent Types

All events are JSON objects with a `"type"` tag (snake_case).

| type | Key fields | When emitted |
|---|---|---|
| `tool_start` | `tool_call_id`, `message_id`, `name`, `arguments`, `label_short`, `label_full`, `path?` | Tool call recorded, about to execute. `path` (optional) is the viewable file the call targets — rendered as a clickable link to the file viewer |
| `tool_done` | `tool_call_id`, `result` | Tool executed successfully |
| `tool_error` | `tool_call_id`, `error` | Tool execution failed |
| `agent_start` | `stack_id`, `parent_tool_call_id`, `agent_id`, `depth` | Sub-agent stack frame opened |
| `agent_done` | `stack_id` | Sub-agent stack frame closed |
| `thinking` | `message_id`, `content`, `input_tokens`, `output_tokens` | LLM produced text before tool calls |
| `pending_write` | `request_id`, `tool_call_id`, `path`, `old_content`, `new_content` | Approval required for write/command |
| `agent_question` | `request_id`, `tool_call_id`, `title`, `question`, `suggested_answers` | Sub-agent needs user clarification |
| `file_changed` | `path` | A tool wrote to a file |
| `open_file` | `path` | Agent-driven file open: the file viewer supports Markdown, source code, plain text, raster images (PNG/JPG/GIF/WebP/…), SVG, PDF, LaTeX (`.tex` / `.latex` — compiled to PDF automatically on the server), and HTML (`.html` / `.htm` — rendered live in an origin-isolated `<iframe srcdoc sandbox="allow-scripts">`, toggleable to source). For a LaTeX document, open the `.tex` source rather than a pre-built `.pdf`: only the `.tex` path is compiled, cached dependency-aware, and watched for dependency changes — a raw `.pdf` is served statically and stays stale when its sources change. Emitted by the `show_file_to_user` interface tool (SPA-only, injected in `ws.rs`; `path` normalised relative to the project root) |
| `done` | `message_id`, `stack_id`, `content`, `input_tokens`, `output_tokens` | Turn complete, final response |
| `truncated` | `output_tokens` | LLM hit token limit (`finish_reason=length`) |
| `error` | `message` | Fatal error (session handler failed) |
| `model_fallback` | `from`, `to`, `reason` | Active model swapped to fallback automatically |
| `llm_failed` | `tried`, `last_error` | All LLM fallback attempts exhausted |
| `approval_required` | `request_id`, `tool_call_id`, `tool_name`, `arguments` | Non-file tool call requires user approval |
| `approval_resolved` | `request_id`, `approved` | Approval resolved (any source); all clients update their UI |
| `user_message` | `message_id`, `content`, `attachments?` | A user message persisted to history, echoed to **every** client of the source (the sender included). Emitted at save time — at turn start, or at a round boundary for mid-turn injection — so the bubble lands in its correct position. Carries the typed text + structured attachments (never the `[SYSTEM INFO]` block) |
| `new_session` | `session_id` | Session was cleared (`/new`, `/clear`); clients reset their message list |
| `turn_running` | `running` | Sent to a client on (re)connect: whether a turn is in flight for its session, so a reloaded page restores the SEND→STOP button |
| `client_selected` | `client` | The pinned LLM client for the source changed (`/model` command or dropdown change). Clients update their dropdown/select to match — the backend is the single source of truth |

---

## Attachments

The desktop copilot and the mobile chat page let the user attach files to a message.
Files are added with the paperclip button, **drag & drop** onto the composer, or **paste**
(`Ctrl+V`) — all handled by `ChatSession._addFiles` / `_onDrop` / `_onPaste` in
`web/lib/chat-session.js`. Text is required: a message is never sent with attachments alone.

Flow:

1. On selection, each file is uploaded immediately to `POST /api/{source}/uploads`
   (multipart). The handler (`src/frontend/api/uploads.rs`) **streams** each part straight
   to `data/uploads/{session_id}/` (`field.chunk()` → file, never buffered in RAM) and the
   route disables the default body-size limit. It returns the saved `Attachment`s
   (`{ path, name, mimetype, filesize }`, `path` project-root-relative so `/data/…` serves it).
2. The pending attachments render as **chips above the textarea** (`renderAttachmentChips` in
   `copilot-render.js`, `removable: true`, with a spinner while the upload is in flight).
3. On send, the client posts `{ content, attachments }` over the WebSocket. `content` is the
   clean typed text; `attachments` are the uploaded objects.
4. Server-side, the message is persisted as a user `chat_history` row, and a `user_message`
   event (carrying its `message_id` + `attachments`) is broadcast **at save time** — at turn
   start, or at a round boundary for messages injected mid-turn (see *Telnet-style echo* below).
   The attachments are stored in the generic `metadata` JSON column. **The `[SYSTEM INFO]` block
   the LLM sees is generated on the fly** by the message builder from `metadata.attachments`
   (path-only — the agent reads the files with its own tools), so `content` and the UI stay
   clean. On reload, `build_items`
   surfaces `attachments` again so the chips reappear (clickable → file viewer).

The Telegram plugin reuses the same `MessageMetadata`/`Attachment` types for Document/Photo
uploads, so those render as chips too when viewing the `telegram` source — see
[plugins/telegram.md](plugins/telegram.md).

## Sending messages: telnet-style echo + mid-turn injection

The client does **not** render the user's message optimistically. `_send()` clears the
composer and posts `{ content, attachments }` over the WebSocket; the bubble appears only when
the backend persists the message and echoes it back as a `user_message` event (with its real
`message_id`). This "telnet" model makes the backend the single source of truth — no
client-generated id, no content-based dedup, and every client (the sender included) renders the
same echo. The `user_message` handler in `chat-session.js` therefore just pushes a bubble; the
old dedup against a local optimistic push is gone.

- **Sending while a turn is running is allowed.** The composer is no longer disabled on
  `_waiting`, and the send button is shown **alongside** the STOP button during a turn (Enter
  still sends on desktop). The message is queued and [injected into the running turn](session.md#mid-turn-injection)
  at its next round boundary; the bubble appears (via echo) at that moment — i.e. after the
  current round's tools, where the agent actually sees it. With a long-running tool the echo is
  delayed until the round ends.
- **Slash commands are the exception:** they are handled server-side and never persisted/echoed,
  so `_send()` renders them optimistically (`content.startsWith('/')`).
- A `/stop` before the next round boundary drops the queued message: no echo, no bubble.

## Slash Commands (Web Copilot)

The web copilot supports the following slash commands, intercepted server-side in
`src/frontend/api/ws.rs` before reaching the LLM:

| Command | Effect |
|---|---|---|
| `/new` | Create a new chat session (handled client-side, clears context) |
| `/help` | Show available commands |
| `/models` | List available LLM models ordered by priority (numbered `0..N`, index 0 is `auto`) |
| `/model <N\|name\|auto>` | Pin the model for this chat by index, name (substring allowed), or reset to `auto`. The web dropdown and the `/model` command share the same backend state (`ChatHub.selected_clients[source]`); changes from either mutate the SOT and broadcast `ClientSelected`, so all open tabs/mobile update in sync. Cleared on server restart |
| `/context` | Show last turn's token usage (`↑X tok · ↓Y tok`) |
| `/cost` | Show total spend for this session in USD (sync sub-agents included; async tasks excluded). `None` → "no cost recorded" when the provider does not report pricing |
| `/compact` | Force context compaction (bypasses the token threshold) |
| `/resettools` | Remove all activated tool groups (MCP servers + `config`) from the session |
| `/sethome` | Set web as the home source for background notifications |

Any other message starting with `/` is treated as an unknown command: the server
replies with an "Unknown command" notice followed by the help list, and never
forwards it to the LLM.

---

## Tool Call Status Lifecycle

Tool calls in `chat_llm_tools` progress through these states:

| DB status  | Meaning | Frontend `build_items` |
|------------|---------|------------------------|
| `running`  | Tool executing — no user action required | `status: 'error', error: 'Interrupted.'` (shown after page refresh/restart) |
| `pending`  | Blocked on explicit user input (approval gate `Require`, or `ask_user_clarification`) | `status: 'pending'` → shows approval/clarification form |
| `done`     | Completed successfully | `status: 'done'` |
| `failed`   | Terminated with error | `status: 'error'` |

On **page refresh** or **app restart**, the frontend detects pending/interrupted tools in history (`_hasPendingTools` flag set in `_loadHistory`). On `ws.onopen` it sends `{"type":"resume"}`, which triggers `resume_turn()` → `resume_pending_tools()`:
- `running` tools → re-executed through the approval gate
- `pending` tools (approval) → approval channel re-registered, `approval_required` re-emitted with new `request_id`
- `pending` tools (`ask_user_clarification`) → question re-asked via `dispatch_ask_user_clarification`
- `call_agent` tools → skipped here; child stack is resumed by `resume_turn()` cascade (see below)

`resume_turn()` also cascades upward when a sub-agent stack completes: it terminates the child, marks the parent's `call_agent` tool as `done`, then continues running the parent stack until the root emits `Done`.

---

## Approval Flow

1. Server emits `pending_write` with `request_id`, `path`, `old_content`, `new_content`.
2. Frontend shows a diff and prompts the user.
3. User approves → client sends: `{"type":"approve_write","request_id":<N>}`
4. User rejects → client sends: `{"type":"reject_write","request_id":<N>,"note":"<optional reason>"}`
5. Server receives the message via `handle_approval_msg()`, calls `handler.resolve_approval(request_id, decision)`.
6. The `oneshot` channel unblocks in `run_agent_turn`, execution proceeds or is skipped.

Before blocking on the approval channel, the server sets `status='pending'` in `chat_llm_tools` via `set_approval_pending()`. This is what distinguishes "waiting for user" from "tool was executing when the session was interrupted" (`running`).

## Clarification Flow

### Interactive sessions (web / Telegram)

1. An agent (root or sub-agent) calls `ask_user_clarification(title, question, suggested_answers?)`.
2. Server sets `status='pending'` for the tool call, registers it with `ClarificationManager` (so it also appears in the Agent Inbox), then sends `agent_question` with `request_id`, `title`, `question`, and optional `suggested_answers`.
3. Frontend shows the question and collects a free-text answer (suggested answers shown as clickable chips).
   The `question` body is rendered as **sanitised Markdown** via the shared `renderMarkdown()` (`web/lib/base.js`, marked + DOMPurify), so the agent may use `**bold**`, lists, `code`, etc. The `title` and the suggested-answer chips remain plain text.
4. Client sends: `{"type":"answer_question","request_id":<N>,"answer":"<user text>"}`
5. Server calls `handler.resolve_question(request_id, answer)`.
6. The answer is returned as the tool result and the agent continues.

On WS disconnect while waiting, `cancel_pending_questions()` drops all channels, causing the awaiting tool call to fail with an error. On reconnect, auto-resume re-asks the question.

### Background sessions (cron / tic)

1. The agent (root or sub-agent) calls `ask_user_clarification(title, question, suggested_answers?)`.
2. `dispatch_ask_user_clarification` sets `status='pending'` then registers with `ClarificationManager` (in-memory, in-process).
3. The entry appears in `GET /api/inbox` under `clarifications`.
4. User answers via the Agent Inbox page → `POST /api/inbox/clarifications/:request_id/resolve`.
5. The `oneshot` channel unblocks, answer is returned as tool result, agent continues.

Cancel message (abort current turn): `{"type":"cancel"}`

---

## Elicitation Flow (MCP server-initiated input)

An MCP server can request input *during* a tool call (e.g. a sudo password). Unlike
clarification, this is driven by the **server**, not an agent tool call, and supports
`accept`/`decline`/`cancel` with a masked input. See `docs/mcp.md` for the protocol.

1. The MCP server sends `elicitation/create`; the `mcp-client` read-loop bridges it to
   `ElicitationManager::register` (in-memory, no session binding).
2. The entry appears in `GET /api/inbox` under `elicitations` and as a global
   `elicitation_requested` event (so the Inbox badge / mobile push update).
3. The Agent Inbox renders a **"Secrets"** card (`_renderElicitationCard` in
   `web/lib/inbox-mixin.js`): a masked `<input type="password">` when `sensitive`, a
   plain input otherwise, or just Confirm/Reject when `is_confirmation`.
4. User confirms or rejects → `POST /api/inbox/elicitations/:request_id/resolve` with
   `{action, content?}`. On `accept` the value is packed as `{ [field_name]: value }`.
5. `ElicitationManager::resolve` unblocks the bridge, which writes the JSON-RPC reply to
   the server's stdin. The value is **never** logged, broadcast, or persisted.

---

## Lit Component Inventory

| File | Element | Responsibility |
|---|---|---|---|
| `web/lib/chat-session.js` | `ChatSession` (base) | Shared WS logic, message state, all approval/LLM event handling, **voice recording + transcription** (`_checkTranscribe`, `_startRecording`, `_stopRecording`, `_toggleRecording`, `_submitAudio`; renders a mic button when `/api/transcribe/has` returns 204), and textarea helpers (`_inputEl` hook, `_autoResize`). Subclasses override `_wsSource`, `_inputEl`, `_getInputContent`/`_clearInput` (defaults now driven by `_inputEl`), `_scrollToBottom`, `_onMessagePushed`. Effective source is `_source` (`_activeSource ?? _wsSource`); `_switchSource(source)` tears down the WS, reloads history, and reconnects to switch sessions live. **Attachments** (`_attachments` state, `_addFiles`/`_removeAttachment`/`_onDrop`/`_onPaste`): upload on selection, send with the next message — see [Attachments](#attachments) |
| `web/components/copilot.js` | `<app-copilot>` | Desktop copilot panel (`_wsSource='web'`); resize, composer input with model pill and auto-resize textarea. **Voice recording is inherited from `ChatSession`**; only the desktop-only Ctrl+Space push-to-talk shortcut (`_onKeydown`/`_onKeyup`) lives here. Browser-style tabs (`General` + project chats); listens for the `project-chat-open` window event to add/focus a project tab |
| `web/components/shared/chat-page.js` | `<chat-page>` | Mobile chat page; extends `ChatSession` with a mobile-specific layout. Composer mirrors the desktop copilot: a single unified box (`.chat-page-composer`) wrapping an auto-resizing textarea with a toolbar below — toolbar-left holds a native `<select>` model pill (`auto` + providers, opens the OS picker), toolbar-right holds the mic button (inherited recording) and the send/stop button. **Enter inserts a newline** (no Shift+Enter on mobile) — only the send button submits. The `source` prop (default `mobile`) re-points the chat: when it changes the component calls `_switchSource` to bind to a project's `project-{id}` session; it also honours `source` on the first connect (cold deep link from the native shell); inside a project the header shows the project `label` + a back button that emits `project-exit` |
| `web/components/shared/projects-page.js` | `<projects-page>` | Mobile project list. Loads `GET /api/projects`; tapping a project `POST`s `/api/projects/{id}/session` and emits a `project-open` event (`{source, label}`) so `<mobile-app>` re-points the chat |
| `web/components/copilot-render.js` | (helpers) | Renders messages, tool call blocks, diffs — shared by copilot and chat-page. Tool labels and diff headers render the call's `path` (when present) as a clickable link via `renderLabel`/`renderPath` → `openFile(path)` |
| `web/components/sidebar.js` | `<app-sidebar>` | Navigation sidebar; polls `/api/inbox` every 10 s for badge count |
| `web/components/topbar.js` | `<app-topbar>` | Top navigation bar |
| `web/components/editor.js` | (removed) | The legacy `<app-main>` editor panel was removed. Use `<file-viewer>` (see [File Viewer](#file-viewer)) instead |
| `web/components/shared/file-viewer-base.js` | `FileViewerBase` (base) | Shared file-viewer engine: fetch, kind detection (image/pdf/svg/latex/html/text/binary), markdown asset rewriting, LaTeX compile + error formatting, HTML preview⇄source toggle, live watcher, and `_renderBody`. Navigation-agnostic — driven by `_show(path)` / `_hide()`; subclasses supply the chrome |
| `web/components/file-viewer-page.js` | `<file-viewer-page>` | Desktop subclass of `FileViewerBase`. Self-routes off the hash (`#file_viewer?path=...`) via the `llm-page-change` + `hashchange` events; renders in the main workspace. Opened by `window.openFile(path)`. Preview only — editor + watcher tabs planned |
| `web/components/shared/file-viewer-mobile.js` | `<mobile-file-viewer-page>` | Mobile subclass of `FileViewerBase`. Prop-driven (`visible` / `path`, set by `<mobile-app>`'s hash router); full-screen with a mobile header + back button |
| `web/components/cron-jobs.js` | `<cron-jobs-page>` | Cron job management UI — columns: Title (+ one-shot badge), Cron, Agent, Last run, Next run, Enabled, Actions |
| `web/components/agent-inbox.js` | `<agent-inbox-page>` | Unified inbox for pending approvals, clarifications, and MCP elicitations ("Secrets"); polls `/api/inbox` every 8 s when open |
| `web/components/models-hub.js` | `<models-hub-page>` | Models hub — 3-card landing page (LLM / Transcription / Image Generation) with live model counts; internal navigation to sub-sections |
| `web/components/models-llm.js` | `<models-llm-section>` | LLM model management: drag-and-drop priority, catalog picker (OpenRouter/Ollama/…), add/edit/delete |
| `web/components/models-transcribe.js` | `<models-transcribe-section>` | Transcription model CRUD; filters providers by `supported_types.includes('transcribe')` |
| `web/components/models-image.js` | `<models-image-section>` | Image generation model CRUD; filters providers by `supported_types.includes('image_generate')` |
| `web/components/llm-providers.js` | `<llm-providers-page>` | LLM provider management |
| `web/components/agents.js` | `<agents-page>` | Agent discovery and configuration |
| `web/components/approval-groups.js` | `<approval-groups-page>` | Groups list: create, rename, duplicate, delete permission groups; navigates to rules view via `approval-navigate` event |
| `web/components/approval-rules.js` | `<approval-rules-page>` | Per-group rules view: rule matrix, override/low-priority panels, default action bar; shows when `approval-navigate` fires with a non-null group |
| `web/components/llm-requests.js` | `<llm-requests-page>` | LLM request log viewer with filterable table, pagination, clickable rows that drill into detail view (`#llm-requests/<id>`) |
| `web/components/llm-request-detail.js` | `<llm-request-detail>` | LLM request detail: stat bar, system prompt, conversation messages, tool definitions, response — with collapsible sections |
| `web/components/session-detail.js` | `<session-detail-page>` | Read-only debug view of any session. Navigate to `#session/{id}` to load. Shows full message tree with tool calls, sub-agent frames, synthetic user messages, and collapsible reasoning blocks. Not linked from the sidebar — accessed by typing the hash directly. |

All components extend `LightElement` from `web/lib/base.js` (Lit-based).

### Markdown rendering & link behavior

`renderMarkdown(text)` (in `web/lib/base.js`) is the single entry point for rendering assistant/file markdown: it runs `marked.parse` then `DOMPurify.sanitize`. **External links** (http/https whose origin differs from the page) get `target="_blank" rel="noopener noreferrer"` via a DOMPurify `uponSanitizeElement` hook, so they open in a new tab instead of navigating away from the app. Relative paths, hash anchors (e.g. the app's `#file_viewer?...` routing), and non-http schemes (`mailto:`, `tel:`) are left untouched, preserving in-app navigation and native handlers.

### Approval Rules navigation protocol

`<approval-groups-page>` and `<approval-rules-page>` communicate via a custom DOM event instead of shared state:

| Event | Detail | Who fires | Who handles |
| --- | --- | --- | --- |
| `approval-navigate` | `{ group: ToolPermissionGroup \| null }` | groups page (navigate to rules) | rules page (show with group) |
| `approval-navigate` | `{ group: null }` | rules page (`← Back` button) | groups page (show again) |

Hash persistence: `window.location.hash` is set to `#approval/{group_id}` when navigating to a rules view. On page load, the groups page reads the hash and re-fires the event so deep-links and page reloads restore the correct sub-view.

### Agent Inbox page

Approval cards have a yellow left border; clarification cards have a blue left border. Clarification cards show suggested-answer chips (click pre-populates the input) and a free-text input — submit with Enter or the Send button.

Approval cards have Approve / Reject buttons and a timed bypass menu (15 min / 1 hour / Session) scoped to the tool's category or MCP server. The bypass scope auto-detects from the pending approval's metadata: `tool_category` for category-scoped, `mcp_server` for MCP server-scoped, otherwise `all`. The REST API also supports `bypass_secs` and `bypass_scope` fields in the resolve body.

---

## Mobile App & Native Shell

The mobile UI (`web/mobile.html` → `<mobile-app>`) is the same SPA the desktop uses, laid out for touch. It is also what the **native iOS shell** renders in a WKWebView over the relay (see [relay/pipe.md](relay/pipe.md)).

### Hash routing

`<mobile-app>` drives its active section from the URL hash — the same model as the desktop sidebar (`web/components/sidebar.js`), so the URL is always the source of truth. `_readHash()` / `_applyHash()` react to `hashchange` and `popstate`; `_nav(section)` sets `location.hash`. This gives deep links, working back/refresh, and — for the native shell — a single observable signal for menu sync.

| Hash | Section | Notes |
|---|---|---|
| `#inbox` | Inbox | Pending approvals + clarifications |
| `#projects` | Projects | Project list |
| `#chat` | Chat | Main mobile session (source `mobile`) |
| `#chat/project-<id>` | Chat | Bound to a project's session (source `project-<id>`). The header label resolves from `/api/projects` (cached in `<mobile-app>`), so a cold deep link still shows the name. Back/refresh keep the user inside the project |
| `#file_viewer?path=<enc>` | File viewer | Full-screen file preview, reached from content via `openFile(path)` (e.g. a clickable tool path) — **not** a bottom-nav tab. The back button returns to the previous section via history |
| `#notifications`, `#settings` | (coming soon) | Placeholder |

`<chat-page>` (`web/components/shared/chat-page.js`) honours its `source` prop on the **first** connect (via `_activeSource`), so a cold `#chat/project-<id>` deep link connects straight to that session instead of opening the `mobile` session and switching a tick later.

`_applyHash()` **skips** the `skaldNav` notify for the `file_viewer` section: the viewer is a transient overlay reached from content (not a tab), so opening a file from the chat must not deselect the native "chat" tab.

### Native shell mode (`?native=true`)

When loaded with `?native=true`, `<mobile-app>` sets a `data-native` attribute and **hides its HTML bottom nav** — the native tab bar is the chrome. `web/css/mobile.css` drops the web-side safe-area insets under `mobile-app[data-native]` (the native chrome owns the status-bar + home-indicator insets). Everything else is identical to the mobile-browser path.

### Native ↔ Web contract

The native tab bar and the web router stay in sync over one mechanism each direction:

| Direction | Mechanism | Payload / call |
|---|---|---|
| Native → Web | set the hash | `webView.evaluateJavaScript("location.hash='#projects'")` — the web `hashchange` handler switches section. A project deep link works too (`#chat/project-<id>`). Same code path the browser uses. |
| Web → Native | `WKScriptMessageHandler` named **`skaldNav`** | on every section change `<mobile-app>` calls `window.webkit.messageHandlers.skaldNav.postMessage({ section, project })`, where `project` is `null` or `'project-<id>'`. The shell updates its tab highlight. No-op when the handler is absent (mobile browser). |

The `skaldNav` bridge is the reliable sync: relying solely on observing the WKWebView URL is fragile, because same-document (hash-only) navigations don't reliably fire `WKNavigationDelegate` callbacks across iOS versions.

---

## File-Change Watcher (live reload)

`<file-viewer-page>` automatically reloads when the file it is showing changes
on disk — whether the change comes from a Skald tool, an external editor
(VSCode, vim, …), or any other process. The mechanism is a dedicated
WebSocket.

### Endpoint

`GET /api/file/watch` — upgrades to a long-lived WebSocket. Client → server
commands:

| Command | Effect |
|---|---|
| `{"op":"subscribe","path":"docs/index.md"}` | Start watching `path` (relative or absolute — same path model as `GET /api/file`) |
| `{"op":"unsubscribe","path":"docs/index.md"}` | Stop watching `path` |

Server → client messages:

| Message | Meaning |
|---|---|
| `{"type":"subscribed","path":"..."}` | Ack — watch installed successfully |
| `{"type":"unsubscribed","path":"..."}` | Ack — watch removed |
| `{"type":"changed","path":"..."}` | The file at `path` changed on disk (any event kind: create/modify/remove) |
| `{"type":"error","path":"...","error":"..."}` | Watch install failed (e.g. path does not exist, permission denied) |
| `{"type":"error","error":"..."}` | Malformed client message or unknown op (no `path`) |

The `path` field always round-trips the original user-supplied string, so the
client can match it against the path it asked to watch.

### Implementation notes

- **Backend** (`src/frontend/api/file_watch.rs`): one `notify::RecommendedWatcher`
  per watched file per connection (one watcher per file — for a LaTeX source
  that means one per dependency, see below). On disconnect every watcher is
  dropped and OS resources are released automatically. Path resolution uses
  `fs_tools::resolve` (same as `GET /api/file`), so absolute paths are used
  as-is and relative paths resolve against Skald's process CWD.
- **LaTeX dependency watching**: when subscribing to a `.tex` / `.latex`
  source, the server expands the single path into the full dependency set
  discovered via `LatexCompiler::watch_paths_for()` (which reads the cached
  `.fls` recorder file — see [LaTeX](#latex) below). One OS watcher is
  installed per dependency; any change to any of them is forwarded to the
  client as a `changed` event for the original `.tex` path. The dependency
  set is re-synced on every change event (watchers dropped and re-installed
  with the fresh `.fls`), so newly-added `\input`s are picked up
  automatically. On the very first subscribe, when no compile has happened
  yet, only the main `.tex` itself is watched; once the viewer's first
  compile writes the `.fls`, the next change event triggers the re-sync.
- **Frontend** (`web/lib/file-watcher.js`): singleton `fileWatcher` with a
  single persistent connection, ref-counting per path (multiple consumers of
  the same path share one OS watcher and one subscribe message),
  auto-reconnect on close with 2 s backoff, and automatic re-subscribe of all
  active paths on reconnect. Consumers call `fileWatcher.watch(path, cb)` and
  get back an `unsub()` function.
- **`<file-viewer-page>`** subscribes when it opens (or when the path changes
  via hash navigation) and unsubscribes when it closes or navigates away.
  Change notifications are debounced (300 ms) and trigger a **silent reload**
  (no spinner, no flicker — image previews swap the object URL only after the
  new blob is ready, text previews replace the content atomically).
- **Cross-platform:** uses `notify`'s recommended backend (FSEvents on macOS,
  inotify on Linux, ReadDirectoryChangesW on Windows).
- **Dirty-buffer conflict handling** is not implemented yet — there is no
  editor tab yet. When the CodeMirror editor lands (roadmap), a changed event
  arriving while the buffer has unsaved edits will show an "Overwrite / Discard
  / Ignore" banner instead of auto-reloading.

---

## File Viewer

`<file-viewer-page>` is a top-level page that previews files from disk in the
main workspace, so users (and agents, in future phases) can read
markdown/code/images without leaving the UI. It is registered in
`web/app.js` and lives once in the DOM at `index.html` (default
`display:none`, shown via the standard page router — see below).

The fetch / kind-detection / markdown-asset / LaTeX-compile / live-watch logic
and `_renderBody` live in `FileViewerBase` (`web/components/shared/file-viewer-base.js`),
shared with the mobile viewer. The base is navigation-agnostic — driven only by
`_show(path)` / `_hide()`; each subclass supplies its own chrome and decides when
to call them: the desktop `<file-viewer-page>` from the hash, the mobile
`<mobile-file-viewer-page>` from props (see [Mobile](#mobile) below).

### Opening files

The global helper `openFile(path)` is the single entry point — defined in
`web/lib/open-file.js`:

```js
openFile('data/memory/index.md');
// or
window.openFile('docs/frontend.md');
```

`openFile(path)` sets `location.hash` to `#file_viewer?path=<enc>`, which the
sidebar hash router (`web/components/sidebar.js:_pageFromHash`) resolves to
the `file_viewer` page. This means:

- **Back/forward browser navigation** works naturally.
- **Deep-linkable** — the URL can be shared or bookmarked.
- **The chat and everything else stay usable** while the file is open
  (clicking any other sidebar entry just changes the hash and the page
  switches out).

Both surfaces (`openFile(...)` and setting the hash directly) are equivalent.
Components that want to open a file should call `openFile(...)` so the URL
format lives in one place.

**Callers of `openFile`:**

- **Tool-call cards & write diffs** in the copilot/chat transcript. When a tool
  call targets a single viewable file, the backend reports the path in
  `ServerEvent::ToolStart.path` (via `Tool::target_path` — see
  [tools.md](tools.md#clickable-target-path)); `copilot-render.js` renders it as
  a clickable link. Falls back gracefully: tools without a `path` render the
  plain label, unsupported file types show the viewer's "preview not available"
  state, and unreadable paths show its error state.
- **The `show_file_to_user` tool**, via the `OpenFile` WebSocket event
  (`open_file`, handled in `chat-session.js`). It is an `InterfaceTool` injected
  only for SPA clients (`web` + `mobile`) in `src/frontend/api/ws.rs`, so the
  assistant can proactively open a file — see
  [tools.md](tools.md#registration-pattern). Every kind — HTML included — routes
  through `openFile` and renders inside the viewer.

### Routing

`file_viewer` is registered in the sidebar's segment whitelist
(`sidebar.js:_pageFromHash`) but has **no sidebar menu entry** — like
`#session/{id}`, it's an "accessory" page reachable only via link or
`openFile`. The page follows the standard pattern: it listens for
`llm-page-change` (shows/hides itself) and `hashchange` (re-reads the path
from the URL when navigating between files while staying on the page).

Path resolution is delegated to the backend via `GET /api/file?path=<enc>`
(`src/frontend/api/files.rs`), which calls `fs_tools::resolve`:

- **Relative paths** resolve against Skald's process CWD (the data root).
- **Absolute paths** are used as-is — required when opening files that live
  outside the data root, e.g. inside a project's custom working directory.

`get_file` serves **raw bytes** with a `Content-Type` derived from the extension
(`content_type_for`), not `read_to_string` — so binary formats (images, PDFs)
work. The viewer reads text kinds via `res.text()` and binary kinds via
`res.blob()` → object URL.

A query parameter `?force_download=true` makes the handler add
`Content-Disposition: attachment` so the browser **saves** the file instead of
rendering it inline. The attachment filename is the path's basename — or, when
combined with `?compile-latex=true` on a `.tex` source, `<stem>.pdf`. The
filename is sanitised to visible ASCII (header-value constraint). This backs the
header's **download button** (see below).

A query parameter `?compile-latex=true` switches the handler into LaTeX mode
when `path` is a `.tex` / `.latex` file: instead of returning the raw source,
the server runs `latexmk -xelatex` (via `LatexCompiler` in
`src/core/latex/`) and returns the resulting PDF (`application/pdf`). Compiled
PDFs are cached under `<tmp>/skald-latex/` in a **dependency-aware** way:

- `<path-hash>.fls` — the `.fls` recorder file from the last compile of that
  source (keyed by SHA-256 of the source's absolute path). Lists every file TeX
  actually read.
- `<deps-hash>.pdf` — the compiled PDF (keyed by SHA-256 of every
  user-controlled input's contents, sorted by path).

On each request the compiler first re-derives `deps-hash` from the cached
`.fls` and serves the matching PDF without invoking `latexmk` if it exists.
This means a change to any `\input`'ed fragment, custom `.sty` / `.cls`
package, `.bib`, or `\includegraphics` target invalidates the cache correctly
even when the main `.tex` file is unchanged. Inputs under system TeX
distribution paths (`/usr/local/texlive`, `/Library/TeX`, …) and TeX
auxiliary outputs (`.aux`, `.log`, `.fls`, `.synctex.gz`, …) are filtered out
of the dependency set — they only change on a distro upgrade, which is rare
and easy to handle by clearing the cache. Failures produce a non-2xx response
with the textual `latexmk` log in the body:

| Outcome | Status | Body |
|---|---|---|
| Compiled (or cache hit) | `200` | PDF bytes (`application/pdf`) |
| Compilation error | `422` | `latexmk` log (`text/plain`) |
| `latexmk` not installed | `501` | Explanatory message |
| Compile timeout (> 30s) | `504` | Explanatory message |

### Header chrome

Both chromes render a header with the file name and a **download button**
(`bi-download`, right-aligned). The button calls `_download()` in
`FileViewerBase`, which builds `/api/file?path=…&force_download=true` (adding
`compile-latex=true` for LaTeX kinds, so a `.tex` always downloads its compiled
PDF) and clicks a transient `<a download>` — the server's `Content-Disposition`
supplies the saved filename.

The file name uses **tail-truncation**: when a path is too long the ellipsis is
placed at the *start* (`…/dir/report.tex`) so the filename stays visible, via
`direction: rtl; text-align: left` with the path wrapped in `<bdi>` (to keep its
characters left-to-right). The full path remains on the `title` attribute. The
desktop chrome shows the full path; the mobile chrome shows only the basename.

### Supported kinds

| Kind | Extensions | Rendering |
|---|---|---|
| **Markdown** | `.md`, `.markdown` | `renderMarkdown()` (marked + DOMPurify) via `unsafeHTML`. Relative `<img>` sources are rewritten (`rewriteMarkdownAssets`) to `/api/file?path=<dir-of-md + src>` so images referenced relative to the file load from disk; external/`data:`/root-relative URLs are left untouched |
| **Image** | `.png .jpg .jpeg .gif .webp .bmp .ico .avif` | `<img>` loaded as a Blob from `/api/file` (object URL) |
| **SVG** | `.svg` | `<iframe sandbox="allow-same-origin">` to a Blob object URL. Rendered in a sandboxed iframe (not `<img>`): the SVG root fills the iframe viewport so viewBox-only files scale correctly, and `allow-scripts` is withheld so any embedded `<script>` cannot execute. `allow-same-origin` is required for the iframe to read the blob: URL |
| **PDF** | `.pdf` | `<iframe>` to a Blob object URL — the browser's native PDF viewer |
| **HTML** | `.html`, `.htm` | Fetched as text, then rendered live in `<iframe srcdoc sandbox="allow-scripts allow-forms allow-modals allow-popups">`. `srcdoc` (not a blob `src`) gives the frame a **unique opaque origin**, so its JS runs but is fully isolated from the app origin — it cannot read cookies/localStorage or reach `/api/*`. `allow-same-origin` is deliberately withheld: combined with `allow-scripts` it would let the frame strip its own sandbox. A header toggle (`_renderModeToggle`) flips between the live preview and the raw source (`<pre><code>`). Limitation: relative asset paths inside the HTML don't resolve (opaque origin has no disk base) — self-contained HTML and absolute/CDN URLs work |
| **LaTeX** | `.tex`, `.latex` | On open, the viewer first requests `?compile-latex=true`; on `200` it renders the resulting PDF in an `<iframe>` (same path as a native `.pdf`). On any non-2xx response (compilation error, missing `latexmk`, timeout) it falls back to showing the raw source as a `<pre><code>` block, with the extracted compilation error in a collapsible banner — `formatLatexError` distils the full latexmk log down to the actionable `path:line: …` / `! …` lines plus context (the leading banner + package preamble are dropped), so the shown text is what a user pastes into an agent. The file watcher installs one OS watcher per dependency discovered via the `.fls` recorder file (`\input`'ed fragments, custom `.sty` / `.cls`, `.bib`, images, etc.) — so saving any of them triggers an automatic recompile. Requires `latexmk` with `xelatex` on the server's `PATH` (e.g. MacTeX / TeX Live). See the [LaTeX compile & cache](#latex-compile--cache) section below for the full dependency-aware algorithm. |
| **Text/code** | `.txt .rs .js .ts .py .json .yml .toml .sh .sql .go .css .vue ...` (see `TEXT_EXTS` in the source) | `<pre><code>` block, monospace, horizontal scroll |
| **Binary/unknown** | anything else | Placeholder: "Preview not available for this file type." |

### LaTeX compile & cache

The `.tex` kind is special: it is the only kind where the server produces a
derived artefact (PDF) on demand rather than serving the raw file. The
`LatexCompiler` in `src/core/latex/` orchestrates `latexmk -xelatex` and
maintains a dependency-aware cache so:

- saving any `\input`'ed fragment, custom `.sty` / `.cls`, `.bib`, or
  `\includegraphics` target invalidates the cache correctly (even when the
  main `.tex` is unchanged);
- unchanged inputs are served without recompiling.

Two artefacts live under `<tmp>/skald-latex/`:

| Artefact          | Key                                            | Purpose                                          |
|-------------------|------------------------------------------------|--------------------------------------------------|
| `<path-hash>.fls` | SHA-256 of the `.tex` absolute path            | Last-known input list for that source            |
| `<deps-hash>.pdf` | SHA-256 of every user-controlled input's bytes | The compiled PDF for that exact content state    |

Per request:

1. Read `<path-hash>.fls` (the recorder file produced by the last compile).
   Missing → fresh compile.
2. Filter out system TeX paths (`/usr/local/texlive`, `/Library/TeX`, …) and
   auxiliary artefacts (`.aux`, `.log`, `.fls`, `.synctex.gz`, …).
3. Hash every remaining input's contents, derive `<deps-hash>`.
4. If `<deps-hash>.pdf` exists → cache hit, serve it.
5. Otherwise → run `latexmk` in a per-compile scratch directory with
   `-output-directory=<tmp>/skald-latex/<path-key>-<pid>-<ns>/`, capture the
   new `.fls`, overwrite the `<path-hash>.fls` sidecar, save the PDF as
   `<deps-hash>.pdf`, serve.

The file watcher (`/api/file/watch`) re-syncs its OS watchers on every change
event for a `.tex` source — dropping the per-dependency watchers and
re-installing them with the fresh `.fls`, so newly-added `\input`s are picked
up automatically. On the very first subscribe (no `.fls` yet), only the main
`.tex` is watched; once the first compile writes the sidecar, the next change
event triggers the re-sync.

Limitations: system TeX distribution files are excluded from the dependency
hash (they only change on a distro upgrade — clear the cache directory to
force a rebuild); shell-escape inputs (`\input{|"command"}`) are not tracked.

### Mobile

The mobile app renders its own `<mobile-file-viewer-page>` (`web/components/shared/file-viewer-mobile.js`), a thin subclass of `FileViewerBase` that shares all of the desktop viewer's fetch/render/watch logic and only swaps the chrome (full-screen page, mobile header + back button). `<mobile-app>`'s hash router (see [Mobile App & Native Shell](#mobile-app--native-shell)) routes `#file_viewer?path=...` to a non-tab `file_viewer` section and binds the component's `visible` / `path` props; the same `openFile(path)` used in the desktop transcript (a clickable tool path) therefore works unchanged on mobile. The back button returns to the previous section via history, and `_applyHash` skips the `skaldNav` notify so the native tab highlight stays put.

### Roadmap

The page is the foundation for several follow-up phases (tracked separately):

1. **Tab Editor (CodeMirror 6)** — second tab in the page with syntax-highlighted
   editable buffer; saves via `PUT /api/file`. Bypasses the approval gate (user is
   editing manually, not via an agent tool). Will introduce the "Overwrite /
   Discard / Ignore" banner for dirty-buffer conflicts.
2. **Agent-driven opening** — new `ServerEvent::OpenFile { path }` emitted by a
   `show_file_to_user(path)` interface tool; `chat-session.js` sets the hash from
   the WS payload, so both manual and agent-driven paths funnel into the same
   `<file-viewer-page>`.
3. **More media** — video (`<video>`), audio (`<audio>`), PDF (`<iframe>`).

### Files

| File | Purpose |
|---|---|
| `web/lib/open-file.js` | Defines and registers `window.openFile`; sets `location.hash` |
| `web/components/shared/file-viewer-base.js` | `FileViewerBase` — shared engine: fetch, kind detection, markdown assets, LaTeX compile, watcher, `_renderBody`. Driven by `_show`/`_hide` |
| `web/components/file-viewer-page.js` | `<file-viewer-page>` desktop subclass — hash routing (`llm-page-change` + `hashchange`) + desktop chrome |
| `web/components/shared/file-viewer-mobile.js` | `<mobile-file-viewer-page>` mobile subclass — prop-driven (`visible`/`path`) + mobile chrome (full-screen, back button) |
| `web/lib/file-watcher.js` | Singleton client for `/api/file/watch` — ref-counting, auto-reconnect, re-subscribe |
| `web/css/file-viewer.css` | Page + content styling (markdown, code, image, LaTeX compile-error banner, state). Loaded by both `index.html` and `mobile.html` |
| `src/frontend/api/file_watch.rs` | `/api/file/watch` WS handler — `notify::RecommendedWatcher` per watched file (one per LaTeX dependency for `.tex` sources) |
| `src/core/latex/mod.rs`, `src/core/latex/compiler.rs` | `LatexCompiler` — `latexmk -xelatex` invocation, SHA-256 content cache, error mapping. Called by `get_file` when `?compile-latex=true` |

---

## Adding a New ServerEvent

1. Add the variant to `ServerEvent` enum in `src/core/events.rs`.
2. Add the `type_name()` match arm in `src/core/events.rs`.
3. Emit it at the appropriate point (session handler, ChatHub, or ws.rs).
4. Handle it in `web/lib/chat-session.js` `_handleServerMsg()` — all clients inherit the handler automatically.
5. Update the ServerEvent Types table above.

---

## Debug Mode

A persistent flag stored in the `config` DB table under key `DEBUG_MODE` (`"true"` / `"false"`). The API is in `src/frontend/api/dev.rs`.

| Method | Path | Body | Response |
| --- | --- | --- | --- |
| `GET` | `/api/dev/debug_mode` | — | `{ "enabled": bool }` |
| `POST` / `PUT` | `/api/dev/debug_mode` | `{ "enabled": bool }` | `{ "enabled": bool }` |
| `GET` | `/api/dev/llm-requests` | query: `?page=1&per_page=20&agent_id=&source=&from=&to=` | `{ items: LlmRequest[], total: int }` |
| `GET` | `/api/dev/llm-requests/{id}` | — | Full request/response payload with system prompt, messages, tool definitions, and response |

The frontend reads this flag at startup and uses it to show or hide sections in the sidebar menu that are otherwise invisible in production.

---

## When to Update This File

- A `ServerEvent` variant is added, removed, or its fields change
- `ClientMessage` gains or loses a field
- A new Lit component is added
- The approval message format changes
- The debug-mode endpoint changes
- The file viewer gains a new phase (editor tab, agent-driven opening) or a new supported kind
- The `/api/file/watch` protocol (commands, messages) changes