# Web UI: how it works

This document explains the built-in browser UI served by the gateway.

Source file:

- `src/gateway/web-ui.ts`

---

## Overview

The Web UI is a single HTML page returned by `GET /` (when enabled).

It is intentionally simple:

- plain HTML/CSS/JS (no framework)
- sends requests to `/v1/chat/stream`
- renders streamed assistant text in real time
- stores and reuses `conversationId` in `localStorage`

---

## Availability

The UI route is controlled by `GATEWAY_ENABLE_WEB_UI`:

- `true` (default): `GET /` returns UI
- `false`: `GET /` returns `404` with `{ "error": "Web UI disabled" }`

If `GATEWAY_AUTH_TOKEN` is enabled, `GET /` also requires an `Authorization` header, because auth is global in the gateway.

---

## UI sections

### 1) Session/header card

- **Conversation ID input** (`#conversationId`)
  - if empty, server auto-creates one during first message
  - persisted locally under `pi_gateway_conversation_id`
- **Auth token input** (`#token`)
  - optional bearer token included in API requests from the page
  - this affects `fetch` calls only; it does not add auth headers to the initial page load

### 2) Messages card

- container `#messages`
- each message is appended as a `.msg.user` or `.msg.assistant` block
- text is rendered as plain text (`textContent`), not Markdown/HTML

### 3) Composer card

- textarea `#message`
- status text `#status`
- buttons:
  - `Send`
  - `New session`

---

## Local state

The page keeps only minimal browser-side state:

- `conversationId` in input + local storage
- rendered message list in DOM
- current request state via button disabled/enabled

Storage key:

- `pi_gateway_conversation_id`

On load, if this key exists, it pre-fills the conversation input.

---

## Send flow

When user presses **Send** (or Cmd/Ctrl + Enter):

1. Trim textarea value; ignore empty input.
2. Disable `Send` and `New session` buttons.
3. Append user message bubble.
4. Append empty assistant bubble.
5. Build payload:
   - required: `message`
   - optional: `conversationId` (if input non-empty)
6. POST to `/v1/chat/stream` with JSON body.
7. Parse SSE stream incrementally.
8. Update assistant bubble and status based on events.
9. Re-enable buttons when request finishes/fails.

---

## SSE event handling in UI

Handled events:

- `assistant_text_delta`
  - appends `data.delta` to assistant message bubble
- `done`
  - reads `data.conversationId`
  - updates conversation input
  - writes `pi_gateway_conversation_id`
  - status becomes `Done • conversation <id>`
- `error`
  - status becomes error text
  - writes fallback error into assistant bubble if empty

Other event types are currently ignored by the UI.

---

## New session button behavior

Clicking **New session**:

- does nothing if a request is currently streaming (`Send` disabled)
- clears conversation ID input
- removes `pi_gateway_conversation_id` from local storage
- clears rendered message list
- sets status to `New session ready`
- focuses the message textarea

This starts a fresh client-side chat thread. The next send will create a new conversation on the server.

---

## Keyboard shortcut

In the message textarea:

- `Cmd + Enter` (macOS) or `Ctrl + Enter` (Windows/Linux)
- triggers the same send flow as the Send button

---

## Limitations

Current UI is intentionally minimal:

- no server-side message history loading
- no cancel/abort button for in-flight response
- no rendering for tool events/thinking events
- no Markdown formatting
- no multi-conversation sidebar

It is best used as a lightweight test/debug interface.

---

## Related API docs

For full gateway/API details, see:

- `docs/gateway.md`