@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/skills/orbit/references/import-export.md

@@ -0,0 +1,115 @@
+<!-- A copy of docs/import-export.md, made by scripts/build-llms.ts, with links to other files pointing at the repository. Edit the original. -->
+
+# Maps from other apps
+
+Orbit reads the maps people already have in other apps: OPML, which outliners and most mind map apps write, FreeMind and Freeplane's `.mm` files, and XMind's `.xmind` workbooks. They become ordinary Orbit maps, with their notes, links, folded branches and pictures. Orbit writes OPML too, so a map moves out as easily as it came in.
+
+## Bring a map in
+
+`importMap` reads a file's bytes (OPML and `.mm` files work as text too) and tells the format from what the file holds, then from its name:
+
+```ts
+import { importMap, serializeOrbitMarkdown } from '@restless-dreams/orbit';
+
+const bytes = new Uint8Array(await file.arrayBuffer());
+const { format, maps } = importMap(bytes, { name: file.name });
+
+for (const map of maps) {
+  const markdown = serializeOrbitMarkdown(map.document);
+
+  for (const [path, data] of Object.entries(map.media)) {
+    // Save each picture at this path next to the map: `media/sunrise.png`.
+  }
+
+  for (const warning of map.warnings) {
+    console.warn(`${warning.message} [${warning.code}]`);
+  }
+}
+```
+
+- `maps` holds one map, or one for each sheet of an XMind workbook.
+- Each map's `document` is what `parseOrbit` would give for the markdown `serializeOrbitMarkdown` writes for it, ids included: draw it, edit it or save it as you would any map.
+- `media` holds the pictures inside the file, by the address the map gives them. Only XMind workbooks carry pictures; the others point at files on the computer they were made on, which can't come along.
+- `warnings` say what the other app had that Orbit keeps another way, or couldn't keep (see [Warnings](#warnings)).
+- Options: `name`, the file's name, which also names a map with several top ideas and no title; `format`, to skip telling the format (`opml`, `freemind` or `xmind`); and `untitled`, the name for a map with several top ideas and nothing to name it after (default "Untitled map").
+
+`detectImportFormat(bytes, name)` tells the format without reading the map: `opml`, `freemind`, `xmind`, or `null` for anything else, Orbit's own markdown, YAML and zips included. `importOPML`, `importFreeMind` and `importXMind` read one format each and take the same options.
+
+A file Orbit can't read at all throws an `OrbitImportError`, whose `code` says why:
+
+| Code | Why |
+| --- | --- |
+| `unknown-format` | It's none of the formats Orbit reads. |
+| `unreadable` | It's damaged, or not what its name says: the message says where. |
+| `empty` | It holds no ideas. |
+| `password-protected` | An XMind workbook with a password. Open it in XMind and save it without one first. |
+| `too-large` | More than 100,000 ideas, or more than 500 levels deep. |
+
+## From the command line
+
+```bash
+npx @restless-dreams/orbit convert --to md Garden.xmind --out garden.md   # every sheet, its pictures in media/
+npx @restless-dreams/orbit convert --to md outline.opml > outline.md
+npx @restless-dreams/orbit convert --to opml my-map.md --out my-map.opml
+```
+
+Warnings go to stderr. With `--out`, a workbook's other sheets go next to the first (`garden-2.md`, `garden-3.md`) and its pictures in `media/` beside them; without it, Orbit writes the first sheet and says what it left out.
+
+## What comes over
+
+Everything a reader would miss comes over, as Orbit says it. Titles keep every word on one line, and an emoji at the start of a title becomes its icon, as in Orbit's own markdown. Notes in HTML become markdown: paragraphs, headings, lists, quotes, code, bold, italics, strikethrough, links and pictures. When markdown would show a note's words any other way (a `*` or `_` in it, or a line that starts like a list), the note stays plain text instead, exactly as written, without its formatting.
+
+| | OPML | FreeMind and Freeplane | XMind |
+| --- | --- | --- | --- |
+| Note | `_note` (also `note`, and a feed's `description`) | the note and Freeplane's details, in HTML or plain text, and attributes as a list | the note, in HTML or plain text; XMind 8's comments, with their authors |
+| Link | `type="link"`'s or an include's `url`, a feed's `htmlUrl` or `xmlUrl` | `LINK` | the topic's link |
+| Links between ideas | `#id` | links to other nodes, and arrow links | links to other topics, and relationships |
+| Status | `_status` (`checked`, `unchecked`, `indeterminate`), `_complete`, `complete` | Freeplane's progress icons and checkboxes | task markers |
+| Priority | | priority icons (`full-1` to `full-9`) | priority markers |
+| Icon | an emoji at the start of the text | built-in icons, as emoji, and Freeplane's emoji | markers and stickers, as emoji |
+| Tags | `category` | | labels |
+| Color | | the background color | the fill color a topic was given |
+| Folded | | `FOLDED` | folded branches |
+| Picture | | a picture on the web | pictures inside the workbook, and on the web |
+
+An idea with a link of its own keeps it, and a second link, or a link between ideas with a label, becomes a line of its note: `→ [builds on](#chapter-2)`.
+
+## Warnings
+
+What has no place in a tree of ideas keeps its content where it can, and each kind gets one warning that counts the places and names a few:
+
+| Code | What changed |
+| --- | --- |
+| `floating-ideas-moved` | XMind's floating topics are ideas under the center. |
+| `summaries-moved` | XMind's summaries are ideas beside the ideas they sum up. |
+| `callouts-moved` | XMind's callouts are ideas under the topic they point at. |
+| `boundaries-in-notes` | A titled boundary's title is in the note of the idea whose ideas it surrounds. |
+| `links-in-notes` | A link beyond an idea's first, or a labeled link between ideas, is a line of its note. |
+| `missing-link-targets` | A link to an idea that isn't in the map (another sheet's, or one deleted) was left out. |
+| `icons-not-kept` | An icon with no emoji like it, or one past an idea's first, was left out. |
+| `pictures-not-kept` | A picture that isn't in the file was left out. |
+| `attachments-not-kept` | A file attached to an idea was left out; the idea keeps its name. |
+| `local-links-not-kept` | A link to a file on the computer the map was made on was left out. |
+| `encrypted-branches-not-read` | A branch FreeMind or Freeplane encrypted with a password couldn't be read; its ideas were left out. |
+| `formatting-not-kept` | A note is plain text, without its formatting, because markdown would have shown its words differently. |
+
+Styles (fonts, shapes, line colors) and positions are left out without a warning: Orbit draws every map its own way.
+
+## Write OPML
+
+`exportOPML` writes a map, as markdown or YAML text or a document, as OPML 2.0:
+
+```ts
+import { exportOPML } from '@restless-dreams/orbit';
+
+const opml = exportOPML(markdown, { title: 'Launch plan' });
+```
+
+- The root is the one top outline, and each node an outline with its icon and text in `text`.
+- A note goes in `_note`, as its markdown or plain text.
+- A link is `type="link"` with its `url`, a link between ideas included (`#research`).
+- A status is `_status`: `checked`, `unchecked` and `indeterminate` for `done`, `todo` and `active`, which outliners show as checkboxes; any other word as it is. Done statuses add `_complete="true"`, which Workflowy reads.
+- Tags are `category`, separated by commas.
+- `title` names the outline in its head. Default: the map's `title`, or its root's text.
+
+Two attributes only Orbit reads say what the text alone can't: `_noteFormat` when a note would read the other way (a markdown note with a line break, which OPML readers show as two lines, or a plain one that looks like markdown), and `_textFormat="plain"` when a title looks like HTML. With them, a map Orbit writes reads back the same: its text, icons, notes, statuses, links, tags and tree. Pictures, videos, colors, priorities and folds have no place in OPML; the map's own file, or a zip of it and its pictures, keeps them.

