@markdy/renderer-dom 0.8.19 → 0.8.21

package/README.md

@@ -70,18 +70,21 @@ diagram.destroy();    // clean up DOM + cancel animations
 |---|---|---|---|
 | `container` | `HTMLElement` | *(required)* | DOM element to mount the scene into |
 | `code` | `string` | *(required)* | MarkdyScript source code |
-| `autoplay` | `boolean` | `true` | Start playing immediately |
-| `loop` | `boolean` | `true` | Loop the animation when it reaches the end |
-| `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` | 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 |
+| `autoplay` | `boolean` | `plan.meta.autoplay ?? true` | Start playing immediately |
+| `loop` | `boolean` | `plan.meta.loop ?? true` | Loop the animation when it reaches the end |
+| `copyright` | `boolean` | `plan.meta.copyright ?? true` | Show a small "Powered by Markdy" badge below the animation |
+| `progressBar` | `boolean \| string` | `true` | Deprecated compatibility flag for the scene-boundary progress bar |
+| `sceneBoundaryProgress` | `boolean \| string` | `true` | Show boundary progress bar, or pass a custom color/gradient string |
+| `progressColor` | `string` | `plan.meta.progressColor ?? "rainbow"` | Custom progress bar color (e.g. `"#3b82f6"`) or gradient (e.g. `"#ec4899, #8b5cf6"`) |
+| `playbackRate` | `number` | `plan.meta.playbackRate ?? 1` | Normalized timeline speed multiplier; `1` is Markdy's normal pace |
+| `interactiveViewport` | `boolean` | `controls \|\| plan.meta.interactiveViewport` | Enable wheel zoom and drag pan on the rendered viewport |
+| `controls` | `boolean` | `plan.meta.controls ?? false` | Show left-aligned footer controls toolbar (play/pause, restart, speed, reset view); 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 |
 
+> **Note:** Directives declared inside the MarkdyScript code (e.g. `controls true`, `interactive true`, `progressColor "#3b82f6"`) apply automatically if the corresponding JavaScript option is omitted (`undefined`). Options passed to `createDiagram()` override the in-script declarations.
+
 ### `Diagram`
 
 | Method | Description |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BeatRange, Diagnostic } from '@markdy/core';
+import { BeatRange, Diagnostic, RenderPlan } from '@markdy/core';
 
 /**
  * Markdy diagram runtime — renders a RenderPlan via WAAPI.
@@ -17,9 +17,13 @@ interface DiagramOptions {
      */
     assets?: Record<string, string>;
     /** @deprecated Prefer sceneBoundaryProgress. */
-    progressBar?: boolean;
-    /** Show rainbow progress around scene boundary. Defaults to true. */
-    sceneBoundaryProgress?: boolean;
+    progressBar?: boolean | string;
+    /** Show rainbow progress around scene boundary, or specify a custom color/gradient. Defaults to true. */
+    sceneBoundaryProgress?: boolean | string;
+    /** Custom progress bar color or gradient. Defaults to rainbow. */
+    progressColor?: string;
+    /** @deprecated Prefer progressColor. */
+    progressBarColor?: string;
     /** 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. */
@@ -50,4 +54,54 @@ type IconSpec = SvgSpec;
 /** Read-only monochrome glyph registry; callers can inspect or choose keys without injecting markup. */
 declare const ICON_REGISTRY: Readonly<Record<string, IconSpec>>;
 
-export { type Diagram, type DiagramOptions, ICON_REGISTRY, type IconSpec, createDiagram };
+/**
+ * packages/renderer-dom/src/export/gif-encoder.ts
+ * Pure TypeScript GIF89a Encoder with LZW Compression & Floyd-Steinberg Dithering.
+ * Zero external dependencies.
+ */
+interface AnimationRecordFrame {
+    imageData: ImageData;
+    delayMs: number;
+}
+interface GifExportOptions {
+    dither?: boolean;
+    loop?: boolean;
+}
+declare function encodeGifSequence(frames: AnimationRecordFrame[], options?: GifExportOptions): Uint8Array;
+
+/**
+ * packages/renderer-dom/src/export/svg-exporter.ts
+ * Standalone Vector SVG & Figma-compatible design token asset export.
+ * Zero external dependencies.
+ */
+interface SvgExportOptions {
+    includeThemeStyles?: boolean;
+    transparentBackground?: boolean;
+    scale?: number;
+}
+declare function exportDiagramAsVectorSvg(containerEl: HTMLElement, options?: SvgExportOptions): string;
+
+/**
+ * packages/renderer-dom/src/presentation-controller.ts
+ * Interactive Beat Navigation & Keyboard-driven presentation controller.
+ * Zero external dependencies.
+ */
+
+interface ControllerOptions {
+    enableKeyboard?: boolean;
+    onBeatChange?: (beatName: string, index: number) => void;
+}
+declare class DiagramPresentationController {
+    private diagram;
+    private plan;
+    private currentBeatIndex;
+    constructor(diagram: Diagram, plan: RenderPlan, options?: ControllerOptions);
+    nextBeat(): void;
+    prevBeat(): void;
+    getCurrentBeatIndex(): number;
+    togglePlay(): void;
+    setSpeed(rate: number): void;
+    private attachKeyboardListener;
+}
+
+export { type AnimationRecordFrame, type ControllerOptions, type Diagram, type DiagramOptions, DiagramPresentationController, type GifExportOptions, ICON_REGISTRY, type IconSpec, type SvgExportOptions, createDiagram, encodeGifSequence, exportDiagramAsVectorSvg };

