@markdy/renderer-dom 0.8.14 → 0.8.16

package/README.md

@@ -11,7 +11,8 @@ Web Animations API renderer for [MarkdyScript](../../docs/SYNTAX.md) scenes. Tra
 - **Focused diagram visuals** — flowchart shapes, tree buses, state self-loops, sequence lifelines/messages, constellation orbits, group zones, and annotations
 - **Semantic node cards** — compact SVG glyphs for browsers, services, gateways, queues, workers, databases, storage, CDN, security, platform, and more
 - **Seek-safe** — manual `currentTime` control enables reliable `seek()` in any direction
-- **Playback-rate controls** — set timeline speed to slow down or speed up diagrams without rebuilding animations
+- **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
 - **Semantic themes** — `paper`, `editorial`, `nebula`, `midnight`, `blueprint`, and `graphite`, with per-role node and edge colors
 - **Single dependency** — only `@markdy/core`
 
@@ -73,7 +74,8 @@ diagram.destroy();    // clean up DOM + cancel animations
 | `copyright` | `boolean` | `true` | Show a small "Powered by Markdy" badge below the animation |
 | `progressBar` | `boolean` | `true` | Deprecated compatibility flag for the rainbow scene-boundary progress bar |
 | `sceneBoundaryProgress` | `boolean` | `progressBar ?? true` | Preferred flag for the rainbow scene-boundary progress bar |
-| `playbackRate` | `number` | `1` | Timeline speed multiplier |
+| `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 |
 | `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

