pele-animate 0.16.2 → 0.17.0

package/README.md

@@ -9,7 +9,7 @@ step through it, and nodes can carry icons. A small post-processor for [Pele](ht
 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.
 
-**[Website](https://pele-animate.pages.dev/) · [Docs](docs/getting-started.md) · [npm](https://www.npmjs.com/package/pele-animate) · [Changelog](CHANGELOG.md)**
+**[Website](https://pele-animate.danielkimdev.com/) · [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">
 
@@ -51,15 +51,17 @@ Mermaid source:
 
 ```mermaid-icons
 flowchart LR
-  %% pa: 1=C 2=L 3=S
+  %% pa: 1=C 2=C>L 3=L>S 4=S>L 5=L>C
   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
+  C -->|request| L
+  L -->|forward| S
+  S -->|response| L
+  L -->|reply| C
 ```
 
-`%% pa: 1=C 2=L 3=S` pins the order (optional). `form: "square", h: 88` makes a large frameless icon.
+`%% pa: 1=C 2=C>L 3=L>S 4=S>L 5=L>C` pins the order: the request first, then each leg of the round trip (optional). `form: "square", h: 88` makes a large frameless icon.
 
 ## Documentation
 

package/docs/api.md

@@ -13,10 +13,9 @@ 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. |
+| `watch` | `watch(container: HTMLElement, source?: string): 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. |
 | `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. |
 
 `svg.paSteps` (type `PaStep[]`, where `PaStep = Array<[element: Element, parts: Element[]]>`) is set by `animate()`: one array per

package/docs/diagram-types.md

@@ -64,11 +64,11 @@ 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)). The pins here follow a request: the user, the CDN, the API, the cache and database together, then the queue and worker.
+names work (import the packs as for [icons](./icons.md)). The pins show the services first (the request path, then what sits behind the API), then trace the request one edge at a time with edge pins (`3=user>cdn`).
 
 ```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
+  %% pa: 1=user,cdn,api 2=cache,db,queue,worker 3=user>cdn 4=cdn>api 5=api>cache 6=api>db 7=api>queue 8=queue>worker
   group edge(cloud)[Edge]
   group core(cloud)[Core]
   service user(device-desktop)[User]
@@ -96,7 +96,7 @@ start and end markers are nodes too, with the ids `root_start` and `root_end`, s
 
 ```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
+  %% pa: 1=root_start 2=Idle 3=Loading 4=Playing 5=Paused 6=Error 7=Error>Idle 8=root_end
   [*] --> Idle
   Idle --> Loading: play
   Loading --> Playing: ready
@@ -107,18 +107,18 @@ stateDiagram-v2
   Playing --> [*]: stop
 ```
 
-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
+The pins give each state its own step, in the order a viewer meets them, and the `retry` transition (`Error>Idle`) its own step after `Error` is on screen. 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`. The example adds the DRM service, CDN and analytics one at a time, then the operator who reads the analytics.
+give `Person(...)` and `System(...)`; an edge pin is `3=app>drm`. The example puts the landscape on screen first, then draws the relationships one at a time, then adds analytics and the operator who reads it.
 
 ```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
+  %% pa: 1=viewer,app,drm,cdn 2=viewer>app 3=app>drm 4=app>cdn 5=analytics,admin 6=app>analytics 7=admin>analytics
   Person(viewer, "Viewer", "Watches video")
   System(app, "Player app", "Plays protected video")
   System_Ext(drm, "DRM service", "Issues licenses")
@@ -158,11 +158,11 @@ 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. `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.
+and then `Video`, whichever way the arrowhead points. Pins use the class names; the example shows the base class, its subtypes, the inheritance arrows as their own step, then the classes that use them. An edge pin may name the ends in either order, so `Video>Media` follows the arrow while the source says `Media <|-- Video`.
 
 ```mermaid live title="Class: media types, player and license"
 classDiagram
-  %% pa: 1=Media 2=Video,Audio 3=Player 4=License 5=Session
+  %% pa: 1=Media 2=Video,Audio 3=Video>Media,Audio>Media 4=Player 5=License 6=Session
   Media <|-- Video
   Media <|-- Audio
   Player --> Media : plays

package/docs/getting-started.md

@@ -45,12 +45,14 @@ The Mermaid source:
 
 ```mermaid-icons live title="Icons: request, load balancer and cloud service"
 flowchart LR
-  %% pa: 1=C 2=L 3=S
+  %% pa: 1=C 2=C>L 3=L>S 4=S>L 5=L>C
   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
+  C -->|request| L
+  L -->|forward| S
+  S -->|response| L
+  L -->|reply| C
 ```
 
 What you get:
@@ -60,7 +62,7 @@ What you get:
 - Click, or focus and press Enter: **step mode**. Previous, play/pause and next buttons appear, and Space, ←, → and Esc work.
 - With `prefers-reduced-motion`, the motion is off and the finished picture shows.
 
-The `%% pa: 1=C 2=L 3=S` comment pins the order. Without it, the order follows the edges. See [step order](./step-order.md).
+The `%% pa: 1=C 2=C>L 3=L>S 4=S>L 5=L>C` comment pins the order: the request first, then each leg of the round trip. Without it, the order follows the edges. See [step order](./step-order.md).
 
 ## Next
 

package/docs/how-it-works.md

@@ -20,7 +20,6 @@ Two layers, one diagram:
 - `watch(el, src)` is pele-animate's. It marks the container as a scene (class `pa-scene`), animates each SVG Pele renders into
   it, and re-applies after Pele re-draws on resize. The intro is skipped on those re-draws once it has played.
 - `animate(svg, { source })` does one SVG. Use it if you render with Pele yourself and do not want `watch()`.
-- `replay(svg)` plays the intro again.
 
 ## The three kinds of motion
 

package/docs/icons.md

@@ -61,7 +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).
+- The [icon browser](https://pele-animate.danielkimdev.com/icons/) searches names and tags and copies a ready snippet; the same list is [icons.json](https://pele-animate.danielkimdev.com/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/migrating.md

@@ -9,6 +9,10 @@ section: Reference
 
 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.16 to 0.17
+
+`replay(svg)` and `watch(el, src, { controls: false })` are removed. A click or Enter on a diagram always enters step mode. To restart the intro yourself, remove the `pa-in` and `pa-done` classes from the svg, force a reflow, and add `pa-in` again.
+
 ## 0.12 to 0.13
 
 Two breaking changes.

package/docs/step-order.md

@@ -51,6 +51,7 @@ flowchart LR
 Rules that avoid surprises:
 
 - **Pin the nodes first.** An edge pinned before its target appears lands early.
+- Edge pins work in every diagram type that has edges, not only flowcharts.
 - 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.
@@ -67,8 +68,6 @@ Click the diagram, or focus it and press Enter or Space. A small bar appears wit
 | ← | 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:

package/package.json

@@ -1,26 +1,68 @@
 {
   "name": "pele-animate",
-  "version": "0.16.2",
+  "version": "0.17.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" },
+  "publishConfig": {
+    "access": "public"
+  },
   "author": "Daniel Kim",
-  "repository": { "type": "git", "url": "git+https://github.com/dkdev24/pele-animate.git" },
-  "keywords": ["mermaid", "pele", "svg", "diagram", "animation"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dkdev24/pele-animate.git"
+  },
+  "keywords": [
+    "mermaid",
+    "pele",
+    "svg",
+    "diagram",
+    "animation"
+  ],
   "types": "./types/index.d.ts",
   "exports": {
-    ".": { "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" },
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./pele-animate.js"
+    },
+    "./glyphs": {
+      "types": "./types/glyphs.d.ts",
+      "default": "./glyphs.js"
+    },
+    "./preset-doverunner": "./preset-doverunner.js",
     "./style.css": "./pele-animate.css",
-    "./tabler/*": { "types": "./types/tabler-pack.d.ts", "default": "./tabler/*.js" }
+    "./tabler/*": {
+      "types": "./types/tabler-pack.d.ts",
+      "default": "./tabler/*.js"
+    }
+  },
+  "files": [
+    "pele-animate.js",
+    "pele-animate.css",
+    "glyphs.js",
+    "preset-doverunner.js",
+    "tabler",
+    "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"
   },
-  "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" }
-}
+  "scripts": {
+    "test": "node scripts/check-docs.mjs",
+    "build": "pnpm -r --filter ./site build"
+  }
+}

package/pele-animate.js

@@ -319,8 +319,8 @@ function leaveStep(svg) {
 }
 
 // mount() re-renders on container resize; re-animate each new <svg>, skipping the intro once it has played.
-// Click (or Enter/Space) enters step mode: previous | play/pause | next, Space, ←/→, Esc to leave. `controls: false` keeps click-to-replay.
-export function watch(container, source = '', { controls = true } = {}) {
+// Click (or Enter/Space) enters step mode: previous | play/pause | next, Space, ←/→, Esc to leave.
+export function watch(container, source = '') {
   let played = false;
   let k = -1; // current step; -1 = not in step mode
   let timer = 0;
@@ -401,27 +401,14 @@ export function watch(container, source = '', { controls = true } = {}) {
   new MutationObserver(run).observe(container, { childList: true });
   container.classList.add('pa-scene');
   container.tabIndex = 0;
-  container.title ||= controls ? 'Click to step through' : 'Click to replay';
-  if (!controls) {
-    container.addEventListener('click', () => replay(cur()));
-    container.addEventListener('keydown', (e) => (e.key === 'Enter' || e.key === ' ') && (e.preventDefault(), replay(cur())));
-  } else {
-    container.addEventListener('click', () => k < 0 && enter());
-    container.addEventListener('keydown', (e) => {
-      const key = e.key;
-      if (e.target.closest('button') && (key === 'Enter' || key === ' ')) return; // native button activation
-      if (k < 0) return (key === 'Enter' || key === ' ') && (e.preventDefault(), enter());
-      const act = { ' ': toggle, ArrowRight: () => manual(k + 1), ArrowLeft: () => manual(k - 1), Escape: exit }[key];
-      if (act) { e.preventDefault(); act(); }
-    });
-  }
+  container.title ||= 'Click to step through';
+  container.addEventListener('click', () => k < 0 && enter());
+  container.addEventListener('keydown', (e) => {
+    const key = e.key;
+    if (e.target.closest('button') && (key === 'Enter' || key === ' ')) return; // native button activation
+    if (k < 0) return (key === 'Enter' || key === ' ') && (e.preventDefault(), enter());
+    const act = { ' ': toggle, ArrowRight: () => manual(k + 1), ArrowLeft: () => manual(k - 1), Escape: exit }[key];
+    if (act) { e.preventDefault(); act(); }
+  });
   run();
 }
-
-// Play the intro again (removing pa-in/pa-done restarts the CSS animations).
-export function replay(svg) {
-  if (!svg || reduced()) return;
-  svg.classList.remove('pa-in', 'pa-done');
-  void svg.getBoundingClientRect();
-  svg.classList.add('pa-in');
-}

package/skills/pele-animate/SKILL.md

@@ -60,12 +60,14 @@ Icon nodes use Mermaid's own syntax:
 
 ```mermaid-icons
 flowchart LR
-  %% pa: 1=C 2=L 3=S
+  %% pa: 1=C 2=C>L 3=L>S 4=S>L 5=L>C
   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
+  C -->|request| L
+  L -->|forward| S
+  S -->|response| L
+  L -->|reply| C
 ```
 
 - `form: "square", h: 88` = large frameless icon. Leave both out for a small icon in a frame.
@@ -99,7 +101,7 @@ Default order follows the edges. Override with one comment line anywhere in the
 - `%% 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.
+Click or Enter on a diagram starts step mode (prev / play / next; Space, ←, →, Esc).
 To review the order of existing diagrams against the page text, use the `diagram-step-order` skill.
 
 ## 5. Theme

package/types/index.d.ts

@@ -5,11 +5,6 @@ export interface AnimateOptions {
   source?: string;
 }
 
-export interface WatchOptions {
-  /** `false` keeps the old click-to-replay instead of step mode. Default `true`. */
-  controls?: boolean;
-}
-
 /** One step: the elements that appear and, for each, the parts that pop in. */
 export type PaStep = Array<[element: Element, parts: Element[]]>;
 
@@ -29,7 +24,4 @@ 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. */
-export function replay(svg: SVGSVGElement | null | undefined): void;
+export function watch(container: HTMLElement, source?: string): void;

package/types/preset-doverunner.d.ts

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