# artifacts

An **artifact** is a web page the agent made: one HTML file, a few files, or a whole built app. It opens in a window beside the chat that made it (web), or in the browser from a row in the transcript (terminal), on its `latest/` address, which follows updates. Every version is kept, and artifacts outlive their session: deleting a session leaves its artifacts in the gallery, which is the only place an artifact is deleted.

The `artifacts` extension (`src/albedo/harness/extensions/artifacts/`, enabled by default) owns the storage, the Python module, the HTTP service and the page bridge. Clients draw it: `web/` has the window and the gallery, `cli/internal/tui` the row, and `albedo web` (`cli/internal/webui`) serves the pages.

## the model's side

The Python module `artifacts`:

- `artifacts.create(title, html=None, *, files=None, directory=None, entry="index.html")` makes an artifact at version 1. Give exactly one source: `html` (the entry file's text), `files` (a dict of relative path to `str` or `bytes`), or `directory` (a folder to publish whole, such as a build's `dist`).
- `artifacts.update(id, html=None, *, files=None, directory=None, entry=None, title=None)` writes the next version. `html` replaces the entry file and keeps the rest; `files` changes only the paths it names (a value of `None` removes that path); `directory` replaces the whole tree; with no source it only renames.
- `artifacts.list(limit=20, session=None)` lists artifacts, newest change first; `session="current"` keeps this session's.
- `artifacts.get(id, version=None)` describes one version: `id`, `title`, `version`, `versions`, `entry`, `files` (path to size), `session`, `created_at`, `updated_at`.
- `artifacts.read(id, path=None, version=None)` returns one file (the entry by default), `str` for text, `bytes` otherwise.
- `artifacts.state(id)` is what the page saved through `localStorage`; `artifacts.errors(id)` is what failed in the page (newest last, at most 20).
- `artifacts.url(id, version=None)` is the page's address on the running `albedo web`, for checking it with the browser plugin. Without a version it is the `latest/` address, which follows updates (below).

Each `create` and `update` adds an `artifact` activity to the running cell's trace: `{"kind": "artifact", "target": <title>, "artifact": {"id": <id>, "version": <n>}}`. That is how both clients learn of it, from history they already read; the trace holds no capability key.

Uploads are content addressed: the module hashes each file (SHA-256), asks the daemon which it lacks (`artifacts.missing`), sends only those (`artifacts.upload`, one file per call, base64), then saves the version as a manifest of path, hash and size (`artifacts.save`). Publishing an app again sends only the files that changed.

Limits: 16 MiB per file, 64 MiB and 2,000 files per version. A path is relative, uses `/`, has no empty, `.` or `..` segment, does not start with `.albedo/`, and is at most 512 bytes. Titles are 1 to 200 characters.

## storage

| table | holds |
| --- | --- |
| `artifacts` | `id`, `key` (the capability, 32 hex characters), `session`, `workspace`, `title`, `version` (latest), `created_at`, `updated_at` (ms) |
| `artifact_versions` | `artifact`, `version`, `entry`, `manifest` (JSON: path to `{hash, size}`), `cell`, `created_at` |
| `artifact_files` | `hash` (SHA-256 hex), `size`, `data` |
| `artifact_state` | `artifact`, `state` (JSON object of string to string), `updated_at` |
| `artifact_errors` | `artifact`, `version`, `at`, `message`, `source`, `line`, `column`, `stack` |

Nothing is deleted with its session. Deleting an artifact removes its rows and every file no remaining version names.

## HTTP

Under `/extensions/artifacts/`, all with the daemon token:

- `GET items?limit=&next=&session=` — the gallery, newest change first: `{items: [Artifact], next}`. An `Artifact` is `{id, key, title, version, versions, entry, session_id, session_name, session_deleted, workspace, created_at, updated_at, bytes}`.
- `GET items/{id}` — one artifact with `history`: `[{version, entry, created_at, cell_id, files: [{path, size}], bytes}]`, newest first.
- `DELETE items/{id}` — `204`.
- `GET frame/{id}.{key}/{version}/{path}` — one file of one version, with its content type. An HTML file gets the bridge (below) injected first thing in its `<head>`. A wrong key is `404`, as is a missing path; a path ending in `/` serves its `index.html`, and an empty one the version's entry. A bare `{version}` without the slash redirects (`302`, relative) to `{version}/`, and an empty path whose entry sits in a folder to that entry, so the page's relative paths resolve inside the version. `{version}` may be `latest`: the newest version, whatever it is when asked, so the page's relative files follow too. A numbered version's files are `immutable`; under `latest` they are `no-cache` with the file's hash as `ETag` (`If-None-Match` answers `304`). HTML is always `no-store`, since it carries the saved storage.
- `GET frame/{id}.{key}/{version}/.albedo/version?after=` — `{version}`, the artifact's latest, `no-store`. With `after`, the daemon holds the answer until the latest passes it or 25 s pass (the waiting request registers in an ETS table, `albedo_artifacts:listen`, and saving or deleting the artifact wakes it, so nothing polls); without, it answers at once. `{version}` only has to exist: a following page asks under the version it shows.
- `POST frame/{id}.{key}/{version}/.albedo/state` — the page's `localStorage`, a JSON object of string to string, at most 1 MiB; `204`.
- `POST frame/{id}.{key}/{version}/.albedo/errors` — one failure, `{message, source, line, column, stack}`, at most 16 KiB; `204`.

