pele-animate 0.16.0 → 0.16.2

package/docs/contributing.md

@@ -18,6 +18,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.
+- Every `live` fence carries a title after the word `live`: `title="Flowchart: cache hit or miss"`. The playground's examples menu shows it (grouped by page), so write "Type: what it shows".
 - 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,16 +7,38 @@ section: Start
 
 # Diagram types
 
-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.
+pele-animate animates these Mermaid diagram types. Each one plays an intro when it scrolls into view and, on click, steps through its
+items with previous / play / next controls.
+
+| Type | Each step reveals | Pins, icons | Remarks |
+|---|---|---|---|
+| [Flowchart](#flowcharts)<br>`flowchart` | Nodes level by level, edges from their source | Pins and icons | The fullest support: groups, edge labels, large icon nodes. |
+| [Sequence diagram](#sequence-diagrams)<br>`sequenceDiagram` | Actors, then one message at a time | Neither | The order is the source order; reordering messages changes what the diagram says. |
+| [Architecture](#architecture-diagrams)<br>`architecture-beta` | Services level by level, edges from their source | Pins and icons | Icons are written `(name)` and are small and fixed in size. |
+| [State diagram](#state-diagrams)<br>`stateDiagram-v2` | States and transitions from the start marker | Pins | Markers are `root_start` and `root_end`. Composite states are untested. |
+| [C4 context](#c4-context-diagrams)<br>`C4Context` | People and systems, then relationships | Pins | Only `C4Context` is checked. Keep `Rel` labels short. |
+| [Block diagram](#block-diagrams)<br>`block-beta` | Blocks and arrows from their source | Pins | Put linked blocks in the same row or column. |
+| [Class diagram](#class-diagrams)<br>`classDiagram` | Classes and relationships, from the class written first | Pins | `A <\|-- B` reveals `A`, then `B`. |
+| [ER diagram](#er-diagrams)<br>`erDiagram` | Entities and relationships, from the entity written first | Pins | Same written-order rule as class diagrams. |
+| [Timeline](#timelines-journeys-git-graphs-and-gantt-charts)<br>`timeline` | One time period with its events | Neither | Section headers stay visible. |
+| [User journey](#timelines-journeys-git-graphs-and-gantt-charts)<br>`journey` | One task, its face and the line joining it to the last | Neither |  |
+| [Git graph](#timelines-journeys-git-graphs-and-gantt-charts)<br>`gitGraph` | One commit with its edge; a branch with its first commit | Neither | Cherry-picks and tags are untested. |
+| [Gantt chart](#timelines-journeys-git-graphs-and-gantt-charts)<br>`gantt` | One task, top to bottom | Neither | `todayMarker` and parallel tasks are untested. |
+
+Pins are `%% pa:` comments; see [step order](./step-order.md). Types without pins use their source order. Icons are set up in
+[icons](./icons.md). Pele renders the other Mermaid types too (pie, quadrant, radar and the rest), but pele-animate is not built
+for them; see [Everything else](#everything-else).
 
 ## 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
+The pins below put "Serve" (the cache hit) before "Fetch", then draw the `Fetch` to `Serve` edge as its own last step. Without them, `Serve` and `Fetch` would appear together.
+
+```mermaid live title="Flowchart: cache hit or miss, with pins and an edge pin"
 flowchart LR
+  %% pa: 1=A 2=B 3=C 4=D 5=D>C
   A[Client] --> B{Cached?}
   B -->|yes| C[Serve]
   B -->|no| D[Fetch] --> C
@@ -24,11 +46,13 @@ flowchart LR
 
 ## Sequence diagrams
 
-Actors appear first, then the messages in order. Participant boxes in a row get the same height, and group titles are bold.
+Actors appear first, then one step per message in source order, so a cache miss reads as five short steps. Participant boxes in a row get the same height, and group titles are bold.
 
-```mermaid live
+```mermaid live title="Sequence: API request with a cache miss"
 sequenceDiagram
   Client->>API: request
+  API->>Cache: lookup
+  Cache-->>API: miss
   API->>Database: query
   Database-->>API: rows
   API-->>Client: response
@@ -40,19 +64,26 @@ sequenceDiagram
 
 `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)).
+names work (import the packs as for [icons](./icons.md)). The pins here follow a request: the user, the CDN, the API, the cache and database together, then the queue and worker.
 
-```mermaid-icons live
+```mermaid-icons live title="Architecture: request path through CDN, API, cache, database and worker"
 architecture-beta
+  %% pa: 1=user 2=cdn 3=api 4=cache,db 5=queue 6=worker
   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 cache(bolt)[Cache] in core
   service db(database)[Database] in core
+  service queue(mail)[Queue] in core
+  service worker(settings)[Worker] in core
   user:R --> L:cdn
   cdn:R --> L:api
-  api:R --> L:db
+  api:T --> B:cache
+  api:B --> T:db
+  api:R --> L:queue
+  queue:R --> L:worker
 ```
 
 Icons here are small and fixed in size; `form` and `h` apply to flowcharts only. Edges are read from their written direction
@@ -63,35 +94,43 @@ Icons here are small and fixed in size; `form` and `h` apply to flowcharts only.
 `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
+```mermaid live title="State: media player with loading, error and retry"
 stateDiagram-v2
-  %% pa: 1=root_start 2=Idle 3=Running 4=Paused 5=root_end
+  %% pa: 1=root_start 2=Idle 3=Loading 4=Playing 5=Paused 6=Error 7=root_end
   [*] --> Idle
-  Idle --> Running: start
-  Running --> Paused: pause
-  Paused --> Running: resume
-  Running --> [*]: done
+  Idle --> Loading: play
+  Loading --> Playing: ready
+  Playing --> Paused: pause
+  Paused --> Playing: resume
+  Loading --> Error: fail
+  Error --> Idle: retry
+  Playing --> [*]: stop
 ```
 
-Without pins the order is breadth-first from the start marker, which shows `Paused` and the end marker together. Pele gives
+The pins give each state its own step, in the order a viewer meets them. Without pins the order is breadth-first from the start marker, which shows states at the same distance together (here `Playing` and `Error`). 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`.
+give `Person(...)` and `System(...)`; an edge pin is `3=app>drm`. The example adds the DRM service, CDN and analytics one at a time, then the operator who reads the analytics.
 
-```mermaid live
+```mermaid live title="C4 context: player app and the systems around it"
 C4Context
-  %% pa: 1=viewer 2=app 3=drm,cdn
+  %% pa: 1=viewer 2=app 3=drm 4=cdn 5=analytics 6=admin
   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")
+  System_Ext(cdn, "CDN", "Delivers segments")
+  System(analytics, "Analytics", "Tracks playback")
+  Person(admin, "Operator", "Reviews usage")
+  Rel(viewer, app, "watches")
   Rel(app, drm, "license")
   Rel(app, cdn, "segments")
+  Rel(app, analytics, "events")
+  Rel(admin, analytics, "reviews")
+  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
 ```
 
 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:
@@ -101,14 +140,16 @@ keep `Rel` labels short. Only `C4Context` has been checked; the other C4 types a
 
 `block-beta`: blocks appear in step order and each arrow draws from its source block. Pins use the block ids.
 
-```mermaid live
+```mermaid live title="Block: video pipeline with a storage branch"
 block-beta
-  columns 3
-  %% pa: 1=client 2=server 3=db
-  client["Client"] space server["Server"]
-  space space db[("Database")]
-  client --> server
-  server --> db
+  columns 4
+  %% pa: 1=src 2=enc 3=pkg 4=cdn 5=store
+  src["Source"] enc["Encode"] pkg["Package"] cdn["CDN"]
+  space space store[("Storage")] space
+  src --> enc
+  enc --> pkg
+  pkg --> cdn
+  pkg --> store
 ```
 
 Pele routes arrows between blocks in straight lines or short bends, so place linked blocks in the same row or column; a diagonal
@@ -116,30 +157,35 @@ neighbour can give a bent arrow that runs along another one. Block diagrams take
 
 ## 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.
+`classDiagram`: classes appear in step order, relationships draw from the class written first. `Media <|-- Video` reveals `Media`
+and then `Video`, whichever way the arrowhead points. Pins use the class names; the example shows the base class, its subtypes, then the classes that use them.
 
-```mermaid live
+```mermaid live title="Class: media types, player and license"
 classDiagram
-  %% pa: 1=Animal 2=Dog,Cat 3=Owner
-  Animal <|-- Dog
-  Animal <|-- Cat
-  Dog --> Owner : has
-  Animal : +name
-  Dog : +bark()
+  %% pa: 1=Media 2=Video,Audio 3=Player 4=License 5=Session
+  Media <|-- Video
+  Media <|-- Audio
+  Player --> Media : plays
+  Player --> License : needs
+  License --> Session : opens
+  Media : +id
+  Media : +title
+  Player : +play()
+  License : +expiry
 ```
 
 ## ER diagrams
 
 `erDiagram`: entities appear in step order, relationships draw from the entity written first (`CUSTOMER ||--o{ ORDER` reveals
-`CUSTOMER`, then `ORDER`).
+`CUSTOMER`, then `ORDER`). The example reads from the customer down to the supplier.
 
-```mermaid live
+```mermaid live title="ER: customer orders and product suppliers"
 erDiagram
-  %% pa: 1=CUSTOMER 2=ORDER 3=LINE,PRODUCT
+  %% pa: 1=CUSTOMER 2=ORDER 3=LINE 4=PRODUCT 5=SUPPLIER
   CUSTOMER ||--o{ ORDER : places
   ORDER ||--|{ LINE : contains
-  PRODUCT ||--o{ LINE : in
+  LINE }o--|| PRODUCT : lists
+  PRODUCT }o--|| SUPPLIER : "supplied by"
 ```
 
 Neither takes icons.
@@ -149,53 +195,66 @@ Neither takes icons.
 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.
+- **`timeline`:** one step per time period, with its events. List periods in time order.
 
-```mermaid live
+```mermaid live title="Timeline: product history in two phases"
 timeline
-  title History
-  section Early
-    2002 : Launch : Beta
-    2004 : Growth
-  section Late
-    2010 : Scale
+  title Product history
+  section Build
+    2019 : Prototype
+    2020 : Private beta : First customers
+  section Grow
+    2021 : Public launch
+    2023 : Mobile apps : Offline mode
+    2025 : Global rollout
 ```
 
 - **`journey`:** one step per task: the task, its face, and the line segment that joins it to the task before.
 
-```mermaid live
+```mermaid live title="User journey: watching a protected video"
 journey
-  title My day
-  section Work
-    Make tea: 5: Me, Bob
-    Do work: 3: Me
-  section Home
-    Relax: 4: Me
+  title Watching a protected video
+  section Find
+    Open the app: 5: Viewer
+    Pick a title: 4: Viewer
+  section Play
+    Wait for the license: 2: Viewer, App
+    Playback starts: 5: Viewer
+  section Finish
+    Resume later: 4: Viewer
+    Rate the title: 3: Viewer
 ```
 
 - **`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
+```mermaid live title="Git graph: feature branch, merge and release"
 gitGraph
-  commit id: "a"
-  branch dev
-  commit id: "b"
+  commit id: "init"
+  branch feature
+  commit id: "api"
+  commit id: "ui"
   checkout main
-  commit id: "c"
-  merge dev id: "m"
+  commit id: "fix"
+  merge feature id: "m"
+  branch release
+  commit id: "v1"
 ```
 
-- **`gantt`:** one step per task, top to bottom.
+- **`gantt`:** one step per task, top to bottom: write tasks in the order you want them to appear.
 
-```mermaid live
+```mermaid live title="Gantt: plan, build and ship"
 gantt
   dateFormat YYYY-MM-DD
+  section Plan
+    Scope :a1, 2024-01-01, 3d
+    Design :after a1, 4d
   section Build
-    Design :a1, 2024-01-01, 3d
-    Code :after a1, 4d
+    Code :b1, 2024-01-08, 8d
+    Review :after b1, 2d
   section Ship
-    Test :2024-01-08, 2d
+    Test :2024-01-18, 4d
+    Release :2024-01-22, 1d
 ```
 
 None of these take icons. Only these small examples have been checked in a browser; long diagrams, `todayMarker`, tags, cherry-picks and

package/docs/getting-started.md

@@ -43,7 +43,7 @@ watch(el, src);            // pele-animate animates it, and re-applies when Pele
 
 The Mermaid source:
 
-```mermaid-icons live
+```mermaid-icons live title="Icons: request, load balancer and cloud service"
 flowchart LR
   %% pa: 1=C 2=L 3=S
   C@{ icon: "http-get", form: "square", h: 88, label: "Request" }

package/docs/icons.md

@@ -9,7 +9,7 @@ section: Guides
 
 A flowchart node becomes an illustrated node with Mermaid's own `@{ }` syntax:
 
-```mermaid-icons live
+```mermaid-icons live title="Icons: laptop sending a request to a server"
 flowchart LR
   A@{ icon: "device-desktop", form: "square", h: 88, label: "Laptop" }
   B@{ icon: "server", form: "square", h: 88, label: "Server" }

package/docs/step-order.md

@@ -26,7 +26,7 @@ them. By default, the order follows the edges. A `%% pa:` comment lets you set i
 
 Add one comment line anywhere in the source:
 
-```mermaid live
+```mermaid live title="Pins: request, validate, respond with a shortcut"
 flowchart LR
   %% pa: 1=A 2=B 3=C
   A[Request] --> B[Validate] --> C[Respond]
@@ -40,7 +40,7 @@ level.
 
 `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
+```mermaid live title="Edge pins: a reply as its own step"
 flowchart LR
   %% pa: 1=A,B 2=C 3=A>B
   A[Client] --> B[Server]
@@ -52,6 +52,7 @@ 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`).
+- The ends may be named in either order (`Video>Media` or `Media>Video`), unless the diagram also has the opposite edge: then the order picks which of the two is meant.
 - 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.
 

package/package.json

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

package/pele-animate.js

@@ -127,12 +127,15 @@ function sequentialSteps(svg) {
   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');
+    // Wide: tasks, faces and one polyline are separate. Narrow (vertical list): each step holds its face, edges join the steps.
+    const tasks = all('.pele-task, .pele-journey-step');
+    const faces = all('.pele-face').filter((f) => !f.closest('.pele-node'));
     // 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 (const line of all('path.pele-edge')) {
+      const d = line.getAttribute('d');
+      if (!/^M[-\d.,]+(L[-\d.,]+)+$/.test(d)) { segs.push(line); continue; }
+      const p = 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]}`);
@@ -216,13 +219,17 @@ export function animate(svg, { hover = svg, source = '' } = {}) {
       return geoEndpoints(e, boxes);
     });
     const level = bfs(ids, pairs.filter(Boolean), parseOrder(source));
+    // An edge pin may name the ends in either order (`Video>Media` for `Media <|-- Video`, or either end of an undirected edge),
+    // unless the diagram also has the opposite edge, where the order picks which of the two is meant.
+    const real = new Set(pairs.filter(Boolean).map(([a, b]) => `${a}>${b}`));
+    const pinOf = (s, d) => level.get(`${s}>${d}`) ?? (real.has(`${d}>${s}`) ? undefined : level.get(`${d}>${s}`));
     const u = Math.min(UNIT, MAX_INTRO / (Math.max(0, ...level.values()) + 1));
     const k = u / UNIT;
     nodes.forEach((n) => { set(n, level.get(n.dataset.id) * u); step.set(n, level.get(n.dataset.id)); });
     // Start after the source is up, but never so early that the arrow lands before its target appears (pinned steps).
     edges.forEach((e, i) => {
       const [s, d] = pairs[i] ?? [];
-      const pin = level.get(`${s}>${d}`); // edge pinned to a step: starts with that step, once its source is up
+      const pin = pinOf(s, d); // edge pinned to a step: starts with that step, once its source is up
       step.set(e, pin ?? Math.max(level.get(s) ?? 0, level.get(d) ?? 0));
       times.set(e, pin !== undefined
         ? Math.max(pin * u, (level.get(s) ?? 0) * u + 0.3 * k)