@markdy/renderer-dom 0.8.16 → 0.8.18

package/README.md

@@ -13,6 +13,7 @@ Web Animations API renderer for [MarkdyScript](../../docs/SYNTAX.md) scenes. Tra
 - **Seek-safe** — manual `currentTime` control enables reliable `seek()` in any direction
 - **Playback-rate controls** — set normalized timeline speed to slow down or speed up diagrams without rebuilding animations
 - **Interactive viewport** — opt into wheel zoom and drag pan while click-to-pause stays available
+- **Embed controls** — opt into a compact playback toolbar with restart, speed, and view reset controls
 - **Semantic themes** — `paper`, `editorial`, `nebula`, `midnight`, `blueprint`, and `graphite`, with per-role node and edge colors
 - **Single dependency** — only `@markdy/core`
 
@@ -76,6 +77,7 @@ diagram.destroy();    // clean up DOM + cancel animations
 | `sceneBoundaryProgress` | `boolean` | `progressBar ?? true` | Preferred flag for the rainbow scene-boundary progress bar |
 | `playbackRate` | `number` | `1` | Normalized timeline speed multiplier; `1` is Markdy's normal pace |
 | `interactiveViewport` | `boolean` | `false` | Enable wheel zoom and drag pan on the rendered viewport |
+| `controls` | `boolean` | `false` | Show a compact toolbar with play/pause, restart, speed, and view reset controls; also enables viewport interaction |
 | `onWarning` | `(warning: Diagnostic) => void` | `console.warn` | Called for each soft parse warning |
 | `onTimeUpdate` | `(seconds: number, durationSeconds: number) => void` | — | Called whenever playback or seek changes the current time |
 | `onPlayStateChange` | `(playing: boolean) => void` | — | Called when playback starts or pauses |

package/dist/index.d.ts

