pele-animate 0.12.0 → 0.14.0

package/README.md

@@ -1,13 +1,14 @@
 # pele-animate
 
-Animated, illustrated SVG scenes from plain Mermaid code. A small post-processor for
-[Pele](https://github.com/obsidianmd/pele) (MIT), which renders the Mermaid; this adds the motion and the pictures.
+Mermaid diagrams that explain themselves one step at a time, with icons. You choose the order things appear in, readers
+step through it, and nodes can carry icons. A small post-processor for [Pele](https://github.com/obsidianmd/pele) (MIT),
+which renders the Mermaid; this adds the step order, the playback and the icons. It is not a theme package.
 Unofficial add-on; not affiliated with or endorsed by the Pele or Obsidian teams.
 The source stays valid Mermaid, so GitHub or Obsidian still show a normal diagram.
 
 - Nodes appear in order (BFS from the sources, or pinned with a `%% pa:` comment), edges draw in, labels fade in.
 - Hover or focus: tokens travel the edges in sequence. The intro plays once on scroll-in. Click (or Enter) enters step mode: previous / play-pause / next buttons, with Space (play/pause), ←/→ (step) and Esc (leave).
-- `@{ icon: "name" }` nodes become illustrations from a glyph pack. Unknown names fall back to a plain Pele box.
+- `@{ icon: "name" }` nodes become illustrations from a glyph pack. Unknown names get a neutral rounded-square glyph.
 - Sequence diagrams: participant boxes in a row get the tallest height (Pele sizes each to its own text). Group and box titles are bold.
 - Idle state is the finished picture; `prefers-reduced-motion` turns the motion off. Light and dark themes.
 
@@ -43,9 +44,9 @@ sequenceDiagram
 | Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p2.png" width="560" alt="Sequence diagram rendered by Pele"> |
 | pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a2.gif" width="560" alt="Animated sequence diagram: messages appear in order, tokens travel"> |
 
-With glyphs (`@{ icon }` nodes, `%% pa: 1=P 2=O 3=D` pins the order):
+With icons (`@{ icon }` nodes from the Tabler `computers` pack, `%% pa: 1=C 2=L 3=S` pins the order):
 
-<img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a3.gif" width="560" alt="Animated scene with illustrated Player, OTT service and DRM server">
+<img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a3.gif" width="560" alt="Animated scene with Tabler icons: a request, a load balancer and a cloud service">
 
 ## Install
 
@@ -59,7 +60,7 @@ npm i pele-animate pele
 import { mount } from 'pele';
 import { watch } from 'pele-animate';
 import { icons } from 'pele-animate/glyphs';
-import 'pele-animate/preset-doverunner'; // optional extra glyphs
+import 'pele-animate/tabler/computers'; // one Tabler icon category; import as many as you need
 import 'pele-animate/style.css';
 
 for (const el of document.querySelectorAll('pre.mermaid')) {
@@ -73,45 +74,32 @@ Mermaid source:
 
 ```mermaid
 flowchart LR
-  %% pa: 1=P 2=O 3=D
-  P@{ icon: "player", form: "square", h: 88, label: "Player" }
-  O@{ icon: "server", form: "square", h: 88, label: "OTT service" }
-  D@{ icon: "key", form: "square", h: 88, label: "DRM server" }
-  P <-->|auth token| O
-  P <-->|token / license| D
+  %% pa: 1=C 2=L 3=S
+  C@{ icon: "http-get", form: "square", h: 88, label: "Request" }
+  L@{ icon: "load-balancer", form: "square", h: 88, label: "Load balancer" }
+  S@{ icon: "cloud-computing", form: "square", h: 88, label: "Cloud service" }
+  C <-->|route| L
+  L <-->|forward| S
 ```
 
-`form: "square", h: 88` makes a large frameless glyph; leave both out for a small icon in a frame.
-`%% pa: 1=P 2=O 3=D` pins nodes to steps (optional). `X>Y` pins the edge from X to Y, so an edge between nodes that are
-already visible can have its own step: `%% pa: 1=A,B 2=C,B>C 3=C>B`. Pin the nodes first; an edge pinned before its target appears lands early.
-Sequence diagrams animate actors, then messages in order.
+`%% pa: 1=C 2=L 3=S` pins the order (optional). `form: "square", h: 88` makes a large frameless icon.
 
-## API
+## Documentation
 
-| Export | |
-|---|---|
-| `watch(container, source?)` | Animate the SVG inside `container` (and every re-render of it); adds the scene panel and step mode (click / Enter); pass `{ controls: false }` as a third argument for click-to-replay instead |
-| `animate(svg, { hover, source })` | Animate one SVG; you handle re-renders |
-| `replay(svg)` | Play the intro again |
-| `parseOrder(source)` | Read the `%% pa:` pins: `Map(nodeId or 'X>Y' -> level)` |
-| `svg.paSteps` | Set by `animate()`: one array per step, each item `[element, parts that animate in]`. Step mode uses it; read it to check the order |
-| `registerGlyphs(pack, strokeWidth = 1.1)` (`/glyphs`) | Add glyphs: `{ name: '<inner markup of a 24x24 svg>' }`; colors via `--pa-solid` / `--pa-light` |
-| `icons` (`/glyphs`) | Pele `icons` resolver |
-
-Generic glyphs: `player`, `server`, `key`, `document`, `shield`, `phone`, `cloud`. `preset-doverunner`: `package`, `token`, `lock`,
-`database`, `video`, `media`, `encoder`, `storage`, `plugin`, `variants`, `watermark`, `bits-a`, `bits-b`.
-
-## Theme
+Everything is in [`docs/`](docs/getting-started.md), and ships inside the npm package:
 
-`watch()` adds class `pa-scene` to the container. Override `--pa-bg`, `--pa-solid`, `--pa-light` or any `--pele-*`
-variable on it; defaults are `:where()` rules, so your stylesheet wins.
-
-## Limits
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) · [How it works](docs/how-it-works.md) · [Diagram types](docs/diagram-types.md) | The basics |
+| [Icons](docs/icons.md) · [Custom icons](docs/custom-icons.md) · [Step order](docs/step-order.md) · [Theming](docs/theming.md) · [Recipes](docs/recipes.md) | Guides (Vite, Astro, SvelteKit, Nuxt, React) |
+| [API](docs/api.md) · [Compatibility](docs/compatibility.md) · [Accessibility](docs/accessibility.md) · [Security](docs/security.md) | Reference |
+| [Migrating](docs/migrating.md) · [For coding agents](docs/agents.md) · [FAQ](docs/faq.md) · [Contributing](docs/contributing.md) | Everything else |
 
-- Relies on Pele's SVG structure (`.pele-node`, `.pele-edge`, `data-id`); `pele` is a peer dependency pinned to `^1.7.0`.
-- Flowcharts and sequence diagrams only. No types yet.
-- Glyph art is square-boxed; wide art is drawn as a wide glyph inside the square.
+**Coding agents:** the package includes a skill, `skills/pele-animate/`, that wires the library into a project and checks the
+result in a browser. See [For coding agents](docs/agents.md).
 
-## Changelog
+## Credits and license
 
-See [CHANGELOG.md](CHANGELOG.md).
+MIT. Built on [Pele](https://github.com/obsidianmd/pele) by kepano (MIT); this is an unofficial add-on, not affiliated with or
+endorsed by the Pele or Obsidian teams. The Tabler icon packs come from [Tabler Icons](https://github.com/tabler/tabler-icons)
+(MIT, Paweł Kuna); see [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md). See also [CHANGELOG.md](CHANGELOG.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,28 @@
+# Third-party notices
+
+## Tabler Icons
+
+The `tabler/*.js` glyph packs are generated from [Tabler Icons](https://github.com/tabler/tabler-icons) 3.49.0 (outline set)
+by `scripts/build-tabler.mjs`. Icon names and categories are Tabler's own.
+
+MIT License
+
+Copyright (c) 2020-2026 Paweł Kuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/accessibility.md

@@ -0,0 +1,20 @@
+---
+title: Accessibility
+description: What pele-animate does for keyboard users and reduced motion, and what has not been audited.
+order: 11
+section: Reference
+---
+
+# Accessibility
+
+What is in place:
+
+- **Reduced motion.** `prefers-reduced-motion: reduce` turns off the intro and the tokens. The finished diagram shows.
+- **Keyboard.** The diagram container is focusable (`tabindex="0"`). Enter or Space starts step mode; then Space plays or pauses, ← and → step, and Esc leaves.
+- **Step controls.** The bar has `role="toolbar"` with an accessible name, and its buttons have labels. Previous and next use
+  `aria-disabled` at the ends.
+- **Focus outline.** A visible focus ring uses the `--pa-solid` color.
+
+What has **not** been checked: a pass with a screen reader, and contrast ratios of custom palettes. Treat the diagram as an
+illustration and keep the key information in the surrounding text as well, as with any diagram. The text of the Mermaid
+source is not a substitute for a description.

package/docs/agents.md

@@ -0,0 +1,63 @@
+---
+title: For coding agents
+description: How a coding agent should use pele-animate in a project, and how to verify the result.
+order: 14
+section: Reference
+---
+
+# For coding agents
+
+If you are an AI coding agent adding pele-animate to a project, use the skill that ships with the package. It carries the rules
+below in an order that works.
+
+## Install the skill
+
+The skill is in the npm package, so after `npm i pele-animate` it is at `node_modules/pele-animate/skills/pele-animate/SKILL.md`.
+For Claude Code, copy it where skills live:
+
+```sh
+mkdir -p .claude/skills
+cp -r node_modules/pele-animate/skills/pele-animate .claude/skills/
+```
+
+Or clone just the skill folder from [GitHub](https://github.com/dkdev24/pele-animate/tree/main/skills/pele-animate) (it has `SKILL.md`, `verify.js` and `references/`).
+
+A second skill, `diagram-step-order`, reviews a page's diagrams so the step order matches the text around them.
+
+No skill support? Paste this into your instructions file:
+
+```md
+## Diagrams (pele-animate)
+- Animated Mermaid diagrams use `pele` + `pele-animate`; mount on the client only (see node_modules/pele-animate/docs or the README).
+- Icon names must exist: read node_modules/pele-animate/tabler/<category>.js. Never invent names. Unknown names render a plain square.
+- Order with `%% pa: 1=A 2=B,C`; check svg.paSteps in a browser.
+- Verify by rendering the page and confirming no unexpected rounded-square icons.
+```
+
+## Rules
+
+1. **Client only.** Never import `pele` or `pele-animate` in server code. Use the framework's mounted hook ([recipes](./recipes.md)).
+2. **Never invent icon names.** Look them up in `node_modules/pele-animate/tabler/<category>.js` (object keys) and import that category.
+   An unknown name does not fail; it renders a rounded square, so a made-up name is a silent bug.
+3. **Import three things:** `pele-animate/glyphs` (`icons`), the icon pack modules you use, and `pele-animate/style.css`.
+4. **Pin the order** with `%% pa:` when the default is wrong ([step order](./step-order.md)). Do not rename node ids after pinning.
+5. **Verify in a browser**, not by reading the code.
+
+## Verify
+
+Render the page in a headless browser (Playwright, or any CLI browser) and run this in the page:
+
+```js
+(() => {
+  const svgs = [...document.querySelectorAll('.pa-scene svg.pele')];
+  const icons = [...document.querySelectorAll('.pa-scene svg.pele-icon[data-icon]')];
+  return {
+    diagrams: svgs.length,
+    steps: svgs.map((s) => s.paSteps?.length ?? 0),
+    emptyIcons: icons.filter((i) => !i.innerHTML.trim()).map((i) => i.dataset.icon),
+  };
+})()
+```
+
+Expect `diagrams` equal to the number you added, every `steps` entry above 0, and `emptyIcons` empty. A name that was not registered renders
+a rounded square instead of nothing, so also compare the icon names in your Mermaid with the pack source.

package/docs/api.md

@@ -0,0 +1,49 @@
+---
+title: API reference
+description: Every export of pele-animate, with types.
+order: 9
+section: Reference
+---
+
+# API reference
+
+TypeScript types ship with the package (`types/`).
+
+## `pele-animate`
+
+| Export | Signature | Description |
+|---|---|---|
+| `watch` | `watch(container: HTMLElement, source?: string, options?: { controls?: boolean }): void` | Marks the container as a scene (`pa-scene`), animates each SVG Pele renders into it and re-applies after Pele re-lays-out on resize. `controls: false` keeps click-to-replay instead of step mode. |
+| `animate` | `animate(svg: SVGSVGElement, options?: { hover?: Element; source?: string }): void` | Animates one rendered svg. `source` is read for `%% pa:` pins. Sets `svg.paSteps`. |
+| `replay` | `replay(svg: SVGSVGElement \| null \| undefined): void` | Plays the intro again. |
+| `parseOrder` | `parseOrder(source?: string): Map<string, number>` | Parses the `%% pa:` comment: node id, or `'X>Y'` for an edge, to a 0-based step. |
+
+`svg.paSteps` (type `PaStep[]`, where `PaStep = Array<[element: Element, parts: Element[]]>`) is set by `animate()`: one array per
+step.
+
+## `pele-animate/glyphs`
+
+| Export | Signature | Description |
+|---|---|---|
+| `icons` | `icons(name: string): string` | Pele's `icons` resolver. Unknown names return a neutral rounded square. |
+| `registerGlyphs` | `registerGlyphs(pack: Record<string, string>, strokeWidth?: number): void` | Adds glyphs: `{ name: '<inner markup of a 24x24 svg>' }`. Default stroke width 1.1. |
+| `registerTabler` | `registerTabler(pack: Record<string, string>, strokeWidth?: number): void` | Adds outline icons whose stroke width follows `--pa-stroke` (fallback `strokeWidth`, default 1.5). |
+| `S`, `L`, `W` | `string` | Theme color expressions for glyph markup: solid, light, white. |
+
+## `pele-animate/tabler/<category>`
+
+Importing a module registers that category's icons. It also exports `pack: Record<string, string>` (name to inner markup).
+Categories are listed in [icons](./icons.md).
+
+## `pele-animate/preset-doverunner`
+
+Importing it registers the 20 `doverunner-*` glyphs. No exports.
+
+## `pele-animate/style.css`
+
+The scene frame, motion and step controls. Import it once.
+
+## Classes you may see
+
+`pa-scene` (container), `pa-ready` (an animated svg), `pa-in` and `pa-done` (intro states), `pa-stepping` (step mode), `pa-controls`
+(the button bar). These are internal and may change; prefer the CSS variables in [theming](./theming.md) over targeting them.

package/docs/compatibility.md

@@ -0,0 +1,33 @@
+---
+title: Compatibility
+description: Versions of Pele, browsers, and the parts of Pele's markup pele-animate depends on.
+order: 10
+section: Reference
+---
+
+# Compatibility
+
+| | Supported |
+|---|---|
+| Pele | `^1.7.0` (peer dependency). Tested with 1.7 (the docs site), 1.8 and 1.9. |
+| Diagram types | Flowcharts and sequence diagrams ([diagram types](./diagram-types.md)) |
+| Browsers | Current browsers with the Web Animations API, `IntersectionObserver` and `matchMedia` (Chrome, Edge, Firefox, Safari). Without `IntersectionObserver` the intro plays at once. |
+| Module format | ESM only |
+| Server rendering | Not applicable: mount on the client ([recipes](./recipes.md)) |
+
+## What pele-animate depends on in Pele
+
+pele-animate reads the SVG Pele produces. It selects on these class names and attributes:
+
+`.pele-node`, `.pele-edge`, `.pele-edge-label`, `.pele-marker`, `.pele-cluster-label`, `.pele-icon`, `.pele-lifeline`,
+`.pele-actor-participant`, and the `data-id` attribute.
+
+Pele has not promised these are stable across releases (the question is open upstream). That is why Pele is a peer dependency:
+upgrade it deliberately, and re-check your diagrams afterwards. The repository's tests render every documentation example,
+which catches parse errors but not visual changes.
+
+## Known limits
+
+- Sequence-diagram participants ignore `@{ icon }`.
+- Step mode is browser-tested on flowcharts only.
+- Glyph art is square-boxed; wide art is drawn as a wide shape inside the square.

package/docs/contributing.md

@@ -0,0 +1,24 @@
+---
+title: Contributing
+description: Set up the repository, run the checks, and regenerate the Tabler packs.
+order: 15
+section: Reference
+---
+
+# Contributing
+
+```sh
+git clone https://github.com/dkdev24/pele-animate
+cd pele-animate
+pnpm install
+pnpm test    # renders every Mermaid example in the docs and README with Pele, and checks icon names
+pnpm build   # builds the site (a placeholder until the site lands)
+```
+
+- The package is plain ESM at the repository root: no build step. The site lives in `site/`.
+- Docs are the Markdown files in `docs/`. A fenced block marked `mermaid` must render, and every `@{ icon }` name in it must exist.
+- Tabler packs are generated: `node scripts/build-tabler.mjs <path to a tabler-icons checkout>` rewrites `tabler/*.js`. Do not edit those
+  files by hand. The Tabler version is recorded in each file header and in `THIRD-PARTY-NOTICES.md`.
+- Add an entry to `CHANGELOG.md` for any user-visible change. Breaking changes also get a section in `docs/migrating.md`.
+- Versioning stays on `0.x`.
+- Keep example diagrams generic (clients, APIs, databases).

package/docs/custom-icons.md

@@ -0,0 +1,39 @@
+---
+title: Custom icons
+description: Register your own glyphs with registerGlyphs.
+order: 5
+section: Guides
+---
+
+# Custom icons
+
+Register your own icons with `registerGlyphs`:
+
+```js
+import { registerGlyphs, S, L } from 'pele-animate/glyphs';
+
+registerGlyphs({
+  'my-box': `<rect x="4" y="6" width="16" height="12" rx="2" fill="${L}" stroke="${S}"/>`,
+});
+```
+
+Then use `icon: "my-box"` in your Mermaid.
+
+## The contract
+
+- A glyph is the **inner markup** of a 24 by 24 SVG: shapes only, no `<svg>` wrapper. Draw inside the 24 by 24 box.
+- Colors: use `S` (solid) and `L` (light), which are the CSS variables `--pa-solid` and `--pa-light` with fallbacks, plus
+  `W` for white. Then the glyph follows light and dark themes (see [theming](./theming.md)).
+- `registerGlyphs(pack, strokeWidth = 1.1)` wraps each glyph in a group with that stroke width. Pele draws icons at stroke
+  width 2, which looks heavy on a large icon, so glyphs get a thinner one.
+- Line icons that should respond to `--pa-stroke` (as the Tabler packs do) can use `registerTabler(pack, strokeWidth = 1.5)`
+  instead. It sets fill none, round caps and joins, and the stroke color for you.
+
+## Names
+
+Registering a name that already exists replaces it. Choose a prefix for your own pack (`acme-box`) so your names never clash
+with Tabler's plain names.
+
+## Safety
+
+Glyph markup is inserted into the page as SVG. Only register markup you trust. See [security](./security.md).

package/docs/diagram-types.md

@@ -0,0 +1,43 @@
+---
+title: Diagram types
+description: Which Mermaid diagrams pele-animate animates, and what each one does.
+order: 3
+section: Start
+---
+
+# Diagram types
+
+pele-animate supports **flowcharts** and **sequence diagrams**. Pele renders other diagram types too, but they are outside what
+pele-animate is built for.
+
+## Flowcharts
+
+Nodes appear in step order, edges draw from their source node, and edge labels fade in. Groups (`subgraph`) and their titles
+are kept. Icon nodes (`@{ icon }`) work here; see [icons](./icons.md).
+
+```mermaid live
+flowchart LR
+  A[Client] --> B{Cached?}
+  B -->|yes| C[Serve]
+  B -->|no| D[Fetch] --> C
+```
+
+## Sequence diagrams
+
+Actors appear first, then the messages in order. Participant boxes in a row get the same height, and group titles are bold.
+
+```mermaid live
+sequenceDiagram
+  Client->>API: request
+  API->>Database: query
+  Database-->>API: rows
+  API-->>Client: response
+```
+
+**Limit:** Pele ignores `@{ icon }` on sequence participants (the box shows its id), so icons apply to flowcharts only.
+
+## Everything else
+
+Other Mermaid types (class, state, ER, gantt, pie and the rest) render through Pele as usual. pele-animate is not designed for
+them and its behavior on them is untested, so use plain Pele for those. Step mode has been checked in a browser on
+flowcharts only; sequence diagrams have not been checked the same way yet.

package/docs/faq.md

@@ -0,0 +1,30 @@
+---
+title: FAQ
+description: Common questions about pele-animate, Pele, and licenses.
+order: 16
+section: Reference
+---
+
+# FAQ
+
+**Is this part of Pele?** No. It is an unofficial add-on, not affiliated with or endorsed by the Pele or Obsidian teams. Pele does the
+layout and drawing; pele-animate adds step order, step-by-step playback and icons on top.
+
+**Why not just use Pele?** Pele alone draws a static diagram. Use it directly if that is enough. pele-animate is for diagrams
+you want to explain in order.
+
+**Is it a theme?** No. It does not offer visual styles beyond a simple scene frame and light/dark colors you can override.
+
+**Why not Mermaid.js?** Pele is much smaller and renders synchronously. pele-animate is built on Pele, so it follows that choice.
+
+**Does it work with server rendering?** Mount it on the client ([recipes](./recipes.md)). Static site generators are fine.
+
+**How big is it?** The core (`pele-animate.js` plus CSS) is about 20 KB unminified. Icon packs are separate modules, so you only
+ship the categories you import (the largest, `system`, is about 199 KB unminified).
+
+**Which diagrams does it support?** Flowcharts and sequence diagrams ([diagram types](./diagram-types.md)).
+
+**Can I use my own icons?** Yes ([custom icons](./custom-icons.md)).
+
+**Licenses.** pele-animate is MIT. Pele is MIT. The Tabler icon packs are from Tabler Icons (MIT, Paweł Kuna); see
+`THIRD-PARTY-NOTICES.md`.

package/docs/getting-started.md

@@ -0,0 +1,66 @@
+---
+title: Getting started
+description: Install pele-animate and render your first step-by-step Mermaid diagram.
+order: 1
+section: Start
+---
+
+# Getting started
+
+pele-animate makes a [Pele](https://pele.run) diagram explain itself one step at a time. You choose the order things appear
+in, readers step through it with buttons or the keyboard, and any node can carry an icon from a large set. It is an
+unofficial add-on for Pele and does not change how Pele lays out or draws diagrams.
+
+## Install
+
+```sh
+npm i pele-animate pele
+```
+
+`pele` is a peer dependency (`^1.7.0`). Both run in the browser: they need the DOM, so mount them on the client (see
+[recipes](./recipes.md) for frameworks).
+
+## First diagram
+
+Put the Mermaid source in an element, then mount it with Pele and hand it to `watch()`:
+
+```js
+import { mount } from 'pele';
+import { watch } from 'pele-animate';
+import { icons } from 'pele-animate/glyphs';
+import 'pele-animate/tabler/computers'; // icons: one Tabler category, import as many as you need
+import 'pele-animate/style.css';
+
+const el = document.querySelector('pre.mermaid');
+const src = el.textContent;
+mount(el, src, { icons }); // Pele draws the SVG
+watch(el, src);            // pele-animate animates it, and re-applies when Pele re-lays-out on resize
+```
+
+The Mermaid source:
+
+```mermaid live
+flowchart LR
+  %% pa: 1=C 2=L 3=S
+  C@{ icon: "http-get", form: "square", h: 88, label: "Request" }
+  L@{ icon: "load-balancer", form: "square", h: 88, label: "Load balancer" }
+  S@{ icon: "cloud-computing", form: "square", h: 88, label: "Cloud service" }
+  C <-->|route| L
+  L <-->|forward| S
+```
+
+What you get:
+
+- The intro plays once when the diagram scrolls into view: nodes appear in order, edges draw in, labels fade in.
+- Hover or focus: small tokens travel along the edges.
+- Click, or focus and press Enter: **step mode**. Previous, play/pause and next buttons appear, and Space, ←, → and Esc work.
+- With `prefers-reduced-motion`, the motion is off and the finished picture shows.
+
+The `%% pa: 1=C 2=L 3=S` comment pins the order. Without it, the order follows the edges. See [step order](./step-order.md).
+
+## Next
+
+- Pick icons: [icons](./icons.md).
+- Control the order: [step order](./step-order.md).
+- Match your site's colors: [theming](./theming.md).
+- Upgrading from 0.12: [migrating](./migrating.md).

package/docs/how-it-works.md

@@ -0,0 +1,44 @@
+---
+title: How it works
+description: What Pele does, what pele-animate adds, and the three kinds of motion.
+order: 2
+section: Start
+---
+
+# How it works
+
+Two layers, one diagram:
+
+1. **Pele** parses the Mermaid, lays the diagram out and returns an SVG. That is all Pele's job; pele-animate does not
+   touch layout, sizing or syntax.
+2. **pele-animate** reads that SVG after Pele draws it, works out the order things should appear in, and adds the motion,
+   the step playback and the icons. The Mermaid source stays valid Mermaid, so GitHub or Obsidian still show a normal diagram.
+
+## The calls
+
+- `mount(el, src, { icons })` is Pele's. The `icons` option is how glyphs get in (see [icons](./icons.md)).
+- `watch(el, src)` is pele-animate's. It marks the container as a scene (class `pa-scene`), animates each SVG Pele renders into
+  it, and re-applies after Pele re-draws on resize. The intro is skipped on those re-draws once it has played.
+- `animate(svg, { source })` does one SVG. Use it if you render with Pele yourself and do not want `watch()`.
+- `replay(svg)` plays the intro again.
+
+## The three kinds of motion
+
+| Motion | When | Notes |
+|---|---|---|
+| **Intro** | Once, when the diagram is 30% in view | Nodes appear by step, each edge draws from its source, labels fade in. A long diagram squeezes its steps so the intro stays near 3 seconds. |
+| **Tokens** | While hovering or focusing the diagram | Small dots travel along the edges in sequence. |
+| **Step mode** | Click, or Enter | You move through the same steps one at a time. See [step order](./step-order.md). |
+
+The resting state is always the finished picture. Everything honors `prefers-reduced-motion`.
+
+## Where the order comes from
+
+Order is a list of **steps**. By default, a flowchart's steps are the breadth-first levels from the nodes that nothing points to;
+a sequence diagram's steps are its actors, then its messages in order. A `%% pa:` comment overrides that. After
+`animate()` runs, `svg.paSteps` holds one array per step, which is also what step mode uses.
+
+## What it depends on in Pele
+
+pele-animate selects on class names in Pele's SVG (`.pele-node`, `.pele-edge`, and a few others) and on the `data-id` attribute.
+Pele is a peer dependency so you control its version. See [compatibility](./compatibility.md).

package/docs/icons.md

@@ -0,0 +1,82 @@
+---
+title: Icons
+description: Use icons on flowchart nodes, pick names from 4,000+ Tabler icons, and control stroke width.
+order: 4
+section: Guides
+---
+
+# Icons
+
+A flowchart node becomes an illustrated node with Mermaid's own `@{ }` syntax:
+
+```mermaid live
+flowchart LR
+  A@{ icon: "device-desktop", form: "square", h: 88, label: "Laptop" }
+  B@{ icon: "server", form: "square", h: 88, label: "Server" }
+  A --> B
+```
+
+Both names are in the Tabler `devices` category, so this needs `import 'pele-animate/tabler/devices'`.
+
+- `icon` is the glyph name. `label` is the caption.
+- `form: "square", h: 88` makes a large frameless icon. Leave both out for a small icon inside a frame.
+- Unknown names get a neutral rounded square, never a blank slot. Pele ships no icons of its own, so every name must come
+  from a pack you import.
+
+## Packs
+
+Icons come from packs. Importing a pack module registers its icons.
+
+| Pack | Import | Contents |
+|---|---|---|
+| **Tabler categories** | `pele-animate/tabler/<category>` | 4,368 outline icons in 36 categories, from [Tabler Icons](https://github.com/tabler/tabler-icons) 3.49.0 (MIT) |
+| **doverunner-\*** (optional) | `pele-animate/preset-doverunner` | 20 filled, two-tone illustrations named `doverunner-<name>` (see below) |
+| **Your own** | `registerGlyphs()` | See [custom icons](./custom-icons.md) |
+
+Pass the resolver to Pele: `mount(el, src, { icons })` with `import { icons } from 'pele-animate/glyphs'`.
+
+### Tabler categories
+
+Import only the categories you use; each is its own module (the largest, `system`, is about 199 KB).
+
+| Category | Icons | Category | Icons | Category | Icons |
+|---|---|---|---|---|---|
+| system | 784 | map | 263 | food | 96 |
+| devices | 363 | document | 209 | buildings | 95 |
+| design | 350 | text | 194 | vehicles | 90 |
+| arrows | 333 | shapes | 187 | math | 88 |
+| media | 160 | e-commerce | 155 | health | 87 |
+| communication | 121 | sport | 76 | currencies | 76 |
+| development | 63 | weather | 61 | photography | 52 |
+| mood | 52 | nature | 50 | games | 48 |
+| computers | 44 | database | 42 | laundry | 40 |
+| charts | 39 | symbols | 37 | badges | 22 |
+| electrical | 19 | animals | 18 | gestures | 17 |
+| version-control | 16 | extensions | 13 | logic | 8 |
+
+Brand, Letters, Numbers, Zodiac and Gender are not included. Counts are for Tabler 3.49.0.
+
+### Finding a name
+
+Do not guess names. Look them up:
+
+- Tabler's own site, [tabler.io/icons](https://tabler.io/icons), lists names and categories (use the outline style).
+- In your project: `node_modules/pele-animate/tabler/<category>.js` lists every name in that category as an object key.
+- Names that exist in more than one place are not a problem: Tabler names are plain (`server`, `lock`), `doverunner-*` names are prefixed.
+
+## Stroke width
+
+Tabler icons are line icons drawn to work at any stroke width. Set the CSS variable `--pa-stroke` on the container:
+
+```css
+.pa-scene { --pa-stroke: 1; }
+```
+
+The default is `1.5`. Tabler draws at 2. The `doverunner-*` glyphs have a fixed stroke width.
+
+## The optional doverunner-* pack
+
+`pele-animate/preset-doverunner` ships 20 filled, two-tone glyphs in the style of the DoveRunner Lab product cards, named
+`doverunner-<name>`: `player`, `server`, `key`, `document`, `shield`, `phone`, `cloud`, `package`, `token`, `lock`,
+`database`, `video`, `media`, `encoder`, `storage`, `plugin`, `variants`, `watermark`, `bits-a`, `bits-b`. Import it only
+if you want that look; nothing else needs it.