pele-animate 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# pele-animate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Animated, illustrated SVG scenes from plain Mermaid code. A small post-processor for
+[Pele](https://github.com/obsidianmd/pele) (MIT), which renders the Mermaid; this adds the motion and the pictures.
+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. Click or Enter replays the intro.
+- `@{ icon: "name" }` nodes become illustrations from a glyph pack. Unknown names fall back to a plain Pele box.
+- Idle state is the finished picture; `prefers-reduced-motion` turns the motion off. Light and dark themes.
+
+## Install
+
+```sh
+npm i pele-animate pele
+```
+
+## Use
+
+```js
+import { mount } from 'pele';
+import { watch } from 'pele-animate';
+import { icons } from 'pele-animate/glyphs';
+import 'pele-animate/preset-doverunner'; // optional extra glyphs
+import 'pele-animate/style.css';
+
+for (const el of document.querySelectorAll('pre.mermaid')) {
+  const src = el.textContent;
+  mount(el, src, { icons });
+  watch(el, src); // re-applies after Pele re-lays-out on resize
+}
+```
+
+Mermaid source:
+
+```mermaid
+flowchart LR
+  %% pa: 1=P 2=O 3=D
+  P@{ icon: "player", form: "square", h: 88, label: "Player" }
+  O@{ icon: "server", form: "square", h: 88, label: "OTT service" }
+  D@{ icon: "key", form: "square", h: 88, label: "DRM server" }
+  P <-->|auth token| O
+  P <-->|token / license| D
+```
+
+`form: "square", h: 88` makes a large frameless glyph; leave both out for a small icon in a frame.
+`%% pa: 1=P 2=O 3=D` pins nodes to steps (optional). Sequence diagrams animate actors, then messages in order.
+
+## API
+
+| Export | |
+|---|---|
+| `watch(container, source?)` | Animate the SVG inside `container` (and every re-render of it); adds the scene panel, click and Enter replay |
+| `animate(svg, { hover, source })` | Animate one SVG; you handle re-renders |
+| `replay(svg)` | Play the intro again |
+| `parseOrder(source)` | Read the `%% pa:` pins |
+| `registerGlyphs(pack, strokeWidth = 1.1)` (`/glyphs`) | Add glyphs: `{ name: '<inner markup of a 24x24 svg>' }`; colors via `--pa-solid` / `--pa-light` |
+| `icons` (`/glyphs`) | Pele `icons` resolver |
+
+Generic glyphs: `player`, `server`, `key`, `document`, `shield`, `phone`. `preset-doverunner`: `package`, `token`, `lock`,
+`database`, `bits-a`, `bits-b`.
+
+## Theme
+
+`watch()` adds class `pa-scene` to the container. Override `--pa-bg`, `--pa-solid`, `--pa-light` or any `--pele-*`
+variable on it; defaults are `:where()` rules, so your stylesheet wins.
+
+## Limits
+
+- Relies on Pele's SVG structure (`.pele-node`, `.pele-edge`, `data-id`); `pele` is a peer dependency pinned to `^1.7.0`.
+- Flowcharts and sequence diagrams only. No types yet.
+- Glyph art is square-boxed; wide art is drawn as a wide glyph inside the square.

package/glyphs.js

@@ -0,0 +1,22 @@
+// Glyph registry. 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)';
+export const W = '#fff';
+const reg = new Map();
+
+// Pele draws icons with stroke-width 2 in a 24 box, which turns heavy once a node is sized up; glyphs get a thin line instead.
+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}"/>`,
+});

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "pele-animate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "Animated, illustrated SVG scenes from plain Mermaid code, as a post-processor for Pele.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/dkdev24/pele-animate#readme",
+  "publishConfig": { "access": "public" },
+  "author": "Daniel Kim",
+  "repository": { "type": "git", "url": "git+https://github.com/dkdev24/pele-animate.git" },
+  "keywords": ["mermaid", "pele", "svg", "diagram", "animation"],
+  "exports": {
+    ".": "./pele-animate.js",
+    "./glyphs": "./glyphs.js",
+    "./preset-doverunner": "./preset-doverunner.js",
+    "./style.css": "./pele-animate.css"
+  },
+  "files": ["pele-animate.js", "pele-animate.css", "glyphs.js", "preset-doverunner.js", "README.md", "LICENSE"],
+  "sideEffects": ["*.css", "./preset-doverunner.js"],
+  "peerDependencies": { "pele": "^1.7.0" },
+  "devDependencies": { "pele": "^1.7.0" }
+}

