# web client

`web/` is the browser client: a canvas (Svelte 5, Svelte Flow) where sessions open as panels. It is a client like the TUI, not an extension; it reads the same daemon HTTP API.

`albedo web` (`cli/internal/cli/web.go`) finds or starts the daemon, serves `web/dist` (or `ALBEDO_WEB_DIST`, which the Nix package sets to its `web` build, `.#albedo-web`: `buildNpmPackage` over `web/`, so bump `npmDepsHash` in `nix/packages/web.nix` when `package-lock.json` changes) on `127.0.0.1:4317` (`--port`, 0 for any) and, when this machine is on a tailnet, on its tailnet address too (below), prints a launch link and opens it unless `--no-open` or `ALBEDO_NO_BROWSER` is set, then returns after the detached server is ready. Repeating the command reuses the server and link; changing the listen options requires `--stop` first. `--stop` stops it, `--new-link` replaces its sign-in key and signs existing browsers out, and `--foreground` runs the server in the calling terminal until interrupted. The detached process is not supervised: it does not restart after a crash or reboot. `cli/internal/webui` owns the boundary:

- Each browser tab multiplexes its session panels and root-list follow over one WebSocket at `/api/events`, avoiding the HTTP/1.1 six-connection SSE limit across tabs. `stream.ts` sends new follows immediately on an open socket, preserves each session cursor independently, and resubscribes an ended follow. Unsubscribe sends a stop only for a follow actually sent. Hidden tabs stop chat follows but keep one root-list follow for completion alerts; without that background follow they close pending and open sockets and reopen on return. Stale socket callbacks cannot revive them. Older daemons fall back to the existing SSE routes, retaining their connection budget and visibility cancellation. Both the Go proxy and Vite forward WebSocket upgrades with the daemon bearer token. `npm test` in `web/` exercises the stream lifecycle with mocked browser transport and timers.
- The daemon token never reaches the browser. The page calls `/api/...` on its own origin; the proxy strips `/api`, drops `Origin`, `Cookie` and `Referer`, and adds `Authorization: Bearer <token>`. Session streams pass through unbuffered.
- The launch key persists in `$ALBEDO_HOME/web-key` across stops and restarts. `/?key=<key>` sets an `HttpOnly`, `SameSite=Strict` cookie that lasts a year and redirects to `/`; `/api` without that cookie answers `401 web_signed_out`. `--new-link` revokes the previous key and cookies.
  `--tailnet-auth` makes the tailnet the sign-in: a request from `100.64.0.0/10`, or from the loopback `tailscale serve` proxy that terminates its TLS, gets the cookie without a link (`Server.TrustTailnet`, `Server.fromTailnet`). The cookie still lasts a year, so a tailnet browser signs in once and keeps the session. This trusts every device on the tailnet with the daemon's full control; leave it off unless that is the boundary. It is recorded in `web.json` (`tailnet_auth`) like the other flags.
- Requests whose `Host` is not `127.0.0.1`, `localhost`, a shared address, an answered tailnet name or the published origin's host are refused (DNS rebinding), and so is an `Origin` that is neither the request host's own, whatever scheme it arrived with (a TLS terminator makes the page https while the server speaks http), nor the published origin (`Server.ownOrigin`). The Origin comparison loses the default port on both sides, so `Host: name:443` and `Origin: https://name` are the same origin; any other port still tells two pages apart.
- `--allow <network>` (repeatable; CIDR, or an IPv4 address whose trailing zero octets stand for any, so `10.0.0.0` is `/8` and `100.64.0.0` is `/16`; `webui.ParseNetwork`) shares it with other devices: it listens on `0.0.0.0`, answers only on this machine's addresses inside an allowed network (also accepted as `Host`) and only to clients from one or from loopback (`403` otherwise), and prints a launch link per address. Devices still sign in with the key. `--save` stores the given networks in the daemon's `ui.web_allow` setting, which a later `albedo web` without `--allow` uses; `--save` alone clears it.
- On a machine signed in to Tailscale (`tailscale status --json` reports `Running`; `webui.CurrentTailnet`), `albedo web` with no `--allow` and nothing saved shares to `100.64.0.0/10` (`webui.TailscaleNetwork`) as if it had been given, and `Server.Answer` also accepts the machine's MagicDNS name (full and short; the suffix is the tailnet's own, never assumed to be `ts.net`) as `Host`, case-insensitively. It prints `on your tailnet: <full name>` beside the per-address links. When stdin and stdout are a terminal it then draws a QR code (`cli/internal/qr`: a small in-repo encoder, byte mode, level L, versions 1-10, half-block rendering in explicit black on white) of the first link another device can reach: the tailnet name, else the first shared address; a loopback-only run prints none. Tailnet traffic is authenticated device to device and the launch key is still required. Without a tailscale CLI or a running tailnet it is loopback-only as before. `--allow` or a saved `ui.web_allow` replaces the default; `--local` (exclusive with `--allow`, ignores the saved networks) serves this machine only. `--allow` takes networks, not device names: a device's own address is never one of this machine's.
- `--public-url https://albedo.example.ts.net` names the origin a proxy in front serves this listener through: the printed link and QR carry it instead of loopback's http, and `Server.Publish` answers its host and accepts it as the page's own `Origin`, so a proxy may pass the public name or loopback as `Host` (`webui.ParseOrigin` lower-cases the host, leaves out a default port, and refuses a path, query or fragment). `--tailnet-https` gets that origin from Tailscale: `webui.Tailnet.ServeHTTPS` first requires `CertDomains` in `tailscale status --json` to cover the machine's MagicDNS name (on Tailscale, HTTPS certificates in the admin console; on Headscale, `dns.certificates`), and refuses before running any `serve` command otherwise. `Serve.Claim` then points `tailscale serve`'s https:443 root at this listener, or reuses a root already pointing here, reading `tailscale serve status --json` rather than its text; it refuses a root that publishes anything else or that Funnel opens to the internet, and removes a handler it created but could not confirm. The command that set the handler removes it on Ctrl-C, a failed start and `--stop`, only while it still points at this listener (`Serve.Release`). Each tailscale command has 5 s; a background start or stop gets 30 s (`webGrace`), both ending the server with SIGTERM so its handler comes down before a SIGKILL. Both flags are recorded in `web.json` (`public`, `tailnet_https`), so a later `albedo web` reprints the same link and `--new-link` resumes them. `test/e2e/web_test.py` drives this through a fake `tailscale` on `PATH`.
- A transport failure or a 401 from the daemon triggers `Connection.Refresh`, so a restarted daemon is found on the next request.
- `/assets/*` (content-hashed by Vite) is cached as immutable; everything else is `no-cache`.
- `/frame/...` forwards artifact files to the daemon without requiring the web sign-in cookie. It permits `GET`/`HEAD`, and `POST` only to `.albedo/state` and `.albedo/errors`, which it forwards, and `.albedo/message`, which it answers itself (`message.go`): a page in a tab of its own posts its chat messages there, and albedo web sends them to the artifact's session after checking the key and the loop guard (robot-docs/artifacts.md). The `GET .albedo/version` long-poll a `latest/` tab waits on passes like any file, without a timeout. It strips browser `Cookie`, `Origin` and `Referer`, adds the daemon bearer token, streams the response, and applies the artifact sandbox/CORS/referrer/nosniff headers to every response.
- While serving, the command atomically owns `$ALBEDO_HOME/web.json` (`pid`, actual `port`, `url`, `names`, `addresses`, `allow`, `local`, `public`, `tailnet_https`, `tailnet_auth`). A second live server leaves the existing manifest alone and removes only a manifest that still names its own pid. Sharing to a network (the tailnet by default) listens on every address, which binds beside a server already on `127.0.0.1` (Go sets `SO_REUSEADDR`) while that one keeps answering loopback, so before listening it claims `127.0.0.1:<port>` once and refuses to start when another server holds it.

