pele-animate 0.12.0 → 0.14.0

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/glyphs.js

@@ -1,4 +1,4 @@
-// Glyph registry. A glyph is the inner markup of a 24x24 SVG; colors come from --pa-* variables so packs can theme.
+// Glyph registry. No art lives here: the illustrated glyphs are in preset-doverunner.js, named `doverunner-<name>`; plain names belong to the Tabler packs. A glyph is the inner markup of a 24x24 SVG; colors come from --pa-* variables so packs can theme.
 // Pass `icons` to pele's render()/mount() options: mount(el, text, { icons }).
 export const S = 'var(--pa-solid,#4F378B)';
 export const L = 'var(--pa-light,#d9d0f0)';
@@ -9,15 +9,12 @@ const reg = new Map();
 export function registerGlyphs(pack, strokeWidth = 1.1) {
   for (const [name, markup] of Object.entries(pack)) reg.set(name, `<g stroke-width="${strokeWidth}">${markup}</g>`);
 }
-// Returning null makes pele fall back to its default node.
-export const icons = (name) => reg.get(name) ?? null;
-
-registerGlyphs({
-  player: `<defs><linearGradient id="pa-g-screen" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#6b4fb5"/><stop offset="1" stop-color="#2c1f52"/></linearGradient></defs><rect x="2" y="4" width="20" height="13" rx="2" fill="url(#pa-g-screen)" stroke="${S}"/><path d="M10 7.8v5.4l4.8-2.7z" fill="${W}" stroke="none"/><path d="M9 20.5h6M12 17v3.5" stroke="${S}"/>`,
-  server: `<rect x="3" y="3.5" width="18" height="7" rx="2" fill="${L}" stroke="${S}"/><rect x="3" y="13.5" width="18" height="7" rx="2" fill="${L}" stroke="${S}"/><circle cx="7" cy="7" r="1" fill="${S}" stroke="none"/><circle cx="7" cy="17" r="1" fill="${S}" stroke="none"/><path d="M12 7h6M12 17h6" stroke="${S}"/>`,
-  key: `<circle cx="8" cy="12" r="4.5" fill="${L}" stroke="${S}"/><circle cx="8" cy="12" r="1.4" fill="${S}" stroke="none"/><path d="M12.5 12H21M18 12v3.5M21 12v2.5" stroke="${S}"/>`,
-  document: `<path d="M6 2.5h8l4.5 4.5v14a1 1 0 0 1-1 1h-11.5a1 1 0 0 1-1-1v-17.5a1 1 0 0 1 1-1z" fill="${L}" stroke="${S}"/><path d="M14 2.5V7h4.5" fill="none" stroke="${S}"/><path d="M8.5 12h7M8.5 15.5h7" stroke="${S}"/>`,
-  shield: `<path d="M12 2.5l8 3v6c0 5-3.4 8.5-8 10-4.6-1.5-8-5-8-10v-6z" fill="${S}" stroke="none"/><path d="M8.5 12l2.6 2.6 4.6-5" fill="none" stroke="${W}" stroke-width="2.2"/>`,
-  phone: `<rect x="6.5" y="2" width="11" height="20" rx="2.5" fill="${W}" stroke="${S}"/><path d="M10.5 3.8h3" stroke="${S}"/><rect x="8.5" y="6" width="7" height="4" rx="1" fill="${S}" stroke="none"/><path d="M8.5 12.5h7M8.5 15h7M8.5 17.5h4" stroke="${S}"/><path d="M10.5 20.2h3" stroke="${S}"/>`,
-  cloud: `<path d="M7 18a4 4 0 0 1-.6-7.96A5.5 5.5 0 0 1 17 8.5a4.75 4.75 0 0 1 .5 9.5z" fill="${L}" stroke="${S}"/>`,
-});
+// Tabler packs (tabler/*.js): outline icons drawn for any stroke width. Width comes from the CSS variable --pa-stroke, so a
+// stylesheet can thicken or thin every Tabler glyph at once; `strokeWidth` is the fallback. Illustrated glyphs are all prefixed `doverunner-`, so Tabler names never collide.
+export function registerTabler(pack, strokeWidth = 1.5) {
+  const g = (m) => `<g fill="none" stroke="${S}" stroke-linecap="round" stroke-linejoin="round" style="stroke-width:var(--pa-stroke,${strokeWidth})">${m}</g>`;
+  for (const [name, markup] of Object.entries(pack)) reg.set(name, g(markup));
+}
+// Unknown names get a neutral rounded square instead of Pele's blank icon slot (Pele ships no icons of its own).
+const fallback = `<g fill="none" stroke="${S}" stroke-linecap="round" stroke-linejoin="round" style="stroke-width:var(--pa-stroke,1.5)"><rect x="4" y="4" width="16" height="16" rx="4"/></g>`;
+export const icons = (name) => reg.get(name) ?? fallback;

