pele-animate 0.13.0 → 0.15.0

package/README.md

@@ -1,134 +1,114 @@
 # 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.
-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 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.
-
-## Compare
-
-The same Mermaid source, three renderers. The pele-animate images loop: the intro draws in, then tokens travel the edges (as on hover).
-Regenerate with `examples/capture.sh`.
+[![npm](https://img.shields.io/npm/v/pele-animate)](https://www.npmjs.com/package/pele-animate)
+[![CI](https://github.com/dkdev24/pele-animate/actions/workflows/ci.yml/badge.svg)](https://github.com/dkdev24/pele-animate/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/pele-animate)](LICENSE)
 
-```mermaid
-flowchart LR
-  A[Player] -->|auth token| B[OTT service]
-  A -->|license request| C[DRM server]
-  C -->|license| A
-```
-
-| Renderer | Result |
-|---|---|
-| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m1.png" width="560" alt="Flowchart rendered by Mermaid"> |
-| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p1.png" width="560" alt="Flowchart rendered by Pele"> |
-| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a1.gif" width="560" alt="Animated flowchart: nodes appear, edges draw in, tokens travel"> |
-
-```mermaid
-sequenceDiagram
-  Player->>OTT: sign in
-  OTT-->>Player: token
-  Player->>DRM: token
-  DRM-->>Player: license
-```
+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.
 
-| Renderer | Result |
-|---|---|
-| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m2.png" width="560" alt="Sequence diagram rendered by Mermaid"> |
-| 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"> |
+**[Website](https://pele-animate.pages.dev/) · [Docs](docs/getting-started.md) · [npm](https://www.npmjs.com/package/pele-animate) · [Changelog](CHANGELOG.md)**
 
-With glyphs (`@{ icon }` nodes, `%% pa: 1=P 2=O 3=D` pins the order):
+<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">
 
-<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">
+- **You set the order.** Nodes appear in the order of a `%% pa:` comment, or by default along the edges; edges draw in and labels fade in.
+- **Readers step through it.** Click (or Enter) starts step mode: previous / play-pause / next buttons, Space, ←/→ and Esc. Hover or focus sends tokens along the edges.
+- **Icons.** `@{ icon: "name" }` nodes use any of 4,368 [Tabler](https://github.com/tabler/tabler-icons) icons (loaded per category) or your own. Unknown names get a neutral rounded square.
+- Flowcharts and sequence diagrams. The finished picture is the resting state; `prefers-reduced-motion` turns the motion off. Light and dark themes.
+- The source stays valid Mermaid. One catch: GitHub's own Mermaid renderer does not know the icon names and draws "?" boxes, so the icon examples in this repository are shown as source text.
 
 ## Install
 
 ```sh
 npm i pele-animate pele
+# or
+pnpm add pele-animate pele
+yarn add pele-animate pele
+bun add pele-animate pele
 ```
 
+`pele` is a peer dependency (`^1.7.0`): install it alongside. Both packages run in the browser and need the DOM, so mount them on the client (see [recipes](docs/recipes.md)). ESM only.
+
 ## Use
 
 ```js
 import { mount } from 'pele';
-import { watch } from 'pele-animate';
+import { watch, prepare } from 'pele-animate';
 import { icons } from 'pele-animate/glyphs';
-import 'pele-animate/preset-doverunner'; // the illustrated `doverunner-*` glyphs; skip it to use only Tabler packs
+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')) {
   const src = el.textContent;
-  mount(el, src, { icons });
+  mount(el, prepare(src), { icons });
   watch(el, src); // re-applies after Pele re-lays-out on resize
 }
 ```
 
 Mermaid source:
 
-```mermaid
+```mermaid-icons
 flowchart LR
-  %% pa: 1=P 2=O 3=D
-  P@{ icon: "doverunner-player", form: "square", h: 88, label: "Player" }
-  O@{ icon: "doverunner-server", form: "square", h: 88, label: "OTT service" }
-  D@{ icon: "doverunner-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.
+
+## Documentation
 
-## API
+Everything is in [`docs/`](docs/getting-started.md), and ships inside the npm package:
 
-| 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; unknown names get a neutral rounded square, since Pele ships no icons of its own |
+| [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 |
 
-Illustrated glyphs (filled, two-tone, DoveRunner style) come from `pele-animate/preset-doverunner` and are all 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`. Plain names (`server`, `lock`, ...) are Tabler's.
+**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).
 
-### Tabler icon packs
+## Compare
 
-About 4,300 line icons from [Tabler Icons](https://github.com/tabler/tabler-icons) (MIT), split by Tabler's own categories. Import only what you need:
+The same Mermaid source, three renderers. The pele-animate images loop: the intro draws in, then tokens travel the edges (as on hover).
+Regenerate with `examples/capture.sh`.
 
-```js
-import 'pele-animate/tabler/devices';   // also: system, database, development, communication, charts, ...
+```mermaid
+flowchart LR
+  A[Client] -->|request| B[API]
+  A -->|sign in| C[Auth server]
+  C -->|token| A
 ```
 
-Then use any name from that category: `A@{ icon: "device-tv", form: "square", h: 88 }`. The illustrated glyphs are prefixed `doverunner-`, so no Tabler name is shadowed.
-Tabler icons are stroke-only, so the stroke width is adjustable: set `--pa-stroke` on the container (default `1.5`; Tabler draws at 2 and
-designs every icon to work at other widths). Categories: see `tabler/` (Brand, Letters, Numbers, Zodiac and Gender are left out).
-Regenerate with `node scripts/build-tabler.mjs <tabler-icons checkout>`. License notice: `THIRD-PARTY-NOTICES.md`.
+| Renderer | Result |
+|---|---|
+| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m1.png" width="560" alt="Flowchart rendered by Mermaid"> |
+| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p1.png" width="560" alt="Flowchart rendered by Pele"> |
+| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a1.gif" width="560" alt="Animated flowchart: nodes appear, edges draw in, tokens travel"> |
 
-```css
-.pa-scene { --pa-stroke: 1; }
+```mermaid
+sequenceDiagram
+  Client->>API: sign in
+  API-->>Client: token
+  Client->>Data: query with token
+  Data-->>Client: result
 ```
 
-## Theme
-
-`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
-
-- 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.
+| Renderer | Result |
+|---|---|
+| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m2.png" width="560" alt="Sequence diagram rendered by Mermaid"> |
+| 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"> |
 
-## 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/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,50 @@
+---
+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. |
+| `prepare` | `prepare(source?: string): string` | Returns the Mermaid source with icon-node labels padded so Pele lays out a box at least as wide as the icon (`h`). Pass its result to `mount()` and the original source to `watch()`. Without it, a label shorter than the icon puts edge ends and arrowheads under the icon. |
+| `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,25 @@
+---
+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.
+- Fence convention: ```` ```mermaid live ```` is a diagram GitHub can also draw; the site animates it. A diagram with `@{ icon }` nodes uses ```` ```mermaid-icons live ````, because GitHub's Mermaid cannot draw icons (it shows "?" boxes), so GitHub shows the source text and the site animates it.
+- 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,70 @@
+---
+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
+# or
+pnpm add pele-animate pele
+yarn add pele-animate pele
+bun add pele-animate pele
+```
+
+`pele` is a peer dependency (`^1.7.0`): install it alongside. Both run in the browser and need the DOM, so mount them on the client (see
+[recipes](./recipes.md) for frameworks). The packages are ESM only.
+
+## 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, prepare } 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, prepare(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-icons 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, prepare(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).