In development, `npm run dev` in `web/` proxies `/api` the same way from `$ALBEDO_HOME/daemon.json`, read once at start (only when serving, so a build needs no daemon), dropping `Origin` and `Cookie`. WebSocket upgrades also drop `Referer` and require the page's own origin when an `Origin` header is present. It listens on the local network, open, so other devices at home can try the client; the `Host` it answers is limited to the machine's own name (bare and `.local`) and Tailscale's `*.ts.net`, since the proxy holds the token and a rebound name must not reach it.

Background alerts (`attention.ts`, `notifications.svelte.ts`, `sessions.svelte.ts`): the tab title counts distinct watched sessions that finished a turn, acquired a blocking reason, or received agent mail while the tab was hidden or unfocused; the favicon gets a small dot. A watched session is pinned, on any open board, or the phone's current chat, excluding archived sessions. Root-list activity supplies busy-to-idle transitions; a changed latest-answer id also catches a turn missed while disconnected. Mail marks the watched recipient, not the sender: task dispatch and system event mail do not count. Unwatched child turns stay quiet. The existing roots collection supplies these events; no per-child follows or daemon changes are needed. A closed board alone does not subscribe its sessions.

Returning to the tab (focus or becoming visible) clears the count and closes its system notifications. The settings switch asks for Notification permission only on a click and saves its opt-in in this browser, off by default. Denial, unavailable APIs and notification construction failures leave tab counts working. System notifications appear only while hidden, once per unread session, contain the session name and event kind (not message contents), and focus the tab and reveal its chat on click, reusing an open board before adding a window. Hidden tabs keep only the collection follow, including SSE fallback; chat/history reads still pause. If that follow is offline, the list is retried every 30 seconds. Browsers may suspend background tabs, so these are best-effort alerts, not push notifications. `npm test` covers counting, duplicate mail, focus clearing, missed transitions and the background transport lifecycle.

Words: a **board** is a named canvas of panels, and the open boards are the tabs along the top (`boards.svelte.ts`). A board holds sessions from any folders. **Workspace** keeps its albedo meaning, a session's folder, and the sidebar shows each session's folder under its name. Its sections are headed as the terminal heads them, the label in the text colour, its count faint, then a thin rule to the edge (the one place lines separate, as `sectionRule` does in the TUI); its rows alternate as the phone's list does, every other row in a section on `--rail-stripe` (the phone's step from its ground, taken from the rail's, about 1.06:1), hover lays a step over a row's own tone, and a session open on the board sits on `--open-tint`, the rail with a flat step of the accent (12% in light, 18% in dark), opaque so the stripes don't show through: a hue over the stripes' tones, under hover's step, and open rows that meet square their corners so a run of them reads as one block. `[` (shown on the sidebar's toggle, as search shows ⌘K; those key chips sit a 12% step of ink above their button) hides or shows the sidebar; hidden, it pops out floating over the canvas, without animation, as soon as the pointer is within 20 px of the canvas's edge on its side, or further out the faster it is heading there (15 px more per px/ms, up to 50 px), so a flick toward the edge opens it early (`App.svelte`, watched from the canvas so the edge still pans). It stays while the pointer is on it or within 48 px of it, the top bar above it included, or while its filter has focus, and goes 100 ms after the pointer is clearly elsewhere or leaves the page; `/` brings it out the same way with the filter focused (Escape clears it and puts it away), and only focuses the filter when the sidebar is shown. `+` makes a new board; double-click or F2 renames one; closing a tab keeps the board, which the palette reopens (`Open board: <name>`); `Delete board` removes it. The last tab cannot be closed, so there is always a canvas.