package/package.json

@@ -1,22 +1,26 @@
 {
   "name": "pele-animate",
-  "version": "0.12.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",
-    "./style.css": "./pele-animate.css"
+    ".": { "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/*": { "types": "./types/tabler-pack.d.ts", "default": "./tabler/*.js" }
   },
-  "files": ["pele-animate.js", "pele-animate.css", "glyphs.js", "preset-doverunner.js", "README.md", "LICENSE"],
-  "sideEffects": ["*.css", "./preset-doverunner.js"],
+  "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/preset-doverunner.js

@@ -1,4 +1,4 @@
-// DoveRunner vocabulary (DRM / forensic watermarking / packaging). Add on top of the generic pack in glyphs.js.
+// DoveRunner illustrated glyphs, all named `doverunner-<name>`: generic player/server/key/document/shield/phone/cloud, plus DRM / forensic watermarking / packaging vocabulary. Needs the registry in glyphs.js.
 import { registerGlyphs, S, L, W } from './glyphs.js';
 
 // A row of six video-segment chips; bit 1 = filled, bit 0 = outline.
@@ -12,17 +12,27 @@ const chips = (bits) =>
     .join('');
 
 registerGlyphs({
-  package: `<path d="M12 2.5l8.5 4.5v10L12 21.5 3.5 17V7z" fill="${L}" stroke="${S}"/><path d="M3.5 7L12 11.5 20.5 7M12 11.5v10" fill="none" stroke="${S}"/><path d="M8 4.8l8.5 4.5" stroke="${S}"/>`,
-  token: `<path d="M3 7.5A1.5 1.5 0 0 1 4.5 6h15A1.5 1.5 0 0 1 21 7.5V10a2 2 0 0 0 0 4v2.5a1.5 1.5 0 0 1-1.5 1.5h-15A1.5 1.5 0 0 1 3 16.5V14a2 2 0 0 0 0-4z" fill="${L}" stroke="${S}"/><circle cx="9" cy="12" r="2.2" fill="${S}" stroke="none"/><path d="M13.5 10.5h4.5M13.5 13.5h3" stroke="${S}"/>`,
-  lock: `<path d="M8.5 10.5V8a3.5 3.5 0 0 1 7 0v2.5" fill="none" stroke="${S}"/><rect x="5" y="10.5" width="14" height="10" rx="2" fill="${S}" stroke="none"/><circle cx="12" cy="15" r="1.5" fill="${W}" stroke="none"/><path d="M12 15.5v2.2" stroke="${W}"/>`,
-  video: `<rect x="2" y="6" width="13" height="12" rx="2" fill="${L}" stroke="${S}"/><path d="M15 10.8l6-3.6v9.6l-6-3.6z" fill="${S}" stroke="${S}"/><circle cx="5.6" cy="9.4" r="1" fill="${S}" stroke="none"/>`,
-  media: `<rect x="2" y="4" width="15" height="11" rx="2" fill="${L}" stroke="${S}"/><path d="M7.6 7.2v5.6l4.6-2.8z" fill="${S}" stroke="none"/><ellipse cx="14.8" cy="19" rx="2.3" ry="1.8" fill="${S}" stroke="none"/><path d="M17 19V9.5q3 .2 3.6 3.4" fill="none" stroke="${S}"/>`,
-  storage: `<ellipse cx="12" cy="6" rx="8" ry="2.6" fill="${L}" stroke="${S}"/><path d="M4 6l2.4 13.4c.4 1.3 3 2.1 5.6 2.1s5.2-.8 5.6-2.1L20 6" fill="${L}" stroke="${S}"/><path d="M4.6 9.6c1.6 1.2 4.2 1.8 7.4 1.8s5.8-.6 7.4-1.8" fill="none" stroke="${S}"/>`,
-  plugin: `<path d="M4 8h4.5a2.2 2.2 0 1 1 4.4 0H17v4.1a2.2 2.2 0 1 1 0 4.4V20H4z" fill="${L}" stroke="${S}"/><path d="M17 8h3v12h-3" fill="none" stroke="${S}"/>`,
-  variants: `<rect x="2.5" y="3" width="14" height="9.5" rx="2" fill="${L}" stroke="${S}"/><rect x="7.5" y="11.5" width="14" height="9.5" rx="2" fill="${W}" stroke="${S}"/><text x="9.5" y="10.4" font-size="6.5" font-weight="700" text-anchor="middle" fill="${S}" stroke="none">A</text><text x="14.5" y="19" font-size="6.5" font-weight="700" text-anchor="middle" fill="${S}" stroke="none">B</text>`,
-  watermark: `<rect x="2.5" y="4" width="19" height="16" rx="2" fill="${L}" stroke="${S}"/><path d="M12 7.4c2.9 3.3 4.2 5 4.2 7a4.2 4.2 0 0 1-8.4 0c0-2 1.3-3.7 4.2-7z" fill="${S}" stroke="none"/><path d="M10.2 14.6a1.9 1.9 0 0 0 1.4 1.9" fill="none" stroke="${W}"/>`,
-  encoder: `<rect x="1.5" y="4" width="9" height="16" rx="1.5" fill="${L}" stroke="${S}"/><rect x="4.3" y="7" width="3.4" height="10" rx=".6" fill="${W}" stroke="${S}"/><path d="M2.9 6.5h.9M2.9 10.5h.9M2.9 14.5h.9M8.2 6.5h.9M8.2 10.5h.9M8.2 14.5h.9" stroke="${S}"/><path d="M12 12h3.5M14 10l2 2-2 2" fill="none" stroke="${S}"/><rect x="17.6" y="6.2" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/><rect x="20.4" y="6.2" width="2.4" height="2.8" rx=".5" fill="${W}" stroke="${S}"/><rect x="17.6" y="10.6" width="2.4" height="2.8" rx=".5" fill="${W}" stroke="${S}"/><rect x="20.4" y="10.6" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/><rect x="17.6" y="15" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/><rect x="20.4" y="15" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/>`,
-  database: `<path d="M4 6v12c0 1.7 3.6 3 8 3s8-1.3 8-3V6" fill="${L}" stroke="${S}"/><ellipse cx="12" cy="6" rx="8" ry="3" fill="${L}" stroke="${S}"/><path d="M4 12c0 1.7 3.6 3 8 3s8-1.3 8-3" fill="none" stroke="${S}"/>`,
+  'doverunner-player': `<defs><linearGradient id="pa-g-screen" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#6b4fb5"/><stop offset="1" stop-color="#2c1f52"/></linearGradient></defs><rect x="2" y="4" width="20" height="13" rx="2" fill="url(#pa-g-screen)" stroke="${S}"/><path d="M10 7.8v5.4l4.8-2.7z" fill="${W}" stroke="none"/><path d="M9 20.5h6M12 17v3.5" stroke="${S}"/>`,
+  'doverunner-server': `<rect x="3" y="3.5" width="18" height="7" rx="2" fill="${L}" stroke="${S}"/><rect x="3" y="13.5" width="18" height="7" rx="2" fill="${L}" stroke="${S}"/><circle cx="7" cy="7" r="1" fill="${S}" stroke="none"/><circle cx="7" cy="17" r="1" fill="${S}" stroke="none"/><path d="M12 7h6M12 17h6" stroke="${S}"/>`,
+  'doverunner-key': `<circle cx="8" cy="12" r="4.5" fill="${L}" stroke="${S}"/><circle cx="8" cy="12" r="1.4" fill="${S}" stroke="none"/><path d="M12.5 12H21M18 12v3.5M21 12v2.5" stroke="${S}"/>`,
+  'doverunner-document': `<path d="M6 2.5h8l4.5 4.5v14a1 1 0 0 1-1 1h-11.5a1 1 0 0 1-1-1v-17.5a1 1 0 0 1 1-1z" fill="${L}" stroke="${S}"/><path d="M14 2.5V7h4.5" fill="none" stroke="${S}"/><path d="M8.5 12h7M8.5 15.5h7" stroke="${S}"/>`,
+  'doverunner-shield': `<path d="M12 2.5l8 3v6c0 5-3.4 8.5-8 10-4.6-1.5-8-5-8-10v-6z" fill="${S}" stroke="none"/><path d="M8.5 12l2.6 2.6 4.6-5" fill="none" stroke="${W}" stroke-width="2.2"/>`,
+  'doverunner-phone': `<rect x="6.5" y="2" width="11" height="20" rx="2.5" fill="${W}" stroke="${S}"/><path d="M10.5 3.8h3" stroke="${S}"/><rect x="8.5" y="6" width="7" height="4" rx="1" fill="${S}" stroke="none"/><path d="M8.5 12.5h7M8.5 15h7M8.5 17.5h4" stroke="${S}"/><path d="M10.5 20.2h3" stroke="${S}"/>`,
+  'doverunner-cloud': `<path d="M7 18a4 4 0 0 1-.6-7.96A5.5 5.5 0 0 1 17 8.5a4.75 4.75 0 0 1 .5 9.5z" fill="${L}" stroke="${S}"/>`,
+});
+
+registerGlyphs({
+  'doverunner-package': `<path d="M12 2.5l8.5 4.5v10L12 21.5 3.5 17V7z" fill="${L}" stroke="${S}"/><path d="M3.5 7L12 11.5 20.5 7M12 11.5v10" fill="none" stroke="${S}"/><path d="M8 4.8l8.5 4.5" stroke="${S}"/>`,
+  'doverunner-token': `<path d="M3 7.5A1.5 1.5 0 0 1 4.5 6h15A1.5 1.5 0 0 1 21 7.5V10a2 2 0 0 0 0 4v2.5a1.5 1.5 0 0 1-1.5 1.5h-15A1.5 1.5 0 0 1 3 16.5V14a2 2 0 0 0 0-4z" fill="${L}" stroke="${S}"/><circle cx="9" cy="12" r="2.2" fill="${S}" stroke="none"/><path d="M13.5 10.5h4.5M13.5 13.5h3" stroke="${S}"/>`,
+  'doverunner-lock': `<path d="M8.5 10.5V8a3.5 3.5 0 0 1 7 0v2.5" fill="none" stroke="${S}"/><rect x="5" y="10.5" width="14" height="10" rx="2" fill="${S}" stroke="none"/><circle cx="12" cy="15" r="1.5" fill="${W}" stroke="none"/><path d="M12 15.5v2.2" stroke="${W}"/>`,
+  'doverunner-video': `<rect x="2" y="6" width="13" height="12" rx="2" fill="${L}" stroke="${S}"/><path d="M15 10.8l6-3.6v9.6l-6-3.6z" fill="${S}" stroke="${S}"/><circle cx="5.6" cy="9.4" r="1" fill="${S}" stroke="none"/>`,
+  'doverunner-media': `<rect x="2" y="4" width="15" height="11" rx="2" fill="${L}" stroke="${S}"/><path d="M7.6 7.2v5.6l4.6-2.8z" fill="${S}" stroke="none"/><ellipse cx="14.8" cy="19" rx="2.3" ry="1.8" fill="${S}" stroke="none"/><path d="M17 19V9.5q3 .2 3.6 3.4" fill="none" stroke="${S}"/>`,
+  'doverunner-storage': `<ellipse cx="12" cy="6" rx="8" ry="2.6" fill="${L}" stroke="${S}"/><path d="M4 6l2.4 13.4c.4 1.3 3 2.1 5.6 2.1s5.2-.8 5.6-2.1L20 6" fill="${L}" stroke="${S}"/><path d="M4.6 9.6c1.6 1.2 4.2 1.8 7.4 1.8s5.8-.6 7.4-1.8" fill="none" stroke="${S}"/>`,
+  'doverunner-plugin': `<path d="M4 8h4.5a2.2 2.2 0 1 1 4.4 0H17v4.1a2.2 2.2 0 1 1 0 4.4V20H4z" fill="${L}" stroke="${S}"/><path d="M17 8h3v12h-3" fill="none" stroke="${S}"/>`,
+  'doverunner-variants': `<rect x="2.5" y="3" width="14" height="9.5" rx="2" fill="${L}" stroke="${S}"/><rect x="7.5" y="11.5" width="14" height="9.5" rx="2" fill="${W}" stroke="${S}"/><text x="9.5" y="10.4" font-size="6.5" font-weight="700" text-anchor="middle" fill="${S}" stroke="none">A</text><text x="14.5" y="19" font-size="6.5" font-weight="700" text-anchor="middle" fill="${S}" stroke="none">B</text>`,
+  'doverunner-watermark': `<rect x="2.5" y="4" width="19" height="16" rx="2" fill="${L}" stroke="${S}"/><path d="M12 7.4c2.9 3.3 4.2 5 4.2 7a4.2 4.2 0 0 1-8.4 0c0-2 1.3-3.7 4.2-7z" fill="${S}" stroke="none"/><path d="M10.2 14.6a1.9 1.9 0 0 0 1.4 1.9" fill="none" stroke="${W}"/>`,
+  'doverunner-encoder': `<rect x="1.5" y="4" width="9" height="16" rx="1.5" fill="${L}" stroke="${S}"/><rect x="4.3" y="7" width="3.4" height="10" rx=".6" fill="${W}" stroke="${S}"/><path d="M2.9 6.5h.9M2.9 10.5h.9M2.9 14.5h.9M8.2 6.5h.9M8.2 10.5h.9M8.2 14.5h.9" stroke="${S}"/><path d="M12 12h3.5M14 10l2 2-2 2" fill="none" stroke="${S}"/><rect x="17.6" y="6.2" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/><rect x="20.4" y="6.2" width="2.4" height="2.8" rx=".5" fill="${W}" stroke="${S}"/><rect x="17.6" y="10.6" width="2.4" height="2.8" rx=".5" fill="${W}" stroke="${S}"/><rect x="20.4" y="10.6" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/><rect x="17.6" y="15" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/><rect x="20.4" y="15" width="2.4" height="2.8" rx=".5" fill="${S}" stroke="${S}"/>`,
+  'doverunner-database': `<path d="M4 6v12c0 1.7 3.6 3 8 3s8-1.3 8-3V6" fill="${L}" stroke="${S}"/><ellipse cx="12" cy="6" rx="8" ry="3" fill="${L}" stroke="${S}"/><path d="M4 12c0 1.7 3.6 3 8 3s8-1.3 8-3" fill="none" stroke="${S}"/>`,
 });
 // Thinner line: the chips are small even at full box size.
-registerGlyphs({ 'bits-a': chips('011010'), 'bits-b': chips('101101') }, 0.5);
+registerGlyphs({ 'doverunner-bits-a': chips('011010'), 'doverunner-bits-b': chips('101101') }, 0.5);

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`.