@@ -24,6 +24,8 @@ interface DiagramOptions {
     playbackRate?: number;
     /** Enable wheel zoom and drag pan on the rendered viewport. Defaults to false. */
     interactiveViewport?: boolean;
+    /** Show built-in playback and viewport controls. Also enables viewport interaction. Defaults to false. */
+    controls?: boolean;
     onWarning?: (warning: Diagnostic) => void;
     onTimeUpdate?: (seconds: number, durationSeconds: number) => void;
     onPlayStateChange?: (playing: boolean) => void;

package/dist/index.js

@@ -1863,7 +1863,8 @@ function createDiagram(opts) {
     progressBar,
     sceneBoundaryProgress,
     playbackRate: initialPlaybackRate = DEFAULT_PLAYBACK_RATE,
-    interactiveViewport = false,
+    controls = false,
+    interactiveViewport = controls,
     onWarning = (w) => console.warn(`[markdy] line ${w.line}: ${w.message}`),
     onTimeUpdate,
     onPlayStateChange
@@ -2074,9 +2075,17 @@ function createDiagram(opts) {
   let dragLastY = 0;
   let dragMoved = false;
   let suppressNextClick = false;
+  let controlsPlayButton = null;
+  let controlsRateButtons = [];
   function applyViewportTransform() {
     viewportTransform.style.transform = `translate(${viewportPanX}px, ${viewportPanY}px) scale(${viewportScale})`;
   }
+  function resetViewportTransform() {
+    viewportScale = 1;
+    viewportPanX = 0;
+    viewportPanY = 0;
+    applyViewportTransform();
+  }
   function handleViewportWheel(event) {
     event.preventDefault();
     const rect = viewport.getBoundingClientRect();
@@ -2123,6 +2132,28 @@ function createDiagram(opts) {
     dragMoved = false;
     viewport.style.cursor = interactiveViewport ? "grab" : "pointer";
   }
+  function handleViewportDoubleClick(event) {
+    event.preventDefault();
+    suppressNextClick = false;
+    resetViewportTransform();
+  }
+  function syncControls() {
+    if (controlsPlayButton) {
+      controlsPlayButton.textContent = isPlaying ? "Pause" : "Play";
+      controlsPlayButton.setAttribute("aria-label", isPlaying ? "Pause diagram" : "Play diagram");
+    }
+    for (const button of controlsRateButtons) {
+      const rate = Number(button.dataset.rate ?? "1");
+      const active = Math.abs(rate - playbackRate) < 1e-3;
+      button.setAttribute("aria-pressed", active ? "true" : "false");
+      button.style.background = active ? "rgba(15, 23, 42, 0.92)" : "rgba(255, 255, 255, 0.92)";
+      button.style.color = active ? "#ffffff" : "#111827";
+    }
+  }
+  function emitPlayStateChange(playing) {
+    onPlayStateChange?.(playing);
+    syncControls();
+  }
   function applyCurrentTime() {
     for (const anim of allAnims) anim.currentTime = sceneMs;
     onTimeUpdate?.(sceneMs / 1e3, durationSeconds);
@@ -2136,7 +2167,7 @@ function createDiagram(opts) {
         sceneMs = totalDurationMs;
         applyCurrentTime();
         isPlaying = false;
-        onPlayStateChange?.(false);
+        emitPlayStateChange(false);
         lastRafTs = null;
         rafId = null;
         return;
@@ -2150,14 +2181,14 @@ function createDiagram(opts) {
     play() {
       if (isPlaying) return;
       isPlaying = true;
-      onPlayStateChange?.(true);
+      emitPlayStateChange(true);
       lastRafTs = null;
       rafId = requestAnimationFrame(rafTick);
     },
     pause() {
       if (!isPlaying) return;
       isPlaying = false;
-      onPlayStateChange?.(false);
+      emitPlayStateChange(false);
       if (rafId !== null) cancelAnimationFrame(rafId);
       rafId = null;
       lastRafTs = null;
@@ -2170,6 +2201,7 @@ function createDiagram(opts) {
     setPlaybackRate(rate) {
       if (!Number.isFinite(rate) || rate <= 0) return;
       playbackRate = rate;
+      syncControls();
     },
     playbackRate() {
       return playbackRate;
@@ -2199,6 +2231,91 @@ function createDiagram(opts) {
       if (viewport.parentNode === container) container.removeChild(viewport);
     }
   };
+  function togglePlayback() {
+    if (isPlaying) diagram.pause();
+    else {
+      if (!loop && sceneMs >= totalDurationMs) sceneMs = 0;
+      diagram.play();
+    }
+  }
+  function makeControlButton(label, ariaLabel) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.textContent = label;
+    button.setAttribute("aria-label", ariaLabel);
+    button.title = ariaLabel;
+    Object.assign(button.style, {
+      appearance: "none",
+      border: "1px solid rgba(15, 23, 42, 0.16)",
+      borderRadius: "6px",
+      background: "rgba(255, 255, 255, 0.92)",
+      color: "#111827",
+      cursor: "pointer",
+      font: "600 11px/1.2 system-ui, sans-serif",
+      padding: "6px 8px",
+      minWidth: "34px",
+      whiteSpace: "nowrap",
+      boxShadow: "0 1px 2px rgba(15, 23, 42, 0.08)"
+    });
+    return button;
+  }
+  function mountControls() {
+    const toolbar = document.createElement("div");
+    toolbar.className = "markdy-controls";
+    toolbar.setAttribute("role", "toolbar");
+    toolbar.setAttribute("aria-label", "Diagram controls");
+    Object.assign(toolbar.style, {
+      position: "absolute",
+      left: "50%",
+      bottom: "10px",
+      zIndex: "10000",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flexWrap: "wrap",
+      gap: "6px",
+      maxWidth: "calc(100% - 20px)",
+      padding: "6px",
+      border: "1px solid rgba(15, 23, 42, 0.12)",
+      borderRadius: "8px",
+      background: "rgba(255, 255, 255, 0.78)",
+      boxShadow: "0 10px 28px rgba(15, 23, 42, 0.16)",
+      backdropFilter: "blur(10px)",
+      transform: "translateX(-50%)",
+      pointerEvents: "auto"
+    });
+    for (const eventName of ["click", "dblclick", "pointerdown", "pointermove", "pointerup", "wheel"]) {
+      toolbar.addEventListener(eventName, (event) => event.stopPropagation());
+    }
+    controlsPlayButton = makeControlButton("Play", "Play diagram");
+    controlsPlayButton.className = "markdy-control-play";
+    controlsPlayButton.addEventListener("click", togglePlayback);
+    toolbar.appendChild(controlsPlayButton);
+    const restartButton = makeControlButton("Restart", "Restart diagram");
+    restartButton.className = "markdy-control-restart";
+    restartButton.addEventListener("click", () => {
+      diagram.seek(0);
+      diagram.play();
+    });
+    toolbar.appendChild(restartButton);
+    controlsRateButtons = [0.5, 1, 2].map((rate) => {
+      const button = makeControlButton(`${rate}x`, `Set playback speed to ${rate}x`);
+      button.className = "markdy-control-rate";
+      button.dataset.rate = String(rate);
+      button.setAttribute("aria-pressed", "false");
+      button.addEventListener("click", () => diagram.setPlaybackRate(rate));
+      toolbar.appendChild(button);
+      return button;
+    });
+    if (interactiveViewport) {
+      const resetButton = makeControlButton("Reset", "Reset diagram view");
+      resetButton.className = "markdy-control-reset-view";
+      resetButton.addEventListener("click", resetViewportTransform);
+      toolbar.appendChild(resetButton);
+    }
+    viewport.appendChild(toolbar);
+    syncControls();
+  }
   viewport.style.cursor = interactiveViewport ? "grab" : "pointer";
   if (interactiveViewport) {
     viewport.style.touchAction = "none";
@@ -2207,17 +2324,15 @@ function createDiagram(opts) {
     viewport.addEventListener("pointermove", handleViewportPointerMove);
     viewport.addEventListener("pointerup", handleViewportPointerEnd);
     viewport.addEventListener("pointercancel", handleViewportPointerEnd);
+    viewport.addEventListener("dblclick", handleViewportDoubleClick);
   }
+  if (controls) mountControls();
   viewport.addEventListener("click", () => {
     if (suppressNextClick) {
       suppressNextClick = false;
       return;
     }
-    if (isPlaying) diagram.pause();
-    else {
-      if (!loop && sceneMs >= totalDurationMs) sceneMs = 0;
-      diagram.play();
-    }
+    togglePlayback();
   });
   if (autoplay) diagram.play();
   return diagram;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdy/renderer-dom",
-  "version": "0.8.16",
+  "version": "0.8.18",
   "description": "Browser renderer for diagram-native animated MarkdyScript architecture diagrams, built on the Web Animations API.",
   "license": "MIT",
   "type": "module",
@@ -44,14 +44,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@markdy/core": "0.8.16"
+    "@markdy/core": "0.8.18"
   },
   "devDependencies": {
     "jsdom": "^29.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.7",
-    "@markdy/stdlib-systems": "0.8.16"
+    "@markdy/stdlib-systems": "0.8.18"
   },
   "scripts": {
     "build": "tsup",