A board is an open canvas. **Windows** sit anywhere on it; the view pans freely and zooms out to an overview. Svelte Flow draws, drags and resizes the windows; `board.svelte.ts` places new ones (right of the selected window, top-aligned, stepping past overlaps) and owns the viewport. The wheel is handled in `Canvas.svelte` rather than by Svelte Flow, because windows and canvas share the trackpad: a pinch (ctrl-wheel) zooms around the pointer anywhere, a mouse wheel's notch with ctrl or ⌘ by one 10% step (a notch is a jump of 50 px or more, or any line-mode delta, where a pinch moves a few pixels at a time), an up-down scroll over a window that can scroll scrolls it while the zoom is readable (60% and up), so does a sideways scroll over anything under the pointer that scrolls sideways (a diff's code inside Pierre's shadow root, a wide table; found through `composedPath()`), and every other scroll pans. Dragging empty canvas pans; holding Space (unless a text field has focus) or the middle button drags the canvas from anywhere, over windows too, taking the pointer before Svelte Flow or the window sees it; holding Alt (Option), a drag anywhere on a window or note moves it, not only by its title bar, without selecting text, and the click that ends it is swallowed (Option-click would download a link), and Space with a double-click anywhere glides the view there, centred at 90% (`Board.centreOn`, 300 ms from the middle of the pane up to 500 ms from a corner), where a plain double-click on empty canvas leaves a note. + and − zoom in and out by 5 points (the buttons too), ⇧1 fits all windows, ⇧0 returns to 100%, M shows an overview map, ⌥←/⌥→ moves between windows. The view controls (zoom, fit, map) in the bottom-right corner, under the overview map when it shows (as wide as the controls, measured, and showing and fading with them), and key hints in the bottom-left as the terminal's footer lists them (spc and a grab to pan, ⌥ and a move to move a window, cmd and a scroll to zoom, ⇧1, ⌥←→, spc and two clicks to zoom at a spot, two clicks for a note; the mouse gestures are Lucide's icons, drawn in `Gesture.svelte`, to keep them short; keys in the text colour, what they do muted, each pair on a surface of its own with a small gap between), fade in while the view moves and fade out 4 s after it stops; hovering or focusing them keeps them, and once faded they let clicks through to the windows beneath. What a window shows is a **view**, each framed by `nodes/WindowFrame.svelte`: a session's chat, or a review of one turn's changes; files, terminals and agent-made pages are meant to follow. A view opened from a window names it as its `parent`, opens beside it, and the canvas draws a faint dashed line between them (the board derives Svelte Flow edges from those parents; every window carries invisible handles for them).

The review (`nodes/ReviewNode.svelte`, `review.ts`) opens from "review N files +a −r" on a turn's sign-off, or from the +a −r on any work line, which also scrolls it to the first file that stretch of work changed (`data.jump`). It needs no daemon support beyond history: every tool call's trace records each file it changed, with the unified diff (`changes[].diff`, or `reason` when the file was binary, unreadable or too large). Writes the harness makes for itself stay out of it (`albedo_trace.unobserved()`): the browser plugin's profile lock and marker and its auto-named screenshots (in the cache, see [kernel](kernel.md#browser-gestures)) among them; a screenshot saved to a path the cell chose is still the cell's change. The window keeps the session, the turn and the turn's first history position, reads that turn's entries (`after=`, until the next turn starts), hydrates their traces, and shows the files with their counts, then each file's diffs in order. Diffs are drawn by `@pierre/diffs` (Shiki highlighting, `pierre-dark`/`pierre-light` tokens over the canvas's own ground and diff colours; `views/DiffView.svelte`), loaded with the first review so the rest of the client stays small. The margin button beside a line (drag for several) leaves a note on the canvas beside the window, tied to those lines; "send review" sends every unsent note tied into the review as one message, after an optional overall line. While the session works, the review reads what came after the entries it has every 2.5 s, and once more when it stops (`readTurn` without `seek` ends at the first entry of another turn, so an older turn's review costs one page a read); results already filled in are kept, and a file whose changes grew glows in the index for a moment.

The **terminal** (`nodes/TerminalNode.svelte`, `views/TerminalView.svelte`, `jobs.svelte.ts`) shows one background job's output, read-only. A terminal icon in a chat's title bar (`JobsButton.svelte`, on the phone above the composer, shown once the session has had a job; it and the artifacts icon share `MenuButton.svelte`) counts the running jobs and lists them, finished ones with their exit codes while the kernel keeps their output; the list polls `GET /extensions/run/sessions/{id}/jobs/recent` every 2 s while a job runs, 6 s otherwise. Choosing one opens a window beside the chat, tied to it like a review. The window opens on the last page of `.../jobs/{job}/output` and follows `next_offset` every 700 ms while the job runs (once more after it ends), keeps at most 400,000 characters, drops colour codes and shows a `\r`-redrawn line as its last draw. Its stop button asks twice, then posts `.../jobs/{job}/stop`. A job the kernel no longer has (a restarted kernel) says so. On a phone the same view opens in the chat's dock, above the composer.

The **trace** (`nodes/TraceNode.svelte`, `views/TraceView.svelte`, `trace.ts`, `TraceTie.svelte`, `tracelink.svelte.ts`) shows one task as albedo ran it: "trace" on the sign-off of a turn that ran tools opens it beside the chat, tied to it like a review. A task is that turn and the turns after it until the person types again (mail from a child, continuations), so a parent's wait for its agents and their replies fall inside it. A trace opened on the session's newest task follows the session instead: every later turn is added as it begins, each message the person sent marked on the axis ("you"), and it reads again whenever the session's phase changes as well as every 3 s while anything in it works, never while the tab is hidden, and every 5 s while a read fails. Its axis runs ahead of now (a dashed line), by a quarter of the task or at least 30 s, and grows only when now reaches the end, so the calls already drawn hold still under the pointer between reads. "earlier turn" adds the turn before the earliest shown (`turnBefore` walks history back to the person's previous message; the count is saved on the window as `earlier`), read in place so the view keeps its zoom.