The frame routes are what `albedo web` forwards; a browser never reaches the daemon itself.

## albedo web

`/frame/...` forwards to the daemon's `/extensions/artifacts/frame/...` with the token and without the cookie, `Origin` or `Referer`. It needs no sign-in: the key in the path is the capability. Only `GET` and `HEAD` (files, `latest/` and the `.albedo/version` wait, whose cache headers it passes through untouched, with no timeout of its own), and `POST` to the two `.albedo/` paths, pass. Every answer carries

```
Content-Security-Policy: sandbox allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-modals allow-downloads allow-pointer-lock
Access-Control-Allow-Origin: *
Cross-Origin-Resource-Policy: cross-origin
Referrer-Policy: no-referrer
X-Content-Type-Options: nosniff
```

so a page opened in its own tab is sandboxed exactly as one in a window.

While it runs, `albedo web` keeps `$ALBEDO_HOME/web.json` with its `pid`, bound `port`, loopback `url` (`http://127.0.0.1:4317`), `names`, `addresses`, `allow`, `local`, `public`, and `tailnet_https`. It removes the file when it stops.

## the boundary

A page has the network: it can load libraries from a CDN, call APIs and open websockets, as the kernel already can. What it must never reach is albedo: the daemon's API, the web client's cookie or page, the browser storage of albedo's origin. Both the window's `<iframe sandbox>` (without `allow-same-origin`) and the CSP `sandbox` header give the page an opaque origin, so:

- its requests to `/api` carry `Origin: null`, which the proxy refuses, and no cookie (they are cross-site, and the cookie is `SameSite=Strict`);
- `parent.document`, `document.cookie`, `localStorage` and `sessionStorage` throw, until the bridge stands in for the last three;
- it cannot navigate the window that holds it.

Measured in Chrome on 2026-10-21 with a throwaway server shaped like this one: the frame's own document request carries the cookie (it is same-site), every request from inside the page carries neither cookie nor origin, a module script needs the `Access-Control-Allow-Origin: *` above, and `Object.defineProperty(window, "localStorage", ...)` replaces the throwing getter.

## the bridge

