@markdy/renderer-dom 0.8.15 → 0.8.17

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 when viewport interaction is enabled |
 | `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. Defaults to false. */
+    controls?: boolean;
     onWarning?: (warning: Diagnostic) => void;
     onTimeUpdate?: (seconds: number, durationSeconds: number) => void;
     onPlayStateChange?: (playing: boolean) => void;

package/dist/index.js

@@ -1864,6 +1864,7 @@ function createDiagram(opts) {
     sceneBoundaryProgress,
     playbackRate: initialPlaybackRate = DEFAULT_PLAYBACK_RATE,
     interactiveViewport = false,
+    controls = false,
     onWarning = (w) => console.warn(`[markdy] line ${w.line}: ${w.message}`),
     onTimeUpdate,
     onPlayStateChange
@@ -1930,15 +1931,6 @@ function createDiagram(opts) {
   }
   ensureSceneStyles(document);
   ensureNodeStyles(document);
-  const viewportTransform = document.createElement("div");
-  viewportTransform.className = "markdy-viewport-transform";
-  Object.assign(viewportTransform.style, {
-    position: "absolute",
-    inset: "0",
-    transformOrigin: "0 0",
-    willChange: interactiveViewport ? "transform" : "auto"
-  });
-  viewport.appendChild(viewportTransform);
   const scene = document.createElement("div");
   scene.className = "markdy-scene-root";
   Object.assign(scene.style, {
@@ -1952,11 +1944,20 @@ function createDiagram(opts) {
     transformOrigin: "0 0"
   });
   applyThemeToScene(scene, plan.theme);
-  viewportTransform.appendChild(scene);
+  viewport.appendChild(scene);
+  const viewportTransform = document.createElement("div");
+  viewportTransform.className = "markdy-viewport-transform";
+  Object.assign(viewportTransform.style, {
+    position: "absolute",
+    inset: "0",
+    transformOrigin: "0 0",
+    willChange: interactiveViewport ? "transform" : "auto"
+  });
+  scene.appendChild(viewportTransform);
   const sceneContent = document.createElement("div");
   sceneContent.className = "markdy-scene-content";
   Object.assign(sceneContent.style, { position: "absolute", inset: "0" });
-  scene.appendChild(sceneContent);
+  viewportTransform.appendChild(sceneContent);
   const titleEl = createTitleEl(plan.title);
   sceneContent.appendChild(titleEl);
   const cameraLayer = document.createElement("div");
@@ -2014,9 +2015,11 @@ function createDiagram(opts) {
     nodeLayer.appendChild(el);
     nodeEls.set(node.id, el);
   }
+  let fitScale = 1;
   function scaleScene() {
-    const s = viewport.clientWidth / plan.meta.width;
-    scene.style.transform = `scale(${s})`;
+    const width = viewport.clientWidth || plan.meta.width;
+    fitScale = width / plan.meta.width;
+    scene.style.transform = `scale(${fitScale})`;
   }
   scaleScene();
   const resizeObserver = new ResizeObserver(scaleScene);
@@ -2072,14 +2075,22 @@ 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();
-    const pointerX = event.clientX - rect.left;
-    const pointerY = event.clientY - rect.top;
+    const pointerX = (event.clientX - rect.left) / fitScale;
+    const pointerY = (event.clientY - rect.top) / fitScale;
     const nextScale = Math.min(MAX_VIEWPORT_ZOOM, Math.max(MIN_VIEWPORT_ZOOM, viewportScale * Math.exp(-event.deltaY * VIEWPORT_ZOOM_STEP)));
     if (nextScale === viewportScale) return;
     const sceneX = (pointerX - viewportPanX) / viewportScale;
@@ -2102,8 +2113,8 @@ function createDiagram(opts) {
   }
   function handleViewportPointerMove(event) {
     if (event.pointerId !== activePointerId) return;
-    const deltaX = event.clientX - dragLastX;
-    const deltaY = event.clientY - dragLastY;
+    const deltaX = (event.clientX - dragLastX) / fitScale;
+    const deltaY = (event.clientY - dragLastY) / fitScale;
     const totalX = event.clientX - dragStartX;
     const totalY = event.clientY - dragStartY;
     if (!dragMoved && Math.hypot(totalX, totalY) >= DRAG_CLICK_THRESHOLD_PX) dragMoved = true;
@@ -2121,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);
@@ -2134,7 +2167,7 @@ function createDiagram(opts) {
         sceneMs = totalDurationMs;
         applyCurrentTime();
         isPlaying = false;
-        onPlayStateChange?.(false);
+        emitPlayStateChange(false);
         lastRafTs = null;
         rafId = null;
         return;
@@ -2148,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;
@@ -2168,6 +2201,7 @@ function createDiagram(opts) {
     setPlaybackRate(rate) {
       if (!Number.isFinite(rate) || rate <= 0) return;
       playbackRate = rate;
+      syncControls();
     },
     playbackRate() {
       return playbackRate;
@@ -2197,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";
@@ -2205,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.15",
+  "version": "0.8.17",
   "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.15"
+    "@markdy/core": "0.8.17"
   },
   "devDependencies": {
     "jsdom": "^29.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.7",
-    "@markdy/stdlib-systems": "0.8.15"
+    "@markdy/stdlib-systems": "0.8.17"
   },
   "scripts": {
     "build": "tsup",