The trace is read in parallel where it can be: agents, jobs and model calls start with its history, and the session's own lane shows before its agents are read. Each window keeps per-lane history positions, request sequences and known children. Live reads append new entries and calls, close pending tools, and reuse completed child lanes until their activity changes; running jobs and child summaries are reconciled. A followed child keeps growing while its parent waits. Hydrated inputs and traces are kept, with a tool’s later result fetched separately. Earlier-turn changes and failed reads discard the cursors. Initial model-call reads use `since_ms` to skip requests that finished before the task; a daemon rejecting it with 400 is detected once, then uses the older parallel single-row probing search. Later reads use request sequences on either daemon. It animates only transform and opacity, and nothing animates while it is out of view.

Rows come from three places: model calls from the session's request records (`GET /sessions/{id}/context?view=requests`, oldest first; `since_ms` finds the task’s first records, with single-row probes only on older daemons), tool calls from the transcript (a call's entry to its result's; input a history page only referenced is read afterwards in one `history/content` walk per agent), and agents from `GET /sessions?parent_id=`, three deep, kept when they were alive during the task. Each agent is one lane: its calls never overlap, so model calls (grey, the wait for the first byte lighter) and tool calls (the lane's hue, which keeps clear of red; failures are red) take turns along one strip, and a gap of 1.5 s or more while an agent below works is hatched as waiting. Under the strip, each tool call has one chip naming the most telling thing it did, read from its trace (a web search, then an MCP call, the computer, an artifact, an edit, a command, a search, a read, a listing, a display; the first line of its code when it did none of them), with the rest counted ("+3") and listed on hover and in its drawer. Calls closer than a readable chip (64 px) share one cluster chip that counts their kinds (as many as fit) and zooms to its stretch when pressed; clusters are worked out again as the zoom changes, and no chip runs past the next, so none overlaps. Jobs are packed by where they end on screen, at least 18 px wide, for the same reason. A fold's idle label stays off the ticks, and gives way to the person's "you" when their message ended it. Under the chips, the lane's background jobs (`GET /extensions/run/sessions/{id}/jobs/recent`, kept only while the kernel keeps them) on the same clock, packed into as few tracks as keep them apart; tracks past the first fold into a thin band of ticks, and pointing at them floats them out over the lanes below, so opening them never moves the layout. A running job shimmers, one that failed or timed out is red, one started as a service is dashed, and a click opens its terminal beside the trace. Jobs never keep idle time from folding. The gutter gives each lane's model and how much context its last call sent, and what share came from the cache; a compaction summary's call is drawn in the accent. Calls are often a few pixels wide, so the strip is taller than its bars and finds the call itself (`callAt`): the nearest within 10 px, a tool call close by beating the model call under the pointer. Spawn arrows leave the parent's tool call running when the child was created; reply arrows leave the child's last step before its mail landed. Above the lanes, one bar says where the task's own time went (`spent`): thinking, running code, waiting on agents, waiting on the person (an idle stretch their message ended), and the gaps between steps, with the duration, tokens, calls and failures beside it; all of it follows the playhead.

A press on a call opens a drawer under its lane: what it did (each edit opens the review of its turn at that file, through `onreview`), its code and output (read then, in one batch), or a model call's first byte, tokens sent, cache share and tokens written; ← and → step along the lane, Esc closes. Hovering a tool call in either the trace or the chat lights it in both (`traceLink.entry`, keyed by the chat's entry: the result once there is one), and `TraceTie` draws a line between them over the canvas, pinned to the chat's edge when the call is scrolled out of view; opening one in the trace sets `traceLink.reveal`, which opens its stretch in the chat and scrolls it there. Any stretch of 20 s or more with nothing running is folded into a 2.5 s break labelled with how long it was idle (`clockOf`, a polylinear d3 scale); ticks are round elapsed times within each busy stretch. Zooming, panning and replaying only move CSS variables (`--w` the axis width, `--left` the pan, `--t` the playhead), so none re-renders a bar: a pinch zooms at the pointer, a sideways swipe pans (the canvas leaves both to anything inside `.zooms-itself` while the window is readable), a press on the axis scrubs, a double-click on it or "fit" shows the whole task, a double-click on a call zooms to it, and the replay plays any task in about 12 s. Search matches a call's name, the first 4000 characters of its input and its error; Enter opens each match in turn. `prefers-reduced-motion` drops every animation but the replay.


