@restless-dreams/orbit 0.0.0-stage → 0.1.0

package/llms.txt

@@ -0,0 +1,35 @@
+# Orbit
+
+> Mind maps written in markdown and explored like a solar system. The node in focus is the sun, its children orbit it as planets and their children are moons; readers click a planet to fly into it, zoom, and flick the orbit to spin it. Framework-agnostic and dependency-free, with a web component, React and marked integrations, SVG export without a browser, and a command line.
+
+- Install with `npm install @restless-dreams/orbit`. The package is ESM-only. React (`@restless-dreams/orbit/react`) and marked (`@restless-dreams/orbit/marked`) are optional peers.
+- A map fills its container: always give the container a height.
+- Write maps in orbit-md, Orbit's markdown (every heading and list item is a node, text under it is its note, `<!-- orbit key: value -->` comments set attributes), or in YAML (`nodes:` with `text` and `children`).
+- Check a map with `npx @restless-dreams/orbit validate --json map.md`: every problem comes with a suggested fix, and its line where it has one. `npx @restless-dreams/orbit example` prints a map with the main features, and `orbit convert --to yaml map.md` (or `--to md`) turns one flavor into the other.
+- Draw one with `createOrbitMap(element, markdown, options)`, the `<orbit-map>` element, `<OrbitMindMap source={markdown} />` from `@restless-dreams/orbit/react`, or `renderToSVGString(markdown, options)` without a browser.
+- Share a map as one web page, which opens in any browser, offline: `npx @restless-dreams/orbit export --html map.md --out map.html`.
+- Let people build the map on the map with `editable: true` (a + in the orbit, text typed inside nodes), and save what they make with `map.toMarkdown()` on the `edit` event.
+- Let a language model read and change a map with `createMapTools(map)`: `tools.for('anthropic' | 'openai' | 'openai-chat' | 'gemini')` lists the tools for its API, and `tools.run(name, input).text` is each call's result.
+- Maps speak the page's language (`lang`): English and Spanish are built in, `registerLanguage` adds more.
+- Themes: `paper` (default), `night`, `glass`, `glass-night`, `cosmos`, `blueprint`, `ink`, `contrast`, `flat`, `flat-night`, `material`, `material-night`, `liquid`, `liquid-night`, `auto`. Pass `theme: 'night'` or `theme: { preset: 'night', tokens: { … } }`, or set `--orbit-*` CSS custom properties.
+
+## Docs
+
+- [Map format](https://github.com/restless-dreams/orbit/blob/main/docs/format.md): headings, lists, notes, media, every attribute and document option, the YAML flavor, and every diagnostic code
+- [README](https://github.com/restless-dreams/orbit/blob/main/README.md): install and a quick start for each way to draw a map
+- [Guide](https://github.com/restless-dreams/orbit/blob/main/docs/guide.md): every renderer option, event and method, the React component, the element, marked, pictures and videos, SVG export and the command line
+- [Recipes](https://github.com/restless-dreams/orbit/blob/main/docs/recipes.md): plain HTML, React and Next.js, Vue, Svelte, Astro, remark and rehype, static sites
+- [Theming](https://github.com/restless-dreams/orbit/blob/main/docs/theming.md): the fourteen themes, Material themes from any color, and every CSS custom property
+- [Extending](https://github.com/restless-dreams/orbit/blob/main/docs/extending.md): node types, your own actions, status words and named themes, for one map or every map
+- [Editing](https://github.com/restless-dreams/orbit/blob/main/docs/editing.md): context menus on a long press, adding, renaming, moving and removing nodes on the map, and saving the result as orbit-md
+- [Map tools for AI](https://github.com/restless-dreams/orbit/blob/main/docs/map-tools.md): tools for any model to read and change a map, on screen or on a server, for each provider's API and MCP
+- [Languages](https://github.com/restless-dreams/orbit/blob/main/docs/languages.md): maps in the page's language, English and Spanish built in, adding languages and changing single words
+- [Pictures and videos](https://github.com/restless-dreams/orbit/blob/main/docs/media.md): the media viewer, its keys, YouTube and Vimeo, sound and autoplay, and opening, playing and following media from code
+- [Coding agents](https://github.com/restless-dreams/orbit/blob/main/docs/agents.md): the skill, validation as JSON, and messages for setup mistakes
+- [Everything in one file](https://cdn.jsdelivr.net/npm/@restless-dreams/orbit/llms-full.txt): the README and all of the guides above, for the latest release
+- [Website](https://orbit.hyuchia.com): live examples, the themes side by side, setup for each integration, and a playground to write a map and explore it in the browser
+
+## Optional
+
+- [Accessibility](https://github.com/restless-dreams/orbit/blob/main/docs/accessibility.md): keyboard, screen readers, reduced motion and contrast
+- [API reference](https://github.com/restless-dreams/orbit/blob/main/docs/api/README.md): every export, generated from the types

package/package.json

@@ -1,6 +1,120 @@
 {
   "name": "@restless-dreams/orbit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Markdown-first orbit/solar-system mind map renderer.",
+  "keywords": [
+    "markdown",
+    "mind-map",
+    "mindmap",
+    "svg",
+    "react",
+    "marked",
+    "visualization"
+  ],
+  "author": "Diana Islas Ocampo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/restless-dreams/orbit.git"
+  },
+  "homepage": "https://orbit.hyuchia.com",
+  "bugs": {
+    "url": "https://github.com/restless-dreams/orbit/issues"
+  },
+  "packageManager": "bun@1.4.2",
+  "bin": {
+    "orbit": "./dist/bin/orbit.js"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "skills",
+    "llms.txt",
+    "llms-full.txt",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./marked": {
+      "types": "./dist/marked/index.d.ts",
+      "default": "./dist/marked/index.js"
+    },
+    "./web-page.js": {
+      "types": "./dist/web-page.d.ts",
+      "default": "./dist/web-page.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build:js": "bun run scripts/build.ts",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build": "bun run build:js && bun run build:types",
+    "test": "bun test",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "verify": "bun run lint && bun run typecheck && bun run test && bun run build && bun run check:dist && bun run lint:package",
+    "check:dist": "bun run scripts/check-dist.ts",
+    "clean": "rm -rf dist",
+    "pack:lib": "bun run build && bun pm pack",
+    "prepack": "bun run build",
+    "lint:package": "publint --strict && attw --pack . --profile esm-only",
+    "test:browser": "bun run build && docker run --rm --ipc=host -e CI -v \"$PWD\":/work -w /work mcr.microsoft.com/playwright:v1.63.0-noble node node_modules/@playwright/test/cli.js test",
+    "bench": "bun run build && docker run --rm --ipc=host -v \"$PWD\":/work -w /work mcr.microsoft.com/playwright:v1.63.0-noble node scripts/bench-animations.mjs",
+    "docs:api": "typedoc",
+    "docs:llms": "bun run scripts/build-llms.ts"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "marked": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "marked": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/js": "^9.0.0",
+    "@happy-dom/global-registrator": "^20.9.0",
+    "@playwright/test": "1.63.0",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "bun-types": "^1.3.13",
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^14.0.0",
+    "marked": "^18.0.3",
+    "publint": "^0.3.25",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "sass": "^1",
+    "typedoc": "^0.28",
+    "typedoc-plugin-markdown": "^4",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.0.0"
+  }
+}

package/skills/orbit/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: orbit
+description: Write, check and embed Orbit mind maps (@restless-dreams/orbit), written in markdown (orbit-md) or YAML and drawn as interactive solar systems you fly through, or as SVG pictures. Use when asked to make, draw or visualize a mind map, or to turn an outline, roadmap or other hierarchy into an interactive map or a picture of one, or when code uses @restless-dreams/orbit, createOrbitMap, the orbit-map element, OrbitMindMap, renderToSVGString or the orbit command. Not for flowcharts, sequence or architecture diagrams, or charts.
+---
+
+# Orbit
+
+Orbit draws a tree as a solar system: the node in focus is the sun, its children orbit it as planets, and their children are moons. Readers click a planet to fly into it, zoom, and flick the orbit to spin it. Maps are written in orbit-md, its markdown (headings and lists), or in YAML.
+
+## Write a map
+
+```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
+<!-- orbit
+status: active
+color: "#C6B4F2"
+-->
+### Frontend
+- [/] App shell
+- Offline sync <!-- orbit status: blocked -->
+  Waiting on the [storage review](#storage-review).
+### Storage review
+
+## [Launch](https://example.com/launch-plan)
+![The launch poster](images/poster.png)
+```
+
+- Every heading and every list item is a node; everything else belongs to the node above it. One top heading is the root (several share one named after `title`). Every list under a heading is its children; indent list items to nest them.
+- Text under a heading, or indented under a list item, is the node's note (markdown, shown in the detail sheet). Quote a bullet list with `>` to keep it in the note instead of making children.
+- An emoji at the start of a title is the node's icon; a link in the title sets its link (`#id` flies to that node); `[ ]` / `[x]` / `[/]` set status `todo` / `done` / `active`; hashtags at the end are tags. `**bold**`, `*italics*` and `` `code` `` show as plain text; a backslash keeps a character literal.
+- A line with only `![alt](src)` is the node's image. A line with only a markdown link to a YouTube or Vimeo video, or to an `.mp4`, `.webm` or `.mov` file, is its video: `[Trailer](https://youtu.be/…)` (a bare address stays text in the note). Under a list item, indent them.
+- Attributes go in `<!-- orbit key: value -->` (at the end of a line; separate several with commas) or a block `<!-- orbit … -->` (YAML, after a heading or indented under a list item): `color`, `icon`, `status`, `priority` (a number), `tags` (a list, or words separated by commas), `collapsed`, `type`, `link`, `note`, `noteFormat`, `image`, `video`, `embed`, `caption`, `id`. Other keys are kept as your own attributes. Other HTML comments are hidden, as in markdown: `<!-- status: done -->` without `orbit` sets nothing, and `validate` says so.
+- Status words with a colored dot: `active`, `done`, `blocked`, `todo` (and synonyms such as `in progress`, `shipped`, `at risk`, `planned`).
+- Frontmatter: `title` (the map's accessible name too), `theme`, `view` (`focus` or `all`), `palette`, `maxDepth`, `showRings`, `interactive`, `animation`, `speed` (seconds per turn of the drift), `baseUrl`, `className`, and `height`, which sizes `<orbit-map>` and marked's placeholders only (in code and React, size the container).
+- Themes: `paper` (default), `night`, `glass`, `glass-night`, `cosmos`, `blueprint`, `ink`, `contrast`, `flat`, `flat-night`, `material`, `material-night`, `liquid`, `liquid-night`, `auto`. In code, `materialTheme('#0B57D0')` makes a Material theme from any color.
+- For everyone: give pictures alt text, keep titles short with the detail in notes, and don't say things with color alone (statuses have words).
+- `npx @restless-dreams/orbit example` prints a map with the main features; `npx @restless-dreams/orbit example --yaml` prints it as YAML.
+
+Every rule, with tables of attributes, options and diagnostics: [references/format.md](references/format.md).
+
+## Check it
+
+```bash
+npx @restless-dreams/orbit validate --json map.md
+```
+
+It prints `valid`, the `flavor`, the `root` text, the number of `nodes`, the `depth`, and `diagnostics`, each with a `code`, a `severity`, a message that says how to fix it ("Did you mean "status"?") and its `line` where it has one. It exits with 1 while the map has a problem: fix them and validate again until `valid` is true. Some diagnostics only note something and leave the map valid: an attribute Orbit doesn't know, kept as your own (`unknown-attribute`: fix it when it's a typo), a root made up for several top-level nodes (`synthetic-root`), a caption with no media and an upgraded format. `validate` doesn't know themes registered in code and reports them as unknown; `--loose` accepts that. Add `--tree` to print the map as Orbit reads it, a node a line with its `#id`: it shows what became a node, and the ids for `#id` links and `--focus`. In code, `parseOrbit(source).diagnostics` holds the same list.
+
+## Show it
+
+The map fills its container: **always give the container a height**, or nothing shows (the console says so).
+
+```ts
+// Any page: one call
+import { createOrbitMap } from '@restless-dreams/orbit';
+const map = createOrbitMap(document.querySelector('#map')!, markdown, { theme: 'auto' });
+map.on('focus-change', ({ node }) => console.log(node.text));
+```
+
+```html
+<!-- No build step: the web component -->
+<script type="module">
+  import { defineOrbitMapElement } from 'https://cdn.jsdelivr.net/npm/@restless-dreams/orbit/+esm';
+  defineOrbitMapElement();
+</script>
+<orbit-map height="420" theme="night">
+  # Launch
+  ## Research
+  ## Build
+</orbit-map>
+```
+
+```tsx
+// React and Next.js ("use client" is built in; it renders a static SVG on the server)
+import { OrbitMindMap } from '@restless-dreams/orbit/react';
+<div style={{ height: 480 }}><OrbitMindMap source={markdown} theme="cosmos" /></div>
+```
+
+```ts
+// No browser: static SVG for files, emails, server rendering
+import { renderToSVGString } from '@restless-dreams/orbit';
+const svg = renderToSVGString(markdown, { width: 1200, height: 800, theme: 'paper', viewMode: 'all' });
+```
+
+- **Afterwards:** `map.render(source)` redraws and keeps the reader's place, `map.setOptions({ … })` changes options, `map.flyTo(id)` and `map.overview()` move, and `map.destroy()` cleans up. Events come through `map.on(name, listener)`, or as `orbit-<name>` DOM events that bubble out of `<orbit-map>` (details in `event.detail`).
+- **Your own controls over the map:** `insets: { bottom: 72 }` fits each view into what a toolbar floating over the map leaves.
+- **From the command line:** `npx @restless-dreams/orbit render map.md --view all --out map.svg --theme night` draws the whole map; without `--view all` it draws it as it opens, where only the root and its children have labels. `orbit convert --to yaml map.md` (or `--to md`) turns one flavor into the other.
+- **To share a map for review** (with someone, or to the user's own phone): `npx @restless-dreams/orbit export --html map.md --out map.html` makes one web page with Orbit, the map and its pictures inside, which opens in any browser, offline, to explore or present.
+- **marked:** `new Marked(orbitMarked())` (from `@restless-dreams/orbit/marked`) turns ```` ```orbit ```` fences into placeholders, and `hydrateOrbitBlocks(container)` makes them maps. Fences take display options: ```` ```orbit height=480 view=all ````.
+
+Every option, event and method: [references/guide.md](references/guide.md). Vue, Svelte, Astro and markdown pipelines: [references/recipes.md](references/recipes.md).
+
+## Style it
+
+`theme` takes a name or `{ preset, tokens }`, where tokens are the CSS custom properties without `--orbit-`: `{ preset: 'night', tokens: { surface: '#0b1020', 'ring-dash': 'none' } }`. In CSS, set `--orbit-*` properties on the container; they win over the theme. All properties: [references/theming.md](references/theming.md).
+
+## Pictures, videos and languages
+
+- Pictures and videos open in a viewer over the whole window, to zoom into and to play, stepping through the map's media. `mediaViewer: false` shows them in the detail sheet instead, an `onAction` that returns `false` handles them yourself, and `map.openMedia(id)` opens one from code. YouTube's videos don't play in a page opened from a file: serve it. All of it: [references/media.md](references/media.md).
+- Maps speak the language of the closest `lang` around them: English and Spanish are built in, and other languages fall back to English. `language: 'es'` picks one, `strings: { … }` changes single words, `registerLanguage(tag, strings)` adds a language, and `orbit render --language es` draws in one. Every word: [references/languages.md](references/languages.md).
+
+## Extend it
+
+- **Node types:** a node picks one with `<!-- orbit type: milestone -->`. The `nodeTypes` option, or `registerNodeType(name, …)` for every map, sets the type's `label`, default `icon` and `color`, theme `tokens`, `render(node, element)` to draw inside the node, `details(node, element)` for the detail sheet, and its own `actions`.
+- **Actions:** `actions: [{ id, label, icon, when, run }]` (or `registerAction`) adds buttons under the focused node and in its detail sheet. They fire the `action` event with `action` set to the id.
+- **Status words and themes:** `statuses: { review: 'active', 'on hold': '#A855F7' }` (or `registerStatus`) colors status words. `registerTheme('brand', { preset, tokens })` makes `theme: brand` work in options, frontmatter and `<orbit-map theme>`.
+
+Every option, with examples: [references/extending.md](references/extending.md).
+
+## Edit it on the map
+
+- `editable: true` (or `<orbit-map editable>`): a + in the orbit adds ideas, typed inside their new planet, one after another; a long press, a right click or F2 edits a node's text in place, and a node held still lifts and can be dragged onto another node or along the orbit. Save on `edit` (its `kind` is `add`, `update`, `remove` or `move`) with `map.toMarkdown()`, or `serializeOrbitYAML(map.getDocument())` for a YAML map.
+- `editingKeys: true` as well (`<orbit-map editable editing-keys>`): Tab adds an idea under the node with keyboard focus, Shift+Enter one beside it, Delete removes it; while typing, Tab and Shift+Tab go a level down and up.
+- `onNodeContext: ({ node, x, y }) => …` (or `map.on('node-context', …)`) fires for a long press, a right click or the context menu key on a node: show your own menu at `x`, `y` (CSS pixels from the map's top left corner), and call `map.editNode(id)` or `map.editNewNode(parentId)` from it.
+- `map.addNode(parentId, { text, … }, index?)`, `map.updateNode(id, changes)` (`undefined` removes an attribute), `map.removeNode(id)` and `map.moveNode(id, parentId, index?)` change the map with an animation, fire `edit` (`onEdit`), and return the node, or `null` when there's nothing to do.
+- Ids follow the text: read a node's current id from what the method returns.
+- For an AI assistant in an app, `createMapTools(map)` gives a language model tools to read the map and change it: `tools.for('anthropic' | 'openai' | 'openai-chat' | 'gemini')` for its API (`tools.definitions` for MCP), `tools.instructions` for its system prompt, and `tools.run(call.name, call.input).text` as each call's result. Don't write tools of your own for this: these check every call, animate each change, and say what to fix when a call is wrong.
+
+Ids, focus, saving, React and `<orbit-map>`: [references/editing.md](references/editing.md). The map tools, with the loop for each provider: [references/map-tools.md](references/map-tools.md).
+
+## Mistakes to avoid
+
+- A container without a height: the map is 0 px tall.
+- `view: overview`: the overview is `view: all`. In code it's `viewMode: 'all'`, and `view-mode="all"` on `<orbit-map>`; the frontmatter's `animation`, `speed` and `title` are `orbitAnimation`, `orbitSpeed` and `ariaLabel` in code.
+- A bullet list meant as part of a note, written without `>`: it becomes child nodes.
+- A `#id` link to a node that isn't in the map: `validate` reports it and suggests the id you meant.
+- YAML nodes use `text` and `children` (not `title`, `name` or `items`, which `validate` reports); `nodes:` holds the root (several share one named after `title`).
+- Inventing options: every option and prop is typed in the package's declarations (`RendererOptions`). TypeScript rejects one that doesn't exist; plain JavaScript ignores it without a word. `validate` checks the map file only.

package/skills/orbit/references/editing.md

@@ -0,0 +1,194 @@
+<!-- A copy of docs/editing.md, made by scripts/build-llms.ts, with links to other files pointing at the repository. Edit the original. -->
+
+# Editing on the map
+
+People can build a map on the map itself. A **+** in the orbit adds an idea, typed right inside its new planet, a node's text is edited where it is, and a node is dragged to wherever it should go. Each edit animates into place, and the map comes back as orbit-md to save.
+
+## Turn it on
+
+```js
+import { createOrbitMap } from '@restless-dreams/orbit';
+
+const map = createOrbitMap(element, markdown, {
+  editable: true,
+  onEdit: () => save(map.toMarkdown()),
+});
+```
+
+With `editable`:
+
+- **A + in the orbit.** In focus mode, the orbit keeps a free place after the planets, drawn as a dashed planet with a plus.
+  - Press it and type: the text goes inside the new planet.
+  - Enter adds the idea right where it was typed and opens the next one after it, so ideas go in one after another, the keyboard staying up.
+  - Escape, or Enter with nothing typed, stops.
+- **Text edited where it is.** A long press, a right click or F2 on a node turns its label into a field.
+  - Enter saves, and Escape leaves the text as it was. Tapping anywhere else saves.
+  - A moon flies into its planet's orbit first, so its text has room. In the overview, small nodes get a field floating over them, at a size you can read.
+- **Nodes dragged somewhere else** (see [Dragging nodes](#dragging-nodes)).
+
+`<orbit-map editable>` and `<OrbitMindMap editable>` turn it on too.
+
+## Your own menu
+
+To offer more than editing text, show your own menu when a node is long-pressed, right-clicked, or chosen with the context menu key:
+
+```js
+const map = createOrbitMap(element, markdown, {
+  editable: true,
+  onNodeContext: ({ node, x, y }) => showMenu(x, y, [
+    { label: 'Rename', run: () => map.editNode(node.id) },
+    { label: 'Add an idea under it', run: () => map.editNewNode(node.id) },
+    { label: 'Mark done', run: () => map.updateNode(node.id, { status: 'done' }) },
+    { label: 'Delete', run: () => map.removeNode(node.id) },
+  ]),
+  onEdit: () => save(map.toMarkdown()),
+});
+```
+
+- **What `node-context` reports:** a long press (half a second, held still; `longPressDelay` changes it) with a finger or a pen, a right click, or the context menu key or Shift+F10 on the node with keyboard focus. `x` and `y` are where to put your menu, in CSS pixels from the map's top left corner: the press, or the node's center for the keyboard.
+- **The press is yours** with an `onNodeContext` callback or a `node-context` listener (`map.on('node-context', …)`). It doesn't open the node, it doesn't start editing the text, and the browser's own menu stays closed. A listener for the `orbit-node-context` DOM event takes it by calling `event.preventDefault()`.
+- **Without any of them,** a long press edits the text on an editable map, once it's let go without moving: moving it drags the node instead. On other maps, it is an ordinary tap and a right click opens the browser's menu.
+- **The same long press can drag the node.** Your menu opens as the press is held; if the finger then moves, `node-drag` fires with `phase: 'start'`, and that's the moment to close the menu: the node is on its way somewhere else.
+
+## Dragging nodes
+
+On an editable map, a node held still lifts: a long press with a finger or a pen, or the mouse held down half a second. Move it, and it follows the press, its moons with it.
+
+- **Onto another node:** that node grows and takes a ring. Let go, and the dragged node goes into it, after its last child.
+- **Along the orbit:** a planet keeps its place held, an empty ring where it was, so nothing slides under the finger. Carried along the ring, the place moves as it passes each planet, and the others make room. A planet catches a drop only near its middle; over its rim, the press is on the orbit, placing the node beside it. A moon or a deeper node carried to the orbit takes the + as its place.
+- **Let go anywhere else,** and it lands in the place held for it. One that never left its place goes back down. Escape, or a second finger, puts it back.
+- **What can't happen:** a node can't go inside itself or anything under it, the sun and the root don't lift, and a map that isn't editable never lifts a node.
+
+Each drop is a `moveNode`: it fires `edit` with `kind: 'move'`, the node flies from where it was let go to its place, and Orbit announces it. A mouse that's let go without moving still clicks, so a slow click opens the node as usual.
+
+```js
+const map = createOrbitMap(element, markdown, {
+  editable: true,
+  onNodeContext: ({ node, x, y }) => showMenu(x, y, node),
+  onNodeDrag: ({ phase }) => {
+    if (phase === 'start') {
+      closeMenu();
+    }
+  },
+  onEdit: () => save(map.toMarkdown()),
+});
+```
+
+`node-drag` reports each step: `start` as the node leaves its place (with where it was), `over` whenever where it would go changes (`parent` and `index`, or `null` over no place, for haptics or a hint), and `end` when it's let go (where it went, after the `edit`; `null` when it went back).
+
+## Keys for editing
+
+With `editingKeys` as well as `editable`, the keyboard builds a map the way mind-map apps do:
+
+```js
+const map = createOrbitMap(element, markdown, { editable: true, editingKeys: true });
+```
+
+| Key | On a node with keyboard focus | While typing |
+| --- | --- | --- |
+| Tab | Adds an idea under it (Insert does too) | Keeps what was typed and goes on under it. With nothing typed, moves the field under the idea before. |
+| Shift+Tab | Leaves the map, as usual | Keeps what was typed and goes on a level up, beside the parent |
+| Shift+Enter | Adds an idea beside it, right after it | |
+| Enter | Flies into it, as without the keys | Keeps what was typed and goes on beside it |
+| Delete | Removes it, with everything under it | |
+
+- **A whole map without the mouse:** Tab on the sun and type. Enter brings the next idea, Tab goes under the one just typed, Shift+Tab comes back up, and Escape stops.
+- **Tab stays in the map.** Without the keys the map is one tab stop, and Tab leaves it. With them, Tab on a node adds an idea, and Shift+Tab leaves. Turn them on where the map is the page's main tool, such as an editor, rather than for a map among other controls.
+- **After Delete,** keyboard focus moves on to the node after the removed one, or the one before it, or its parent. The root stays. To offer undo, keep the markdown from before each edit (see [Saving](#saving)).
+
+## The editing methods
+
+| Method | What it does |
+| --- | --- |
+| `editNode(id)` | Opens the field over a node, to type its text where it is. |
+| `editNewNode(parentId?, index?)` | Opens the field in the orbit of `parentId` (default: the node in focus), at `index` among its children (default: after the last). It flies there first. |
+| `stopEditing(save?)` | Closes the field, keeping what was typed unless `save` is false. |
+| `addNode(parentId, { text, …, children }, index?)` | Adds a node under `parentId`, at `index` among its children (default: last), with the nodes `children` lists under it, as many levels down as you like. Returns the new node. |
+| `updateNode(id, changes)` | Changes text and attributes: `{ text: 'Budget' }`, `{ status: 'done', color: '#E8A33D' }`. `undefined` removes one: `{ color: undefined }`. Returns the node. |
+| `removeNode(id)` | Removes a node and everything under it. The root stays. Returns the removed node. |
+| `moveNode(id, parentId, index?)` | Moves a node, with everything under it, under `parentId` at `index`. Under the same parent, it changes the order. Returns the node. |
+| `getDocument()` | The map as a document: its tree, and the options its frontmatter set. |
+| `toMarkdown()` | The map as orbit-md, frontmatter included. |
+
+To let a language model make these changes, see [Map tools for AI](map-tools.md).
+
+`editNode` and `editNewNode` return false, and the others `null`, when there's nothing to do: an id that isn't in the map, removing or moving the root, or moving a node inside itself. They work on any interactive map. `editable` adds the ways people edit by themselves: the +, editing on a long press, a right click, the context menu key or F2, and dragging.
+
+Besides `text`, `addNode` and `updateNode` take the node's attributes: `icon`, `color`, `status`, `priority`, `tags`, `collapsed`, `type`, `link`, `note`, `noteFormat`, `image`, `video`, `embed`, and `attrs` for your own.
+
+- **Ids come from the text,** as when a map is read from markdown: "Night markets" is `night-markets`, and a second "Ideas" is `ideas-2`. New text gives a node a new id, so the saved file needs no `id` attribute. A node keeps its id when a `#id` link points at it, or when the id was set by hand. Read a node's current id from what the method returns.
+- **Titles are one line:** line breaks become spaces, typed or pasted.
+- **The reader keeps their place.** When the node in focus, or a node above it, is removed, the nearest node left takes the focus and `focus-change` fires. A node in focus that gets a new id stays in focus.
+- **Edits change the tree in place:** `getDocument().root`, which is the tree you passed to `render()` if you passed one.
+
+## Events
+
+| Event | DOM event | Option | Detail |
+| --- | --- | --- | --- |
+| `edit` | `orbit-edit` | `onEdit` | `{ kind, node, tree }`: `kind` is `add`, `update`, `remove` or `move` |
+| `editor-open` | `orbit-editor-open` | `onEditorOpen` | `{ node, parent }`: the node whose text is typed, or `node: null` and the `parent` of a new idea |
+| `editor-close` | `orbit-editor-close` | `onEditorClose` | the same |
+| `node-context` | `orbit-node-context` | `onNodeContext` | `{ node, x, y }` |
+| `node-drag` | `orbit-node-drag` | `onNodeDrag` | `{ phase, node, parent, index }`: `phase` is `start`, `over` or `end` |
+
+The field's events help a page around the map: hide a button that would cover the keyboard, say, or bring a phone's keyboard up when an app opens the field itself.
+
+## Saving
+
+Save the map on every `edit`:
+
+```js
+map.on('edit', () => localStorage.setItem('map', map.toMarkdown()));
+```
+
+- **`toMarkdown()` reads back as the same map,** ids included, and keeps the file as it was written: only the ideas an edit changed are written again, so a note written by hand or by another app keeps its formatting and everything Orbit doesn't read (see [What saving keeps](format.md#what-saving-keeps)). New ideas are written the way people write maps: headings for the root and its children, lists below them, checkboxes for statuses, hashtags for tags. For YAML, use `serializeOrbitYAML(map.getDocument())`.
+- **A map written for a newer version of the format** has an `unsupported-schema-version` diagnostic: open it without `editable`, so nothing is changed that this version doesn't understand.
+- **Drawing the saved text again is fine.** When `render()` gets the map as it already is, Orbit keeps the view, and an edit's animation carries on.
+- **Undo is yours to keep:** save the markdown before an edit, and `render()` it to go back. Orbit animates to the restored map and keeps the reader's place.
+
+## In React
+
+`<OrbitMindMap>` takes `editable`, `onEdit`, `onNodeContext`, `onNodeDrag`, `onEditorOpen` and `onEditorClose`, and the ref's `renderer` has the methods:
+
+```tsx
+import { useRef, useState } from 'react';
+import { OrbitMindMap, type OrbitMindMapRef } from '@restless-dreams/orbit/react';
+
+export const Brainstorm = ({ initial }: { initial: string }) => {
+  const map = useRef<OrbitMindMapRef>(null);
+  const [source, setSource] = useState(initial);
+  return (
+    <div style={{ height: 480 }}>
+      <OrbitMindMap
+        ref={map}
+        source={source}
+        editable
+        onEdit={() => setSource(map.current?.renderer?.toMarkdown() ?? source)}
+      />
+    </div>
+  );
+};
+```
+
+Setting `source` to what the map just wrote doesn't draw it again.
+
+## In `<orbit-map>`
+
+```html
+<orbit-map editable>
+# Weekend in Lisbon
+## Food
+## Places
+</orbit-map>
+```
+
+The element's `renderer` has the same methods, and its events bubble out of it: listen for `orbit-edit` and save `element.renderer.toMarkdown()`. Edits change the map, not the element's text. `<orbit-map editable editing-keys>` turns on the [keys for editing](#keys-for-editing) too.
+
+## Keyboard and screen readers
+
+- **F2** edits the text of the node with keyboard focus. With `editingKeys`, Tab, Shift+Enter and Delete add and remove ideas too (see [Keys for editing](#keys-for-editing)).
+- **The +** takes its turn among the planets with `←` and `→`; Enter or Space on it adds an idea.
+- **The context menu key** and Shift+F10 open your menu for the node with keyboard focus, so whatever a long press offers works from the keyboard too.
+- **The field** is named after what it's for ("Text of Food", "New idea for Trip"), and when it closes with Enter or Escape, keyboard focus returns to the node, or to the +.
+- **Announcements:** Orbit announces added, removed and moved nodes in its live region ("Added Night markets").
+- **Moving without dragging:** dragging needs a pointer, so offer a way to move nodes in your menu too, with `moveNode` (earlier, later, in, out), as the keyboard can reach it.