pele-animate 0.16.1 → 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

@@ -36,7 +36,7 @@ are kept. Icon nodes (`@{ icon }`) work here; see [icons](./icons.md).
 
 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
+```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?}
@@ -48,7 +48,7 @@ flowchart LR
 
 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
@@ -66,7 +66,7 @@ sequenceDiagram
 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)). 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]
@@ -94,7 +94,7 @@ 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=Loading 4=Playing 5=Paused 6=Error 7=root_end
   [*] --> Idle
@@ -116,7 +116,7 @@ states and forks are untested. State diagrams take no icons.
 `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`. 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 4=cdn 5=analytics 6=admin
   Person(viewer, "Viewer", "Watches video")
@@ -140,7 +140,7 @@ 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 4
   %% pa: 1=src 2=enc 3=pkg 4=cdn 5=store
@@ -160,7 +160,7 @@ neighbour can give a bent arrow that runs along another one. Block diagrams take
 `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=Media 2=Video,Audio 3=Player 4=License 5=Session
   Media <|-- Video
@@ -179,7 +179,7 @@ classDiagram
 `erDiagram`: entities appear in step order, relationships draw from the entity written first (`CUSTOMER ||--o{ ORDER` reveals
 `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 4=PRODUCT 5=SUPPLIER
   CUSTOMER ||--o{ ORDER : places
@@ -197,7 +197,7 @@ diagrams). Section headers, axes, grids and legends stay visible.
 
 - **`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 Product history
   section Build
@@ -211,7 +211,7 @@ timeline
 
 - **`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 Watching a protected video
   section Find
@@ -228,7 +228,7 @@ journey
 - **`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: "init"
   branch feature
@@ -243,7 +243,7 @@ gitGraph
 
 - **`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

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.1",
+  "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

@@ -219,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)