The **artifact** (`nodes/ArtifactNode.svelte`, `views/ArtifactView.svelte`, `artifacts.svelte.ts`; robot-docs/artifacts.md) is a page the agent made, live in a sandboxed `<iframe>` (no `allow-same-origin`) on `/frame/{id}.{key}/{version}/{entry}`. The chat learns of one from the `artifact` activity in a cell's trace: a line under the turn's summary (`made counter`, `updated counter v2`) opens it, and one that arrives while the chat is open (`Transcript.made`, never history read on opening) opens a window beside the chat, tied to it like a review; the view moves only when that chat is the selected window, and then shows both (`Board.revealTogether`, zooming out no further than 60%). An open window follows each new version in place unless the version menu pinned it; a window the reader closed stays closed. Its new-tab button opens `/frame/{id}.{key}/latest/` while it follows, a tab that reloads itself as the agent revises the page (robot-docs/artifacts.md, the bridge), and the pinned version's own address while pinned. The board saves the artifact's id, its session, the pinned version and the newest version heard of, never the page. The window answers the page's bridge (`PageHost`): the theme and the client's colours resolved to plain values (`themeVariables`, sent again when the theme or palette changes), the page's messages to the chat headed `From the artifact “<title>” (v<n>):`, with the loop guard (five a minute without a click behind each; the rest wait behind send and discard), failures shown under the page with "ask albedo to fix it", and a pinch over the page replayed on the frame so it zooms the canvas. While the canvas is being panned or a window carried, or below 60% zoom, the frame lets the pointer through. On the canvas the page is zoomed, not scaled (`ArtifactView`): the frame gets CSS `zoom` at the canvas's zoom and `scale(1/zoom)`, so its own document lays out at the window's width and draws at the zoom's resolution while its surface reaches the screen untransformed. Chrome draws a scaled frame from another process (the sandboxed page always is one) from a stale or low-resolution raster while it scrolls and after a pinch, then sharpens a moment later; zoomed, there is no scaled surface to resample. Each zoom change re-rasters the page, so mid-zoom the frame catches up only when its zoom is more than a tenth off the canvas's (`DRIFT`), and takes it exactly once the canvas holds still for 40 ms (`SETTLE`); the page is scaled the rest of the way in between. The page sees a `devicePixelRatio` of the screen's times the zoom; `PageHost` maps points through the frame's on-screen size against its `clientWidth`, which already covers it. On a phone the artifact opens in the chat's dock, sized to its page. The palette finds artifacts by title, and `open an artifact…` and `delete an artifact…` list every one, from deleted sessions too. `npm run dev` proxies `/frame/` like `albedo web`, with the same headers.

Design rules the client keeps (from the design pass): surfaces separate by a step in tone, not by lines; only what floats (windows, the palette, the view controls, the overview map) casts a shadow; one accent, albedo's mauve by default and editable, used for focus and selection; no status dots; monospace only for code and tool commands.

The client shares the terminal's voice. `moods.ts` is a port of `cli/internal/tui/moods.go` (its pools, their order and the seeded FNV-1a pick), so a finished turn signs off with the same kaomoji in both clients: its seed is the turn's last entry time in milliseconds, and its class comes from how long it took. A busy session shows an animated face for what it is doing, read from its phase (`preparing`, `generating`, `running` a tool, `compacting`, `interrupting`; only `idle` is at rest) and the tail of its activity, on one shared 500 ms clock for every face on the page (`live.svelte.ts`). Every frame of the animation sits invisibly under the current one, so a face keeps its width and nothing beside it moves. `burst.ts` writes a turn's thinking and tool calls as the terminal's one past-tense line (`thought 12s · read tui/{chat,moods}.go · ran go test ×2  +12 −3`), from each call's trace, fetched when the line scrolls into view. Speakers are named as in the terminal: "albedo" in mauve, "you" in teal, with "2h later" after a pause of 30 minutes or more. Copy is lowercase, and empty and error states carry a face. The canvas has sparse dots (3 px every 36 px, about 1.8:1 on the ground in both themes) that merge rather than fade as the view zooms out (`Dots.svelte`): between 100% and 50% every other dot dissolves into its neighbours, leaving the grid as it looked at 100%, and so on a level up, so the dots on screen stay 18 to 36 px apart and 3 px across at any zoom.