The daemon injects `priv/artifacts/bridge.js` into every HTML file it serves, with `window.__albedo = {id, version, latest, follow, title, base, state}` before it (`version` is the one served and `latest` the newest at the time; `follow` is true when it was served from `latest/`; `base` is the served version's numbered frame path ending in `/`, even under `latest/`, so what the page saves, reports and sends names the version it showed; `state` the saved storage). Pages use plain web APIs and, if they want to talk, `window.albedo`.

- **Storage.** `localStorage` is an in-memory store seeded with the saved state; each change is saved (`POST .albedo/state`, debounced 400 ms, and on `pagehide`). `sessionStorage` and `document.cookie` are in-memory stand-ins. State is per artifact, so it carries across versions and reloads.
- **Errors.** `error` and `unhandledrejection` are sent to `POST .albedo/errors` (at most 20 per load) and posted to the window as `albedo/error`.
- **Theme.** `:root` gets albedo's colours as CSS variables, from the window when it says (`ui/notifications/host-context-changed`), else from `prefers-color-scheme`: `--albedo-bg`, `--albedo-surface`, `--albedo-text`, `--albedo-muted`, `--albedo-faint`, `--albedo-accent`, `--albedo-border`, `--albedo-added`, `--albedo-danger`, `--albedo-sans`, `--albedo-mono`, plus `color-scheme` and `data-albedo-theme` (`light` or `dark`).
- **Messages.** `albedo.send(text)` asks the window to post `text` to the chat as you, and resolves to `{sent: true}` or `{sent: false, reason}` (held by the loop guard, or the chat is gone). In a tab of its own (opened from the terminal, or with the window's new-tab button) there is no window, so the bridge posts `{text, gesture}` to `.albedo/message` and `albedo web` sends it to the artifact's chat with the same header: it reads the artifact with its token, checks the key in the path against it, and keeps the same loop guard in memory per artifact (five a minute without a gesture, thirty in all). There is nothing to hold messages in a tab, so past the guard they are refused, and the reason says to open the page beside the chat.
- **Following.** A page served from `latest/` in a tab of its own (`follow` and not embedded) asks `GET .albedo/version?after=<version>` and asks again each time it answers unchanged; once a newer version exists it saves pending storage (waiting for the save to land, so the next load reads it) and reloads, which serves the newest. A hidden tab stops asking until `visibilitychange` shows it; a failed request retries after 5 s, and `404` (deleted) stops. A window never follows this way: the web client moves its windows between versions itself. This is the address the terminal's artifact row, the window's new-tab button while it follows, and `artifacts.url(id)` open.
- **Size.** Its document's height is posted as `ui/notifications/size-changed`, for the phone, which fits an artifact to its content.
- **Notes.** A canvas note can be tied to a part of the page or a passage of its text. While a note's tie is drawn over the page, the window posts `albedo/point` `{x, y}` (page pixels) and the page answers `albedo/pointed` with the part under it, as a CSS selector (an `#id` where one is unique, else `tag:nth-of-type(n)` steps from `body`), a quote (its text, alt or value, at most 600 characters) and its rect. The part is what a reader sees there, not the markup around it: a control, else the first element up from the deepest one at the point that is a thing of its own (a picture: `img`, `svg` as one, `canvas`, `video` and the like; a box that paints a background, border or shadow; a block with words of its own, directly or in inline elements), climbing past wrappers that paint nothing and refusing one that covers most of the viewport. When only those are there, it is the sentence under the pointer, sent as a `passage` `{exact, prefix, suffix}` (the words, and 32 characters either side, inside the element the selector names) with the sentence's rect. Text the person selects in the page is reported as `albedo/selected` `{text, prefix, suffix, selector, rects}` (the selection's words, its context inside the element holding all of it, and its lines), once they let go and whenever it moves, or `{text: ""}` when it is gone; the window then offers a note on it. For tied notes the window posts `albedo/watch` `{selectors, passages}` (at most 64 each; a passage is `{key, selector, exact, prefix, suffix}`; sent again when the page loads again), and the page reports `albedo/rects` `{rects: {selector: rect or null}, passages: {key: [line rect] or null}}` at once and after every scroll, resize or DOM change, a frame at most, finding each passage again by its words inside its element (or the body), where its context matches best. The page only reports what and where; it learns nothing of albedo or the notes.

The page and the window speak JSON-RPC 2.0 over `postMessage`, a subset of [MCP Apps](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx), so a page written for it mostly works here:

| from the page | the window |
| --- | --- |
| `ui/initialize` (request) | answers `{protocolVersion: "2026-01-26", hostInfo: {name: "albedo"}, hostCapabilities: {message: {}}, hostContext: {theme, styles: {variables}, displayMode: "inline"}}` |
| `ui/notifications/initialized` | nothing |
| `ui/message` (request; `params: {role: "user", content: [{type: "text", text}]}`, plus albedo's `gesture`: whether the person had just clicked or typed in the page) | posts the text to the chat, headed `From the artifact “<title>” (v<n>):`, and answers `{}`; or answers an error when held |
| `ui/notifications/size-changed` | sizes the phone's inline view |
| `albedo/error` | marks the window's title bar and lists the failure under the page |
| `albedo/wheel` (a pinch or ctrl-wheel over the page) | replays it on the frame, so it zooms the canvas |
| `albedo/pointed`, `albedo/rects` (answers to the window's `albedo/point` and `albedo/watch`) | outlines the part a tie would land on; draws the line and tint to each tied part or passage |
| `albedo/selected` (only while embedded) | offers a note on the selected text, beside the window |
| `tools/call` and anything else | an error: pages cannot reach the agent's tools |

**The loop guard.** A message sent with a gesture always goes; the bridge counts one click or key press for one message, since a timer a click started still runs inside the browser's activation window. Without one (a timer, a render loop), a page may send five a minute; past that the window holds them behind a button that says how many are waiting. It guards against a buggy page starting turn after turn, never against a person using one.

## clients

**Web.** A new artifact activity in a chat on the board opens a window beside that chat, tied to it like a review; only activities that arrive while the chat is open do this, never ones loaded from history. A window for an artifact that is already open moves to the new version in place. The view pans to it only when its chat is the selected window. A closed window stays closed; the chat's row says it changed and opens it. A window can be pinned to a version, and then it stays there. On a phone the artifact opens inside the chat, as a review does. A page icon in the chat's title bar (on the phone, at the top of the chat; `ArtifactsButton.svelte`) counts the artifacts the session made and lists them, newest change first, to open one; the list is read when it opens and when the session's work stops. The palette finds artifacts by title; `open an artifact…` and `delete an artifact…` list the whole gallery.

**Terminal.** An `artifact` activity is the row `↗ open artifact albedo made for you: <title> · ⧉` (`… albedo updated: <title> · v<n> · ⧉` after the first version), under its burst whether the burst is open or not. A click opens the page in the browser (or copies the link when clicking `⧉`): the TUI reads the artifact's key from `GET items/{id}`, finds `albedo web` through `web.json` (starting `albedo web --no-open` when it is not running, on another port if its usual one is taken, and showing the server's own message if it still does not start) and uses the version the row names, `<url>/frame/{id}.{key}/{version}/`; the first version's row names none, so it uses `<url>/frame/{id}.{key}/latest/`, which reloads itself as the agent revises the page.