package/pele-animate.css

@@ -0,0 +1,45 @@
+/* Draw-in once when scrolled into view; a dot travels each edge while hovered/focused. Idle = finished picture. */
+.pa-ready:not(.pa-in) .pele-node,
+.pa-ready:not(.pa-in) .pele-edge-label,
+.pa-ready:not(.pa-in) .pele-lifeline,
+.pa-ready:not(.pa-in) .pele-marker { opacity: 0; }
+.pa-ready:not(.pa-in) .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 .pele-node,
+.pa-ready.pa-in .pele-edge-label,
+.pa-ready.pa-in .pele-lifeline,
+.pa-ready.pa-in .pele-marker { animation: pa-fade .4s ease-out backwards; animation-delay: var(--d, 0s); }
+.pa-ready.pa-in .pele-edge > path:not(.pele-marker) { animation: pa-draw .4s ease-out backwards; animation-delay: var(--d, 0s); }
+.pa-ready.pa-done * { animation: none !important; }
+@keyframes pa-fade { from { opacity: 0; } }
+@keyframes pa-draw { from { stroke-dasharray: var(--len); stroke-dashoffset: var(--len); } to { stroke-dasharray: var(--len); stroke-dashoffset: 0; } }
+
+.pa-dot { fill: var(--pele-accent, #4F378B); opacity: 0; offset-rotate: 0deg; }
+
+@media (prefers-reduced-motion: reduce) {
+  .pa-ready * { animation: none !important; }
+  .pa-ready .pele-node, .pa-ready .pele-edge-label, .pa-ready .pele-lifeline, .pa-ready .pele-marker { opacity: 1 !important; }
+  .pa-ready .pele-edge > path { stroke-dasharray: none; stroke-dashoffset: 0 !important; }
+}
+
+/* Scene frame: tinted panel like the Lab product cards. Override any --pa-* / --pele-* on the container to retheme. */
+:where(.pa-scene) {
+  --pa-bg: #efeafa; --pa-solid: #4F378B; --pa-light: #e4dcf6;
+  --pele-bg: transparent; --pele-surface: #fff; --pele-surface-alt: var(--pa-light);
+  --pele-border: color-mix(in srgb, var(--pa-solid) 40%, transparent);
+  --pele-line: color-mix(in srgb, var(--pa-solid) 65%, transparent);
+  --pele-accent: var(--pa-solid); --pele-fg: #1f1a33;
+}
+.pa-scene { background: var(--pa-bg); border-radius: 16px; padding: 1.25rem; margin: 1.5rem 0; display: flex; justify-content: center; overflow-x: auto; cursor: pointer; }
+@media (max-width: 600px) { .pa-scene { padding: .75rem; } }
+@media (prefers-color-scheme: dark) {
+  :where(:root:not([data-theme="light"]) .pa-scene) { --pa-bg: #241d3b; --pa-solid: #b9a6ff; --pa-light: #3a2f5e; --pele-surface: #2f2650; --pele-fg: #ece8ff; }
+}
+:where(:root[data-theme="dark"] .pa-scene) { --pa-bg: #241d3b; --pa-solid: #b9a6ff; --pa-light: #3a2f5e; --pele-surface: #2f2650; --pele-fg: #ece8ff; }
+.pa-scene:focus-visible { outline: 2px solid var(--pa-solid); outline-offset: 2px; }
+
+/* Big icon nodes: the glyph is the picture, the frame rect goes away. */
+.pa-art > rect:first-child { fill: none; stroke: none; }
+/* 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); }

package/pele-animate.js

@@ -0,0 +1,155 @@
+// Post-processor for SVG produced by pele's render()/mount(). Timeline: nodes appear by BFS level, each edge draws from its
+// source once the source is up, the target appears as the edge lands. Sequence diagrams: actors, then messages in order.
+const NS = 'http://www.w3.org/2000/svg';
+const UNIT = 0.8; // seconds per BFS level / message
+const MAX_INTRO = 3; // a long diagram squeezes its steps so the intro never runs past about this many seconds
+const TOKEN = 0.5; // seconds a token takes to cross an edge
+const reduced = () => matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+// `%% pa: 1=A,B 2=C` pins nodes to steps (1-based); returns Map(nodeId -> level). Everything else keeps its BFS level.
+export function parseOrder(source = '') {
+  const m = source.match(/^\s*%%\s*pa:\s*(.+)$/m);
+  const levels = new Map();
+  for (const [, step, ids] of (m?.[1] ?? '').matchAll(/(\d+)\s*=\s*([^\s]+)/g))
+    for (const id of ids.split(',')) levels.set(id.trim(), Number(step) - 1);
+  return levels;
+}
+
+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];
+  return null;
+}
+
+function bfs(ids, pairs, pinned) {
+  const level = new Map(pinned);
+  const hasIn = new Set(pairs.map(([, d]) => d));
+  let queue = ids.filter((i) => !hasIn.has(i));
+  if (!queue.length && ids.length) queue = [ids[0]];
+  for (const q of queue) if (!level.has(q)) level.set(q, 0);
+  while (queue.length) {
+    const next = [];
+    for (const s of queue)
+      for (const [a, d] of pairs)
+        if (a === s && !level.has(d)) { level.set(d, level.get(s) + 1); next.push(d); }
+    queue = next;
+  }
+  for (const i of ids) if (!level.has(i)) level.set(i, 0);
+  return level;
+}
+
+// Spike: icon nodes sized with `h: 88` get a frame of that size; let the glyph fill it and hide the frame so the glyph is the art.
+function fitGlyphs(svg) {
+  svg.querySelectorAll('.pele-node').forEach((n) => {
+    const g = n.querySelector(':scope > svg.pele-icon');
+    const frame = g?.previousElementSibling;
+    if (!g || frame?.tagName !== 'rect' || +frame.getAttribute('width') < 60) return;
+    for (const a of ['x', 'y', 'width', 'height']) g.setAttribute(a, frame.getAttribute(a));
+    n.classList.add('pa-art');
+  });
+}
+
+export function animate(svg, { hover = svg, source = '' } = {}) {
+  fitGlyphs(svg);
+  svg.querySelectorAll('.pa-dot').forEach((d) => d.remove());
+  svg.classList.add('pa-ready');
+  const nodes = [...svg.querySelectorAll('.pele-node')];
+  const edges = [...svg.querySelectorAll('.pele-edge')];
+  const ids = [...new Set(nodes.map((n) => n.dataset.id))];
+  const set = (el, t) => el?.style.setProperty('--d', `${t}s`);
+  const times = new Map(); // edge element -> start time
+
+  if (svg.classList.contains('pele-sequence')) {
+    const u = Math.min(UNIT, MAX_INTRO / Math.max(1, edges.length));
+    nodes.forEach((n) => set(n, 0));
+    svg.querySelectorAll('.pele-lifeline').forEach((l) => set(l, 0.2));
+    edges.forEach((e, i) => times.set(e, 0.5 + i * u));
+  } else {
+    const pairs = edges.map((e) => endpoints(e.dataset.id, ids));
+    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;
+    nodes.forEach((n) => set(n, level.get(n.dataset.id) * u));
+    // 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] ?? [];
+      times.set(e, Math.max((level.get(s) ?? 0) * u + 0.3 * k, (level.get(d) ?? 0) * u - 0.5 * k));
+    });
+  }
+
+  const labels = new Map([...svg.querySelectorAll('.pele-edge-label')].map((l) => [l.dataset.id, l]));
+  const dots = [];
+  for (const [e, t] of times) {
+    const path = e.querySelector('path:not(.pele-marker)');
+    if (!path) continue;
+    path.style.setProperty('--len', path.getTotalLength());
+    set(path, t);
+    set(e.querySelector('.pele-marker'), t + 0.3);
+    set(labels.get(e.dataset.id), t);
+    const dot = document.createElementNS(NS, 'circle');
+    dot.setAttribute('class', 'pa-dot');
+    dot.setAttribute('r', '3');
+    dot.style.offsetPath = `path("${path.getAttribute('d')}")`;
+    e.append(dot);
+    dots.push([dot, t]);
+  }
+
+  // Hover loop: tokens cross the edges in timeline order, then a pause, then again.
+  const cycle = Math.max(0, ...times.values()) + TOKEN + 0.8;
+  let running = [];
+  const play = () => {
+    if (reduced() || running.length) return;
+    running = dots.map(([dot, t]) => {
+      const a = t / cycle, b = (t + TOKEN) / cycle, e = 0.001;
+      return dot.animate(
+        [
+          { offset: 0, opacity: 0, offsetDistance: '0%' },
+          { offset: a, opacity: 0, offsetDistance: '0%' },
+          { offset: a + e, opacity: 1, offsetDistance: '0%' },
+          { offset: b, opacity: 1, offsetDistance: '100%' },
+          { offset: b + e, opacity: 0, offsetDistance: '100%' },
+          { offset: 1, opacity: 0, offsetDistance: '100%' },
+        ],
+        { duration: cycle * 1000, iterations: Infinity }
+      );
+    });
+  };
+  const stop = () => { running.forEach((a) => a.cancel()); running = []; };
+  hover.addEventListener('pointerenter', play);
+  hover.addEventListener('pointerleave', stop);
+  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);
+}
+
+// mount() re-renders on container resize; re-animate each new <svg>, skipping the intro once it has played.
+export function watch(container, source = '') {
+  let played = false;
+  const run = () => {
+    const svg = container.querySelector('svg.pele:not(.pa-ready)');
+    if (!svg) return;
+    animate(svg, { hover: container, source });
+    if (played) svg.classList.add('pa-in', 'pa-done');
+    else svg.addEventListener('animationend', () => (played = true), { once: true });
+  };
+  new MutationObserver(run).observe(container, { childList: true });
+  container.classList.add('pa-scene');
+  container.tabIndex = 0;
+  container.title ||= 'Click to replay';
+  container.addEventListener('click', () => replay(container.querySelector('svg.pele')));
+  container.addEventListener('keydown', (e) => (e.key === 'Enter' || e.key === ' ') && (e.preventDefault(), replay(container.querySelector('svg.pele'))));
+  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/preset-doverunner.js

@@ -0,0 +1,21 @@
+// DoveRunner vocabulary (DRM / forensic watermarking / packaging). Add on top of the generic pack in glyphs.js.
+import { registerGlyphs, S, L, W } from './glyphs.js';
+
+// A row of six video-segment chips; bit 1 = filled, bit 0 = outline.
+const chips = (bits) =>
+  [...bits]
+    .map((b, i) => {
+      const x = 1.1 + i * 3.8;
+      const on = b === '1';
+      return `<rect x="${x}" y="8" width="2.8" height="8" rx=".6" fill="${on ? S : W}" stroke="${S}"/><text x="${x + 1.4}" y="13.5" font-size="3.4" text-anchor="middle" fill="${on ? W : S}" stroke="none" font-family="monospace">${b}</text>`;
+    })
+    .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}"/>`,
+  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);