Markdown (`markdown.ts`) also understands maths and diagrams: `$…$`, `\(…\)` and `$$…$$` / `\[…\]` (a dollar amount like "$5 or $10" stays prose: the opening `$` must touch its text and no digit may follow the closing one) and ```` ```mermaid ```` blocks. They render as placeholders carrying their source, and `enhance.ts` draws them after the message mounts: KaTeX for maths (`trust: false`), Pele (pele.run) for diagrams, themed with `--pele-*` from the canvas tokens, its SVG kept to drawing (no scripts, foreign objects, event attributes or outside links). Both load only when a message needs them.

**Notes** (`nodes/NoteNode.svelte`, `anchors.ts`, `notes.ts`, `quote.ts`, `Tethers.svelte`) are small text boxes on the canvas, saved with the board. Double-click empty canvas or press N for a loose one; the composer's pop-out button moves the draft into a note tied to its chat, for writing at length; selecting text in a window (a message, a step's output, anything of the client's own; not yet a diff, whose text is in Pierre's shadow root) floats a "note" button just under the end of the selection (kept on the canvas, so a window at the edge of the view still shows it), which leaves a note beside the window tied to exactly that text. Dragging a note's grip onto something ties the note to it: the selected text, when the pointer is on it; a window; in a chat, a step (`data-entry`), or in a reply the block under the pointer (a paragraph, list item, code block, heading, quote or table row), with the speaker's name standing for the whole message; a line in a diff (found by the diff's `data-diff` key and the row's number inside Pierre's shadow root); or a part or a passage of an artifact's page (asked of the page through its bridge, since it is another document: `pageHosts` in `artifacts.svelte.ts` holds each artifact window's bridge, the frame lets the pointer through while a tie is drawn, and the part is kept as a CSS selector, the version and a quote; see `robot-docs/artifacts.md`); dropping it on empty canvas sets it loose. A passage of text, the client's own or a page's, is kept as the W3C TextQuoteSelector keeps one (`quote.ts`): its words (up to 2,000 characters) and 32 characters either side, inside the entry it was in, and found again by those after the window redraws, the best match of its context where the words appear more than once; a block is kept the same way. Old saved boards load unchanged. Until a chat's first page is in and scrolled to its end, the thread stays hidden behind a skeleton shaped like the end of a typical chat (measured at phone width: a work line, a message, more work, the reply's last lines and its sign-off), so it never shows its top and then jumps. A chat follows its end as it grows unless the reader has scrolled up (more than 40 px from it); then a pill floats over the composer (on a phone, above the drawer's handle): "see new messages" once the end has changed since they left it (a new last block, or more of a live reply; older pages loading above do not count), "back to latest" until then, and it scrolls back down. Tables in messages scroll sideways instead of squeezing their columns. A review names each file by its last two path segments (`…/chat/Chat.svelte`), the full path as its title.

While the grip is dragged, what it would land on is outlined (`pick` in `anchors.ts`); the drag follows the pointer on the whole document, so a note redrawn mid-drag, or dismissed, never leaves the tie or its outline behind. The target and a quote of it (the diff lines, the passage, or a message's first 600 characters) are kept on the note, so what it was about survives scrolling and closing. A line runs from each tied note to its target, and a target that is a passage (diff lines, a message, a step, selected text, a part of a page) is tinted while on screen: the client's own text under its words with the CSS Custom Highlight API (`albedo-note-normal`, `-lit`, `-sent`), a page's passage line by line over the frame, and a passage that can no longer be found as the block it was in; the note in hand, selected or under the pointer, draws its line and tint strongest. The line is measured in screen space every frame while any note is tied, held inside the window and whatever scrolls it. A note layers like any window: the selected window is on top, so a note just made starts above the rest, and picking a chat or an artifact brings it over the note.

Notes are drafts, as a pending review's comments are: every written, unsent note tied into a session, to its chat or any of its windows (`Board.sessionOf`), goes with that chat's next message: the chat's own notes first, then each window's in board order, each from the top (`drafts` in `notes.ts`). The notes are not drawn in the composer, since each is already tied to its window by a line; the send button widens to a note icon and how many go with the message. A note's footer says what it will do, `with next message` or `on its own`, and a click on it switches (`alone`, saved with the board; boards saved with `held` read as `alone`): a note on its own is sent only by its own button. Sending the composer sends what was typed as the lead and every note that goes with it after it, as one message, through the chat's own send (so it shows as pending and can be retried); with notes going, an empty field sends just them. A note also sends alone (⌘↵ or its send button), a review's notes with "send review" (they go with the next message too, and are done once sent), and the palette's "send all notes" sends every session's notes, except those on their own, as one message each. Each note quotes only what it was tied to (a note tied to a chat window itself is just a message; one tied to a part or passage of a page names the artifact, the version and the selector). Sent notes stay on the board, quieter, until dismissed.

On a narrow screen (760 px or less) the client is a plain chat app unless settings ask for the canvas (`canvasOnPhone`): `layout.svelte.ts` and `Phone.svelte` show the session list, then one session's chat filling the screen, with a back button and the browser's back between them (`history.pushState`). There a review opens inside the chat, under the line that asked for it (`views/ReviewView.svelte`, the review window's body too), and notes and pop-out are off. The phone's session list and drawer are one picker (`SessionPicker.svelte`): up to six tiles (pinned, then sessions opened three or more times, most first, then today's), every other session as a list under them (three dots between the two, and every other row takes a softer step of the tiles' tone, so the stripes don't read as tiles), and a search field with a new-session button docked at the bottom on the ground's tone, within thumb reach; while searching it is all list. The phone's chat reads at 16 px unscaled with narrow margins, its composer floats over the thread (which scrolls on under it and ends clear of it), a chat has no bar and takes no gesture from the browser: a handle floating above the composer raises the session picker as a drawer over the chat. The drawer and the composer are one surface: the handle is the sheet's top edge, resting there when closed, and the sheet stands on the composer's bottom edge rather than the page's, so nothing of it reaches under what floats there (Safari's toolbar) and its search lands where the composer was. Dragging it up (or a quick swipe up from the composer itself, unless it would scroll the draft or follows a hold) raises the sheet with the finger while the composer fades into the search bar pinned in its place; dragging it down from its grip, or from anywhere while its list is at the top, lowers it. Let go and it settles open when past half (lowering: while still two thirds up) or flicked up, and otherwise sinks back into the composer; settling tweens the same number a finger moves, so the sheet, the composer's fade and the scrim stay one motion. A tap on the handle opens it, and a tap on its grip or above it, or choosing a session, closes it, and the browser's back still returns to the list, and the composer is one row (picture, field, stop, send).

**New session** (`NewSession.svelte`; the + beside the sidebar's filter, the phone list and ⌘K): pick the folder from the folders sessions have used (`GET /workspaces`, ranked as you type), type a path, or browse to one (`GET /workspaces?location=`); then the provider profile (`GET /settings?group=providers`, starting on the default), its model (`GET /models?provider_profile=`) and effort, starting on the profile's own. Start is `PUT /sessions/{uuidv7}` with `If-None-Match: *` and `{kind: "new", workspace, provider_profile, model, effort}`, and the session opens.

**Model picker** (`chat/ModelPicker.svelte`, sharing `ModelChoice.svelte` with new session): the composer shows the session's model and effort as a chip; it opens a pane to switch the provider profile, model and effort, which reads the session's configuration for its validator and sends `PATCH /sessions/{id}?view=configuration` as a merge patch with `If-Match`. It applies from the next turn.

**Context meter** (`chat/ContextMeter.svelte`, maths in `context.ts`): beside the model chip, a ring and the share of the window the context fills ("38%"), muted, in the danger colour from 90 % where compaction starts; hovering or focusing it says "76k of 200k tokens · 70k cached". It shows nothing before the session's first usage, and "—" when that usage came from a model other than the session's now. Usage comes from the chat's own session stream (`Transcript.usage`: the reset snapshot's `usage`, then `usage` events), so nothing polls. The window is `GET /sessions/{id}/context-window` (`effective_context_tokens`), read once per model the usage names. The cached count follows `cache_fade` as the terminal footer's does and is redrawn at each step's time, not on an interval. It rides in the same snippet as the model chip, so the phone's composer has it and an inline chat does not. Tested by `scripts/context.test.mjs`.

**Slash commands** (`commands.ts`): the chat reads the session's commands from `GET /sessions/{id}/catalog?kind=commands` (only those a human may call; the list is empty until the session's runtime has loaded once). Typing `/` in the composer lists them, filtered as you type (arrows, Tab or Enter to complete, Escape to clear). A line starting with a command runs it: arguments are read the way the terminal reads them (words in order, the last taking the rest, or a JSON object), and one name that is both a read and a change picks the read when nothing follows it. Skills and command inputs are sent as `{kind: "command"}` inputs; reads and changes are the daemon operations the catalogue declares, with path, query, headers and body bound from the session record, the arguments or literals, and their answer shows above the composer until dismissed.

The (?) between search and settings opens an about pane (`About.svelte`, under it): a one-line description (a placeholder for now), the main contributors with their Bluesky handles (tiles two to a row, an odd one centred under them), thanks to everyone else with a link to the full history on tangled, and the libraries the client is built on with their licences (pills in centred rows), linking `THIRD_PARTY_NOTICES.md`.

Settings (the sliders button at the top right, or ⌘,) is a non-modal pane over the board: the theme (follow the system, the default; light; dark), each mode's colours, the canvas dots, and which side the sessions sit on ("sessions on the right" mirrors the shell: the sidebar, its toggle and the brand on the right, search, about and settings on the left, and the about and settings panes open under their buttons; set on `<html>` as `data-sidebar`). A mode's colours are three seeds and a contrast, as in the Codex app: accent, background (the ground), foreground (the ink) as hex, with a native picker beside each, and contrast from 0 to 100; accent presets fill the accent for the mode being edited, and a theme copies and pastes as JSON (both modes, or one palette for the mode being edited). `app.css` derives every other token from the seeds with `color-mix` in OKLab (surfaces, chrome, fields, secondary text, hover, dots, shadow tint) and relative `oklch()` (the brand's second stop, and "you" opposite the accent), so any three colours make a whole theme; contrast scales how far each step goes. The colours are [madoromi](https://madoromi.moonwit.ch/)'s (MPL-2.0, credited in the pane and in `THIRD_PARTY_NOTICES.md`): the defaults are its spring, haru, by day (`#f6eff8` paper, `#584a5c` ink, `#6928bd` wisteria) and by night (`#241c26`, `#e1d1e7`, `#ddb3ff`); its four seasons set both modes at once, keeping each mode's contrast, and the accent presets are its spring inks. Preferences live in this browser (`prefs.svelte.ts`, `albedo.prefs.v4`, carrying the theme and dots over from earlier keys) and in an `albedo_prefs` cookie, which every port on the host shares, so the dev server and each `albedo web` port open the same way; the cookie wins when both exist, and `albedo web` drops it before forwarding to the daemon. Settings also take an interface and a code font by name (a comma adds fallbacks; each name is quoted and nothing that could end the value survives, see `fontStack`), set as `--sans` and `--mono` on `<html>` ahead of the default stacks; where the browser offers `queryLocalFonts`, the installed families are suggested. The resolved mode is `data-theme` on `<html>` and its seeds are inline custom properties there; a small script in `index.html` applies both before the first paint, and `prefs` follows system changes while the theme is `system`.