package/skills/orbit/references/languages.md

@@ -0,0 +1,160 @@
+<!-- A copy of docs/languages.md, made by scripts/build-llms.ts, with links to other files pointing at the repository. Edit the original. -->
+
+# Languages
+
+Orbit speaks the language of the page it's on: its buttons, the detail sheet, the media viewer, the list of the map, its messages and everything screen readers hear about the map. English and Spanish are built in. You can add any other language, change single words, or pick a language for one map.
+
+Only Orbit's own words change. The text of a map is the author's, and so are the status words written in it (`status: done` shows as "done"). Problems Orbit reports about a map's source (in the console, `orbit validate` and diagnostics) stay in English: they're for the map's author and their tools.
+
+## Which language a map speaks
+
+A map speaks the language of the element it's drawn in: the closest `lang` attribute around it, through shadow roots, and then the page's own `<html lang>`. A page in Spanish gets its maps in Spanish with nothing to set:
+
+```html
+<html lang="es">
+  …
+  <orbit-map># Viaje
+## Comida
+## Lugares</orbit-map>
+```
+
+The `language` option picks a language for one map, whatever the page says:
+
+```ts
+createOrbitMap(element, markdown, { language: 'es' });
+```
+
+```tsx
+<OrbitMindMap source={markdown} language="es" />
+```
+
+On `<orbit-map>`, set its `lang` attribute, as on any element: `<orbit-map lang="es">`.
+
+Languages are [BCP 47 tags](https://www.rfc-editor.org/info/bcp47). A regional tag speaks its language with the region's numbers and plurals: `es-MX` and `es-ES` both speak Spanish, writing 24,000 and 24.000. A language Orbit doesn't have speaks English, and so does a map on a page that names none.
+
+Changing the language later, with `setOptions({ language })`, the `language` prop or the element's `lang` attribute, writes the map's words again where they are.
+
+## Adding a language
+
+`registerLanguage` adds a language for every map, by its tag. Words it leaves out are English, or, for a regional tag like `pt-BR`, its base language's (`pt`) when Orbit has it:
+
+```ts
+import { registerLanguage } from '@restless-dreams/orbit';
+
+registerLanguage('fr', {
+  focus: 'Focus',
+  overview: 'Vue d’ensemble',
+  zoomIn: 'Zoomer',
+  zoomOut: 'Dézoomer',
+  ideaCount: { one: '{count} idée', many: '{count} d’idées', other: '{count} idées' },
+  // …the rest of the words in the table below.
+});
+```
+
+It returns a function that takes the language away again. Registering a language Orbit already has changes its words for every map: `registerLanguage('es', { video: 'Vídeo' })`. `languageTags()` lists the languages maps can speak.
+
+### Placeholders, plurals and lists
+
+- **Placeholders:** words in braces (`{name}`, `{count}`) are filled in for you. Keep them in a translation, in whatever order the language needs.
+- **Plurals:** text with a number is an object of plural forms, one for each [plural category](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/select) the language uses (`zero`, `one`, `two`, `few`, `many`) and `other`, which is required and covers any form left out.
+- **Numbers and lists:** numbers are written the way the language writes them, and lists like "has note, image, and link" are joined the language's way ("tiene nota, imagen y enlace").
+
+## Changing single words
+
+The `strings` option changes words on one map, over its language's:
+
+```ts
+createOrbitMap(element, markdown, { strings: { zoomIn: 'Closer', zoomOut: 'Further' } });
+```
+
+A word Orbit doesn't have, or one of the wrong kind, is skipped with a warning in the console.
+
+## The root Orbit makes up
+
+A map that's just a list, or has several top headings, and has no title gets a root Orbit makes up, named "Untitled map" in the map's language. When you parse maps yourself, `parseOrbit(source, { untitled: 'Mapa sin título' })` gives it that name. Its id is `untitled-map` in every language, so links and saved places keep working, and saving the map writes it as the list it was.
+
+## Without a browser
+
+`renderToSVGString(markdown, { language: 'es' })` writes the drawing's few words in a language: an untitled idea's name, the empty map's message and the map's title when it has none. On the command line: `orbit render map.md --language es`.
+
+## Every word
+
+| Key | English | Spanish |
+| --- | --- | --- |
+| `mindMap` | Mind map | Mapa mental |
+| `mindMapRole` | mind map | mapa mental |
+| `untitled` | Untitled | Sin título |
+| `untitledMap` | Untitled map | Mapa sin título |
+| `emptyMap` | This map is empty | Este mapa está vacío |
+| `emptyMapHint` | Start it with a # heading or a bullet list | Empiézalo con un encabezado # o una lista con viñetas |
+| `mapNotDrawn` | This map couldn’t be drawn | No se pudo dibujar este mapa |
+| `mapNotDrawnReason` | The map could not be drawn. | No se pudo dibujar el mapa. |
+| `problemOnLine` | Line {line}: {message} | Línea {line}: {message} |
+| `mapPath` | Map path | Ruta del mapa |
+| `back` | Back | Atrás |
+| `backTo` | Back to {name} | Volver a {name} |
+| `backToParent` | Back to the parent node | Volver a la idea superior |
+| `view` | View | Vista |
+| `focus` | Focus | Enfoque |
+| `overview` | Overview | Vista general |
+| `showOutline` | Show the map as a list | Mostrar el mapa como lista |
+| `zoom` | Zoom | Zoom |
+| `zoomIn` | Zoom in | Acercar |
+| `zoomOut` | Zoom out | Alejar |
+| `fitMap` | Fit the map | Ajustar el mapa |
+| `scrollToZoom` | Use {key} + scroll to zoom the map | Usa {key} + desplazamiento para acercar o alejar el mapa |
+| `outline` | Map outline | Esquema del mapa |
+| `overviewAnnouncement` | Overview of the whole map | Vista general de todo el mapa |
+| `ideaCount` | one: {count} item; other: {count} items | one: {count} idea; many: {count} ideas; other: {count} ideas |
+| `added` | Added {name} | Se agregó {name} |
+| `removed` | Removed {name} | Se eliminó {name} |
+| `moved` | Moved {name} to {parent} | Se movió {name} a {parent} |
+| `movedToTop` | Moved {name} to the top | Se movió {name} al nivel superior |
+| `anIdea` | a node | una idea |
+| `status` | status {status} | estado {status} |
+| `statusLabel` | Status: {status} | Estado: {status} |
+| `has` | has {list} | tiene {list} |
+| `hasDetails` | details | detalles |
+| `hasNote` | note | nota |
+| `hasImage` | image | imagen |
+| `hasVideo` | video | video |
+| `hasEmbed` | embed | contenido insertado |
+| `hasLink` | link | enlace |
+| `textOf` | Text of {name} | Texto de {name} |
+| `newIdeaFor` | New idea for {name} | Idea nueva en {name} |
+| `newIdea` | New idea | Idea nueva |
+| `addIdeaTo` | Add an idea to {name} | Agregar una idea a {name} |
+| `moveHere` | Move {name} here | Mover {name} aquí |
+| `thisIdea` | this node | esta idea |
+| `theIdea` | the idea | la idea |
+| `ideaActions` | {name} actions | Acciones de {name} |
+| `ideaActionsUntitled` | Node actions | Acciones de la idea |
+| `showDetails` | Show details | Ver detalles |
+| `viewImage` | View image | Ver imagen |
+| `viewImageOf` | View image: {description} | Ver imagen: {description} |
+| `playVideo` | Play video | Reproducir video |
+| `openEmbed` | Open embed | Abrir contenido insertado |
+| `readNote` | Read note | Leer nota |
+| `openLink` | Open link | Abrir enlace |
+| `goTo` | Go to {name} | Ir a {name} |
+| `seeIdea` | See {name} | Ver {name} |
+| `details` | Details | Detalles |
+| `close` | Close | Cerrar |
+| `previous` | Previous | Anterior |
+| `next` | Next | Siguiente |
+| `present` | Present | Presentar |
+| `priority` | Priority {priority} | Prioridad {priority} |
+| `expand` | Expand | Ampliar |
+| `expandVideo` | Expand the video | Ampliar el video |
+| `picture` | Picture | Imagen |
+| `video` | Video | Video |
+| `position` | {index} of {total} | {index} de {total} |
+| `fitPicture` | Fit the picture | Ajustar la imagen |
+| `pictureUnavailable` | This picture can’t be shown. | No se puede mostrar esta imagen. |
+| `videoUnavailable` | This video can’t be played. | No se puede reproducir este video. |
+| `videoUnavailableHere` | This video can’t be played here. | Este video no se puede reproducir aquí. |
+| `openPictureInNewTab` | Open the picture in a new tab | Abrir la imagen en una pestaña nueva |
+| `openVideoInNewTab` | Open the video in a new tab | Abrir el video en una pestaña nueva |
+| `watchOn` | Watch on {provider} | Ver en {provider} |
+
+`OrbitStrings` in the [API reference](https://github.com/restless-dreams/orbit/blob/main/docs/api/README.md) says where each one shows.

package/skills/orbit/references/map-tools.md

@@ -0,0 +1,188 @@
+<!-- A copy of docs/map-tools.md, made by scripts/build-llms.ts, with links to other files pointing at the repository. Edit the original. -->
+
+# Map tools for AI
+
+Map tools let a language model read a map and change it: add ideas and whole branches, rename them, mark them done, move, sort and remove them. They come in the shape each provider's API takes, so an app can offer an assistant with whichever model its people choose. They work on a map on screen, where every change animates into place, or on a document on a server. A call a model gets wrong changes nothing, and its result says what to send instead.
+
+## Add an assistant to a map
+
+`createMapTools(map)` gives the tools for one map. `tools.for(provider)` lists them for the model, and `tools.run(name, input)` carries out each call it makes. With Anthropic's API:
+
+```js
+import Anthropic from '@anthropic-ai/sdk';
+import { createOrbitMap, createMapTools } from '@restless-dreams/orbit';
+
+const map = createOrbitMap(element, markdown, { onEdit: () => save(map.toMarkdown()) });
+const tools = createMapTools(map);
+const client = new Anthropic({ apiKey });
+
+const ask = async (request) => {
+  const messages = [{ role: 'user', content: request }];
+
+  while (true) {
+    const response = await client.messages.create({ model, max_tokens: 4096, system: tools.instructions, tools: tools.for('anthropic'), messages });
+    messages.push({ role: 'assistant', content: response.content });
+    const calls = response.content.filter((block) => block.type === 'tool_use');
+
+    if (calls.length === 0) {
+      return response.content.find((block) => block.type === 'text')?.text;
+    }
+
+    messages.push({
+      role: 'user',
+      content: calls.map((call) => {
+        const result = tools.run(call.name, call.input);
+        return { type: 'tool_result', tool_use_id: call.id, content: result.text, is_error: !result.ok };
+      }),
+    });
+  }
+};
+
+await ask('Add three day trips from Kyoto, each with a one-sentence note');
+```
+
+The map changes as the model works: each new idea flies out of its parent, and `edit` fires for each change, so the map saves as it does when people edit it. Keep API keys off public pages: call the model from your server, or let each person bring their own key.
+
+## Other providers
+
+**OpenAI's Responses API:**
+
+```js
+const input = [{ role: 'user', content: request }];
+
+while (true) {
+  const response = await openai.responses.create({ model, instructions: tools.instructions, tools: tools.for('openai'), input });
+  const calls = response.output.filter((item) => item.type === 'function_call');
+
+  if (calls.length === 0) {
+    return response.output_text;
+  }
+
+  input.push(...response.output);
+
+  for (const call of calls) {
+    input.push({ type: 'function_call_output', call_id: call.call_id, output: tools.run(call.name, call.arguments).text });
+  }
+}
+```
+
+`run` takes the arguments as OpenAI sends them, as JSON text. The tools are written without strict mode, which would make the model send every field of every call.
+
+**Chat Completions,** which most other providers and local servers (OpenRouter, Ollama and many more) offer as well as OpenAI:
+
+```js
+const messages = [{ role: 'system', content: tools.instructions }, { role: 'user', content: request }];
+
+while (true) {
+  const response = await client.chat.completions.create({ model, messages, tools: tools.for('openai-chat') });
+  const message = response.choices[0].message;
+  messages.push(message);
+
+  if (!message.tool_calls?.length) {
+    return message.content;
+  }
+
+  for (const call of message.tool_calls) {
+    messages.push({ role: 'tool', tool_call_id: call.id, content: tools.run(call.function.name, call.function.arguments).text });
+  }
+}
+```
+
+**Gemini,** with `@google/genai`:
+
+```js
+const contents = [{ role: 'user', parts: [{ text: request }] }];
+
+while (true) {
+  const response = await ai.models.generateContent({ model, contents, config: { systemInstruction: tools.instructions, tools: tools.for('gemini') } });
+  const calls = response.functionCalls ?? [];
+
+  if (calls.length === 0) {
+    return response.text;
+  }
+
+  contents.push(response.candidates[0].content);
+  contents.push({
+    role: 'user',
+    parts: calls.map((call) => {
+      const result = tools.run(call.name, call.args);
+      return { functionResponse: { name: call.name, response: result.ok ? { output: result.text } : { error: result.text } } };
+    }),
+  });
+}
+```
+
+**MCP:** `tools.definitions` are tools as MCP lists them (`name`, `description`, `inputSchema` and `annotations`). A server returns them for `tools/list`, and answers `tools/call` with `{ content: [{ type: 'text', text: result.text }], isError: !result.ok }`.
+
+For anything else, such as the Vercel AI SDK or LangChain, build the tools from `tools.definitions`: each has a name, a description, and its input as JSON Schema.
+
+## The tools
+
+| Tool | What it does | Takes |
+| --- | --- | --- |
+| `read_map` | The map as an outline: each node's title, id and attributes, and the start of its note. A big map is cut short, whole levels first, with what's left out counted. | `node_id` (to read one branch), `depth` |
+| `find_nodes` | Searches titles, notes and tags, in any case and with or without accents, and statuses by what they mean: `done` finds `shipped` too. | `query`, `status`, `tag` |
+| `read_node` | Everything about one node: its whole note, its picture, video or page, where it is, its children, and the nodes that link to it. | `node_id` |
+| `add_nodes` | Adds nodes, or whole branches, written as a markdown list. | `parent_id`, `outline`, `index` |
+| `update_node` | Changes a title or attributes, and `clear` removes attributes. | `node_id`, `text`, `note`, `status`, `priority`, `tags`, `icon`, `color`, `link`, `image`, `video`, `embed`, `collapsed`, `clear` |
+| `move_node` | Moves a branch under another node, or to another place among its siblings. | `node_id`, `parent_id`, `index` |
+| `reorder_children` | Puts all the children of a node in a new order at once: to sort them, or to group them. | `parent_id`, `order` |
+| `remove_node` | Removes a branch. Never the root. | `node_id` |
+| `show_node` | Flies the map to a node. Only on a map on screen. | `node_id` |
+
+New ideas come as orbit-md, the way models write any outline: each list item is a node, the items indented under it are its children, at any depth, and indented text that isn't an item is its note. Checkboxes, an emoji first, hashtags at the end and `<!-- orbit … -->` comments set statuses, icons, tags and other attributes, as in any map:
+
+```json
+{
+  "parent_id": "marketing",
+  "outline": "- Social media\n  - [ ] Instagram #social\n  - TikTok\n- Newsletter\n  A weekly email with what shipped."
+}
+```
+
+## What a call returns
+
+`run` returns `{ ok, text, changed }`:
+
+- **`text`** is for the model: send it back as the tool's result. It names nodes with their ids (`"Instagram" #instagram`), gives the new id when a new title changes one, and adds notes worth knowing, such as an id the model wrote as a title, a field the tool doesn't take, or two ideas with the same title side by side.
+- **`ok`** is false when the call couldn't be carried out. Nothing changed, and `text` says why and what to send instead:
+
+```text
+No node has the id "lanch". Did you mean "Launch" #launch? read_map and find_nodes give every node's id.
+
+"Build" #build can't go under "Frontend" #frontend, which is inside it. Move "Frontend" #frontend out of it first, or choose another parent. Nothing changed.
+
+outline doesn't read cleanly. Fix this, and send it again:
+- Line 2: Unknown attribute "colour". Did you mean "color"?
+Lines count from the outline's first line. Nothing changed.
+```
+
+- **`changed`** says whether the map changed.
+
+`run` never throws over a call a model gets wrong. It forgives what models often send: input as JSON text, `null` for a field left out, a number as text, tags as words separated by commas, an id with its `#`, a title only one node has instead of its id, and a field under the name models often give it (`title` for `text`, `parent` for `parent_id`). An id from before a rename still finds its node, and the id of a removed node says it was removed. A misspelled field, or a value the map can't use, changes nothing and says what it takes.
+
+## On screen, or on a server
+
+- **A map on screen:** `createMapTools(map)` takes what `createOrbitMap` returns, the `renderer` of an `<orbit-map>` element, or the `renderer` of `OrbitMindMap`'s ref. Each change goes through `addNode`, `updateNode`, `moveNode` and `removeNode` (see [Editing](editing.md)): it animates, Orbit announces it, and `edit` fires. `read_map` says which node the reader is looking at, and `show_node` takes them to one.
+- **A document:** `createMapTools(markdown)` or `createMapTools(parseOrbit(markdown))`, on a server or anywhere without a map on screen. The tools change the document in place, and `serializeOrbitMarkdown(tools.document)` saves it, the way it was written apart from what changed.
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { createMapTools, serializeOrbitMarkdown } from '@restless-dreams/orbit';
+
+const tools = createMapTools(markdown);
+tools.run('add_nodes', { parent_id: 'research', outline: '- Interviews\n- Survey' });
+await writeFile('map.md', serializeOrbitMarkdown(tools.document));
+```
+
+Options:
+
+- **`readOnly: true`** offers only the tools that read (and `show_node`, on screen): for an assistant that answers questions about a map.
+- **`readLimit`**: the most nodes `read_map` shows at once. Default 250.
+
+## Good to know
+
+- **Instructions.** `tools.instructions` says how to use the tools, and asks for short titles with the detail in notes, ideas in the map's language, and nodes removed only when asked: put it in the system prompt. To save the model a first call, put `tools.run('read_map').text` in the first message too.
+- **Undo.** Keep `map.toMarkdown()` from before a request: `map.render(saved)` puts the map back, animating to it.
+- **Asking first.** Each definition's `annotations` say whether the tool only reads (`readOnlyHint`) and whether it can overwrite or remove something (`destructiveHint`). An app can run the tools that read at once and ask before the others, as MCP clients do.
+- **Schemas every provider reads.** The inputs use plain JSON Schema, without references or unions, and new branches come as markdown rather than nested objects, which some providers' schemas can't describe.
+- **Newer maps.** A map written for a newer version of the format can be read but not changed, so nothing this version doesn't understand is lost.

package/skills/orbit/references/media.md

@@ -0,0 +1,160 @@
+<!-- A copy of docs/media.md, made by scripts/build-llms.ts, with links to other files pointing at the repository. Edit the original. -->
+
+# Pictures and videos
+
+A node's picture shows inside its planet, and a video shows its thumbnail with a play badge ([Media](format.md#media) has how to write them). Under the node in focus, "View image" and "Play video" open them in the media viewer, over the whole window.
+
+- [The media viewer](#the-media-viewer)
+- [Keys](#keys)
+- [Choosing what the buttons do](#choosing-what-the-buttons-do)
+- [From code](#from-code)
+- [Events](#events)
+- [YouTube and Vimeo](#youtube-and-vimeo)
+- [Sound and autoplay](#sound-and-autoplay)
+- [Maps that aren't interactive](#maps-that-arent-interactive)
+- [Looks](#looks)
+
+## The media viewer
+
+The viewer covers the whole window, even when the map sits in a small box on a page, and follows the map's theme, light or dark.
+
+- **Pictures** fit the window, never past twice their own size. The wheel, a pinch, a double click or tap, the `+`, `−` and `0` keys and the zoom buttons zoom around the point under the pointer or between the fingers, and a zoomed picture pans with a drag. Zooming goes to four times the fitted size, or until the picture shows at twice its own size if that's further.
+- **Videos** start at once: files (`.mp4`, `.webm`, `.mov`) in the browser's own player, YouTube and Vimeo in theirs. The player is as big as the window allows, at the video's shape once it's known (16:9 until then, upright for YouTube Shorts). Stepping away from a video stops it.
+- **Every picture and video of the map,** in reading order (the order the outline lists the map, a node's picture before its video): the previous and next buttons, the arrow keys and, on touch screens, a swipe step through them, starting from the one opened. A counter says where you are ("2 of 5"), and screen readers hear it.
+- **Around them,** the node's title, the caption, and the picture's description (its alt text, which is also the picture's name for screen readers), with a link to open the picture on its own, or the video on its site.
+- **Closing:** Esc, the close button, a click around the media or, on touch screens, a swipe down while the picture isn't zoomed. Focus goes back where it was, and the map's own keys, which rest while the viewer is open, work again.
+
+The detail sheet shows a node's picture and video too. Its picture opens the viewer, over the sheet, and its video has an Expand button that moves it there (a video file goes on from where it was); closing the viewer goes back to the sheet.
+
+## Keys
+
+| Key | Does |
+| --- | --- |
+| `←` `→` | The previous or next picture or video; on a zoomed picture, pan it |
+| `↑` `↓` | Pan a zoomed picture |
+| `Home` `End` | The first or last picture or video |
+| `+` `−` `0` | Zoom in, zoom out, fit the picture to the window |
+| `Space` | Play or pause the video |
+| `Escape` | Close the viewer |
+
+On a video's own controls, the arrow keys and the space bar are the player's. Inside YouTube's and Vimeo's players every key is theirs, Escape included: Tab out of the player, or click around it, to close the viewer.
+
+## Choosing what the buttons do
+
+The buttons ask your code first, as every button does: `onAction`, then the `action` event. What happens next:
+
+| Your code | "View image" and "Play video" |
+| --- | --- |
+| Nothing | Open the media viewer |
+| `mediaViewer: false` | Open the detail sheet at the picture or video, as before the viewer |
+| `mediaViewer: false` and `showDetailSheet: false` | Nothing: Orbit opens neither |
+| `showDetailSheet: false` | Open the media viewer: it turns off only the sheet, for notes, embeds and details |
+| `onAction` returns `false`, or `preventDefault()` on the `action` event | Nothing: the press is yours |
+
+The detail sheet's picture and Expand button are presses of "View image" and "Play video" too: your code sees them first, and when it takes one the sheet closes, so what you open is in front. With `mediaViewer: false`, the sheet's picture is only a picture.
+
+```js
+createOrbitMap(element, markdown, {
+  onAction: ({ node, action }) => {
+    if (action === 'image') {
+      openMyLightbox(node.image.src);
+      return false;
+    }
+
+    return undefined;
+  },
+});
+```
+
+## From code
+
+A page can open the viewer itself, to show a picture big or play a video on a screen of its own:
+
+```js
+map.openMedia('summit');                                    // a node's picture, or its video if it has no picture
+map.openMedia('trail', { kind: 'video', autoplay: false }); // its video, ready to play
+map.openMedia('trail', { kind: 'video', startAt: 42 });     // its video, playing from 0:42
+map.playMedia();
+map.seekMedia(42);
+map.pauseMedia();
+map.unmuteMedia();                                          // from a press: the sound of a video a browser started muted
+map.closeMedia();
+```
+
+| Method | Does |
+| --- | --- |
+| `openMedia(nodeId, { kind, autoplay, startAt })` | Shows the node's picture (`kind: 'image'`, the default when it has one) or video (`kind: 'video'`), opening the viewer if it's closed. A video starts playing unless `autoplay` is `false`, from its start or `startAt` seconds in (YouTube and Vimeo start at the whole second). Returns `false` when the map has no such node, or the node no such picture or video. |
+| `closeMedia()` | Closes the viewer. |
+| `playMedia()`, `pauseMedia()` | Plays or pauses the video it shows. Returns `false` when it shows no video it can drive. |
+| `seekMedia(seconds)` | Moves the video to `seconds` from its start. Returns `false` when it shows no video it can drive. |
+| `unmuteMedia()` | Turns on the sound of the video it shows. Browsers allow it only from a press (see [Sound and autoplay](#sound-and-autoplay)). Returns `false` when it shows no video it can drive. |
+
+`openMedia` opens the viewer whatever `mediaViewer`, `showDetailSheet` and `interactive` say: those choose what the buttons do. Files, YouTube and Vimeo can be driven; a video on any other site plays in a frame, with its own controls only. `<orbit-map>` has the same six methods.
+
+This is what an audience's screen does while someone presents from a phone: it opens what the presenter opens, where the presenter's video is, and follows the presenter's player, and tells the phone how the video is going.
+
+```js
+const map = createOrbitMap(element, markdown, { interactive: false, showControls: false });
+
+presenter.addEventListener('message', ({ data }) => {
+  if (data.type === 'media') {
+    map.openMedia(data.id, { kind: data.kind, autoplay: data.playing, startAt: data.seconds });
+  } else if (data.type === 'play') {
+    map.playMedia();
+  } else if (data.type === 'pause') {
+    map.pauseMedia();
+  } else if (data.type === 'seek') {
+    map.seekMedia(data.seconds);
+  } else if (data.type === 'close') {
+    map.closeMedia();
+  }
+});
+
+map.on('media-state', ({ node, playing, time }) => {
+  presenter.postMessage({ type: 'state', id: node.id, playing, time });
+});
+```
+
+## Events
+
+| Event | DOM event | Detail |
+| --- | --- | --- |
+| `media-open` | `orbit-media-open` | `{ node, kind, index, total }`: the viewer opened, or stepped, on a node's picture (`kind: 'image'`) or video (`'video'`), `index` of `total` in reading order, from 0 |
+| `media-close` | `orbit-media-close` | `{ node, kind, index, total }`: the viewer closed, showing that |
+| `media-state` | `orbit-media-state` | `{ node, playing, time, duration, ended, muted }`: the video started, paused, moved to another time, ended or was muted, at once; while it plays, its time a few times a second. `time` and `duration` are in seconds; `duration` is `null` until it's known |
+
+`onMediaOpen`, `onMediaClose` and `onMediaState` receive the same, and so do the React props of the same names. The DOM events bubble from the map's container and out of `<orbit-map>`.
+
+## YouTube and Vimeo
+
+YouTube videos play in YouTube's privacy-enhanced player (`youtube-nocookie.com`), and Vimeo videos in Vimeo's with `dnt=1`, which tracks no sessions. Links to watch pages, `youtu.be`, Shorts, Vimeo channels, groups, showcases and unlisted videos all work; Orbit frames their players, never their pages, which refuse to be framed.
+
+- **The referrer:** the players' frames send the page's origin, never its address (`referrerpolicy="strict-origin-when-cross-origin"`). YouTube's player won't play without knowing the site it's on (its "Error 153"), and a page that sends no referrer (`Referrer-Policy: no-referrer`) still gives its origin to these frames. A page opened from a file has no origin to give, so YouTube's videos don't play there.
+- **Driving them:** `playMedia`, `pauseMedia` and `seekMedia` reach the players through the messages their own JavaScript APIs send (YouTube's `enablejsapi=1`, with the page's `origin`; Vimeo's player.js messages), and `media-state` follows what the players say. Nothing is loaded from either site but the player itself.
+- **Other sites:** a video on any other site plays in a frame, as the detail sheet shows an embed, with only its own controls: `playMedia` and its kin return `false` for it, and it reports no `media-state`.
+
+## Sound and autoplay
+
+Browsers let a video start with sound only once the reader has interacted with the page. A press of "Play video", the arrows or a swipe counts, so those videos play with sound.
+
+A video opened from code on a page nobody has touched yet, such as an audience's screen, may not be allowed to. A video file then starts muted, and its `media-state` says `muted: true`. YouTube's and Vimeo's players decide for themselves: they start muted, or wait for a press. Screens that should play sound from the start can allow it: a kiosk Chrome with `--autoplay-policy=no-user-gesture-required`, or an Android `WebView` with `setMediaPlaybackRequiresUserGesture(false)`.
+
+Elsewhere, offer a button for the sound while `media-state` says the video is muted, or isn't playing when it should. Its press counts as interacting with the page, so `unmuteMedia()` and `playMedia()` from its click play the video with sound, YouTube's and Vimeo's included. The viewer is a modal `<dialog>` in the top layer, and a modal dialog makes the rest of the page inert, popovers included: show the button in a `<dialog>` of its own with `showModal()`, after the viewer opens, so it's on top and can be pressed.
+
+```js
+soundButton.addEventListener('click', () => {
+  map.unmuteMedia();
+  map.playMedia();
+  soundDialog.close();
+});
+```
+
+## Maps that aren't interactive
+
+On a map with `interactive: false`, a still picture, the viewer is the page's to drive. It shows the picture or video with its title and caption, but no buttons, no counter and no controls on videos, and it takes no input of its own: Esc and clicks don't close it, and keys and presses reach the page, so a presentation's own keys keep working. Open, close and play it with the methods above.
+
+## Looks
+
+The viewer takes its colors from the detail sheet's custom properties: `--orbit-sheet-background` behind the media (blurred by `--orbit-sheet-blur` where it's see-through, as in the glass themes), `--orbit-sheet-text` and `--orbit-sheet-muted-text` for the title, caption and counter, and `--orbit-sheet-shadow` under a video. Its buttons are the map's controls (`--orbit-control-*`, `--orbit-focus-ring`). See [Theming](theming.md#custom-properties).
+
+With reduced motion (`prefers-reduced-motion: reduce`), zooms and steps happen at once instead of gliding and fading.