@@ -20,8 +20,10 @@ interface DiagramOptions {
     progressBar?: boolean;
     /** Show rainbow progress around scene boundary. Defaults to true. */
     sceneBoundaryProgress?: boolean;
-    /** Playback speed multiplier. Defaults to 1. */
+    /** Playback speed multiplier. Defaults to 1, where 1 is Markdy's normal pace. */
     playbackRate?: number;
+    /** Enable wheel zoom and drag pan on the rendered viewport. Defaults to false. */
+    interactiveViewport?: boolean;
     onWarning?: (warning: Diagnostic) => void;
     onTimeUpdate?: (seconds: number, durationSeconds: number) => void;
     onPlayStateChange?: (playing: boolean) => void;

package/dist/index.js

@@ -1810,6 +1810,12 @@ function applyThemeToScene(scene, theme) {
 }
 
 // src/diagram.ts
+var NORMAL_PLAYBACK_RATE = 4 / 5;
+var DEFAULT_PLAYBACK_RATE = 1;
+var MIN_VIEWPORT_ZOOM = 0.5;
+var MAX_VIEWPORT_ZOOM = 3;
+var VIEWPORT_ZOOM_STEP = 15e-4;
+var DRAG_CLICK_THRESHOLD_PX = 4;
 function createBeatCaptionLayer(doc, beats) {
   const layer = doc.createElement("div");
   layer.className = "markdy-beat-caption-layer";
@@ -1856,7 +1862,8 @@ function createDiagram(opts) {
     assets,
     progressBar,
     sceneBoundaryProgress,
-    playbackRate: initialPlaybackRate = 1,
+    playbackRate: initialPlaybackRate = DEFAULT_PLAYBACK_RATE,
+    interactiveViewport = false,
     onWarning = (w) => console.warn(`[markdy] line ${w.line}: ${w.message}`),
     onTimeUpdate,
     onPlayStateChange
@@ -1937,10 +1944,19 @@ function createDiagram(opts) {
   });
   applyThemeToScene(scene, plan.theme);
   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");
@@ -1998,9 +2014,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);
@@ -2042,16 +2060,75 @@ function createDiagram(opts) {
     anim.currentTime = 0;
   }
   let sceneMs = 0;
-  let playbackRate = Number.isFinite(initialPlaybackRate) && initialPlaybackRate > 0 ? initialPlaybackRate : 1;
+  let playbackRate = Number.isFinite(initialPlaybackRate) && initialPlaybackRate > 0 ? initialPlaybackRate : DEFAULT_PLAYBACK_RATE;
   let lastRafTs = null;
   let isPlaying = false;
   let rafId = null;
+  let viewportScale = 1;
+  let viewportPanX = 0;
+  let viewportPanY = 0;
+  let activePointerId = null;
+  let dragStartX = 0;
+  let dragStartY = 0;
+  let dragLastX = 0;
+  let dragLastY = 0;
+  let dragMoved = false;
+  let suppressNextClick = false;
+  function applyViewportTransform() {
+    viewportTransform.style.transform = `translate(${viewportPanX}px, ${viewportPanY}px) scale(${viewportScale})`;
+  }
+  function handleViewportWheel(event) {
+    event.preventDefault();
+    const rect = viewport.getBoundingClientRect();
+    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;
+    const sceneY = (pointerY - viewportPanY) / viewportScale;
+    viewportScale = nextScale;
+    viewportPanX = pointerX - sceneX * viewportScale;
+    viewportPanY = pointerY - sceneY * viewportScale;
+    applyViewportTransform();
+  }
+  function handleViewportPointerDown(event) {
+    if (event.button !== 0 || activePointerId !== null) return;
+    activePointerId = event.pointerId;
+    dragStartX = event.clientX;
+    dragStartY = event.clientY;
+    dragLastX = event.clientX;
+    dragLastY = event.clientY;
+    dragMoved = false;
+    viewport.setPointerCapture(event.pointerId);
+    viewport.style.cursor = "grabbing";
+  }
+  function handleViewportPointerMove(event) {
+    if (event.pointerId !== activePointerId) return;
+    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;
+    dragLastX = event.clientX;
+    dragLastY = event.clientY;
+    viewportPanX += deltaX;
+    viewportPanY += deltaY;
+    applyViewportTransform();
+  }
+  function handleViewportPointerEnd(event) {
+    if (event.pointerId !== activePointerId) return;
+    if (dragMoved) suppressNextClick = true;
+    if (viewport.hasPointerCapture(event.pointerId)) viewport.releasePointerCapture(event.pointerId);
+    activePointerId = null;
+    dragMoved = false;
+    viewport.style.cursor = interactiveViewport ? "grab" : "pointer";
+  }
   function applyCurrentTime() {
     for (const anim of allAnims) anim.currentTime = sceneMs;
     onTimeUpdate?.(sceneMs / 1e3, durationSeconds);
   }
   function rafTick(timestamp) {
-    if (lastRafTs !== null) sceneMs += (timestamp - lastRafTs) * playbackRate;
+    if (lastRafTs !== null) sceneMs += (timestamp - lastRafTs) * playbackRate * NORMAL_PLAYBACK_RATE;
     lastRafTs = timestamp;
     if (totalDurationMs > 0 && sceneMs >= totalDurationMs) {
       if (loop) sceneMs = sceneMs % totalDurationMs;
@@ -2122,8 +2199,20 @@ function createDiagram(opts) {
       if (viewport.parentNode === container) container.removeChild(viewport);
     }
   };
-  viewport.style.cursor = "pointer";
+  viewport.style.cursor = interactiveViewport ? "grab" : "pointer";
+  if (interactiveViewport) {
+    viewport.style.touchAction = "none";
+    viewport.addEventListener("wheel", handleViewportWheel, { passive: false });
+    viewport.addEventListener("pointerdown", handleViewportPointerDown);
+    viewport.addEventListener("pointermove", handleViewportPointerMove);
+    viewport.addEventListener("pointerup", handleViewportPointerEnd);
+    viewport.addEventListener("pointercancel", handleViewportPointerEnd);
+  }
   viewport.addEventListener("click", () => {
+    if (suppressNextClick) {
+      suppressNextClick = false;
+      return;
+    }
     if (isPlaying) diagram.pause();
     else {
       if (!loop && sceneMs >= totalDurationMs) sceneMs = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdy/renderer-dom",
-  "version": "0.8.14",
+  "version": "0.8.16",
   "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.14"
+    "@markdy/core": "0.8.16"
   },
   "devDependencies": {
     "jsdom": "^29.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.7",
-    "@markdy/stdlib-systems": "0.8.14"
+    "@markdy/stdlib-systems": "0.8.16"
   },
   "scripts": {
     "build": "tsup",