pele-animate 0.14.0 → 0.16.0

package/README.md

@@ -1,78 +1,55 @@
 # pele-animate
 
+[![npm](https://img.shields.io/npm/v/pele-animate)](https://www.npmjs.com/package/pele-animate)
+[![CI](https://github.com/dkdev24/pele-animate/actions/workflows/ci.yml/badge.svg)](https://github.com/dkdev24/pele-animate/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/pele-animate)](LICENSE)
+
 Mermaid diagrams that explain themselves one step at a time, with icons. You choose the order things appear in, readers
 step through it, and nodes can carry icons. A small post-processor for [Pele](https://github.com/obsidianmd/pele) (MIT),
 which renders the Mermaid; this adds the step order, the playback and the icons. It is not a theme package.
 Unofficial add-on; not affiliated with or endorsed by the Pele or Obsidian teams.
-The source stays valid Mermaid, so GitHub or Obsidian still show a normal diagram.
-
-- Nodes appear in order (BFS from the sources, or pinned with a `%% pa:` comment), edges draw in, labels fade in.
-- Hover or focus: tokens travel the edges in sequence. The intro plays once on scroll-in. Click (or Enter) enters step mode: previous / play-pause / next buttons, with Space (play/pause), ←/→ (step) and Esc (leave).
-- `@{ icon: "name" }` nodes become illustrations from a glyph pack. Unknown names get a neutral rounded-square glyph.
-- Sequence diagrams: participant boxes in a row get the tallest height (Pele sizes each to its own text). Group and box titles are bold.
-- Idle state is the finished picture; `prefers-reduced-motion` turns the motion off. Light and dark themes.
-
-## Compare
-
-The same Mermaid source, three renderers. The pele-animate images loop: the intro draws in, then tokens travel the edges (as on hover).
-Regenerate with `examples/capture.sh`.
-
-```mermaid
-flowchart LR
-  A[Player] -->|auth token| B[OTT service]
-  A -->|license request| C[DRM server]
-  C -->|license| A
-```
-
-| Renderer | Result |
-|---|---|
-| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m1.png" width="560" alt="Flowchart rendered by Mermaid"> |
-| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p1.png" width="560" alt="Flowchart rendered by Pele"> |
-| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a1.gif" width="560" alt="Animated flowchart: nodes appear, edges draw in, tokens travel"> |
-
-```mermaid
-sequenceDiagram
-  Player->>OTT: sign in
-  OTT-->>Player: token
-  Player->>DRM: token
-  DRM-->>Player: license
-```
 
-| Renderer | Result |
-|---|---|
-| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m2.png" width="560" alt="Sequence diagram rendered by Mermaid"> |
-| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p2.png" width="560" alt="Sequence diagram rendered by Pele"> |
-| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a2.gif" width="560" alt="Animated sequence diagram: messages appear in order, tokens travel"> |
-
-With icons (`@{ icon }` nodes from the Tabler `computers` pack, `%% pa: 1=C 2=L 3=S` pins the order):
+**[Website](https://pele-animate.pages.dev/) · [Docs](docs/getting-started.md) · [npm](https://www.npmjs.com/package/pele-animate) · [Changelog](CHANGELOG.md)**
 
 <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">
 
+- **You set the order.** Nodes appear in the order of a `%% pa:` comment, or by default along the edges; edges draw in and labels fade in.
+- **Readers step through it.** Click (or Enter) starts step mode: previous / play-pause / next buttons, Space, ←/→ and Esc. Hover or focus sends tokens along the edges.
+- **Icons.** `@{ icon: "name" }` nodes use any of 4,368 [Tabler](https://github.com/tabler/tabler-icons) icons (loaded per category) or your own. Unknown names get a neutral rounded square.
+- Flowcharts, sequence diagrams, architecture diagrams, state diagrams, C4 context, block, class and ER diagrams, timelines, journeys, git graphs and Gantt charts. The finished picture is the resting state; `prefers-reduced-motion` turns the motion off. Light and dark themes.
+- The source stays valid Mermaid. One catch: GitHub's own Mermaid renderer does not know the icon names and draws "?" boxes, so the icon examples in this repository are shown as source text.
+
 ## Install
 
 ```sh
 npm i pele-animate pele
+# or
+pnpm add pele-animate pele
+yarn add pele-animate pele
+bun add pele-animate pele
 ```
 
+`pele` is a peer dependency (`^1.7.0`): install it alongside. Both packages run in the browser and need the DOM, so mount them on the client (see [recipes](docs/recipes.md)). ESM only.
+
 ## Use
 
 ```js
 import { mount } from 'pele';
-import { watch } from 'pele-animate';
+import { watch, prepare } from 'pele-animate';
 import { icons } from 'pele-animate/glyphs';
 import 'pele-animate/tabler/computers'; // one Tabler icon category; import as many as you need
 import 'pele-animate/style.css';
 
 for (const el of document.querySelectorAll('pre.mermaid')) {
   const src = el.textContent;
-  mount(el, src, { icons });
+  mount(el, prepare(src), { icons });
   watch(el, src); // re-applies after Pele re-lays-out on resize
 }
 ```
 
 Mermaid source:
 
-```mermaid
+```mermaid-icons
 flowchart LR
   %% pa: 1=C 2=L 3=S
   C@{ icon: "http-get", form: "square", h: 88, label: "Request" }
@@ -98,6 +75,38 @@ Everything is in [`docs/`](docs/getting-started.md), and ships inside the npm pa
 **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).
 
+## Compare
+
+The same Mermaid source, three renderers. The pele-animate images loop: the intro draws in, then tokens travel the edges (as on hover).
+Regenerate with `examples/capture.sh`.
+
+```mermaid
+flowchart LR
+  A[Client] -->|request| B[API]
+  A -->|sign in| C[Auth server]
+  C -->|token| A
+```
+
+| Renderer | Result |
+|---|---|
+| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m1.png" width="560" alt="Flowchart rendered by Mermaid"> |
+| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p1.png" width="560" alt="Flowchart rendered by Pele"> |
+| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a1.gif" width="560" alt="Animated flowchart: nodes appear, edges draw in, tokens travel"> |
+
+```mermaid
+sequenceDiagram
+  Client->>API: sign in
+  API-->>Client: token
+  Client->>Data: query with token
+  Data-->>Client: result
+```
+
+| Renderer | Result |
+|---|---|
+| Mermaid | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/m2.png" width="560" alt="Sequence diagram rendered by Mermaid"> |
+| Pele | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/p2.png" width="560" alt="Sequence diagram rendered by Pele"> |
+| pele-animate | <img src="https://raw.githubusercontent.com/dkdev24/pele-animate/main/examples/a2.gif" width="560" alt="Animated sequence diagram: messages appear in order, tokens travel"> |
+
 ## Credits and license
 
 MIT. Built on [Pele](https://github.com/obsidianmd/pele) by kepano (MIT); this is an unofficial add-on, not affiliated with or

package/docs/api.md

@@ -14,6 +14,7 @@ TypeScript types ship with the package (`types/`).
 | Export | Signature | Description |
 |---|---|---|
 | `watch` | `watch(container: HTMLElement, source?: string, options?: { controls?: boolean }): void` | Marks the container as a scene (`pa-scene`), animates each SVG Pele renders into it and re-applies after Pele re-lays-out on resize. `controls: false` keeps click-to-replay instead of step mode. |
+| `prepare` | `prepare(source?: string): string` | Returns the Mermaid source with icon-node labels padded so Pele lays out a box at least as wide as the icon (`h`). Pass its result to `mount()` and the original source to `watch()`. Without it, a label shorter than the icon puts edge ends and arrowheads under the icon. |
 | `animate` | `animate(svg: SVGSVGElement, options?: { hover?: Element; source?: string }): void` | Animates one rendered svg. `source` is read for `%% pa:` pins. Sets `svg.paSteps`. |
 | `replay` | `replay(svg: SVGSVGElement \| null \| undefined): void` | Plays the intro again. |
 | `parseOrder` | `parseOrder(source?: string): Map<string, number>` | Parses the `%% pa:` comment: node id, or `'X>Y'` for an edge, to a 0-based step. |

package/docs/contributing.md

@@ -17,6 +17,7 @@ pnpm build   # builds the site (a placeholder until the site lands)
 
 - The package is plain ESM at the repository root: no build step. The site lives in `site/`.
 - Docs are the Markdown files in `docs/`. A fenced block marked `mermaid` must render, and every `@{ icon }` name in it must exist.
+- Fence convention: ```` ```mermaid live ```` is a diagram GitHub can also draw; the site animates it. A diagram with `@{ icon }` nodes uses ```` ```mermaid-icons live ````, because GitHub's Mermaid cannot draw icons (it shows "?" boxes), so GitHub shows the source text and the site animates it.
 - Tabler packs are generated: `node scripts/build-tabler.mjs <path to a tabler-icons checkout>` rewrites `tabler/*.js`. Do not edit those
   files by hand. The Tabler version is recorded in each file header and in `THIRD-PARTY-NOTICES.md`.
 - Add an entry to `CHANGELOG.md` for any user-visible change. Breaking changes also get a section in `docs/migrating.md`.

package/docs/diagram-types.md

@@ -7,7 +7,7 @@ section: Start
 
 # Diagram types
 
-pele-animate supports **flowcharts** and **sequence diagrams**. Pele renders other diagram types too, but they are outside what
+pele-animate supports **flowcharts**, **sequence diagrams**, **architecture diagrams** and **state diagrams** and **C4 context diagrams** and **block diagrams**, **class diagrams**, **ER diagrams**, **timelines**, **user journeys**, **git graphs** and **Gantt charts**. Pele renders other diagram types too, but they are outside what
 pele-animate is built for.
 
 ## Flowcharts
@@ -36,8 +36,173 @@ sequenceDiagram
 
 **Limit:** Pele ignores `@{ icon }` on sequence participants (the box shows its id), so icons apply to flowcharts only.
 
+## Architecture diagrams
+
+`architecture-beta`: services in groups, joined by edges. Services appear in step order like flowchart nodes, groups stay visible,
+and `%% pa:` pins work the same way. The icon in parentheses is looked up in your icon packs, so Tabler names and `doverunner-*`
+names work (import the packs as for [icons](./icons.md)).
+
+```mermaid-icons live
+architecture-beta
+  group edge(cloud)[Edge]
+  group core(cloud)[Core]
+  service user(device-desktop)[User]
+  service cdn(cloud-computing)[CDN] in edge
+  service api(server)[API] in core
+  service db(database)[Database] in core
+  user:R --> L:cdn
+  cdn:R --> L:api
+  api:R --> L:db
+```
+
+Icons here are small and fixed in size; `form` and `h` apply to flowcharts only. Edges are read from their written direction
+(`user:R --> L:cdn` is user to cdn). A node id containing `-` can be mistaken for two ids on an edge, so use plain ids.
+
+## State diagrams
+
+`stateDiagram-v2`: states appear in step order, transitions draw from their source state, and transition labels fade in. The
+start and end markers are nodes too, with the ids `root_start` and `root_end`, so pins can name them.
+
+```mermaid live
+stateDiagram-v2
+  %% pa: 1=root_start 2=Idle 3=Running 4=Paused 5=root_end
+  [*] --> Idle
+  Idle --> Running: start
+  Running --> Paused: pause
+  Paused --> Running: resume
+  Running --> [*]: done
+```
+
+Without pins the order is breadth-first from the start marker, which shows `Paused` and the end marker together. Pele gives
+state edges no readable ids, so pele-animate finds each transition's ends from where its path starts and stops. Composite
+states and forks are untested. State diagrams take no icons.
+
+## C4 context diagrams
+
+`C4Context`: people and systems appear in step order and each `Rel` draws from its source, with its label. Pins use the ids you
+give `Person(...)` and `System(...)`; an edge pin is `3=app>drm`.
+
+```mermaid live
+C4Context
+  %% pa: 1=viewer 2=app 3=drm,cdn
+  Person(viewer, "Viewer", "Watches video")
+  System(app, "Player app", "Plays protected video")
+  System_Ext(drm, "DRM service", "Issues licenses")
+  System(cdn, "CDN", "Delivers segments")
+  Rel(viewer, app, "uses")
+  Rel(app, drm, "license")
+  Rel(app, cdn, "segments")
+```
+
+Pele lays C4 diagrams out in rows, so a long label between two boxes in the same row can leave no room for the arrowhead:
+keep `Rel` labels short. Only `C4Context` has been checked; the other C4 types and boundaries are untested. C4 shapes take no icons.
+
+## Block diagrams
+
+`block-beta`: blocks appear in step order and each arrow draws from its source block. Pins use the block ids.
+
+```mermaid live
+block-beta
+  columns 3
+  %% pa: 1=client 2=server 3=db
+  client["Client"] space server["Server"]
+  space space db[("Database")]
+  client --> server
+  server --> db
+```
+
+Pele routes arrows between blocks in straight lines or short bends, so place linked blocks in the same row or column; a diagonal
+neighbour can give a bent arrow that runs along another one. Block diagrams take no icons.
+
+## Class diagrams
+
+`classDiagram`: classes appear in step order, relationships draw from the class written first. `Animal <|-- Dog` reveals `Animal`
+and then `Dog`, whichever way the arrowhead points. Pins use the class names.
+
+```mermaid live
+classDiagram
+  %% pa: 1=Animal 2=Dog,Cat 3=Owner
+  Animal <|-- Dog
+  Animal <|-- Cat
+  Dog --> Owner : has
+  Animal : +name
+  Dog : +bark()
+```
+
+## ER diagrams
+
+`erDiagram`: entities appear in step order, relationships draw from the entity written first (`CUSTOMER ||--o{ ORDER` reveals
+`CUSTOMER`, then `ORDER`).
+
+```mermaid live
+erDiagram
+  %% pa: 1=CUSTOMER 2=ORDER 3=LINE,PRODUCT
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--|{ LINE : contains
+  PRODUCT ||--o{ LINE : in
+```
+
+Neither takes icons.
+
+## Timelines, journeys, git graphs and Gantt charts
+
+These have no edges to follow, so each steps through its items in reading order and `%% pa:` pins do nothing (as for sequence
+diagrams). Section headers, axes, grids and legends stay visible.
+
+- **`timeline`:** one step per time period, with its events.
+
+```mermaid live
+timeline
+  title History
+  section Early
+    2002 : Launch : Beta
+    2004 : Growth
+  section Late
+    2010 : Scale
+```
+
+- **`journey`:** one step per task: the task, its face, and the line segment that joins it to the task before.
+
+```mermaid live
+journey
+  title My day
+  section Work
+    Make tea: 5: Me, Bob
+    Do work: 3: Me
+  section Home
+    Relax: 4: Me
+```
+
+- **`gitGraph`:** one step per commit in the order written, with the edge that ends on it. A branch's label and lane appear with
+  its first commit.
+
+```mermaid live
+gitGraph
+  commit id: "a"
+  branch dev
+  commit id: "b"
+  checkout main
+  commit id: "c"
+  merge dev id: "m"
+```
+
+- **`gantt`:** one step per task, top to bottom.
+
+```mermaid live
+gantt
+  dateFormat YYYY-MM-DD
+  section Build
+    Design :a1, 2024-01-01, 3d
+    Code :after a1, 4d
+  section Ship
+    Test :2024-01-08, 2d
+```
+
+None of these take icons. Only these small examples have been checked in a browser; long diagrams, `todayMarker`, tags, cherry-picks and
+parallel tasks are untested.
+
 ## Everything else
 
-Other Mermaid types (class, state, ER, gantt, pie and the rest) render through Pele as usual. pele-animate is not designed for
+Other Mermaid types (pie, quadrant, radar 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.
+the types above only; sequence diagrams have not been checked the same way yet.

package/docs/faq.md

@@ -22,7 +22,7 @@ you want to explain in order.
 **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)).
+**Which diagrams does it support?** Flowcharts, sequence diagrams, architecture diagrams, state diagrams, C4 context, block, class and ER diagrams, timelines, journeys, git graphs and Gantt charts ([diagram types](./diagram-types.md)).
 
 **Can I use my own icons?** Yes ([custom icons](./custom-icons.md)).
 

package/docs/getting-started.md

@@ -15,10 +15,14 @@ unofficial add-on for Pele and does not change how Pele lays out or draws diagra
 
 ```sh
 npm i pele-animate pele
+# or
+pnpm add pele-animate pele
+yarn add pele-animate pele
+bun add pele-animate pele
 ```
 
-`pele` is a peer dependency (`^1.7.0`). Both run in the browser: they need the DOM, so mount them on the client (see
-[recipes](./recipes.md) for frameworks).
+`pele` is a peer dependency (`^1.7.0`): install it alongside. Both run in the browser and need the DOM, so mount them on the client (see
+[recipes](./recipes.md) for frameworks). The packages are ESM only.
 
 ## First diagram
 
@@ -26,20 +30,20 @@ Put the Mermaid source in an element, then mount it with Pele and hand it to `wa
 
 ```js
 import { mount } from 'pele';
-import { watch } from 'pele-animate';
+import { watch, prepare } from 'pele-animate';
 import { icons } from 'pele-animate/glyphs';
 import 'pele-animate/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
+mount(el, prepare(src), { icons }); // Pele draws the SVG
 watch(el, src);            // pele-animate animates it, and re-applies when Pele re-lays-out on resize
 ```
 
 The Mermaid source:
 
-```mermaid live
+```mermaid-icons live
 flowchart LR
   %% pa: 1=C 2=L 3=S
   C@{ icon: "http-get", form: "square", h: 88, label: "Request" }

package/docs/how-it-works.md

@@ -16,7 +16,7 @@ Two layers, one diagram:
 
 ## The calls
 
-- `mount(el, src, { icons })` is Pele's. The `icons` option is how glyphs get in (see [icons](./icons.md)).
+- `mount(el, prepare(src), { icons })` is Pele's. The `icons` option is how glyphs get in (see [icons](./icons.md)).
 - `watch(el, src)` is pele-animate's. It marks the container as a scene (class `pa-scene`), animates each SVG Pele renders into
   it, and re-applies after Pele re-draws on resize. The intro is skipped on those re-draws once it has played.
 - `animate(svg, { source })` does one SVG. Use it if you render with Pele yourself and do not want `watch()`.

package/docs/icons.md

@@ -9,17 +9,18 @@ section: Guides
 
 A flowchart node becomes an illustrated node with Mermaid's own `@{ }` syntax:
 
-```mermaid live
+```mermaid-icons live
 flowchart LR
   A@{ icon: "device-desktop", form: "square", h: 88, label: "Laptop" }
   B@{ icon: "server", form: "square", h: 88, label: "Server" }
-  A --> B
+  A -->|request| 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.
+- Call `mount(el, prepare(src), { icons })` with `prepare` from `pele-animate`. Pele sizes an icon node from its label, so a label shorter than `h` would put edge ends and arrowheads under the icon; `prepare` pads the label so the box fits.
 - 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.
 
@@ -60,6 +61,7 @@ Brand, Letters, Numbers, Zodiac and Gender are not included. Counts are for Tabl
 
 Do not guess names. Look them up:
 
+- The [icon browser](https://pele-animate.pages.dev/icons/) searches names and tags and copies a ready snippet; the same list is [icons.json](https://pele-animate.pages.dev/icons.json).
 - 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.

package/docs/recipes.md

@@ -13,14 +13,14 @@ rendered.** Load them with dynamic `import()` inside the framework's mounted hoo
 The shape is always:
 
 ```js
-const [{ mount }, { watch }, { icons }] = await Promise.all([
+const [{ mount }, { watch, prepare }, { 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 });
+mount(el, prepare(src), { icons });
 watch(el, src);
 ```
 
@@ -49,13 +49,13 @@ Notes for all of them:
 <script>
   // runs in the browser only
   import { mount } from 'pele';
-  import { watch } from 'pele-animate';
+  import { watch, prepare } 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 });
+    mount(el as HTMLElement, prepare(src), { icons });
     watch(el as HTMLElement, src);
   });
 </script>
@@ -69,10 +69,10 @@ Notes for all of them:
   let el;
   const src = 'flowchart LR\n  A --> B';
   onMount(async () => {
-    const [{ mount }, { watch }, { icons }] = await Promise.all([
+    const [{ mount }, { watch, prepare }, { icons }] = await Promise.all([
       import('pele'), import('pele-animate'), import('pele-animate/glyphs'), import('pele-animate/style.css'),
     ]);
-    mount(el, src, { icons });
+    mount(el, prepare(src), { icons });
     watch(el, src);
   });
 </script>

package/docs/step-order.md

@@ -14,6 +14,12 @@ them. By default, the order follows the edges. A `%% pa:` comment lets you set i
 
 - **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.
+- **Architecture diagram:** like a flowchart: services appear by level, edges follow their written direction, pins work the same way.
+- **Timeline, journey, git graph, Gantt chart:** one step per item in reading order (period, task, commit, task); pins do nothing.
+- **Class and ER diagrams:** like a flowchart, but a relationship runs from the class or entity written first.
+- **Block diagram:** like a flowchart, from the blocks nothing points to.
+- **C4 context diagram:** like a flowchart, from the people and systems nothing points to.
+- **State diagram:** like a flowchart, starting from the start marker (`root_start`); the end marker is `root_end`.
 - **Sequence diagram:** actors first, then the messages in order.
 
 ## Pins

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pele-animate",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Step-by-step animated Mermaid diagrams with icons: an unofficial add-on for the Pele renderer.",
   "type": "module",
   "license": "MIT",

package/pele-animate.css

@@ -2,14 +2,16 @@
 .pa-ready:not(.pa-in):not(.pa-step) .pele-node,
 .pa-ready:not(.pa-in):not(.pa-step) .pele-edge-label,
 .pa-ready:not(.pa-in):not(.pa-step) .pele-lifeline,
-.pa-ready:not(.pa-in):not(.pa-step) .pele-marker { opacity: 0; }
+.pa-ready:not(.pa-in):not(.pa-step) .pele-marker,
+.pa-ready:not(.pa-in):not(.pa-step) .pa-item { opacity: 0; }
 .pa-ready:not(.pa-in):not(.pa-step) .pele-edge > path:not(.pele-marker) { stroke-dasharray: var(--len); stroke-dashoffset: var(--len); }
 
 /* Keyframes carry the dash, so edges that are dashed in the diagram go back to their own dash pattern afterwards. */
 .pa-ready.pa-in:not(.pa-step) .pele-node,
 .pa-ready.pa-in:not(.pa-step) .pele-edge-label,
 .pa-ready.pa-in:not(.pa-step) .pele-lifeline,
-.pa-ready.pa-in:not(.pa-step) .pele-marker { animation: pa-fade .4s ease-out backwards; animation-delay: var(--d, 0s); }
+.pa-ready.pa-in:not(.pa-step) .pele-marker,
+.pa-ready.pa-in:not(.pa-step) .pa-item { animation: pa-fade .4s ease-out backwards; animation-delay: var(--d, 0s); }
 .pa-ready.pa-in:not(.pa-step) .pele-edge > path:not(.pele-marker) { animation: pa-draw .4s ease-out backwards; animation-delay: var(--d, 0s); }
 .pa-ready.pa-done:not(.pa-step) * { animation: none !important; }
 @keyframes pa-fade { from { opacity: 0; } }
@@ -19,7 +21,7 @@
 
 @media (prefers-reduced-motion: reduce) {
   .pa-ready * { animation: none !important; }
-  .pa-ready:not(.pa-step) .pele-node, .pa-ready:not(.pa-step) .pele-edge-label, .pa-ready:not(.pa-step) .pele-lifeline, .pa-ready:not(.pa-step) .pele-marker { opacity: 1 !important; }
+  .pa-ready:not(.pa-step) .pele-node, .pa-ready:not(.pa-step) .pele-edge-label, .pa-ready:not(.pa-step) .pele-lifeline, .pa-ready:not(.pa-step) .pele-marker, .pa-ready:not(.pa-step) .pa-item { opacity: 1 !important; }
   .pa-ready .pele-edge > path { stroke-dasharray: none; stroke-dashoffset: 0 !important; }
 }
 
@@ -51,6 +53,9 @@
 /* Edge labels sit on the line; give them the panel color so the line doesn't strike through the text. */
 .pa-scene .pele-edge-label rect { fill: var(--pa-bg); }
 
+/* Pele colours text on solid fills (timeline periods, gantt bars, git branch tags) with --_bg, which the scene makes transparent: use the panel surface instead. */
+.pa-scene text[fill="var(--_bg)"] { fill: var(--pele-surface); }
+
 /* Group and box titles read as headings. */
 :where(.pa-scene) .pele-cluster-label { font-weight: 700; }
 

package/pele-animate.js

@@ -16,11 +16,33 @@ export function parseOrder(source = '') {
   return levels;
 }
 
+// Edge ids by diagram type: flowchart `L_A_B_0`, architecture and C4 `A-B` (repeat edges get `-N`), block `1-A-B`, class `id_A_B_1`,
+// ER `id_entity-A-0_entity-B-1_0`. Ends follow the written order (`A <|-- B` is A, then B).
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 function endpoints(edgeId, ids) {
-  for (const s of ids) for (const d of ids) if (new RegExp(`^L_${s}_${d}_\\d+$`).test(edgeId)) return [s, d];
+  for (const s of ids)
+    for (const d of ids)
+      if (new RegExp(`^(?:L_${esc(s)}_${esc(d)}_\\d+|(?:\\d+-)?${esc(s)}-${esc(d)}(?:-\\d+)?|id_${esc(s)}_${esc(d)}_\\d+|id_entity-${esc(s)}-\\d+_entity-${esc(d)}-\\d+_\\d+)$`).test(edgeId)) return [s, d];
   return null;
 }
 
+// State diagrams name edges `edge0`, `edge1`, ... with no ends in the id, so read the ends off the geometry:
+// the node nearest to where the path starts (source) and ends (target).
+function geoEndpoints(edge, boxes) {
+  const path = edge.querySelector('path:not(.pele-marker)');
+  if (!path) return null;
+  const near = (pt) => {
+    let best = null, bd = 12; // an end more than 12 px from every node is not an end
+    for (const [id, b] of boxes) {
+      const d = Math.hypot(Math.max(b.x - pt.x, 0, pt.x - b.x - b.width), Math.max(b.y - pt.y, 0, pt.y - b.y - b.height));
+      if (d < bd) { bd = d; best = id; }
+    }
+    return best;
+  };
+  const s = near(path.getPointAtLength(0)), d = near(path.getPointAtLength(path.getTotalLength()));
+  return s && d ? [s, d] : null;
+}
+
 function bfs(ids, pairs, pinned) {
   const level = new Map(pinned);
   const hasIn = new Set(pairs.map(([, d]) => d));
@@ -77,11 +99,97 @@ function equalizeActors(svg) {
   }
 }
 
+// Pele sizes an icon node's layout box from its label alone but draws the icon at `h`, so a label narrower than the icon puts
+// the edge ends (and arrowheads) under the icon. Pad such labels with non-breaking spaces so the box is at least `h` wide.
+// Use as: mount(el, prepare(src), { icons }); keep passing the original `src` to watch().
+const NBSP = '\u00a0';
+const WJ = '\u2060'; // zero-width, not whitespace: keeps Pele from trimming the padding
+export function prepare(source = '') {
+  return source.replace(/@\{([^}]*)\}/g, (all, body) => {
+    const h = +/\bh:\s*(\d+)/.exec(body)?.[1];
+    if (!h) return all;
+    const label = /\blabel:\s*"([^"]*)"/.exec(body)?.[1] ?? '';
+    // ponytail: a character counts as ~7 px (a space too); a real measurer would be exact. Over-padding only widens the gap.
+    const need = Math.ceil(h / 7) - label.length;
+    if (need <= 0) return all;
+    const pad = NBSP.repeat(Math.ceil(need / 2));
+    const next = `label: "${WJ}${pad}${label}${pad}${WJ}"`;
+    return `@{${/\blabel:/.test(body) ? body.replace(/\blabel:\s*"[^"]*"/, next) : `${body.replace(/\s*$/, '')}, ${next} `}}`;
+  });
+}
+
+
+// Diagrams with no edges to follow (timeline, journey, gitGraph, gantt) step through their items in reading order.
+// Returns [[element, ...], ...], one array per step, or null for any other diagram.
+const pts = (path) => path.getAttribute('d').match(/-?[\d.]+/g)?.map(Number) ?? [];
+function sequentialSteps(svg) {
+  const all = (sel) => [...svg.querySelectorAll(sel)];
+  if (svg.classList.contains('pele-timeline')) return all('.pele-period').map((p) => [p]);
+  if (svg.classList.contains('pele-gantt')) return all('.pele-task').map((t) => [t]);
+  if (svg.classList.contains('pele-journey')) {
+    const tasks = all('.pele-task'), faces = all('.pele-face');
+    const line = svg.querySelector('path.pele-edge');
+    // The satisfaction line is one polyline `M x,yL x,y...`: split it so each segment arrives with its task.
+    const segs = [];
+    if (line && /^M[-\d.,]+(L[-\d.,]+)+$/.test(line.getAttribute('d'))) {
+      const p = line.getAttribute('d').slice(1).split('L');
+      for (let i = 1; i < p.length; i++) {
+        const seg = line.cloneNode();
+        seg.setAttribute('d', `M${p[i - 1]}L${p[i]}`);
+        line.before(seg);
+        segs.push(seg);
+      }
+      line.remove();
+    }
+    return tasks.map((t, i) => [t, faces[i], segs[i - 1]].filter(Boolean));
+  }
+  if (svg.classList.contains('pele-gitGraph')) {
+    const commits = all('.pele-commit');
+    const at = (c) => { const e = c.querySelector('circle'); return [+e.getAttribute('cx'), +e.getAttribute('cy')]; };
+    const steps = commits.map((c) => [c]);
+    // an edge arrives with the commit it ends on
+    for (const e of all('.pele-edge')) {
+      const path = e.matches('path') ? e : e.querySelector('path');
+      const end = path.getPointAtLength(path.getTotalLength());
+      let best = steps.length - 1, bd = Infinity;
+      commits.forEach((c, i) => { const [x, y] = at(c), d = Math.hypot(x - end.x, y - end.y); if (d < bd) { bd = d; best = i; } });
+      steps[best]?.push(e);
+    }
+    // a branch (label and lane) appears with its first commit: the commit whose y is on the lane
+    for (const b of all('.pele-branch')) {
+      const y = pts(b.querySelector('.pele-lane'))[1];
+      const first = commits.findIndex((c) => Math.abs(at(c)[1] - y) < 1);
+      steps[first < 0 ? 0 : first].push(b);
+    }
+    return steps;
+  }
+  return null;
+}
+
+// Intro for sequentialSteps: each step fades in after the one before; the same steps drive step mode.
+function introSteps(svg, steps) {
+  const u = Math.min(UNIT, MAX_INTRO / Math.max(1, steps.length));
+  steps.forEach((els, i) => els.forEach((el) => { el.classList.add('pa-item'); el.style.setProperty('--d', `${i * u}s`); }));
+  svg.paSteps = steps.map((els) => els.map((el) => [el, [el]]));
+  reveal(svg);
+}
+
+function reveal(svg) {
+  if (!('IntersectionObserver' in window)) return svg.classList.add('pa-in');
+  svg.classList.remove('pa-in');
+  const io = new IntersectionObserver(([en]) => {
+    if (en.isIntersecting) { svg.classList.add('pa-in'); io.disconnect(); }
+  }, { threshold: 0.3 });
+  io.observe(svg);
+}
+
 export function animate(svg, { hover = svg, source = '' } = {}) {
   fitGlyphs(svg);
   equalizeActors(svg);
   svg.querySelectorAll('.pa-dot').forEach((d) => d.remove());
   svg.classList.add('pa-ready');
+  const seq = sequentialSteps(svg);
+  if (seq) return introSteps(svg, seq);
   const nodes = [...svg.querySelectorAll('.pele-node')];
   const edges = [...svg.querySelectorAll('.pele-edge')];
   const ids = [...new Set(nodes.map((n) => n.dataset.id))];
@@ -96,7 +204,17 @@ export function animate(svg, { hover = svg, source = '' } = {}) {
     edges.forEach((e, i) => { times.set(e, 0.5 + i * u); step.set(e, i + 1); });
     nodes.forEach((n) => step.set(n, 0));
   } else {
-    const pairs = edges.map((e) => endpoints(e.dataset.id, ids));
+    const boxes = new Map();
+    const pairs = edges.map((e) => {
+      const found = endpoints(e.dataset.id, ids);
+      if (found) return found;
+      if (!boxes.size)
+        for (const n of nodes) {
+          const b = n.getBBox(), t = n.transform.baseVal.consolidate()?.matrix;
+          boxes.set(n.dataset.id, { x: b.x + (t?.e ?? 0), y: b.y + (t?.f ?? 0), width: b.width, height: b.height });
+        }
+      return geoEndpoints(e, boxes);
+    });
     const level = bfs(ids, pairs.filter(Boolean), parseOrder(source));
     const u = Math.min(UNIT, MAX_INTRO / (Math.max(0, ...level.values()) + 1));
     const k = u / UNIT;
@@ -164,12 +282,7 @@ export function animate(svg, { hover = svg, source = '' } = {}) {
   hover.addEventListener('focusin', play);
   hover.addEventListener('focusout', stop);
 
-  if (!('IntersectionObserver' in window)) return svg.classList.add('pa-in');
-  svg.classList.remove('pa-in');
-  const io = new IntersectionObserver(([en]) => {
-    if (en.isIntersecting) { svg.classList.add('pa-in'); io.disconnect(); }
-  }, { threshold: 0.3 });
-  io.observe(svg);
+  reveal(svg);
 }
 
 const STEP_MS = 1200; // autoplay pace in step mode

package/skills/pele-animate/SKILL.md

@@ -30,12 +30,12 @@ npm i pele-animate pele        # or pnpm / yarn / bun; pele is a peer dependency
 ## 2. Mount (client side)
 
 ```js
-const [{ mount }, { watch }, { icons }] = await Promise.all([
+const [{ mount }, { watch, prepare }, { 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`
+mount(el, prepare(src), { icons });   // Pele draws the SVG from the Mermaid text in `src`
 watch(el, src);              // pele-animate animates it (also on resize)
 ```
 
@@ -58,7 +58,7 @@ TypeScript: a CSS side-effect import needs a `*.css` module declaration unless t
 
 Icon nodes use Mermaid's own syntax:
 
-```mermaid
+```mermaid-icons
 flowchart LR
   %% pa: 1=C 2=L 3=S
   C@{ icon: "http-get", form: "square", h: 88, label: "Request" }

package/types/index.d.ts

@@ -27,6 +27,8 @@ export function parseOrder(source?: string): Map<string, number>;
 export function animate(svg: SVGSVGElement, options?: AnimateOptions): void;
 
 /** Animate every svg Pele renders into `container`, re-applying after Pele re-lays-out on resize. */
+/** Pad icon-node labels narrower than `h` so Pele's layout box is at least as wide as the drawn icon. Use as `mount(el, prepare(src), { icons })`; pass the original `src` to `watch()`. */
+export function prepare(source?: string): string;
 export function watch(container: HTMLElement, source?: string, options?: WatchOptions): void;
 
 /** Play the intro again. */