# Surfaces

One canvas, many windows onto it. Every surface uses the same tokens, nodes and connectors.

## Web app (after sign-in)
- **The whole window is the canvas.** No header bar.
- **Composer** bottom-center (`Composer`, max 720px, `radius-lg`, `shadow-float`): `+` opens *Upload a file · Paste a link · YouTube video · From Notion (soon)*; attachments appear as `SourceChip`s above the input; Enter sends, Shift+Enter breaks a line; the send button is the view's one `action`. When the Vault is open the dock centers in the remaining space.
- **Chat stays small.** Only the last 2–3 turns float above the Composer (`ChatTurn`): the user's words in a bubble, Visualli's reply as a one-line receipt of what changed on the map, with *Undo*. The full history is a later, optional panel — the map is the answer.
- **Tips live in the chat stack too.** One-time hints from Visualli — e.g. after the first move: "Layout saved. Want to edit the content too? **Edit** ✕" — appear as the newest item in the stack (`ChatTurn tip`), never as a banner at the top of a phone. They are transient: gone after their action, ✕, or the next message, and never saved to the chat history. `VisualMap` hands them over through `onInvite`; maps without a chat show them themselves, above the chat inset.
- **Results of a request are chat receipts, not toasts.** Anything the person asked for — sending a message, *Map it* from Go deeper, an idea action — appears as a Visualli `ChatTurn`: first busy (`busyLabel`, e.g. "Mapping Brood…"), then the change with *Undo* ("Mapped Brood as a layer inside Castes & Roles", "Added a layer inside Method of loci", "Started a new Visualli: Brood"). On sheets and stacks, *Map it* closes Go deeper so the receipt and the growing map are visible; the docked panel stays open.
- **Vault** left (`Vault`, 288px): wordmark, *New Visualli* (primary), search, Visuallis grouped Today / This week / Earlier with an organic topic dot, rename inline (double-click or F2), a `⋯` menu with Rename · Duplicate · Export · Delete, and the user + Comfort button at the foot. Collapses to a single icon button.
- **Ideas are movable**: drag any idea to rearrange the map (connectors follow); *Reset layout* appears in the canvas controls once something has moved. Moves are saved to the Visualli.
- **Go deeper** docks as a 380px panel on the right; the Composer and canvas chrome shift left while it is open (`onDeeperChange`).
- **Canvas chrome** top-right: one floating toolbar — **Edit** (pencil + word; *Editing* and pressed while on — see *Canvas language › Editing*), **Sources** (paperclip + count, pressed while its panel is open), **Export** (download icon — Single-page PDF · Multi-page PDF · .visualli file; see *Export* below) and **?** (help, icon-only) — with `CanvasControls` (zoom −, %, +, fit map to view, reset layout) below it. Labels are words, not developer glyphs: there is no `</>` button; the raw `.visualli` file is an export.
- **Sources** opens `SourcesPanel` in the right-hand slot (it closes Go deeper, and vice versa): every source with the passages the map used; hovering a passage lights up the ideas it fed.
- **Depth trail** top-left of the canvas, right of the Vault.
- Empty vault: a single centered `ThinkingTree`-style tree, the `display-m` line "YOUR VISUAL VAULT", one sentence, and the Composer — no tutorial modal.

## Export
Visuallis are private and there is no collaboration yet, so there is **no Share**: no copy link, no invite. There is one **Export** list, built with `exportItems()` so every entry point shows the same three items in the same order, each with a one-line hint:

| Item | Hint | What it makes |
| --- | --- | --- |
| **Single-page PDF** | The overview on one page | Level 0 as a vector map, fitted to one landscape page (A4 or Letter by locale). Ideas with layers keep their rings. Footer: title, sources, date, the Visualli mark. |
| **Multi-page PDF** | Every layer, with summaries | Page 1 is the overview; then one page per layer, depth first, titled with its depth trail ("How memory sticks › The forgetting curve"), the map on top and each idea's summary listed below; a last page lists the sources. |
| **.visualli file** | The whole map, to open or re-import | The open JSON: every layer, position, connector, anchor and source reference. Opens in the desktop viewer; re-imports into Visualli. |

- **Where:** the canvas toolbar's **Export** button (the open Visualli) and the vault ⋯ menu under an *Export as* heading (any Visualli, without opening it). Mobile has only the vault ⋯ entry.
- PDFs always print in the light theme with brand faces, whatever the person's comfort settings — they are documents for others to read.
- **Feedback:** a busy chat turn while it's prepared (*Laying out your PDF…* / *Packing the file…*), then a dismissible tip: *Downloaded "How memory sticks.pdf" · 5 pages*. Not saved to history, no Undo. On phones the OS share sheet opens to save the file, and the tip reads *Ready: "How memory sticks.pdf" — choose where to save it*.
- When collaboration arrives, **Share** comes back as its own button — never mixed into Export.

## Mobile app
- Full-bleed canvas, Composer pinned above the home indicator (radius 26), title pill top-center between *Vault* and *Comfort* icon buttons.
- The Vault is a bottom sheet (`radius-lg` top corners, grab handle) over a `scrim`.
- **Tap an idea to peek, tap it again to step inside.** The first tap opens the idea's `SemanticPeek` as a bottom sheet and the Composer steps aside until it closes. See *Canvas language › Idea facts*.
- Press and move an idea to rearrange it (a still press stays a tap).
- Pinch to zoom; swipe right from the edge or tap the trail to back out. Touch targets ≥ 44px. Double-tap is never used for our own actions (the system zooms with it).

## MCP app (ChatGPT and other agent hosts)
- An inline card (`radius-lg`, `line` border) inside the host's conversation: a slim header (tree mark 22px, VISUALLI in `display`, map title, expand), a `VisualMap` 320–360px tall without zoom controls, and a footer with one hint and *Open in Visualli* (primary).
- Never imitate the host's chrome; follow the host's light/dark setting.
- Peeks open as a sheet inside the card: summary, terms and *Step inside* — **no Go deeper or Map it** (`deeper={false}`); the card is too small for facets. *Open in Visualli* is the way to go deeper, in the inline card and in full screen alike.

## Chrome extension
- **Two entry points, one result:** the toolbar button ("Visualize this page", Alt+Shift+V) and the page's right-click menu (**Visualize this page**) open Visualli in Chrome's **side panel** beside the page. No selection mapping, nothing injected into other pages.
- The panel is `ExtensionPanel`: the map's title and source, **Open in Visualli** (saves to the vault, opens the app), then *Reading…* → the map, or *Couldn't read this page* + *Try again*. Like the MCP card: no vault, no composer.
- The same `VisualMap`, read-only: peeks, term cards, Step inside, Go deeper (sheet at panel widths), Map it. Editing and arranging continue in the app.

## Desktop viewer (offline)
- **The spec, as an app.** Opens `.visualli` files offline and renders them with `VisualliViewer` from `@visualli/design-system/spec` — read-only browsing exactly as the spec defines it: canvas, depth trail, zoom and fit, peeks, term cards and the 8 themes. Nothing product (no Go deeper, sources, editing, chat or vault); product extensions in the file are ignored and kept. Title bar shows the file name.