pele-animate 0.13.0 → 0.14.0

package/README.md

@@ -1,7 +1,8 @@
 # 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.
 
@@ -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'; // 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')) {
@@ -73,62 +74,32 @@ Mermaid source:
 
 ```mermaid
 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.
 
-## 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; unknown names get a neutral rounded square, since Pele ships no icons of its own |
-
-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.
-
-### Tabler icon packs
-
-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:
-
-```js
-import 'pele-animate/tabler/devices';   // also: system, database, development, communication, charts, ...
-```
+Everything is in [`docs/`](docs/getting-started.md), and ships inside the npm package:
 
-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`.
-
-```css
-.pa-scene { --pa-stroke: 1; }
-```
-
-## 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
+| | |
+|---|---|
+| [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/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.

package/docs/migrating.md

@@ -0,0 +1,58 @@
+---
+title: Migrating
+description: Breaking changes between releases, with the renames to apply.
+order: 13
+section: Reference
+---
+
+# Migrating
+
+pele-animate stays on `0.x`: a minor release may break things. Pin a range such as `^0.13.0` and bump it deliberately.
+
+## 0.12 to 0.13
+
+Two breaking changes.
+
+### 1. Illustrated glyphs are renamed `doverunner-<name>`
+
+The plain names now belong to the Tabler icon packs. Rename the `@{ icon }` values in your Mermaid sources:
+
+| Before | After |
+|---|---|
+| `player` | `doverunner-player` |
+| `server` | `doverunner-server` |
+| `key` | `doverunner-key` |
+| `document` | `doverunner-document` |
+| `shield` | `doverunner-shield` |
+| `phone` | `doverunner-phone` |
+| `cloud` | `doverunner-cloud` |
+| `package` | `doverunner-package` |
+| `token` | `doverunner-token` |
+| `lock` | `doverunner-lock` |
+| `database` | `doverunner-database` |
+| `video` | `doverunner-video` |
+| `media` | `doverunner-media` |
+| `encoder` | `doverunner-encoder` |
+| `storage` | `doverunner-storage` |
+| `plugin` | `doverunner-plugin` |
+| `variants` | `doverunner-variants` |
+| `watermark` | `doverunner-watermark` |
+| `bits-a`, `bits-b` | `doverunner-bits-a`, `doverunner-bits-b` |
+
+A search and replace over `icon: "<name>"` does it. Or switch to Tabler icons and drop the renamed ones; see [icons](./icons.md).
+
+### 2. The glyphs moved into the preset
+
+The seven glyphs that lived in `pele-animate/glyphs` are now in `pele-animate/preset-doverunner`. `pele-animate/glyphs` is only the
+registry (`icons`, `registerGlyphs`, `registerTabler`). If you use any `doverunner-*` glyph, import the preset:
+
+```js
+import 'pele-animate/preset-doverunner';
+```
+
+### New in 0.13
+
+- Tabler icon packs: `pele-animate/tabler/<category>`, with the `--pa-stroke` variable.
+- `icons()` returns a neutral rounded square for unknown names, instead of a blank slot.
+
+A missed rename shows up as that rounded square, not as an error, so look for unexpected squares after upgrading.

package/docs/recipes.md

@@ -0,0 +1,80 @@
+---
+title: Recipes
+description: Using pele-animate in Vite, SvelteKit, Astro, Nuxt, React and plain HTML, with what has been tested.
+order: 8
+section: Guides
+---
+
+# Recipes
+
+Pele and pele-animate need the DOM, so in every framework the rule is the same: **mount on the client, after the page has
+rendered.** Load them with dynamic `import()` inside the framework's mounted hook so server rendering never touches them.
+
+The shape is always:
+
+```js
+const [{ mount }, { watch }, { icons }] = await Promise.all([
+  import('pele'),
+  import('pele-animate'),
+  import('pele-animate/glyphs'),
+  import('pele-animate/tabler/computers'), // your icon categories
+  import('pele-animate/style.css'),
+]);
+mount(el, src, { icons });
+watch(el, src);
+```
+
+| Framework | Status | Where the code goes |
+|---|---|---|
+| Plain HTML / Vite | Tested | A module script, as in [getting started](./getting-started.md) |
+| Astro | Tested in production (the DoveRunner docs site) | A client `<script>` that finds the diagram elements |
+| SvelteKit 3 | Tested (build and browser, static adapter) | `onMount(async () => { ... })` in the page or component |
+| Nuxt 4 | Tested (build and browser, static generate) | `onMounted` in a `.client.vue` component |
+| React / Next.js | Not tested | A client component (`'use client'`) with `useEffect` |
+| Vue (no Nuxt) | Not tested | `onMounted` |
+
+Notes for all of them:
+
+- Give each diagram its own element (`<pre>` or `<div>`) holding the Mermaid source, and call `mount` and `watch` once per
+  element.
+- If the page changes without a reload (client-side routing), mount again for the new elements.
+- Importing the CSS (`pele-animate/style.css`) once is enough. In TypeScript, a CSS side-effect import needs a `*.css` module
+  declaration (Vite projects get it from `vite/client`).
+- Static site generators are fine: nothing here needs a server.
+
+## Astro
+
+```astro
+<pre class="mermaid" set:text={src}></pre>
+<script>
+  // runs in the browser only
+  import { mount } from 'pele';
+  import { watch } from 'pele-animate';
+  import { icons } from 'pele-animate/glyphs';
+  import 'pele-animate/tabler/computers';
+  import 'pele-animate/style.css';
+  document.querySelectorAll('pre.mermaid').forEach((el) => {
+    const src = el.textContent ?? '';
+    mount(el as HTMLElement, src, { icons });
+    watch(el as HTMLElement, src);
+  });
+</script>
+```
+
+## SvelteKit
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  let el;
+  const src = 'flowchart LR\n  A --> B';
+  onMount(async () => {
+    const [{ mount }, { watch }, { icons }] = await Promise.all([
+      import('pele'), import('pele-animate'), import('pele-animate/glyphs'), import('pele-animate/style.css'),
+    ]);
+    mount(el, src, { icons });
+    watch(el, src);
+  });
+</script>
+<div bind:this={el}></div>
+```

package/docs/security.md

@@ -0,0 +1,19 @@
+---
+title: Security
+description: Untrusted diagram text, and what pele-animate adds.
+order: 12
+section: Reference
+---
+
+# Security
+
+- **Diagram text.** Pele escapes diagram text, filters links and styles, and limits source and output size. Read Pele's
+  [security page](https://pele.run/security) before rendering diagrams you did not write. pele-animate does not weaken any of
+  that: it reads the SVG after Pele renders it.
+- **Pins.** The `%% pa:` comment is parsed with a simple pattern (step numbers and ids). It cannot run code.
+- **Glyph markup is trusted.** `registerGlyphs()` and `registerTabler()` insert your markup into the page as SVG. Register only
+  markup you wrote or reviewed. The bundled Tabler and `doverunner-*` packs are static files in the package.
+- **No network.** pele-animate makes no requests and loads no remote assets.
+- **No eval.** Nothing in the package uses `eval` or generates code, so a content security policy without `unsafe-eval` works.
+
+Report a vulnerability by opening an issue on the [GitHub repository](https://github.com/dkdev24/pele-animate) that asks for a private contact. Leave the details out of the public issue.

package/docs/step-order.md

@@ -0,0 +1,75 @@
+---
+title: Step order
+description: Choose the order things appear in, and how step mode works.
+order: 6
+section: Guides
+---
+
+# Step order
+
+Every diagram is a list of **steps**. The intro plays them one after another, and step mode lets the reader move through
+them. By default, the order follows the edges. A `%% pa:` comment lets you set it yourself.
+
+## Default order
+
+- **Flowchart:** nodes appear by level, counting from the nodes nothing points to. Each edge draws from its source once the source
+  is on screen, and its target appears as the edge lands. Branches of a decision appear together.
+- **Sequence diagram:** actors first, then the messages in order.
+
+## Pins
+
+Add one comment line anywhere in the source:
+
+```mermaid live
+flowchart LR
+  %% pa: 1=A 2=B 3=C
+  A[Request] --> B[Validate] --> C[Respond]
+  A --> C
+```
+
+`%% pa: 1=A 2=B,C` means: step 1 shows A, step 2 shows B and C. Steps are numbered from 1. Anything you do not pin keeps its default
+level.
+
+### Edge pins
+
+`X>Y` pins the edge from X to Y to its own step, so an edge between two nodes that are already visible can be a step:
+
+```mermaid live
+flowchart LR
+  %% pa: 1=A,B 2=C 3=A>B
+  A[Client] --> B[Server]
+  B --> C[Database]
+  B --> A
+```
+
+Rules that avoid surprises:
+
+- **Pin the nodes first.** An edge pinned before its target appears lands early.
+- A two-way edge (`A <--> B`) is pinned in the direction you wrote it first (`A>B`).
+- Do not rename node ids after pinning: pins match ids.
+- Translated pages keep the same ids, so copy the `%% pa:` line across languages after checking the ids match.
+
+## Step mode
+
+Click the diagram, or focus it and press Enter or Space. A small bar appears with previous, play/pause and next.
+
+| Key | Action |
+|---|---|
+| Space | Play or pause |
+| → | Next step |
+| ← | Previous step |
+| Esc | Leave step mode |
+
+Pass `{ controls: false }` as the third argument of `watch()` to turn step mode off; a click then just replays the intro.
+
+## Checking your order
+
+After `animate()` runs, `svg.paSteps` is one array per step. Print what each step shows:
+
+```js
+const svg = document.querySelector('.pa-scene svg.pele');
+svg.paSteps.map((items, n) => `${n + 1}: ` + items.map(([el]) => el.textContent.trim() || el.dataset.id).join(' ; '));
+```
+
+`parseOrder(source)` returns the parsed pins as a `Map` (node id or `'X>Y'` to a 0-based step), if you want to check them
+without a browser.

package/docs/theming.md

@@ -0,0 +1,48 @@
+---
+title: Theming
+description: Colors, dark mode, stroke width and reduced motion.
+order: 7
+section: Guides
+---
+
+# Theming
+
+`watch()` adds the class `pa-scene` to the container. That class gives the diagram its tinted panel and its colors. The
+defaults are written with `:where()`, so any rule in your stylesheet wins without a specificity fight.
+
+## Variables
+
+Set these on the container (or any ancestor):
+
+| Variable | What it controls | Default (light) |
+|---|---|---|
+| `--pa-bg` | Panel background | `#efeafa` |
+| `--pa-solid` | Strong color: lines, icon strokes, accents | `#4F378B` |
+| `--pa-light` | Light fill: icon fills, group surfaces | `#e4dcf6` |
+| `--pa-stroke` | Stroke width of Tabler icons | `1.5` |
+| `--pele-*` | Any of Pele's own variables (`--pele-fg`, `--pele-surface`, ...) | Set from the `--pa-*` values |
+
+```css
+.pa-scene {
+  --pa-bg: #f6f6f0;
+  --pa-solid: #0b5fff;
+  --pa-light: #dbe7ff;
+  --pa-stroke: 1.25;
+}
+```
+
+For the full list of `--pele-*` variables, see Pele's [theming docs](https://pele.run).
+
+## Dark mode
+
+Dark colors apply when the system prefers dark, unless the page sets `data-theme="light"` on the root element. To force dark,
+set `data-theme="dark"` on the root element. Both follow the same variables, so overriding `--pa-solid` and friends works in
+either mode.
+
+## Reduced motion
+
+With `prefers-reduced-motion: reduce`, the intro and the tokens do not play: the finished picture shows.
+
+## Scene frame
+
+The panel, its padding and rounded corners come from `.pa-scene`. Override `border-radius`, `padding` or `margin` on it directly.

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "pele-animate",
-  "version": "0.13.0",
-  "description": "Animated, illustrated SVG scenes from plain Mermaid code, as a post-processor for Pele.",
+  "version": "0.14.0",
+  "description": "Step-by-step animated Mermaid diagrams with icons: an unofficial add-on for the Pele renderer.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/dkdev24/pele-animate#readme",
+  "packageManager": "pnpm@10.13.1",
+  "scripts": { "test": "node scripts/check-docs.mjs", "build": "pnpm -r --filter ./site build" },
   "publishConfig": { "access": "public" },
   "author": "Daniel Kim",
   "repository": { "type": "git", "url": "git+https://github.com/dkdev24/pele-animate.git" },
   "keywords": ["mermaid", "pele", "svg", "diagram", "animation"],
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./pele-animate.js",
-    "./glyphs": "./glyphs.js",
-    "./preset-doverunner": "./preset-doverunner.js",
+    ".": { "types": "./types/index.d.ts", "default": "./pele-animate.js" },
+    "./glyphs": { "types": "./types/glyphs.d.ts", "default": "./glyphs.js" },
+    "./preset-doverunner": { "types": "./types/preset-doverunner.d.ts", "default": "./preset-doverunner.js" },
     "./style.css": "./pele-animate.css",
-    "./tabler/*": "./tabler/*.js"
+    "./tabler/*": { "types": "./types/tabler-pack.d.ts", "default": "./tabler/*.js" }
   },
-  "files": ["pele-animate.js", "pele-animate.css", "glyphs.js", "preset-doverunner.js", "tabler", "THIRD-PARTY-NOTICES.md", "README.md", "LICENSE"],
+  "files": ["pele-animate.js", "pele-animate.css", "glyphs.js", "preset-doverunner.js", "tabler", "types", "docs", "skills", "THIRD-PARTY-NOTICES.md", "README.md", "LICENSE"],
   "sideEffects": ["*.css", "./preset-doverunner.js", "./tabler/*.js"],
   "peerDependencies": { "pele": "^1.7.0" },
   "devDependencies": { "pele": "^1.7.0" }

package/skills/diagram-step-order/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: diagram-step-order
+description: Review and fix the animation step order of pele-animate diagrams (Mermaid code blocks in document pages) against the page text, and tune groups, icons and labels so the flow reads clearly. Use when converting existing Mermaid diagrams to pele-animate, or when asked to check or adjust step order, `%% pa:` pins, or step-by-step playback of a diagram.
+---
+
+# Diagram step order
+
+Goal: when a viewer steps through a diagram (click, then ←/→), each step shows what the surrounding text says happens next.
+
+## What controls the order
+
+- **Flowcharts:** nodes appear by BFS level from the sources. An edge appears with its later end. `%% pa: 1=A,B 2=C` (first line inside the block, after the diagram type) pins nodes to steps. `%% pa: 3=A>B` pins the edge from A to B (needed for a reply or any edge between nodes that are already visible). Pin nodes first: an edge pinned before its target exists lands early. Unpinned nodes keep their BFS level; gaps in step numbers are skipped when stepping.
+- **Sequence diagrams:** step 1 is the participants, then one step per message in source order. Pins do nothing. Reordering messages changes what the diagram says, so never do it silently: if the order disagrees with the text, report it.
+- Ties: two edges into the same node share a step. Request and reply between the same two nodes land together unless the reply is edge-pinned.
+
+## Workflow
+
+1. **Find the blocks** in the page and read the prose around each one (heading, the paragraph before and after, captions, numbered lists). Write down the order the text describes, one line per step.
+2. **Probe the current order.** With the site running (restart a dev server after changing a locally copied library, then hard reload; a soft reload can show stale steps): open the page in a headless browser and evaluate `steps.js` in it (for example `agent-browser open <url>` then `agent-browser eval "$(cat steps.js)"`, or Playwright's `page.evaluate`). Each step prints its nodes, `[FROM_TO]` edges and quoted edge labels.
+3. **Triage.**
+   - Sequence diagram: compare message order with the text, change nothing, flag mismatches.
+   - Linear chain or decision tree: BFS order is normally right (branches of a decision appear together). Say "no change" and why.
+   - Existing pins: a person tuned them. Keep their intent; refine only where the text clearly disagrees, and say so.
+   - Topology with lanes or groups: usually needs work.
+4. **Fix** with pins and edge pins, then node declaration order and edge direction. Do not rename node ids (pins and CSS key on them) and do not change labels' meaning. Keep one idea per step: a request and its response are two steps; things that happen at the same moment share one.
+5. **Appearance.** Follow the site's own diagram conventions file (group colour ids, icon set, label length). Within it: put nodes in groups by who owns them, use a glyph where one fits the meaning, keep edge labels to one short line, order nodes inside a lane so arrows run in the reading direction. Do not edit shared styles or the library; list any needed glyph or CSS as a follow-up.
+6. **Mirror translations.** Translated pages have their own labels but the same node ids. Diff the ids between the two sources before copying a `%% pa:` line, then probe the translated page too.
+7. **Re-probe** every changed diagram and confirm the printed steps match the order you wrote down in step 1.
+
+## Lessons from the first run
+
+- Probe every diagram you report on, linear chains included. "Read the source" is not a check; one run left some diagrams unprobed.
+- A `<-->` edge is pinned in its first-written direction (`H>F` for `H <--> F`).
+- When several agents work in parallel, give each its own browser session (`agent-browser --session <name>`) and tell them not to start, stop or restart the shared dev server.
+- After changing a locally copied library, restart the dev server and clear its cache, or the page keeps the old module.
+- Edge pins need a pele-animate release that supports them; until then they are ignored and the node order still applies.
+- Tuned one language? Mirror the pins to the others in the same pass; a tuned EN page next to an untuned KO page is the usual miss.
+
+## Report, one row per diagram
+
+`page | n/total | before steps → after steps | one line tying the order to the text | changes (pins, groups, labels) | follow-ups`
+
+Say "no change" with the reason when you leave one alone. The person reviewing reads this table, so keep each cell short and let the probe output carry the detail.

package/skills/diagram-step-order/steps.js

@@ -0,0 +1,15 @@
+// Paste into the browser (agent-browser eval "$(cat steps.js)"): lists, per animated diagram on the page, what each step reveals.
+// Nodes by label, edges as [FROM_TO], edge labels in quotes. Relies on svg.paSteps, set by pele-animate animate().
+(() => [...document.querySelectorAll('.pa-scene')].map((sc, i) => {
+  const svg = sc.querySelector('svg.pele');
+  if (!svg?.paSteps) return `#${i + 1} (no steps)`;
+  const kind = svg.classList.contains('pele-sequence') ? 'seq' : 'flow';
+  const txt = (el) => el.textContent.replace(/\s+/g, ' ').trim();
+  const lines = svg.paSteps.map((items, n) => `  ${n + 1}: ` + items.map(([el]) => {
+    if (el.classList.contains('pele-edge')) return `[${el.dataset.id.replace(/^L_/, '').replace(/_\d+$/, '')}]`;
+    if (el.classList.contains('pele-edge-label')) return `"${txt(el)}"`;
+    if (el.classList.contains('pele-lifeline')) return '|';
+    return txt(el) || el.dataset.id;
+  }).filter((x) => x !== '|').join(' ; ')).join('\n');
+  return `#${i + 1} ${kind}\n${lines}`;
+}).join('\n'))()

package/skills/pele-animate/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: pele-animate
+description: Add animated, step-by-step Mermaid diagrams to a project with pele-animate (an add-on for the Pele renderer): install, mount on the client, pick icons from the Tabler packs, set the step order with `%% pa:` pins, theme with CSS variables, and verify in a browser. Use whenever asked to animate Mermaid diagrams, add icons to a flowchart, or make a diagram step-through, or when the project already imports `pele-animate`. Do not use for plain static diagrams or other Mermaid renderers.
+---
+
+# pele-animate
+
+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, and flowchart nodes can carry icons. It supports **flowcharts and sequence diagrams only**. Pele
+does the layout; pele-animate is an unofficial add-on and not a theme package.
+
+Your job when this skill is loaded: wire it into the project **and prove it renders**. Do not hand work back unverified.
+
+## Hard rules
+
+1. **Client only.** `pele` and `pele-animate` need the DOM. Load them with dynamic `import()` in the framework's mounted hook,
+   never in server code.
+2. **Never invent icon names.** Unknown names do not fail: they render a plain rounded square. Look names up (see Icons) and
+   import the category that holds them.
+3. **Import three things:** the resolver `icons` from `pele-animate/glyphs`, each icon category you use, and `pele-animate/style.css`.
+4. **Do not rename node ids after pinning the order**: pins match ids.
+5. **Verify in a browser** (last section). Reading the code is not a check.
+
+## 1. Install
+
+```sh
+npm i pele-animate pele        # or pnpm / yarn / bun; pele is a peer dependency (^1.7.0)
+```
+
+## 2. Mount (client side)
+
+```js
+const [{ mount }, { watch }, { icons }] = await Promise.all([
+  import('pele'), import('pele-animate'), import('pele-animate/glyphs'),
+  import('pele-animate/tabler/computers'),   // one import per icon category you use
+  import('pele-animate/style.css'),
+]);
+mount(el, src, { icons });   // Pele draws the SVG from the Mermaid text in `src`
+watch(el, src);              // pele-animate animates it (also on resize)
+```
+
+`el` is an element that holds the Mermaid source: a `<pre>` whose text is the diagram, or any element you set first with
+`el.textContent = src`. Mount once per element. `await` at the top level works in current Vite builds; elsewhere wrap the code
+in an `async` function.
+Framework placement (Vite, Astro, SvelteKit, Nuxt, React): `docs/recipes.md` in the package, or the table below.
+
+| Framework | Put it in |
+|---|---|
+| Plain HTML / Vite | A module script |
+| Astro | A client `<script>` that finds the diagram elements |
+| SvelteKit | `onMount(async () => { ... })` |
+| Nuxt | `onMounted` in a `.client.vue` component |
+| React / Next.js (untested) | A client component, `useEffect` |
+
+TypeScript: a CSS side-effect import needs a `*.css` module declaration unless the project uses Vite's client types.
+
+## 3. Write the diagram
+
+Icon nodes use Mermaid's own syntax:
+
+```mermaid
+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
+```
+
+- `form: "square", h: 88` = large frameless icon. Leave both out for a small icon in a frame.
+- **Sequence diagrams ignore icons** (the participant box shows its id).
+- Keep node ids short and stable (`C`, `L`, `S`); labels are what people read.
+
+### Icons: find the name, then import its category
+
+4,368 Tabler outline icons in 36 categories, each its own module `pele-animate/tabler/<category>`. Category list with sample
+names: `references/categories.md`. To find a name:
+
+```sh
+# by keyword, across all categories (prints  file:"name":)
+grep -o '"[a-z0-9-]*server[a-z0-9-]*":' node_modules/pele-animate/tabler/*.js | head
+# every name in one category
+node -e "import('pele-animate/tabler/devices').then(m => console.log(Object.keys(m.pack).join(' ')))"
+```
+
+The file the keyword appears in tells you which category to import. A keyword grep also matches longer names (`user` matches
+`user-bolt`), so confirm the exact name with an anchored check, e.g. `grep -l '"user":' node_modules/pele-animate/tabler/*.js`.
+Abstract concepts often have no icon of their own (there is no `client`): pick a close synonym (`user`, `device-desktop`) and
+label the node with the real word. Optional extras: `import 'pele-animate/preset-doverunner'`
+adds 20 filled glyphs named `doverunner-<name>`; only use it if the project already does or the user asks for that look.
+Custom glyphs: `registerGlyphs({ name: '<inner markup of a 24x24 svg>' })` from `pele-animate/glyphs`.
+
+## 4. Step order
+
+Default order follows the edges. Override with one comment line anywhere in the source:
+
+- `%% pa: 1=A 2=B,C` : step 1 shows A, step 2 shows B and C (steps count from 1).
+- `%% pa: 1=A,B 2=C 3=A>B` : `X>Y` pins the edge from X to Y to its own step. **Pin the nodes first.** A two-way edge
+  (`A <--> B`) is pinned in the direction you wrote first.
+
+Click or Enter on a diagram starts step mode (prev / play / next; Space, ←, →, Esc). `watch(el, src, { controls: false })` turns that off.
+To review the order of existing diagrams against the page text, use the `diagram-step-order` skill.
+
+## 5. Theme
+
+Set on the container (`.pa-scene`, added by `watch`): `--pa-bg` (panel), `--pa-solid` (strong color), `--pa-light` (light fill),
+`--pa-stroke` (Tabler stroke width, default 1.5), plus any `--pele-*`. Dark mode follows `prefers-color-scheme`, or force it
+with `data-theme="dark"` on the root element. `prefers-reduced-motion` turns the intro and tokens off.
+
+## 6. Verify
+
+Build or run the project, open the page in a headless browser, wait about 3 seconds (the intro starts when 30% of the diagram
+is in view, so scroll it into view first), and evaluate `verify.js` (next to this file) in the page:
+
+```sh
+agent-browser open http://localhost:PORT/page && agent-browser eval "$(cat verify.js)"   # or Playwright page.evaluate
+```
+
+Expect: `diagrams` equals the number you added; every `steps` entry above 0; `emptyIcons` empty; `fallbackIcons` empty unless a
+plain square was intended. Fix by cause:
+
+| Symptom | Cause |
+|---|---|
+| `diagrams: 0` | `watch()` never ran: it was not client-side, or the element was not found |
+| `fallbackIcons` lists a name | The name does not exist, or its category was not imported. Look it up again |
+| Icons missing but names are right | The category import ran after `mount()`; import packs before mounting |
+| `steps` is `[0]` or a single step | `%% pa:` pins mismatched ids, or the diagram type is unsupported |
+| Looks unstyled | `pele-animate/style.css` not imported |
+
+Print the order to compare with the text you meant: `svg.paSteps.map((items, n) => ...)`, or use `diagram-step-order/steps.js`.

package/skills/pele-animate/references/categories.md

@@ -0,0 +1,42 @@
+# Tabler categories (generated by scripts/build-tabler.mjs; Tabler Icons 3.49.0, MIT)
+
+Import `pele-animate/tabler/<category>`. Names below are a sample; the full list is the object keys in `node_modules/pele-animate/tabler/<category>.js`.
+
+| Category | Icons | Sample names |
+|---|---|---|
+| `system` | 784 | ad-circle-off, calendar-exclamation, dental-broken, filter-question, loader-2, pointer-cancel, shield-cog, tip-jar-euro |
+| `devices` | 363 | access-point-off, browser-off, device-desktop-question, device-ipad-horizontal-cog, device-mobile-pin, device-usb, devices-star, power |
+| `design` | 350 | ad-2, bounce-left, color-picker-off, droplet-star, inner-shadow-top-right, layout-grid, pencil-minus, sparkles-2-off |
+| `arrows` | 333 | arrow-autofit-content, arrow-big-up, arrow-merge-alt-right, arrow-sharp-turn-right, arrows-move-vertical, chevrons-down, corner-up-left-double, square-chevrons-left |
+| `map` | 263 | air-traffic-control, flag-pause, location-pin, map-pin-down, medical-cross, pennant-2, sign-left, world-heart |
+| `document` | 209 | archive-off, clipboard-copy, file-cv, file-orientation, file-type-csv, file-zip, folder-stats, receipt-off |
+| `text` | 194 | a-b-2, align-right-2, baseline-density-medium, copy-x, italic-off, overline, sort-ascending, text-regex-plus |
+| `shapes` | 187 | border-corner-ios, circle-minus-2, cylinder-off, heart-plus, hexagonal-prism, pentagon-off, sphere-plus, square-rounded-minus |
+| `media` | 160 | album-off, camera-plus, headset-off, music-cog, photo-cancel, photo-spark, playlist, rewind-forward-50 |
+| `e-commerce` | 155 | backpack-off, basket-star, cash-plus, credit-card, package, shopping-bag-exclamation, shopping-cart-pause, tags-off |
+| `communication` | 121 | address-book-off, mail-down, mail-up, message-2-off, message-check, message-circle-search, message-minus, messages-off |
+| `food` | 96 | apple, bowl, carrot-off, cup, glass-off, lollipop-off, milkshake, salad |
+| `buildings` | 95 | armchair-2-off, building-bridge, building-factory-2, building-stadium, home-2, home-hand, home-share, podium |
+| `vehicles` | 90 | aerial-lift, camper, car-off, engine, motorbike, sailboat-off, steering-wheel, wheelchair |
+| `math` | 88 | abacus-off, decimal, math-1-divide-3, math-integral, math-sin, math-xy, parentheses-off, sum |
+| `health` | 87 | accessible-off, cane, dna-2, eye-table, flask-2, hospital-circle, pill-off, stethoscope |
+| `sport` | 76 | acrobatic, barbell-off, cliff-jumping, hula-hoop, olympics, rugby, soccer-field, trekking |
+| `currencies` | 76 | currency-afghani, currency-dollar-canadian, currency-euro, currency-krone-danish, currency-nano, currency-riyal, currency-tether, taiwan-dollar |
+| `development` | 63 | a-b, api-book, auth-2fa, firewall-check, package-import, scan-traces, thinking-high, timeline-event |
+| `weather` | 61 | cloud-bolt, cloud-fog, cloud-rain, cloud, moon-off, storm, sunset-2, tornado |
+| `photography` | 52 | aperture-off, brightness-up, contrast, exposure, lens-convex, panorama-vertical-off, photo-sensor-3, shadow |
+| `mood` | 52 | mood-angry, mood-confused, mood-heart, mood-nerd, mood-sad-2, mood-silence, mood-tongue-wink-2, mood-wrrr |
+| `nature` | 50 | acorn, butterfly, clover-2, flame-off, leaf-maple, orbit-vertical, ripple-off, wind-electricity |
+| `games` | 48 | archery-arrow, dice-5, ghost, pick, play-card-5, play-card-j, poker-chip, roulette |
+| `computers` | 44 | binary-off, error-404-off, http-get-off, http-patch-off, http-que-off, network, topology-ring-3, topology-star-ring |
+| `database` | 42 | column-insert-left, database-exclamation, database-off, database, row-remove, table-export, table-plus |
+| `laundry` | 40 | bleach-chlorine, ironing-2, ironing, wash-dry-dip, wash-dry-p, wash-dryclean, wash-press, wash-temperature-5 |
+| `charts` | 39 | chart-arcs-3, chart-arrows, chart-candle, chart-donut-2, chart-dots-3, chart-infographic, chart-pie-off, chart-scatter-3d |
+| `symbols` | 37 | ankh, command-off, copyright-off, mars, peace, rating-16-plus, registered, venus |
+| `badges` | 22 | award-off, badge-3d, badge-5k, badge-ad, badge-hd, badge-tm, badge-wc, badges |
+| `electrical` | 19 | circuit-ammeter, circuit-capacitor-polarized, circuit-cell, circuit-diode, circuit-inductor, circuit-resistor, circuit-voltmeter |
+| `animals` | 18 | bat, dog, fish-hook-off, fish, paw-off, pig-off |
+| `gestures` | 17 | hand-click-off, hand-finger-left, hand-finger, hand-love-you, hand-off, hand-three-fingers |
+| `version-control` | 16 | git-branch-check, git-branch-x, git-cherry-pick, git-compare, git-merge-queue, git-pull-request-closed, git-pull-request-draft, git-pull-request-unlisted |
+| `extensions` | 13 | bmp, gif, jpg, pdf, sql, toml, zip |
+| `logic` | 8 | logic-and, logic-buffer, logic-nand, logic-nor, logic-not, logic-or, logic-xnor, logic-xor |

package/skills/pele-animate/verify.js

@@ -0,0 +1,14 @@
+// Evaluate in the page (e.g. `agent-browser eval "$(cat verify.js)"` or Playwright page.evaluate): did pele-animate render?
+// Expect: diagrams = how many you added, every steps entry > 0, emptyIcons = [], and no name in `fallbackIcons` you meant to be real.
+(() => {
+  const svgs = [...document.querySelectorAll('.pa-scene svg.pele')];
+  const icons = [...document.querySelectorAll('.pa-scene svg.pele-icon[data-icon]')];
+  // An unregistered name renders pele-animate's neutral rounded square: one <rect x="4" y="4" ...> and nothing else.
+  const fallback = (i) => /^<g[^>]*><rect x="4" y="4" width="16" height="16" rx="4"(\/>|><\/rect>)<\/g>$/.test(i.innerHTML.trim());
+  return JSON.stringify({
+    diagrams: svgs.length,
+    steps: svgs.map((s) => s.paSteps?.length ?? 0),
+    emptyIcons: icons.filter((i) => !i.innerHTML.trim()).map((i) => i.dataset.icon),
+    fallbackIcons: icons.filter(fallback).map((i) => i.dataset.icon),
+  });
+})()

package/types/glyphs.d.ts

@@ -0,0 +1,13 @@
+/** Theme colors the illustrated glyphs use: CSS variables with fallbacks. */
+export const S: string;
+export const L: string;
+export const W: string;
+
+/** Register glyphs: `{ name: '<inner markup of a 24x24 svg>' }`. Default stroke width 1.1. */
+export function registerGlyphs(pack: Record<string, string>, strokeWidth?: number): void;
+
+/** Register Tabler-style outline icons; stroke width follows the `--pa-stroke` CSS variable (fallback `strokeWidth`, default 1.5). */
+export function registerTabler(pack: Record<string, string>, strokeWidth?: number): void;
+
+/** Pele `icons` resolver. Unknown names return a neutral rounded square. */
+export function icons(name: string): string;

package/types/index.d.ts

@@ -0,0 +1,33 @@
+export interface AnimateOptions {
+  /** Element that triggers the hover token animation. Default: the svg itself. */
+  hover?: Element;
+  /** The Mermaid source, read for `%% pa:` pins. */
+  source?: string;
+}
+
+export interface WatchOptions {
+  /** `false` keeps the old click-to-replay instead of step mode. Default `true`. */
+  controls?: boolean;
+}
+
+/** One step: the elements that appear and, for each, the parts that pop in. */
+export type PaStep = Array<[element: Element, parts: Element[]]>;
+
+declare global {
+  interface SVGSVGElement {
+    /** Set by `animate()`: one array per step. */
+    paSteps?: PaStep[];
+  }
+}
+
+/** Read the `%% pa:` pins: node id, or `'X>Y'` for an edge, to a 0-based step. */
+export function parseOrder(source?: string): Map<string, number>;
+
+/** Animate one rendered Pele svg (flowchart or sequence diagram). */
+export function animate(svg: SVGSVGElement, options?: AnimateOptions): void;
+
+/** Animate every svg Pele renders into `container`, re-applying after Pele re-lays-out on resize. */
+export function watch(container: HTMLElement, source?: string, options?: WatchOptions): void;
+
+/** Play the intro again. */
+export function replay(svg: SVGSVGElement | null | undefined): void;

package/types/preset-doverunner.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tabler-pack.d.ts

@@ -0,0 +1,2 @@
+/** The icons of one Tabler category: name to inner svg markup. Importing the module also registers them. */
+export const pack: Record<string, string>;