# Web client The Svelte client in [`web/`](../web/src/App.svelte) uses the daemon through the local web server. It shares session behavior with the [terminal client](tui.md). ## Server and authentication [`albedo web`](../cli/internal/cli/web.go) starts or connects to the web server. [`webui.Server`](../cli/internal/webui/server.go) serves the built client and uses a launch key to sign a browser in with an HTTP-only, same-site cookie. `--new-link` rotates the key. The server checks the request host and checks the origin of API requests. The browser calls `/api`. The server removes that prefix, strips browser credentials and origin headers, and adds the daemon bearer token before forwarding. The daemon token is not sent to the browser. A page script with the web cookie can still make API requests, so the server's content security policy and the client's handling of untrusted transcript content are security boundaries. ## Streams and artifacts [`stream.ts`](../web/src/lib/stream.ts) manages session event follows. The client also renders artifacts, which have a separate `/frame/` path in [`Server.ServeHTTP`](../cli/internal/webui/server.go). The frame handler applies sandbox headers and forwards artifact requests separately from authenticated `/api` requests. See [artifacts](artifacts.md) for their execution boundary. [`DisplayView.svelte`](../web/src/lib/views/DisplayView.svelte), [`DisplayNode.svelte`](../web/src/lib/nodes/DisplayNode.svelte), and [`display.ts`](../web/src/lib/display.ts) render `display` trace activities from `display(content, title=, description=)` as unified diffs, highlighted code, or Markdown, opening a window on the canvas or in the zen desk / phone dock when a live turn produces one (`Transcript.displayed`, `Board.displayShown`). ## Unread chats [`notifications.svelte.ts`](../web/src/lib/notifications.svelte.ts) marks pinned sessions and chats on open boards unread when a turn ends, a blocking reason changes, or agent mail arrives. One shared session-summary stream covers roots and child agents, including chats on inactive boards. Records for chats on all open boards load independently of their windows. Initial loads do not mark old answers unread. Dots appear beside chat titles and on their containing tabs and board tabs. A rim light plays once unless the chat's board is visible or the chat is open full-screen or on a phone. The browser window need not have keyboard focus. Hidden chats in a visible board stay quiet too. Leaving the board does not replay a skipped flash. Reduced-motion mode keeps the dots without the rim light. Selecting a chat in the focused browser window clears only that session. Returning to the browser does not clear other chats. The browser title and favicon count the same unread sessions. These cues need no system-notification permission and reset on page reload. ## Chat attachments The chat composer attaches images and other files from its picker, from paste, and from a drop anywhere on the chat. [`main.ts`](../web/src/main.ts) stops a file drop outside a chat from navigating the page. Images appear as tiles in the editor. Other files appear as removable cards with a name and size. [`Composer.svelte`](../web/src/lib/chat/Composer.svelte) and [`Chat.svelte`](../web/src/lib/chat/Chat.svelte) own this presentation. On phones, an empty unfocused composer shows one row with the attachment button, message field, and Send or Stop controls. Focusing the field expands it to show model and reasoning controls. Drafts, attachments, pending reads, notices, and edits keep it expanded. Moving focus into its toolbar or picker does not collapse it. Desktop composers keep their existing layout. The composer uses the user-message bubble color instead of a persistent outline. Model, reasoning, and context controls use text and icons without pill backgrounds. [`attachments.ts`](../web/src/lib/chat/attachments.ts) reads files and checks the browser limits in `attachmentProblem`: ten images, ten other files, and 20 MiB of decoded bytes for both kinds together. These limits keep a send inside what the daemon accepts. They are not authorization. The daemon checks its own bounds and can still reject a send. See [input admission](../docs/http-sessions.md#input-admission-and-outcomes). [`Draft`](../web/src/lib/chat/drafts.ts) owns the attachments of an unsent message, by session, so they survive a board switch. It reads files one at a time and reports the result even if the composer unmounted meanwhile. `Draft.reading` and `Draft.problem` block Send while a read is pending or the selection is over a limit. The send handler checks again before it clears the draft. Do not clear a draft before that check, and do not drop files to fit a limit. Let the user remove or split them. Moving a draft into a canvas note moves its prose. Image tiles and file cards stay in the chat. Attachment bytes live only in memory. The draft text is saved to `localStorage` without its `[Image #n]` markers, and a page reload loses its images and files. Other text is kept as typed. Literal text that looks like a file label, such as `[File #1: notes.txt]`, stays in the draft and the message. Generic files require a local workspace, because the daemon saves them on its own host and gives the model their path. For a remote-workspace session, the composer accepts images and refuses other files. The daemon rejects them too. [`Transcript`](../web/src/lib/transcript.svelte.ts) keeps a pending send's payloads in memory. A reload drops that copy, including a failed send that was waiting for retry. Retry resends the same input ID with the same text and attachments. When a stop cancels queued sends, `Transcript.take` returns them and `Draft.restore` appends their text and attachments to the draft. A restored selection can exceed the limits, so Send stays blocked until the user removes some. A committed message shows file cards only from the history entry's `files` metadata, never from its text. Images use the entry's image references. Saved bytes can expire while the history remains. See [saved pastes and uploads](kernel-state.md#saved-pastes-and-uploads) and the [uploaded-file rules](contributing.md#handle-uploaded-files). [`QueuePanel.svelte`](../web/src/lib/chat/QueuePanel.svelte) sits above the composer while anything waits in the session's [inbox](inbox.md). It lists what waits, in the order the session will read it, and drops, reorders, or clears it through the queue routes. `Transcript.queue` holds that list and reads it again when the stream says the queue changed. A send the inbox holds leaves the transcript's pending rows and shows only in the queue until it is committed. [`WorkSteps.svelte`](../web/src/lib/chat/WorkSteps.svelte) also renders images from tool results, including `show_image`, using their history image references. These previews remain visible when tool details collapse. Selecting an uploaded image or tool preview opens the shared [`ImageGallery.svelte`](../web/src/lib/chat/ImageGallery.svelte) full-screen viewer, modelled on the Bluesky web client's lightbox. It browses the existing image strip: one message for uploads, or one tool-work stretch for tool images. The side buttons, Left/Right arrow keys, and a sideways drag page through it without wrapping. Double-click or double-tap, a pinch, or Ctrl-wheel zooms, and a zoomed image pans. A vertical swipe, a click beside the image, Escape, or Close dismisses it and returns focus to the selected preview. A tap toggles the controls. The options menu opens the original in a new tab, downloads it, or shares or copies its link. Modified clicks keep the original image URL available in a new tab. [`lightbox.ts`](../web/src/lib/chat/lightbox.ts) holds the gesture and spring state, a port of the `@oomfware/lightbox` engine with no DOM. Markdown image syntax remains a link, not an automatically loaded remote image. ## Context controls [`ContextChip.svelte`](../web/src/lib/chat/ContextChip.svelte) owns the chat's context popup and undocked context meter. Its strategy menu selects a [compaction strategy](compaction.md) and independently toggles the notes layer for that session. These choices do not change global defaults. Changes made during a turn queue until the session is idle, then save and reload its extensions before any queued compaction. ## Reasoning controls [`ModelPicker.svelte`](../web/src/lib/chat/ModelPicker.svelte) places the model and reasoning words beside the composer in canvas windows, focused chats, and phone chats. The title bar keeps view openers. Undocked controls use the same selection and save lane. Bare monochrome provider marks reuse [`ProviderIcon.svelte`](../web/src/lib/settings/ProviderIcon.svelte) and its extension and endpoint mapping beside the selected model and picker group headings. On phones the model picker opens a native modal sheet that follows the visual viewport above the keyboard. Opening the sheet focuses its close button; search opens the keyboard only when tapped. Dialog and menu touches do not start the phone composer's session-drawer gesture. [`EffortBar.svelte`](../web/src/lib/EffortBar.svelte) opens a level menu directly above its button. The menu escapes a canvas window's clipping and accounts for chat zoom. Phone controls open a bottom sheet. The actual default level carries its source annotation. Choosing that row returns to following the default. Unknown defaults stay unknown. Arrow keys move focus, Enter selects, and Escape closes without saving. Model details contain the profile-bypass action. Changes affect this session; profile defaults remain in Settings → Providers. During session creation, selecting a model advances to the task. Its reasoning word opens the same menu. The model lists and composer prefer catalog display names, with the API ID as a fallback. IDs remain searchable and appear in model row tooltips. [Models](models.md#reasoning-defaults) owns persisted choices and provider resolution. ## Settings [`Settings.svelte`](../web/src/lib/Settings.svelte) owns the settings interface. Its sections include [web search](web-search.md), [webhooks](webhooks.md), and [Discord](discord.md). Their services enforce the corresponding daemon-side rules. A client view is not an authorization boundary. The [HTTP API behavior guide](../docs/http-api-design.md) defines the browser client's ordering and recovery obligations. [OpenAPI](../docs/openapi.yaml) owns its wire shapes. ## Terminals The browser's terminal views attach over the WebSocket route in [`http_terminals.gleam`](../src/albedo/daemon/http_terminals.gleam). The socket attaches from its first message, not from Mist's `on_init`. Mist closes a socket whose `on_init` takes over 500 ms, and starting a terminal waits for its PTY helper, which a loaded host can take longer than that to launch. The [terminal manager](../src/albedo/daemon/terminals.gleam) is one registered process that maps terminal ids to workers and allows at most 32 terminals. Each worker owns a `priv/python/albedo_pty.py` port. It keeps the last 256 KiB of output for reattachment. It serves attach, resize, input, signal and stop before PTY output. A watcher that falls behind gets its output held, at most 64 KiB, with a marker for skipped bytes. An unwatched terminal is stopped after 30 minutes, or 5 minutes once its shell exits. Keep terminal policy in the Gleam module and open the port through [`albedo_ports`](../packages/albedo_ports/src/albedo_ports.gleam). ## Moving a session `/cd` to another host's folder opens the [question dialog](../web/src/lib/chat/CdDialog.svelte). Its state lives in [`cd.svelte.ts`](../web/src/lib/chat/cd.svelte.ts), which mirrors the [terminal's question box](tui.md#moving-a-session). It asks the daemon's preflight, then starts and follows the move. A target that can't take this daemon's data refuses in the preflight or when a move reaches staging. `refusal` reads `transfer_target_older`, `transfer_extension_unavailable` and `transfer_unsupported` in the terminal's words. Only an older target is asked to update albedo. The target's own words, which name what it lacks, follow in smaller monospace text for debugging. Other refusals show their reason as it came. The rules behind the codes are in [moves between versions](workspaces.md#moves-between-versions). ## Manual web review Use the [UI review kit](../test/manual/ux/README.md) for seeded browser reviews, scenario helpers, evidence capture, and private-resource cleanup. These manual checks are separate from the automated gate. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Terminal client](tui.md) - [Artifacts](artifacts.md) - [Workspaces](workspaces.md)