The chat view (`chat/`) reads `GET /sessions/{id}/history` (newest page, then `before=` as the reader scrolls up, and `after=` when the stream says something committed) and sends with `PUT /sessions/{id}/inputs/{uuidv7}`; while the session works, a stop button beside send (or Escape in an empty field) reads the session's `run_id` and `input_order` fresh and posts `/sessions/{id}/interrupt`, so a stop never reaches a later run, `{kind: "message", text}`; images attach by paste, drop or the composer's picture button (`chat/attachments.ts`, the terminal client's scheme: each image leaves an `[Image #n]` marker at the cursor, deleting the marker drops the image, sending renumbers the marked images 1..n in reading order and sends them base64 as `images`, at most 10); a user entry's images show above its bubble from their history references (`/api/sessions/{id}/history/{entry}/image-n`). a send stays on screen as pending until its `input_id` appears in history, and a failed one offers retry with the same id. Your newest message carries a receipt until a reply follows it, drawn as Signal's (`chat/Receipt.svelte`): a dashed ring while sending, a ring with a check once the daemon has accepted it (sent), two filled ones once its entry is in history (seen), which the daemon commits in the same transaction that takes it into the conversation, so the model has it (a message sent while albedo works stays `sent` until the loop takes it at its next step). Until it is seen the bubble stays faded. A waiting input is not listed anywhere, so after a reload it shows nothing until it commits. `transcript.svelte.ts` turns entries into blocks: user bubbles, assistant markdown, and each run of thinking and tool calls between messages folded into one "Worked" line (open while it is the live run). Referenced message text is fetched with the page; tool arguments and output only when their run is opened. Markdown is rendered by `marked` with raw HTML escaped and only http(s)/mailto links (`markdown.ts`), because transcripts carry model and tool text into a page that can reach the daemon. The session list (`sessions.svelte.ts`) follows the collection's stream (`GET /sessions?scope=roots` as server-sent events, `followSessions` in `stream.ts`): each `activity` event patches that session's status and activity in place, so the sidebar, window titles and faces change as the daemon does, and `reset`, `overflow` or `invalidate` reads the list again (once for a burst). While that stream is up the list is also read once a minute in case; while it is down, every 4 s. Both stop while the tab is hidden. A turn's sign-off row carries its actions, trace and copy as icons, shown while the pointer is anywhere over the turn's reply or on the row itself (found from the page when the pointer moves, `hover` in `Chat.svelte`), or always on a screen with no hover. What is typed in a composer is a draft kept by session (`chat/drafts.ts`), outside the composer, which goes with its window when another board is shown, so the draft is there when the board comes back. The text is also written to localStorage (`albedo.draft.v1:<session>`) once typing pauses for 300 ms, and on `pagehide`, so a reload keeps it; sending or emptying the field removes it, and one untouched for 30 days is dropped at the next load. The images it marks are not kept (they are too big for storage), so a reload drops them and their `[Image #n]` markers; switching boards keeps them.

Tool steps and burst clauses read the daemon's derived `title` from history entries, stream events, or tool progress, falling back to line 1 for older daemons or when no title is provided.

Each chat also follows the session's event stream (`stream.ts`: `GET /sessions/{id}?tail=0` as server-sent events, read with `fetch` so it can resume with `after_generation` and `after_seq`, backing off from 0.5 s to 5 s). Thinking and reply deltas show as they are written, tool progress shows as a running step until its call commits, and status events drive the faces ahead of the session list. A reset carries a snapshot whose `active_output` and `current_progress` restore what was in flight. A `committed` event reads the new history first and then drops the live output it names, so a reply never blinks out between its last delta and its entry. While the stream is down the chat falls back to polling every 1.2 s while busy and 5 s otherwise; while it is up, every 20 s.

Boards live in the browser's `localStorage`: the list under `albedo.boards.v1`, and each board's windows (position, size, what they show) and viewport under `albedo.board.v2:<id>`. Only the active board is mounted; `FlowBinder` hands it the flow helpers, and anything asked of a hidden board (revealing a new window) runs when it is shown.

Wire types live in `src/lib/api.gen.d.ts`, generated from `docs/openapi.yaml` with the exact `openapi-typescript` dev dependency. Run `npm run generate` in `web/` after changing the contract; `npm run generate:check` compares the output without writing or downloading dependencies. Version 7.13.0 accepts the canonical OpenAPI 3.2.1 document directly; no projection is needed. SSE item schemas and framing remain handwritten in `stream.ts`. `api.ts`, the command catalogue and tool traces use generated aliases; app-only projections (a profile's map key, normalized review changes) stay local. TypeScript 7 (the native compiler) is the `tsc` of this package (`@typescript/native` is an alias of `typescript@7`), and `npm run check` is `svelte-check --tsgo`, which type-checks `.ts` and `.svelte` with it. The package called `typescript` is Microsoft's `@typescript/typescript6` alias, because svelte-check's source mapping and openapi-typescript import the old JavaScript compiler API that 7.0 does not ship; an `overrides` entry lets openapi-typescript take it despite its `^5.x` peer range. Drop the alias when both tools support 7's API (TypeScript 7.1).

Checks: `npm ci`, then `npm run generate:check`, `npm run check` and `npm run build` in `web/`; `go -C cli test ./internal/webui/` for the boundary. `test.sh` runs the offline generation check beside the Go API generation check, so install the web dependencies first. The dev shell supplies Node. The Svelte check and build are not in `test.sh`.

## seeing the client

A layout or styling change to the client is judged by looking at it, not by `npm run check` and not by the code. Start a private daemon (its own `ALBEDO_HOME` and an `ALBEDO_DAEMON` copy from `test/snapshot-daemon.sh`, as in AGENTS.md), `npm run build` in `web/`, run `albedo web --no-open --port 0` with that `ALBEDO_HOME` (`ALBEDO_WEB_DIST` points it at another build), open the link it prints with the `browser` binding, and screenshot the states you changed:

- a desktop width, the canvas with the panels the change touches open;
- phone width (760 px or less), which is a different layout (`Phone.svelte`), unless `canvasOnPhone` is set;
- light and dark (settings, theme), since the colours are derived from seeds.

`npm run dev` works too (it proxies `/api` from `$ALBEDO_HOME/daemon.json`). Screenshots the `browser` binding saves without a path go to `$ALBEDO_HOME/cache/browser-screenshots/`, not the checkout; `page.screenshot()` returns the path to read. Close the browser, the server and the daemon when you are done, and check `ps` for ones naming your home.