@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/skills/orbit/references/extending.md

@@ -0,0 +1,247 @@
+<!-- A copy of docs/extending.md, made by scripts/build-llms.ts, with links to other files pointing at the repository. Edit the original. -->
+
+# Extending Orbit
+
+Orbit has four ways to make maps your own: **node types**, **actions**, **status words** and **themes**. Each works for one map, through its options, or for every map once registered, which also covers `<orbit-map>` elements and maps in markdown pages, where you don't write code per map. A map's own options win over registered ones.
+
+| | For one map | For every map |
+| --- | --- | --- |
+| Node types | `nodeTypes: { milestone: { … } }` | `registerNodeType('milestone', { … })` |
+| Actions | `actions: [{ id, label, run }]` | `registerAction({ id, label, run })` |
+| Status words | `statuses: { review: 'active' }` | `registerStatus('review', 'active')` |
+| Themes | `theme: { preset, tokens }` | `registerTheme('brand', { preset, tokens })` |
+
+Each `register…` function returns a function that removes the registration again.
+
+## Node types
+
+A node picks a type with the `type` attribute, in any case:
+
+```markdown
+# Launch
+## v1.0 beta <!-- orbit type: milestone -->
+- Ana Torres <!-- orbit type: person, role: Design -->
+```
+
+In YAML it's `type: milestone`. The type decides how those nodes look and behave:
+
+```js
+import { createOrbitMap } from '@restless-dreams/orbit';
+
+createOrbitMap(element, markdown, {
+  nodeTypes: {
+    milestone: {
+      label: 'Milestone',
+      icon: '🏁',
+      color: '#F59E0B',
+      tokens: { 'node-stroke': '#B45309', 'node-stroke-width': '3' },
+    },
+    person: {
+      label: 'Person',
+      render(node, element) {
+        element.textContent = node.text.split(' ').map((word) => word[0]).join('');
+      },
+      details(node, element) {
+        element.textContent = `Role: ${node.attrs?.role ?? 'not set'}`;
+      },
+      actions: [{ id: 'email', label: 'Email', icon: '✉️', run: (node) => window.open(`mailto:${node.attrs?.email}`) }],
+    },
+  },
+});
+```
+
+| Key | What it does |
+| --- | --- |
+| `label` | The type's name for people, shown as a chip in the detail sheet, in the tooltip and to screen readers. |
+| `icon` | The icon these nodes get unless they set their own. |
+| `color` | The color these nodes get unless they set their own. Their children take shades of it. |
+| `tokens` | [Theme tokens](theming.md#custom-properties) for these nodes only, without `--orbit-`: their rim, shadow, glow, label and status colors. |
+| `render(node, element)` | Draws inside the node, the way a picture does. `element` is a 100 × 100 px box, clipped to the node's circle and scaled with it, and the label moves outside, onto a pill that shows the node's icon before its name. Return a function to clean up; it runs when the node leaves the map. |
+| `details(node, element)` | Adds a section to the detail sheet, above the note. These nodes get a "Show details" button. |
+| `actions` | Actions only these nodes offer, after the map's own. |
+| `version` | The version of the fields these nodes keep in their attributes, once the type changes them (1 at first). See [Versions](#versions). |
+| `upgrade(node, from)` | Brings a node written for an older version of the type up to date. |
+
+- **Custom attributes** like `<!-- orbit role: Design -->` are on `node.attrs`, which makes them handy in `render` and `details`.
+- **`render` is for showing:** clicks go through to the node, so use actions for anything to press. It runs when the node comes on the map; navigating away and back draws it again.
+- **Errors stay contained:** if a type's `render` or `details`, or an action, throws, the console says which one and the map keeps working.
+
+### Types for display only
+
+`nodeTypeFor(node)` gives a node that names no type one to be drawn as, as if it said `type: name`: that type's look, what it draws inside and its actions. It's for display only: Orbit never writes it to the map, so saving keeps the node as it was, and never upgrades a node for it.
+
+```js
+createOrbitMap(element, markdown, {
+  nodeTypes: { progress: { label: 'Progress', render: drawProgressRing } },
+  // Ideas with to-dos right under them show a ring, unless they have a type of their own.
+  nodeTypeFor: (node) => (node.children.some((child) => child.status) ? 'progress' : undefined),
+});
+```
+
+- **A node's own `type` wins:** `nodeTypeFor` is only asked about nodes without one.
+- **It's asked whenever the map draws,** often, so keep it quick, and return `undefined` to draw a node as it is. An answer that changes with the map, after an edit to the node's children say, shows as the map draws the edit; after a change elsewhere that answers depend on, `render()` the map again.
+- **The type shows wherever a type does:** in the detail sheet's chip, the tooltip, what screen readers hear, `data-orbit-type`, the label's font and exports (`renderToSVGString(source, { nodeTypes, nodeTypeFor })`).
+- **If it throws,** the console says so once, and nodes are drawn as they are.
+
+### Versions
+
+A type's nodes keep their own fields in attributes, so changing those fields changes what older maps say. Give the type a `version` and an `upgrade` that brings older nodes up to date:
+
+```js
+registerNodeType('task', {
+  label: 'Task',
+  version: 2,
+  // Version 1 kept the person in `assignee`; version 2 calls it `owner`.
+  upgrade(node, from) {
+    if (from < 2 && node.attrs?.assignee !== undefined) {
+      const { assignee, ...rest } = node.attrs;
+      node.attrs = { ...rest, owner: assignee };
+    }
+  },
+});
+```
+
+- **Nodes say which version they were written for:** `type: task@2`; none means 1. A map upgrades older nodes when it draws them, and the next save writes them as `task@2` with their new fields, changing nothing else in the file.
+- **Nodes written for a newer version** than the type knows are left as they are, and saving keeps everything in them.
+- **Without a map** (on a server, in a script), `upgradeNodeTypes(document.root, nodeTypes)` does the same, with the types you pass and the registered ones, and returns how many nodes it upgraded.
+- **If `upgrade` throws,** the console says which type failed and the node stays as it was.
+
+## Actions
+
+Actions are buttons under the node in focus, after Orbit's own (details, picture, video, note, link), and in the node's detail sheet.
+
+```js
+createOrbitMap(element, markdown, {
+  actions: [
+    {
+      id: 'assign',
+      label: 'Assign',
+      icon: '👤',
+      when: (node) => node.children.length === 0,
+      run: (node, event) => openAssignDialog(node),
+    },
+  ],
+});
+```
+
+| Key | What it does |
+| --- | --- |
+| `id` | The action's name in the `action` event. Use ids other than Orbit's own: `details`, `image`, `video`, `embed`, `note` and `link`. |
+| `label` | The button's name, read by screen readers, shown as its tooltip and in the detail sheet. A function gets the node: ``(node) => `Assign ${node.text}` ``. |
+| `icon` | An emoji or short symbol (`'✏️'`), SVG path data on a 24-unit grid (`'M4 20h4L20 8l-4-4L4 16z'`), or one of Orbit's icons: `note`, `link`, `goto`, `info`, `image`, `video`, `embed`, `list`. Without one, the label's first letter. |
+| `when(node)` | Which nodes offer it. Default: every node. |
+| `run(node, event)` | What it does. |
+
+- **The `action` event fires first** (`orbit-action` on the element), with `action` set to the id. `preventDefault()` there, or returning `false` from `onAction`, skips `run`.
+- **In the detail sheet,** pressing an action closes the sheet first, so a dialog your action opens is in front.
+- **One button per id:** a map's own action wins over a registered one with the same id, and a node type's actions come last.
+
+## Status words
+
+`status` is free text, and [some words](format.md#statuses) get a colored dot. Add your own words, as one of the tones or with a color of their own:
+
+```js
+createOrbitMap(element, markdown, {
+  statuses: {
+    review: 'active',
+    shipped: 'done',
+    'on hold': '#A855F7',
+  },
+});
+```
+
+The tones are `active`, `done`, `blocked`, `todo` and `neutral`; their colors come from the theme (`--orbit-status-active`, …). Words match in any case.
+
+## Themes
+
+Register a theme once to use it by name everywhere: in options, in a document's frontmatter and on `<orbit-map theme="…">`.
+
+```js
+import { registerTheme } from '@restless-dreams/orbit';
+
+registerTheme('brand', {
+  preset: 'night',
+  tokens: { 'color-root': '#FFD166', 'color-1': '#06D6A0', surface: '#0B1020' },
+});
+```
+
+```markdown
+---
+theme: brand
+---
+# Launch
+```
+
+- **What a theme is:** it starts from `preset` (a built-in theme or another registered one) and sets its own [tokens](theming.md#custom-properties).
+- **Building on it:** a theme object can start from a registered theme too. `{ preset: 'brand', tokens: { … } }` adds its tokens to brand's.
+- **Names:** built-in names can't be reused, and `themeNames()` lists every name.
+- **Validation:** `orbit validate` doesn't know the themes your code registers, so it reports `theme: brand` as unknown.
+
+## For every map
+
+Register at startup, before maps are created. Maps created earlier pick up registered types, actions and words when they next redraw.
+
+```js
+import { defineOrbitMapElement, registerAction, registerNodeType, registerStatus, registerTheme } from '@restless-dreams/orbit';
+
+registerTheme('brand', { preset: 'night', tokens: { 'color-root': '#FFD166' } });
+registerNodeType('milestone', { label: 'Milestone', icon: '🏁', color: '#F59E0B' });
+registerStatus('review', 'active');
+registerAction({ id: 'copy-link', label: 'Copy link', icon: 'link', run: (node) => navigator.clipboard.writeText(`${location.href}#${node.id}`) });
+defineOrbitMapElement();
+```
+
+```html
+<orbit-map theme="brand">
+# Launch
+## v1.0 beta <!-- orbit type: milestone, status: review -->
+</orbit-map>
+```
+
+The functions they return remove the registrations again, which helps with hot reloading and tests.
+
+## In React
+
+`<OrbitMindMap>` takes the same options as props. Inline objects are fine: the map compares what node types and actions declare, and calls their latest functions, `nodeTypeFor`'s too.
+
+```tsx
+import { OrbitMindMap } from '@restless-dreams/orbit/react';
+
+export const Roadmap = ({ markdown, onAssign }: { markdown: string; onAssign: (id: string) => void }) => {
+  return (
+    <div style={{ height: 480 }}>
+      <OrbitMindMap
+        source={markdown}
+        nodeTypes={{ milestone: { label: 'Milestone', icon: '🏁', color: '#F59E0B' } }}
+        actions={[{ id: 'assign', label: 'Assign', icon: '👤', run: (node) => onAssign(node.id) }]}
+        statuses={{ review: 'active' }}
+      />
+    </div>
+  );
+};
+```
+
+## Styling nodes with CSS
+
+Each node's element and label carry hooks for CSS:
+- `data-orbit-type`: the type, lowercase;
+- `data-orbit-status`: the status word, lowercase;
+- `data-orbit-tags`: the tags, separated by spaces.
+
+Page CSS can target these on maps drawn with `createOrbitMap` or React:
+
+```css
+.orbit-node[data-orbit-type='milestone'] .orbit-node__shade {
+  stroke-dasharray: 4 3;
+}
+
+.orbit-label[data-orbit-tags~='urgent'] {
+  font-weight: 800;
+}
+```
+
+A map inside `<orbit-map>` sits in a shadow root that page CSS can't reach, so use a type's `tokens` there.
+
+## Exports
+
+`toSVGString()`, `renderToSVGString()` and `orbit render` draw node types' icons, colors and tokens, and your status colors. `renderToSVGString(source, { nodeTypes, statuses, nodeTypeFor })` takes them as options too. What `render` draws is HTML, so it isn't part of an exported SVG.

package/skills/orbit/references/format.md

@@ -0,0 +1,331 @@
+<!-- A copy of docs/format.md, made by scripts/build-llms.ts, with links to other files pointing at the repository. Edit the original. -->
+
+# Map format
+
+The complete reference for writing Orbit maps. A map is a tree: one root, and nodes with children. Write it in **orbit-md**, Orbit's markdown (the default, for maps people write), or in **YAML** (for maps programs write). `npx @restless-dreams/orbit example` prints a map with the main features, and `npx @restless-dreams/orbit validate map.md` checks one.
+
+- [Markdown](#markdown)
+  - [The tree](#the-tree)
+  - [Node titles](#node-titles)
+  - [Notes](#notes)
+  - [Links between nodes](#links-between-nodes)
+  - [Media](#media)
+  - [Attributes](#attributes)
+  - [Statuses](#statuses)
+- [Document options](#document-options)
+- [YAML](#yaml)
+- [Which flavor a document is](#which-flavor-a-document-is)
+- [Node ids](#node-ids)
+- [Checking a map](#checking-a-map)
+
+## Markdown
+
+```markdown
+---
+title: Product roadmap
+theme: night
+---
+# 🚀 Product roadmap
+What ships this year.
+
+## Research <!-- orbit status: done -->
+Six weeks of interviews before we commit to scope.
+- [x] User interviews
+- Competitor teardown #market
+
+## Build
+### Frontend
+- [/] App shell
+- Offline sync <!-- orbit status: blocked -->
+  Waits on the [backend](#backend) sync API.
+### Backend
+
+## [Launch](https://example.com/launch-plan)
+![The launch poster](images/poster.png)
+```
+
+### The tree
+
+**Every heading and every list item is a node.** Everything else belongs to the node above it.
+
+- **Headings** (`#` to `######`) nest by level: a heading's children are the headings below it, up to the next heading at its own level or higher. A line underlined with `===` is a `#` heading, and with `---` a `##` heading. Headings may be indented up to three spaces and end with closing `#`s.
+- **Lists** are children of the heading above them, every list, in the order written next to that heading's subheadings. Bullets (`-`, `*`, `+`) and numbered items (`1.`, `1)`) work the same. Indent an item further than the one above it to nest it under that item; lists go as deep as you like, past the six heading levels. A tab counts as four spaces.
+- **The root** is the single top heading: the only heading at the highest level used, usually `#`. Several top headings share a root, as do the top items of a document that is just a list: it's named after the frontmatter `title`, a one-line paragraph above them, or "Untitled map". A list with a single top item is rooted at that item. Text before the root heading belongs to the root.
+- A ```` ```orbit ```` or `~~~orbit` fence around the whole map is fine: `parseOrbit` unwraps it.
+
+### Node titles
+
+A heading's text, or a list item's first line, is the node's title, read in this order:
+
+| Written | Becomes |
+| --- | --- |
+| `[ ] Draft` / `[x] Ship` / `[/] Build` | status `todo` / `done` / `active` |
+| `🚀 Launch` (emoji first) | icon `🚀`, text `Launch` |
+| `Offline sync #frontend #sprint-3` | tags `frontend` and `sprint-3`, text `Offline sync` |
+| `Launch [plan](https://…)` | text `Launch plan`, link `https://…` |
+| `**Frontend**`, `*Docs*`, `` `api` ``, `~~Old idea~~` | the text without the symbols |
+| `Launch <!-- orbit status: active -->` | an attribute, inline (see [Attributes](#attributes)) |
+
+- **Hashtags** count at the end of a title, after a space, and need a letter: `C# rewrite` and `Fix #42` stay as written.
+- **Links:** a title that is all link works the same; with several links, the first is the node's link.
+- **A backslash** keeps a character as written: `\*not bold\*`, `ship \#notatag`, `\[x] not a task`.
+
+They combine: `## 📈 [Growth](https://example.com/growth) #q3 <!-- orbit status: active -->`.
+
+### Notes
+
+A note is longer text shown in the detail sheet, as markdown. Everything under a heading or list item that isn't a heading or list item is its note: paragraphs, `>` quotes, code blocks and tables.
+
+- Under a list item, indent the note under it, as you would write anything under a heading. A line right after the item, with no blank line between, continues the item too.
+- To keep a list inside a note, instead of making it children, quote it with `>`: headings and bullets inside a quote stay note text.
+
+```markdown
+# Launch
+## Research
+Questions to answer:
+> - Who buys it?
+> - Why now?
+
+- Frontend
+  Vite and React. Ships behind the beta flag.
+- Backend
+```
+
+### Links between nodes
+
+A link to `#id` points at another node of the map, the way `#heading` links point at headings in a page: a note link like `[Research](#research)`, or a node whose link is `#research`. It flies to that node instead of opening a page.
+
+```markdown
+# Launch
+## Build
+Starts when [Research](#research) is done.
+## [Read the research](#research)
+## Research
+```
+
+The id is the node's text in lowercase with dashes (see [Node ids](#node-ids)); `#Research` and GitHub-style `#-research` find it too. A link to a node the map doesn't have is reported.
+
+### Media
+
+A node shows its image (or its video's thumbnail) inside it. Its image and video open over the whole window, in the media viewer ([Pictures and videos](media.md)), and its embed in the detail sheet. Put each on a line of its own under the heading, or indented under the list item:
+
+| Line | Becomes |
+| --- | --- |
+| `![Alt text](images/photo.jpg)` | the image |
+| `[Trailer](https://www.youtube.com/watch?v=…)` | the video: YouTube, Vimeo, or a `.mp4`, `.webm` or `.mov` file |
+| `[![Alt text](thumbnail.jpg)](https://vimeo.com/…)` | the video, with that thumbnail |
+| `[Any other link](https://…)` | note text |
+
+A node has at most one image, one video and one embed; extra media lines stay in the note. Embeds (a page shown in a frame) are set with the `embed` attribute. To read a media line differently, follow it with `<!-- orbit contentType: image -->` (or `video`, `embed`, or `none` to keep it as note text), and caption it the same way, with `<!-- orbit caption: The summit at dawn -->` right under it. Relative URLs resolve against `baseUrl`.
+
+```markdown
+# Trip
+- Summit
+  ![The summit at dawn](images/summit.jpg)
+- Trail
+  [Walkthrough](https://www.youtube.com/watch?v=aqz-KE-bpKQ)
+```
+
+Attributes set media too: `<!-- orbit image: images/photo.jpg -->`.
+
+### Attributes
+
+Attributes go in an HTML comment that starts with `orbit` (in any case, with or without a colon after it), written as YAML:
+
+```markdown
+## Build
+<!-- orbit
+color: "#F5A3A8"
+status: active
+priority: 1
+tags: [frontend, sprint-3]
+-->
+
+- Frontend <!-- orbit status: active -->
+- Backend
+  <!-- orbit
+  image: diagrams/backend.png
+  note: Talks to the billing service.
+  -->
+```
+
+- **Block form**: on the lines after a heading, or indented under a list item. Any number of keys. A block written right under a list item without its indent still belongs to the heading above the list, and an `attributes-after-list` note says so: indent it to set the list item's.
+- **Inline form**: at the end of a heading or list item's line. Separate several with commas: `<!-- orbit status: active, priority: 1 -->`.
+- **Other HTML comments** are hidden, as markdown hides them: Orbit keeps them in the file, out of titles, ids and notes as they're shown, and a renamed idea keeps the ones at the end of its title. One that reads like attributes but doesn't start with `orbit` (`<!-- status: done -->`) sets nothing, and a `comment-without-orbit` note says how to write it.
+
+| Key | Value | Example | Effect |
+| --- | --- | --- | --- |
+| `color` | any CSS color | `"#F5A3A8"`, `tomato` | The node's color, instead of its branch's. Its children take shades of it. |
+| `paletteColor` | number | `3` | Which of the palette's colors the node takes when it has no `color`: `1` is the first after the root's, cycling. Its children take shades of it. Editing on the map writes it to keep an idea's color (see [Colors](#colors)). |
+| `icon` | emoji or short symbol | `🚀`, `"★"` | Shown before the text. Same as an emoji at the start of the title. |
+| `status` | text | `active`, `done`, `blocked` | Shown in the detail sheet; some words get a colored dot (see [Statuses](#statuses)). |
+| `priority` | number | `1` | Shown in the detail sheet. |
+| `tags` | list of text | `[frontend, sprint-3]` | Shown in the detail sheet. A single word works too, and so do words separated by commas: `tags: frontend, sprint-3`. Hashtags at the end of the title add to them. |
+| `collapsed` | `true` / `false` | `true` | Hides the node's children (they show as a "+N" count) until you fly into it. |
+| `link` | URL, or `#id` | `https://example.com` | Offered as a button when the node is in focus. Same as a link in the title. `#id` goes to another node (see [Links between nodes](#links-between-nodes)). |
+| `note` | text | `Ships in May.` | The node's note. Same as a paragraph or blockquote. |
+| `noteFormat` | `markdown` / `plain` | `plain` | How the note is shown. Default `markdown`. |
+| `image` | URL, or `{ src, alt, caption }` | `images/photo.jpg` | The node's image. |
+| `video` | URL, or `{ src, provider, thumbnail, caption }` | `https://youtu.be/…` | The node's video. `provider`: `youtube`, `vimeo` or `native`. |
+| `embed` | URL, or `{ src, caption }` | `https://example.com/demo` | A page shown in a frame in the detail sheet. |
+| `caption` | text | `The summit at dawn.` | Caption for the media line just above it, or for the one image, video or embed set next to it. Anywhere else, for the node's video, embed or image (in that order). |
+| `id` | text | `launch` | The node's id, instead of one made from its text (see [Node ids](#node-ids)). |
+| `type` | text | `milestone` | The node's type. A type your code defines sets its look, content and actions (see [Extending](extending.md#node-types)). Any case. |
+| `contentType` | `image` / `video` / `embed` / `none` | `embed` | Markdown only: how to read the media line just above. |
+
+Any other key is kept as a **custom attribute** in `node.attrs`, for your own code (`<!-- orbit owner: Ana -->`). A key that looks like a misspelled attribute (`colour`, `stauts`) is kept too, with a warning that suggests the right one.
+
+### Statuses
+
+`status` is free text, shown as written. These words (any case) also get a colored dot on the node and in the detail sheet:
+
+| Dot | Words |
+| --- | --- |
+| active (blue) | `active`, `doing`, `in progress`, `wip`, `started`, `ongoing` |
+| done (green) | `done`, `complete`, `completed`, `shipped`, `finished`, `closed` |
+| blocked (red) | `blocked`, `stuck`, `at risk`, `failed` |
+| todo (gray) | `todo`, `to do`, `planned`, `backlog`, `next`, `open` |
+
+Other words get a neutral dot. Checkboxes set `todo` (`[ ]`), `done` (`[x]`) and `active` (`[/]`).
+
+### Colors
+
+The root takes the palette's first color: the theme's, or the frontmatter's `palette`. The top-level nodes take the others in turn, cycling, and deeper nodes take shades of their branch's color, so siblings stay apart. A node's own `color` wins, then its type's.
+
+`paletteColor` gives a node one of the palette's colors by number, so it still changes with the theme. The top-level nodes without one take turns with the colors no top-level node has by number: give two nodes the same number for them to share a color.
+
+Edits keep the colors of the nodes around them, on screen and through the map tools: adding, moving or removing a top-level node writes `paletteColor` where a color would change otherwise, as few times as it can.
+
+- A moved node keeps its color, and a new one takes a color no other top-level node has, while there is one.
+- A node moved under another one drops its `paletteColor` and takes its new branch's shade.
+- Where the top level has more nodes than the palette has colors, colors repeat, and an edit that would write more numbers than there are colors writes none.
+
+## Document options
+
+Set in the frontmatter (markdown) or as top-level keys (YAML). Options passed in code win over these.
+
+| Key | Value | Default | |
+| --- | --- | --- | --- |
+| `title` | text | the root's text | The map's accessible name and SVG title. Names the root when a document has no single top heading. |
+| `theme` | `paper`, `night`, `glass`, `glass-night`, `cosmos`, `blueprint`, `ink`, `contrast`, `flat`, `flat-night`, `material`, `material-night`, `liquid`, `liquid-night` or `auto` | `paper` | See [Theming](theming.md). |
+| `view` | `focus` or `all` | `focus` | The first view: one node with its children around it, or the overview of the whole tree. |
+| `palette` | list of colors | the theme's | The root's color, then one per top-level branch, cycling. A comma-separated string works too. |
+| `maxDepth` | number | all levels | Levels below the root to draw: `1` is the root and its children. |
+| `showRings` | `true` / `false` | `true` | Draw the orbit rings. |
+| `interactive` | `true` / `false` | `true` | `false` draws a still picture. |
+| `animation` | `true` / `false` | `false` | Let the orbit drift slowly on its own. |
+| `speed` | seconds | `90` | Seconds per turn of that drift. |
+| `height` | pixels | `420` | Height of `<orbit-map>` elements and marked placeholders. |
+| `baseUrl` | URL | | Resolves relative image, video and link URLs. |
+| `className` | text | | Class names added to the map's element. |
+| `schemaVersion` | number | | The version of the format the document is written for: `1`. See [Versions](#versions). |
+| `flavor` | `markdown` or `yaml` | | Forces the flavor (see [Which flavor a document is](#which-flavor-a-document-is)). |
+
+Flags also read `yes`, `no`, `on` and `off`.
+
+## YAML
+
+For maps that programs generate:
+
+```yaml
+title: Product roadmap
+theme: night
+nodes:
+  - text: Product roadmap
+    icon: 🚀
+    note: What ships this year.
+    children:
+      - text: Research
+        status: done
+        children: [User interviews, Competitor teardown]
+      - text: Build
+        status: active
+        children:
+          - text: Frontend
+            children:
+              - App shell
+              - text: Offline sync
+                status: blocked
+      - text: Launch
+        link: https://example.com/launch-plan
+        image: images/poster.png
+```
+
+- `nodes` is a list with the root node. Several top-level nodes share a root named after `title`, as in markdown.
+- A node is a map with `text` and optionally `children`, plus any [attribute](#attributes) (`icon`, `color`, `status`, `link`, `note`, `image`, …) as a key. Custom keys are kept in `node.attrs`. A node without `text` but with `title`, `name` or `label`, or without `children` but with `items`, `nodes` or `subnodes`, is read with those as its text and children, and reported (`misnamed-node-key`) until they're renamed.
+- A plain string in `children` is a node with just that text.
+- Document options go at the top level, next to `nodes`.
+
+## Which flavor a document is
+
+`parseOrbit` reads a document as YAML when its frontmatter says `flavor: yaml`, its first line is `nodes:`, or the whole text reads as a YAML map: one with a `nodes:` list, or one that starts with a document option (`title:`, `theme:`, `view:`, …). Anything else is markdown, so a first line like `Status: draft`, or a note that starts with `nodes:`, stays markdown. `parseOrbitMarkdown` and `parseOrbitYAML` skip the detection.
+
+## What saving keeps
+
+Orbit never drops what a document says, even what it doesn't read:
+
+- **Saving keeps the file as it was written.** `serializeOrbitMarkdown` (and a map's `toMarkdown()`) write a document parsed from markdown back line for line, and only the ideas an edit changed are written again: a renamed idea gets a new title line, a checked-off item a new checkbox, a moved idea takes its lines along. So a note written by hand or by another app keeps its formatting, its frontmatter keys, its HTML comments and rules, and its link definitions at the end. `{ keepSource: false }` writes the whole map in Orbit's own form instead; so does `orbit convert`.
+- **Keys and values Orbit doesn't read are kept.** Frontmatter and top-level YAML keys it doesn't know are on `document.extra`, and both serializers write them back, with any changes an app makes to them: an app can keep a setting of its own there. A document without `extra` changes none of them, so no key another app wrote is lost; an `extra` object, even `{}`, changes or removes them. An attribute Orbit doesn't know is a custom attribute on `node.attrs`; a value it can't read for one of its own (a list for `status`, a word for `priority`) is reported and kept there under its own name. A picture or video keeps fields Orbit doesn't use (`width`, a `provider` it doesn't know).
+- **A file that isn't a map yet** (only paragraphs) is a root with the text as its note: adding the first idea gives it a heading and keeps the text.
+
+## Versions
+
+A document says which version of the format it's written for with `schemaVersion`; none means `1`, the current one.
+
+- **Older documents are upgraded as they're read.** When the format changes, Orbit brings documents written for the version before up to date as it reads them (a `format-upgraded` note says so), and the next save writes them as the new version, changing only what the upgrade changed.
+- **Newer documents are read as well as they can be,** and reported with `unsupported-schema-version`, an error: apps should open them without letting them be edited. Nothing in them is lost by saving, but what this version doesn't know of them isn't understood either.
+- **Node types have versions of their own,** for the fields their nodes keep in attributes: `type: task@2` says a node was written for version 2 of `task`, and none means 1. A type that changes its fields says so with `version` and brings older nodes up to date with `upgrade` (see [Extending Orbit](extending.md#versions)); a node written for a newer version of its type is left as it is.
+
+### Changing the format
+
+Maps outlive the version of Orbit that wrote them. Older and newer versions read them, and so do apps that bundle a copy of their own. So each change to the format is one of three kinds:
+
+- **Something older versions can do without:** a new attribute (like `paletteColor`) or a new document option. An older version keeps the attribute as a custom one, and the option as an unknown frontmatter key, which it reports. It writes both back unchanged and draws the map as it did before. No new version of the format is needed.
+- **Something an older version would misread:**
+  - a new kind of value for an attribute it already reads: Orbit 0.1.0 takes `color: 3` for a color and draws it wrong, without a word;
+  - new syntax in titles or notes: it shows `==First==` as text;
+  - an attribute renamed, removed, or given a new meaning.
+
+  These raise `schemaVersion`, with a step in `FORMAT_UPGRADES` (`src/core/format-upgrades.ts`) that brings documents written for the version before up to date. Older versions then report `unsupported-schema-version`, and apps open those maps read-only.
+- **A change to a node type's own fields:** the type gets a new `version` and an `upgrade` (see [Extending Orbit](extending.md#versions)), not a new version of the format.
+
+`tests/fixtures/releases/` holds maps as each released version wrote them. Every version must read each one without errors, write it back exactly, and understand it the same way, after its upgrades.
+
+## Node ids
+
+Each node gets an id from its text: lowercase, accents folded, other letters kept (`Investigación` → `investigacion`, `研究` → `研究`, `Q3 plan` → `q3-plan`). Repeated ids get `-2`, `-3`, … in tree order. Set `id` to choose one; ids are what `renderer.flyTo(id)`, the `focus` export option and the React `focusedId` prop take.
+
+## Checking a map
+
+Parsing is forgiving: when something is wrong but the map can still be drawn, the parser works around it and records a diagnostic with a `code`, a `severity`, a message that says how to fix it and the `line` where it has one. `{ strict: true }` throws an `OrbitParseError` on the first one instead, except for the few that only note something and leave the map valid: `unknown-attribute` (kept as your own attribute), `synthetic-root`, `caption-without-media`, `format-upgraded`, `ignored-node-entry`, `comment-without-orbit` and `attributes-after-list`.
+
+```bash
+npx @restless-dreams/orbit validate map.md          # every problem as map.md:line: severity: message [code]
+npx @restless-dreams/orbit validate --json map.md   # the same as JSON: valid, flavor, root, nodes, depth, diagnostics
+npx @restless-dreams/orbit validate --tree map.md   # the map as Orbit reads it, a node a line with its #id
+```
+
+`validate` exits with 1 while the map has a problem that makes it invalid, and lists the notes too (add `--loose` to accept the problems the map works around, but never a map it can't read).
+
+| Code | Meaning |
+| --- | --- |
+| `empty-document` | Nothing to draw. |
+| `no-structure` | No headings or lists (markdown), or no `nodes:` list (YAML). |
+| `synthetic-root` | Several top headings, items or YAML nodes and no title, so the root is called "Untitled map". |
+| `invalid-frontmatter` | The frontmatter isn't valid YAML `key: value` pairs. |
+| `unknown-frontmatter-key` | A frontmatter key Orbit doesn't know: kept and written back, but not used. The message names the one you probably meant. |
+| `unknown-yaml-key` | The same, for a YAML document's top-level keys. |
+| `invalid-option-value` | A document option with a value Orbit can't use, such as an unknown theme or a `flavor` other than `markdown` or `yaml`. |
+| `unsupported-schema-version` | The document is written for a newer version of the format (an error: open it without editing it). |
+| `format-upgraded` | The document was written for an older version of the format and read as the current one; saving writes it in the current one. |
+| `invalid-attributes` | An attribute block isn't valid YAML, or a value has the wrong type: kept as written, but not used. |
+| `unknown-attribute` | A key that looks like a misspelled attribute, kept as a custom one. |
+| `media-missing-source` | An `image`, `video` or `embed` without a URL. |
+| `unknown-content-type` | `contentType` isn't `image`, `video`, `embed` or `none`. |
+| `caption-without-media` | A `caption` on a node with no image, video or embed. |
+| `unknown-link-target` | A `#id` link points at no node of the map; the message suggests the id you probably meant. |
+| `invalid-yaml` | The YAML document can't be read. |
+| `ignored-node-entry` | A YAML node that is neither a map nor text. |
+| `comment-without-orbit` | An HTML comment that reads like attributes (`<!-- status: done -->`) but doesn't start with `orbit`, so it sets nothing. |
+| `attributes-after-list` | An attribute block right under a list item, without its indent: it sets the heading's attributes, not the item's. |
+| `misnamed-node-key` | A YAML node's text under `title`, `name` or `label`, or its children under `items`, `nodes` or `subnodes`: read as them, but write `text` and `children`. |