package/dist/index.js

@@ -327,6 +327,25 @@ function ensureDefs(svg, theme, id) {
     arrow.appendChild(path);
     defs.appendChild(arrow);
   }
+  const filter = document.createElementNS("http://www.w3.org/2000/svg", "filter");
+  filter.setAttribute("id", `${id}-sketchy`);
+  filter.setAttribute("x", "-4%");
+  filter.setAttribute("y", "-4%");
+  filter.setAttribute("width", "108%");
+  filter.setAttribute("height", "108%");
+  const turb = document.createElementNS("http://www.w3.org/2000/svg", "feTurbulence");
+  turb.setAttribute("type", "fractalNoise");
+  turb.setAttribute("baseFrequency", "0.02");
+  turb.setAttribute("numOctaves", "2");
+  turb.setAttribute("seed", "4");
+  turb.setAttribute("result", "noise");
+  const disp = document.createElementNS("http://www.w3.org/2000/svg", "feDisplacementMap");
+  disp.setAttribute("in", "SourceGraphic");
+  disp.setAttribute("in2", "noise");
+  disp.setAttribute("scale", "1.8");
+  filter.appendChild(turb);
+  filter.appendChild(disp);
+  defs.appendChild(filter);
   svg.prepend(defs);
 }
 function createEdgeRuntime(svg, from, to, kind, label, theme, sceneId, routeObstacles, labelObstacles, bounds, lane) {
@@ -742,11 +761,25 @@ function ensureAnnotationStyles(doc) {
 .markdy-annotation {
   position: absolute;
   max-width: 220px;
-  font-family: var(--md-font-title, Georgia, serif);
+  font-family: var(--md-font-title, Georgia, "Times New Roman", serif);
   font-size: 14px;
   font-style: italic;
   color: var(--md-text);
-  line-height: 1.35;
+  line-height: 1.4;
+  letter-spacing: 0.01em;
+  opacity: 0;
+  transform: translateY(6px);
+  transition: opacity 0.5s cubic-bezier(0.2, 0.8, 0.2, 1), transform 0.5s cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+.markdy-annotation[data-visible="1"] {
+  opacity: 1;
+  transform: none;
+}
+.markdy-annotation[data-intent="accent"] {
+  color: var(--md-accent);
+}
+.markdy-annotation[data-intent="muted"] {
+  color: var(--md-text-muted);
 }
 .markdy-annotation__leader {
   position: absolute;
@@ -790,10 +823,13 @@ function mountAnnotations(layer, annotations, nodes, theme, bounds) {
     const path = doc.createElementNS("http://www.w3.org/2000/svg", "path");
     path.setAttribute("d", `M ${ax} ${ay} Q ${(ax + tx) / 2} ${(ay + ty) / 2 - 20} ${tx} ${ty}`);
     path.setAttribute("fill", "none");
-    path.setAttribute("stroke", theme.textMuted);
+    const intent = typeof ann.intent === "string" ? ann.intent : "neutral";
+    const leaderColor = intent === "accent" ? theme.accent : intent === "muted" ? theme.soft ?? theme.textMuted : theme.textMuted;
+    const leaderOpacity = intent === "accent" ? "0.60" : intent === "muted" ? "0.40" : "0.50";
+    path.setAttribute("stroke", leaderColor);
     path.setAttribute("stroke-width", "1");
     path.setAttribute("stroke-dasharray", "4 3");
-    path.setAttribute("opacity", "0.55");
+    path.setAttribute("opacity", leaderOpacity);
     svg.appendChild(path);
     const dot = doc.createElementNS("http://www.w3.org/2000/svg", "circle");
     dot.setAttribute("cx", String(tx));
@@ -1161,6 +1197,45 @@ function ensureNodeStyles(doc) {
 .markdy-scene-root[data-flat="1"] .markdy-node[data-visible="1"] {
   box-shadow: inset 0 0 0 1px var(--md-hairline, color-mix(in srgb, var(--md-border) 50%, transparent));
 }
+.markdy-scene-root[data-flat="1"] .markdy-node[data-focal="1"] {
+  box-shadow: inset 0 0 0 1.5px color-mix(in srgb, var(--md-accent) 60%, transparent);
+  background:
+    linear-gradient(180deg,
+      color-mix(in srgb, var(--md-accent-tint, var(--md-accent)) 8%, transparent),
+      color-mix(in srgb, var(--md-accent-tint, var(--md-accent)) 4%, transparent));
+}
+.markdy-node[data-kind="external"] {
+  border: 1.2px dashed color-mix(in srgb, var(--md-ink, var(--md-text)) 30%, transparent);
+  background: color-mix(in srgb, var(--md-ink, var(--md-text)) 3%, transparent);
+  box-shadow: none;
+}
+.markdy-node[data-kind="optional"] {
+  border: 1px dashed color-mix(in srgb, var(--md-ink, var(--md-text)) 20%, transparent);
+  background: color-mix(in srgb, var(--md-ink, var(--md-text)) 2%, transparent);
+  box-shadow: none;
+  opacity: 0.7;
+}
+.markdy-scene-root[data-markdy-theme="terminal"] .markdy-node {
+  background: var(--md-node-surface, #141414);
+  border: 1px solid #2b2b2b;
+  box-shadow: none;
+  font-family: var(--md-font-mono, ui-monospace, monospace);
+}
+.markdy-scene-root[data-markdy-theme="terminal"] .markdy-node[data-focal="1"] {
+  border-color: #ff5a36;
+  box-shadow: 0 0 18px -8px rgba(255, 90, 54, 0.45);
+}
+.markdy-scene-root[data-markdy-theme="sketchy"] .markdy-node {
+  background: #ffffff;
+  border: 1.5px solid #2d3142;
+  box-shadow: 3px 3px 0 rgba(45, 49, 66, 0.10);
+  border-radius: var(--md-radius-md, 4px);
+}
+.markdy-scene-root[data-markdy-theme="sketchy"] .markdy-node[data-focal="1"] {
+  border-color: #eb6c36;
+  background: rgba(235, 108, 54, 0.06);
+  box-shadow: 3px 3px 0 rgba(235, 108, 54, 0.12);
+}
 `;
   doc.head.appendChild(style);
 }
@@ -1314,6 +1389,60 @@ var ICONS = {
     ["path", { d: "M12 3 21 12 12 21 3 12 12 3Z" }],
     ["path", { d: "M12 8v4" }],
     ["path", { d: "M12 16h.01" }]
+  ],
+  hub: [
+    ["circle", { cx: "12", cy: "12", r: "7.5" }],
+    ["circle", { cx: "12", cy: "12", r: "2.8" }]
+  ],
+  station: [
+    ["rect", { x: "4", y: "4", width: "16", height: "16", rx: "4" }],
+    ["circle", { cx: "12", cy: "12", r: "3" }]
+  ],
+  bronze: [
+    ["rect", { x: "4", y: "5", width: "16", height: "5", rx: "1.5" }],
+    ["rect", { x: "4", y: "14", width: "16", height: "5", rx: "1.5" }]
+  ],
+  silver: [
+    ["path", { d: "M12 2 20 7v10l-8 5-8-5V7z" }]
+  ],
+  gold: [
+    ["path", { d: "M12 2.5 15 8.5l6.5 1-4.7 4.6 1.1 6.4L12 17.5 6.1 20.5l1.1-6.4L2.5 9.5l6.5-1z" }]
+  ],
+  terminal: [
+    ["rect", { x: "3", y: "4", width: "18", height: "16", rx: "2.5" }],
+    ["path", { d: "m7 9 3 3-3 3M13 15h4" }]
+  ],
+  cloud: [
+    ["path", { d: "M7 16a4 4 0 0 1-.88-7.9 5 5 0 0 1 9.76-1.1A4 4 0 0 1 17 16H7z" }]
+  ],
+  firewall: [
+    ["path", { d: "M12 3v18M3 8h18M3 16h18M7.5 3v5M16.5 3v5M7.5 16v5M16.5 16v5M12 8v8" }]
+  ],
+  alert: [
+    ["path", { d: "M12 3 2 20h20L12 3z" }],
+    ["path", { d: "M12 9v4M12 17h.01" }]
+  ],
+  sync: [
+    ["path", { d: "M20 11A8 8 0 0 0 5.6 6.4L3 9" }],
+    ["path", { d: "M3 4v5h5M4 13a8 8 0 0 0 14.4 4.6L21 15" }],
+    ["path", { d: "M21 20v-5h-5" }]
+  ],
+  search: [
+    ["circle", { cx: "11", cy: "11", r: "6.5" }],
+    ["path", { d: "m19 19-3.5-3.5" }]
+  ],
+  log: [
+    ["rect", { x: "4", y: "3", width: "16", height: "18", rx: "2" }],
+    ["path", { d: "M8 7h8M8 11h8M8 15h4" }]
+  ],
+  layers: [
+    ["path", { d: "M12 2 2 7l10 5 10-5-10-5z" }],
+    ["path", { d: "M2 17l10 5 10-5" }],
+    ["path", { d: "M2 12l10 5 10-5" }]
+  ],
+  nested: [
+    ["rect", { x: "3", y: "3", width: "18", height: "18", rx: "3" }],
+    ["rect", { x: "7", y: "7", width: "10", height: "10", rx: "2" }]
   ]
 };
 var ICON_REGISTRY = Object.freeze(ICONS);
@@ -1340,6 +1469,14 @@ function iconKeyForNode(node) {
   if (node.kind === "api" || node.kind === "service" || node.kind === "microservice" || node.kind === "backend" || node.kind === "server" || node.kind === "handler" || node.kind === "controller") return "server";
   if (node.kind === "browser" || node.kind === "web" || node.kind === "frontend" || node.kind === "app") return "browser";
   if (node.kind === "user" || node.kind === "client") return "user";
+  if (node.kind === "cloud") return "cloud";
+  if (node.kind === "firewall") return "firewall";
+  if (node.kind === "alert" || node.kind === "alarm") return "alert";
+  if (node.kind === "sync") return "sync";
+  if (node.kind === "search") return "search";
+  if (node.kind === "log" || node.kind === "audit") return "log";
+  if (node.kind === "layers" || node.kind === "stack") return "layers";
+  if (node.kind === "nested") return "nested";
   if (node.kind === "decision" || node.kind === "condition") return "decision";
   if (node.kind === "cache") return "cache";
   return ICONS[node.kind] ? node.kind : node.role;
@@ -1720,6 +1857,26 @@ function ensureSceneStyles(doc) {
     linear-gradient(180deg, transparent 0%, var(--md-vignette) 100%);
   opacity: 0.8;
 }
+.markdy-scene-root[data-markdy-theme="terminal"]::before {
+  background:
+    radial-gradient(circle at 50% 50%, rgba(255, 255, 255, 0.06) 1px, transparent 1px) 0 0 / 22px 22px;
+  mask-image: none;
+  opacity: 0.4;
+}
+.markdy-scene-root[data-markdy-theme="terminal"]::after {
+  background:
+    radial-gradient(ellipse at 50% 0%, rgba(255, 90, 54, 0.08), transparent 50%),
+    linear-gradient(180deg, transparent, rgba(0, 0, 0, 0.5) 100%);
+  opacity: 0.7;
+}
+.markdy-scene-root[data-markdy-theme="sketchy"]::before {
+  background: none;
+  opacity: 0;
+}
+.markdy-scene-root[data-markdy-theme="sketchy"]::after {
+  background: none;
+  opacity: 0;
+}
 @keyframes markdy-star-twinkle {
   from { opacity: 0.24; transform: scale(0.85); }
   to { opacity: 0.9; transform: scale(1.15); }
@@ -1769,6 +1926,49 @@ function ensureSceneStyles(doc) {
   transform: translateY(8px);
   will-change: opacity, transform;
 }
+.markdy-footer {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+.markdy-controls button {
+  touch-action: manipulation;
+  user-select: none;
+  -webkit-user-select: none;
+  transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease, transform 0.05s ease;
+}
+.markdy-controls button:hover:not([aria-pressed="true"]) {
+  background: rgba(241, 245, 249, 1);
+  color: #1e293b;
+  border-color: rgba(100, 116, 139, 0.6);
+}
+.markdy-controls button:focus-visible {
+  outline: 2px solid #3b82f6;
+  outline-offset: 1px;
+}
+.markdy-controls button:active {
+  transform: scale(0.96);
+}
+.markdy-footer a {
+  transition: opacity 0.15s ease, color 0.15s ease;
+}
+.markdy-footer a:hover {
+  opacity: 1 !important;
+  color: #64748b !important;
+}
+@media (prefers-reduced-motion: reduce) {
+  .markdy-node,
+  .markdy-beat-caption,
+  .markdy-constellation-star {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+  }
+  .markdy-node { opacity: 1 !important; transform: none !important; }
+  .markdy-constellation-star { animation: none !important; opacity: 0.7 !important; }
+}
+@media print {
+  .markdy-node { opacity: 1 !important; transform: none !important; }
+  .markdy-scene-root::before, .markdy-scene-root::after { display: none !important; }
+}
 `;
   doc.head.appendChild(style);
 }
@@ -1856,24 +2056,36 @@ function createDiagram(opts) {
   const {
     container,
     code,
-    autoplay = true,
-    loop = true,
-    copyright = true,
     assets,
     progressBar,
     sceneBoundaryProgress,
-    playbackRate: initialPlaybackRate = DEFAULT_PLAYBACK_RATE,
-    controls = false,
-    interactiveViewport = controls,
+    progressColor,
+    progressBarColor,
+    playbackRate: initialPlaybackRate,
+    controls: explicitControls,
+    interactiveViewport: explicitInteractiveViewport,
+    autoplay: explicitAutoplay,
+    loop: explicitLoop,
+    copyright: explicitCopyright,
     onWarning = (w) => console.warn(`[markdy] line ${w.line}: ${w.message}`),
     onTimeUpdate,
     onPlayStateChange
   } = opts;
-  const showSceneBoundaryProgress = sceneBoundaryProgress ?? progressBar ?? true;
   const { ast, plan } = parseAndCompile(code);
   for (const w of ast.diagnostics) {
     if (w.severity === "warning") onWarning(w);
   }
+  const controls = explicitControls ?? plan.meta.controls ?? false;
+  const interactiveViewport = explicitInteractiveViewport ?? (explicitControls !== void 0 ? explicitControls : plan.meta.interactiveViewport ?? plan.meta.controls ?? false);
+  const autoplay = explicitAutoplay ?? plan.meta.autoplay ?? true;
+  const loop = explicitLoop ?? plan.meta.loop ?? true;
+  const copyright = explicitCopyright ?? plan.meta.copyright ?? true;
+  const rawPlaybackRate = initialPlaybackRate ?? plan.meta.playbackRate ?? DEFAULT_PLAYBACK_RATE;
+  let playbackRate = Number.isFinite(rawPlaybackRate) && rawPlaybackRate > 0 ? rawPlaybackRate : DEFAULT_PLAYBACK_RATE;
+  const showSceneBoundaryProgress = sceneBoundaryProgress === false || sceneBoundaryProgress === void 0 && progressBar === false ? false : plan.meta.progressColor === "none" ? false : true;
+  const rawColor = progressColor ?? progressBarColor ?? (typeof sceneBoundaryProgress === "string" && sceneBoundaryProgress !== "true" && sceneBoundaryProgress !== "false" ? sceneBoundaryProgress : typeof progressBar === "string" && progressBar !== "true" && progressBar !== "false" ? progressBar : void 0) ?? (plan.meta.progressColor && plan.meta.progressColor !== "none" ? plan.meta.progressColor : void 0);
+  const customColor = rawColor && rawColor.trim() !== "rainbow" ? rawColor.trim() : null;
+  const DEFAULT_RAINBOW = "hsl(0,90%,60%), hsl(45,90%,55%), hsl(90,80%,50%), hsl(180,80%,50%), hsl(270,80%,55%), hsl(330,90%,60%)";
   const totalDurationMs = plan.duration * 1e3;
   const durationSeconds = plan.duration;
   const viewport = document.createElement("div");
@@ -1901,8 +2113,8 @@ function createDiagram(opts) {
   function updateProgressBar(pct) {
     if (!progressEl) return;
     const deg = pct * 360;
-    const rainbow = "hsl(0,90%,60%), hsl(45,90%,55%), hsl(90,80%,50%), hsl(180,80%,50%), hsl(270,80%,55%), hsl(330,90%,60%)";
-    progressEl.style.background = `conic-gradient(from ${tlAngleNorm}deg, ${rainbow} ${deg}deg, transparent ${deg}deg)`;
+    const colorStops = customColor ? customColor.includes(",") ? customColor : `${customColor} 0deg, ${customColor}` : DEFAULT_RAINBOW;
+    progressEl.style.background = `conic-gradient(from ${tlAngleNorm}deg, ${colorStops} ${deg}deg, transparent ${deg}deg)`;
     progressEl.style.mask = "linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)";
     progressEl.style.webkitMask = progressEl.style.mask;
     progressEl.style.maskComposite = "exclude";
@@ -1917,7 +2129,7 @@ function createDiagram(opts) {
     Object.assign(footer.style, {
       display: "flex",
       alignItems: "center",
-      justifyContent: "flex-end",
+      justifyContent: "space-between",
       flexWrap: "wrap",
       gap: "6px",
       width: "100%",
@@ -1944,7 +2156,8 @@ function createDiagram(opts) {
       color: "#999",
       textDecoration: "none",
       padding: "0",
-      opacity: "0.7"
+      opacity: "0.7",
+      marginLeft: "auto"
     });
     ensureFooter().appendChild(badge);
   }
@@ -2080,7 +2293,6 @@ function createDiagram(opts) {
     anim.currentTime = 0;
   }
   let sceneMs = 0;
-  let playbackRate = Number.isFinite(initialPlaybackRate) && initialPlaybackRate > 0 ? initialPlaybackRate : DEFAULT_PLAYBACK_RATE;
   let lastRafTs = null;
   let isPlaying = false;
   let rafId = null;
@@ -2158,15 +2370,19 @@ function createDiagram(opts) {
   }
   function syncControls() {
     if (controlsPlayButton) {
-      controlsPlayButton.textContent = isPlaying ? "Pause" : "Play";
-      controlsPlayButton.setAttribute("aria-label", isPlaying ? "Pause diagram" : "Play diagram");
+      const playing = isPlaying;
+      controlsPlayButton.textContent = playing ? "Pause" : "Play";
+      const playLabel = playing ? "Pause diagram" : "Play diagram";
+      controlsPlayButton.setAttribute("aria-label", playLabel);
+      controlsPlayButton.title = playLabel;
     }
     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";
+      button.style.background = active ? "#1e293b" : "rgba(248, 250, 252, 0.92)";
+      button.style.color = active ? "#ffffff" : "#475569";
+      button.style.borderColor = active ? "#0f172a" : "rgba(148, 163, 184, 0.55)";
     }
   }
   function emitPlayStateChange(playing) {
@@ -2288,7 +2504,7 @@ function createDiagram(opts) {
       position: "static",
       display: "flex",
       alignItems: "center",
-      justifyContent: "flex-end",
+      justifyContent: "flex-start",
       flexWrap: "wrap",
       gap: "4px",
       maxWidth: "100%",
@@ -2354,7 +2570,292 @@ function createDiagram(opts) {
   if (autoplay) diagram.play();
   return diagram;
 }
+
+// src/export/gif-encoder.ts
+var GIF_HEADER = "GIF89a";
+var PALETTE_RGB332 = (() => {
+  const palette = new Uint8Array(256 * 3);
+  for (let i = 0; i < 256; i++) {
+    const r = Math.round((i >> 5 & 7) * 255 / 7);
+    const g = Math.round((i >> 2 & 7) * 255 / 7);
+    const b = Math.round((i & 3) * 255 / 3);
+    palette[i * 3] = r;
+    palette[i * 3 + 1] = g;
+    palette[i * 3 + 2] = b;
+  }
+  return palette;
+})();
+function clamp2(value, min = 0, max = 255) {
+  return value < min ? min : value > max ? max : value;
+}
+function nearestColorIndex(r, g, b) {
+  return (clamp2(r) & 224 | (clamp2(g) & 224) >> 3 | (clamp2(b) & 192) >> 6) & 255;
+}
+function quantizeFrame(imageData, dither) {
+  const { width, height, data } = imageData;
+  const pixelCount = width * height;
+  const out = new Uint8Array(pixelCount);
+  if (!dither) {
+    for (let i = 0; i < pixelCount; i++) {
+      const idx = i * 4;
+      out[i] = (data[idx] & 224 | (data[idx + 1] & 224) >> 3 | (data[idx + 2] & 192) >> 6) & 255;
+    }
+    return out;
+  }
+  const errR = new Float32Array(pixelCount);
+  const errG = new Float32Array(pixelCount);
+  const errB = new Float32Array(pixelCount);
+  for (let i = 0; i < pixelCount; i++) {
+    const idx = i * 4;
+    errR[i] = data[idx];
+    errG[i] = data[idx + 1];
+    errB[i] = data[idx + 2];
+  }
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const idx = y * width + x;
+      const r = clamp2(Math.round(errR[idx]));
+      const g = clamp2(Math.round(errG[idx]));
+      const b = clamp2(Math.round(errB[idx]));
+      const colorIdx = nearestColorIndex(r, g, b);
+      out[idx] = colorIdx;
+      const pr = PALETTE_RGB332[colorIdx * 3];
+      const pg = PALETTE_RGB332[colorIdx * 3 + 1];
+      const pb = PALETTE_RGB332[colorIdx * 3 + 2];
+      const dr = errR[idx] - pr;
+      const dg = errG[idx] - pg;
+      const db = errB[idx] - pb;
+      if (x + 1 < width) {
+        errR[idx + 1] += dr * 7 / 16;
+        errG[idx + 1] += dg * 7 / 16;
+        errB[idx + 1] += db * 7 / 16;
+      }
+      if (y + 1 < height) {
+        if (x > 0) {
+          errR[idx + width - 1] += dr * 3 / 16;
+          errG[idx + width - 1] += dg * 3 / 16;
+          errB[idx + width - 1] += db * 3 / 16;
+        }
+        errR[idx + width] += dr * 5 / 16;
+        errG[idx + width] += dg * 5 / 16;
+        errB[idx + width] += db * 5 / 16;
+        if (x + 1 < width) {
+          errR[idx + width + 1] += dr * 1 / 16;
+          errG[idx + width + 1] += dg * 1 / 16;
+          errB[idx + width + 1] += db * 1 / 16;
+        }
+      }
+    }
+  }
+  return out;
+}
+function lzwCompress(pixels, minCodeSize = 8) {
+  const clearCode = 1 << minCodeSize;
+  const endCode = clearCode + 1;
+  let codeSize = minCodeSize + 1;
+  let nextCode = endCode + 1;
+  let dict = /* @__PURE__ */ new Map();
+  for (let i = 0; i < clearCode; i++) {
+    dict.set(String(i), i);
+  }
+  const codes = [clearCode];
+  let prefix = String(pixels[0] ?? 0);
+  for (let i = 1; i < pixels.length; i++) {
+    const suffix = String(pixels[i]);
+    const combo = `${prefix},${suffix}`;
+    if (dict.has(combo)) {
+      prefix = combo;
+      continue;
+    }
+    codes.push(dict.get(prefix));
+    dict.set(combo, nextCode++);
+    prefix = suffix;
+    if (nextCode === 1 << codeSize && codeSize < 12) {
+      codeSize++;
+    }
+    if (nextCode >= 4095) {
+      codes.push(clearCode);
+      dict = /* @__PURE__ */ new Map();
+      for (let j = 0; j < clearCode; j++) dict.set(String(j), j);
+      codeSize = minCodeSize + 1;
+      nextCode = endCode + 1;
+    }
+  }
+  codes.push(dict.get(prefix));
+  codes.push(endCode);
+  const bytes = [];
+  let bitBuffer = 0;
+  let bitCount = 0;
+  codeSize = minCodeSize + 1;
+  nextCode = endCode + 1;
+  for (const code of codes) {
+    bitBuffer |= code << bitCount;
+    bitCount += codeSize;
+    while (bitCount >= 8) {
+      bytes.push(bitBuffer & 255);
+      bitBuffer >>= 8;
+      bitCount -= 8;
+    }
+    if (code === clearCode) {
+      codeSize = minCodeSize + 1;
+      nextCode = endCode + 1;
+    } else if (code !== endCode) {
+      nextCode++;
+      if (nextCode === 1 << codeSize && codeSize < 12) {
+        codeSize++;
+      }
+    }
+  }
+  if (bitCount > 0) {
+    bytes.push(bitBuffer & 255);
+  }
+  return new Uint8Array(bytes);
+}
+function encodeGifSequence(frames, options = {}) {
+  if (frames.length === 0) {
+    throw new Error("Cannot encode GIF without frames");
+  }
+  const { width, height } = frames[0].imageData;
+  const dither = options.dither ?? true;
+  const buffer = [];
+  const pushString = (str) => {
+    for (let i = 0; i < str.length; i++) buffer.push(str.charCodeAt(i));
+  };
+  const pushU16 = (val) => {
+    buffer.push(val & 255, val >> 8 & 255);
+  };
+  pushString(GIF_HEADER);
+  pushU16(width);
+  pushU16(height);
+  buffer.push(247);
+  buffer.push(0);
+  buffer.push(0);
+  for (let i = 0; i < PALETTE_RGB332.length; i++) {
+    buffer.push(PALETTE_RGB332[i]);
+  }
+  if (options.loop !== false) {
+    buffer.push(33, 255, 11);
+    pushString("NETSCAPE2.0");
+    buffer.push(3, 1, 0, 0, 0);
+  }
+  for (const frame of frames) {
+    const quantized = quantizeFrame(frame.imageData, dither);
+    const compressed = lzwCompress(quantized);
+    const delayHundredths = Math.max(2, Math.round(frame.delayMs / 10));
+    buffer.push(33, 249, 4, 4);
+    pushU16(delayHundredths);
+    buffer.push(0, 0);
+    buffer.push(44);
+    pushU16(0);
+    pushU16(0);
+    pushU16(width);
+    pushU16(height);
+    buffer.push(0);
+    buffer.push(8);
+    for (let offset = 0; offset < compressed.length; offset += 255) {
+      const chunk = compressed.slice(offset, offset + 255);
+      buffer.push(chunk.length, ...chunk);
+    }
+    buffer.push(0);
+  }
+  buffer.push(59);
+  return new Uint8Array(buffer);
+}
+
+// src/export/svg-exporter.ts
+function exportDiagramAsVectorSvg(containerEl, options = {}) {
+  const svgEl = containerEl.querySelector("svg");
+  if (!svgEl) throw new Error("No Markdy SVG element found in container");
+  const clonedSvg = svgEl.cloneNode(true);
+  const width = svgEl.getAttribute("width") || String(svgEl.clientWidth || 800);
+  const height = svgEl.getAttribute("height") || String(svgEl.clientHeight || 400);
+  clonedSvg.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+  clonedSvg.setAttribute("xmlns:xlink", "http://www.w3.org/1999/xlink");
+  clonedSvg.setAttribute("width", width);
+  clonedSvg.setAttribute("height", height);
+  clonedSvg.setAttribute("viewBox", `0 0 ${width} ${height}`);
+  if (options.transparentBackground) {
+    const bgRect = clonedSvg.querySelector("rect");
+    if (bgRect) bgRect.remove();
+  }
+  if (options.includeThemeStyles !== false) {
+    const styleEl = document.createElementNS("http://www.w3.org/2000/svg", "style");
+    styleEl.textContent = `
+      text { font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+      .markdy-node { transition: opacity 0.3s ease; }
+    `;
+    clonedSvg.insertBefore(styleEl, clonedSvg.firstChild);
+  }
+  const serializer = new XMLSerializer();
+  return `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+` + serializer.serializeToString(clonedSvg);
+}
+
+// src/presentation-controller.ts
+var DiagramPresentationController = class {
+  diagram;
+  plan;
+  currentBeatIndex = 0;
+  constructor(diagram, plan, options = {}) {
+    this.diagram = diagram;
+    this.plan = plan;
+    if (options.enableKeyboard !== false && typeof window !== "undefined") {
+      this.attachKeyboardListener();
+    }
+  }
+  nextBeat() {
+    if (this.currentBeatIndex < this.plan.beats.length - 1) {
+      this.currentBeatIndex++;
+      const beat = this.plan.beats[this.currentBeatIndex];
+      this.diagram.seek(beat.start);
+    }
+  }
+  prevBeat() {
+    if (this.currentBeatIndex > 0) {
+      this.currentBeatIndex--;
+      const beat = this.plan.beats[this.currentBeatIndex];
+      this.diagram.seek(beat.start);
+    }
+  }
+  getCurrentBeatIndex() {
+    return this.currentBeatIndex;
+  }
+  togglePlay() {
+    this.diagram.play();
+  }
+  setSpeed(rate) {
+    this.diagram.setPlaybackRate(rate);
+  }
+  attachKeyboardListener() {
+    window.addEventListener("keydown", (e) => {
+      if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return;
+      switch (e.key) {
+        case "ArrowRight":
+        case "PageDown":
+          this.nextBeat();
+          break;
+        case "ArrowLeft":
+        case "PageUp":
+          this.prevBeat();
+          break;
+        case " ":
+          e.preventDefault();
+          this.togglePlay();
+          break;
+        case "1":
+          this.setSpeed(1);
+          break;
+        case "2":
+          this.setSpeed(2);
+          break;
+      }
+    });
+  }
+};
 export {
+  DiagramPresentationController,
   ICON_REGISTRY,
-  createDiagram
+  createDiagram,
+  encodeGifSequence,
+  exportDiagramAsVectorSvg
 };

package/package.json

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