# MCP widget

Surface. Prototype: previews/McpWidget.html

The Visualli card inside an agent's chat, shown in a full (fictitious) host conversation so you can judge it in context: the host's sidebar and composer, the person's question with an attached PDF, the assistant's text, the tool call that produced the card, and the follow-up underneath.
- **The card is the only Visualli-styled thing.** The host uses its own neutral palette and system font on purpose: Visualli follows the host's light/dark theme but never imitates its chrome. Header (tree, VISUALLI, the map's title, *Expand*), a compact read-only map (340px, no zoom controls), one hint and **Open in Visualli**.
- **Tool calls:** the host shows *Used Visualli · create_visualli* above the card (click it to see the arguments). Visualli doesn't draw this row; it's the host's — but the tool names and arguments are ours, so keep them readable.
- **The host is the chat.** Reply in the host composer ("add what sleep does to memory"): the host calls `update_visualli`, the same card updates in place and briefly lights the changed ideas, and the assistant says what changed. No second card.
- **Expand** asks the host for full-screen display mode: the same map with canvas controls, an *Exit full screen* control from the host, and Open in Visualli still in the footer.
- Inside the card: peek, terms and Step inside. **No Go deeper or Map it** (`deeper={false}`) — the card is too small for facets; *Open in Visualli* is where that continues. Read-only too — moving and editing continue in Visualli.


## Features

- VI-001 Visualize this page (toolbar, right-click) · Open in Visualli: N/A (The host's chat brings links in)
- VI-002 Map: bloom, step inside, depth trail: UX ready
- VI-003 Touch: tap to peek, tap again to step inside: UX ready
- VI-004 SemanticPeek (an idea's summary): UX ready
- VI-005 SemanticAnchor (term definitions): UX ready
- VI-006 Go deeper (facets for an idea or term): N/A (Too small for facets; Open in Visualli to go deeper)
- VI-007 Map it (inside this map / new Visualli): N/A (Lives in Go deeper; Open in Visualli to map a topic)
- VI-008 Movable ideas and Reset layout: N/A (Embeds are read-only (editable={false}); Open in Visualli to arrange)
- VI-009 Edit mode (ideas, connectors, groups): N/A (Embeds are read-only; Open in Visualli to edit)
- VI-010 Sources panel: N/A (The card shows the map only; sources open in Visualli)
- VI-011 Export: single-page PDF, multi-page PDF, .visualli file (no share link): N/A (Open in Visualli, then export from the app)
- VI-012 Chat: Composer and receipts: N/A (The host app is the chat)
- VI-013 Vault (library of Visuallis): N/A (One map per card)
- VI-014 Comfort & appearance: N/A (Follows the host's light/dark setting)
- VI-015 Tips in the chat stack (e.g. "Layout saved. Want to edit the content too?"): N/A (Embeds are read-only, so nothing triggers a tip)

## Build it

Visualli widgets inside agent hosts (Claude, ChatGPT and others) render in a sandboxed iframe inside the host's conversation.

### Build constraints

- **One self-contained bundle.** Inline or bundle `tokens.css`, `bundle.css` and the component code into the widget; don't rely on loading the docs site or a CDN at runtime.
- **Follow the host's theme.** Map the host's light/dark signal to `data-theme="light"` or `"dark"` on the widget's `<html>`. Never imitate the host's chrome.
- **Stay compact.** A `VisualMap` 320–360px tall, no zoom controls, one hint and an *Open in Visualli* primary button in the footer.
- **Fonts.** Host CSPs can block Google Fonts; the token fallbacks (`system-ui`, `cursive`) must still read well.

### In the conversation

- **One card per Visualli.** Follow-ups ("add what sleep does to memory") call `update_visualli`; the existing card updates in place and lights the changed ideas briefly (`VisualMap` `highlight`). The assistant's text says what changed — the card never adds chat of its own.
- **Tool names read as English** in the host's tool-call row: `create_visualli`, `update_visualli`, `open_visualli`. Arguments are short and human (`source`, `goal`, `request`).
- **Expand** requests the host's full-screen display mode: same map, canvas controls on, Open in Visualli in the footer. The host provides the way out.
- **Browse, don't study.** Peek, terms and Step inside work; Go deeper and Map it don't (`VisualMap deeper={false}`) — they need room, so they continue after *Open in Visualli*.

The prototype above shows the card in a full host conversation; layout rules for every surface are in [Surfaces](../guidelines/surfaces.html).