waygraph 0.12.40 → 0.12.42

package/dist/cli.js

@@ -4,7 +4,7 @@
  *
  * Primary verbs (less is more):
  *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
- *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand` `--ff-disabled`
+ *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--mini` `--ff-expand` `--ff-disabled`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
@@ -274,12 +274,12 @@ async function findBlock(projectDir, ref) {
   if (byRuntimeName.length === 1) return byRuntimeName[0];
   if (byRuntimeName.length > 1) {
     throw new Error(
-      "waygraph chain: \\\"" + ref + "\\\" matches " + byRuntimeName.length + " Blocks by name - " +
+      "waygraph chain: \\"" + ref + "\\" matches " + byRuntimeName.length + " Blocks by name - " +
         byRuntimeName.map((b) => b.exportName + " (" + b.file + ")").join(", ") +
         ". Use the export name to disambiguate.",
     );
   }
-  throw new Error("waygraph chain: no Block named \\\"" + ref + "\\\" found under " + projectDir);
+  throw new Error("waygraph chain: no Block named \\"" + ref + "\\" found under " + projectDir);
 }
 
 /**
@@ -316,7 +316,7 @@ function parseChainSpec(spec) {
       const m = /^([A-Za-z_$][\\w-]*)\\s*(?:\\(([\\s\\S]*)\\))?$/.exec(s);
       if (!m) {
         throw new Error(
-          "waygraph chain: could not parse segment \\\"" + s + "\\\" - expected \\\"blockName\\\" or \\\"blockName({...json...})\\\"",
+          "waygraph chain: could not parse segment \\"" + s + "\\" - expected \\"blockName\\" or \\"blockName({...json...})\\"",
         );
       }
       const ref = m[1];
@@ -329,7 +329,7 @@ function seedMemFromRequires(mem, requires, json, label) {
   if (requires.length === 0) {
     if (json !== undefined) {
       throw new Error(
-        "waygraph chain: \\\"" + label + "\\\" takes no input (empty requires) but got a payload: " + json,
+        "waygraph chain: \\"" + label + "\\" takes no input (empty requires) but got a payload: " + json,
       );
     }
     return;
@@ -341,7 +341,7 @@ function seedMemFromRequires(mem, requires, json, label) {
       json = fromEnv;
     } else {
       throw new Error(
-        "waygraph chain: \\\"" + label + "\\\" requires " + requires.map((k) => k.name).join(", ") +
+        "waygraph chain: \\"" + label + "\\" requires " + requires.map((k) => k.name).join(", ") +
           " - give a JSON payload (inline blockName({...}) or --data '{...}')",
       );
     }
@@ -350,7 +350,7 @@ function seedMemFromRequires(mem, requires, json, label) {
   try {
     parsed = JSON.parse(json);
   } catch (err) {
-    throw new Error("waygraph chain: \\\"" + label + "\\\" payload is not valid JSON - " + String(err));
+    throw new Error("waygraph chain: \\"" + label + "\\" payload is not valid JSON - " + String(err));
   }
   // Keyed-by-name when every require name is a top-level key (preferred for
   // --data and for {"saucedemo.credentials":{...}} even with one require).
@@ -367,13 +367,13 @@ function seedMemFromRequires(mem, requires, json, label) {
   }
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(
-      "waygraph chain: \\\"" + label + "\\\" requires " + requires.length + " keys (" +
+      "waygraph chain: \\"" + label + "\\" requires " + requires.length + " keys (" +
         requires.map((k) => k.name).join(", ") + ") - payload must be an object keyed by each key's name",
     );
   }
   for (const k of requires) {
     if (!(k.name in parsed)) {
-      throw new Error("waygraph chain: \\\"" + label + "\\\" payload is missing required key \\\"" + k.name + "\\\"");
+      throw new Error("waygraph chain: \\"" + label + "\\" payload is missing required key \\"" + k.name + "\\"");
     }
     mem.set(k, parsed[k.name]);
   }
@@ -412,12 +412,10 @@ function seedMemForFlow(mem, flowBlocks, json, label) {
 const RING_CSS =
   "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
   "border:2.5px solid #7C3AED;border-radius:10px;" +
-  "box-shadow:0 0 0 4px rgba(124,58,237,.16);" +
-  "transition:opacity .32s ease,border-color .15s;}" +
-  "#wg-focus-veil{position:fixed;z-index:2147483645;pointer-events:none;opacity:0;" +
-  "border-radius:10px;box-shadow:0 0 0 9999px rgba(12,6,28,.62);" +
-  "transition:opacity .28s ease;}" +
-  "#wg-focus-veil.wg-focus-on{opacity:1;}" +
+  "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease,border-color .15s,box-shadow .15s;}" +
+  // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
+  // Automation (verify fallback, unmatched fill/click) = gray - operators
+  // can ignore engine checks and watch purple + semantic tones.
   "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
   "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
   "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
@@ -433,7 +431,7 @@ const RING_CSS =
   // window.__wgPositionRing in installOverlay.
   "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
   "max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:#7C3AED;color:#fff;" +
-  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .32s ease,background .15s,color .15s;}" +
+  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease,background .15s,color .15s;}" +
   "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
   "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
   "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
@@ -519,24 +517,6 @@ const RING_CSS =
   "#wg-todos .wg-todo-done{color:#6ee7b7;text-decoration:line-through;opacity:.85;}" +
   "#wg-todos .wg-todo-current{color:#fff;}" +
   "#wg-todos .wg-todo-pending{color:#9a7ad1;}" +
-  "#wg-todo-modal{position:fixed;z-index:2147483647;left:14px;bottom:14px;min-width:240px;max-width:min(360px,92vw);" +
-  "padding:14px 16px 12px;background:rgba(18,8,36,.94);color:#f0e8ff;" +
-  "border:1px solid rgba(124,58,237,.55);border-radius:12px;" +
-  "box-shadow:0 12px 40px rgba(0,0,0,.45);backdrop-filter:blur(8px);" +
-  "opacity:0;transform:translateY(8px);pointer-events:none;" +
-  "transition:opacity .28s ease,transform .28s ease;}" +
-  "#wg-todo-modal.wg-todo-on{opacity:1;transform:none;pointer-events:auto;}" +
-  "#wg-todo-modal .wg-todo-head{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
-  "letter-spacing:.04em;text-transform:uppercase;margin:0 0 10px;}" +
-  "#wg-todo-modal ul{list-style:none;margin:0;padding:0;}" +
-  "#wg-todo-modal li{display:flex;gap:10px;align-items:flex-start;margin:0 0 8px;" +
-  "font:600 14px/1.4 system-ui,sans-serif;}" +
-  "#wg-todo-modal li:last-child{margin-bottom:0;}" +
-  "#wg-todo-modal .wg-todo-mark{flex:0 0 auto;width:1.2em;text-align:center;font-size:15px;}" +
-  "#wg-todo-modal .wg-todo-done{color:#6ee7b7;text-decoration:line-through;opacity:.8;}" +
-  "#wg-todo-modal .wg-todo-current{color:#fff;}" +
-  "#wg-todo-modal .wg-todo-current .wg-todo-mark{color:#c9a6ff;}" +
-  "#wg-todo-modal .wg-todo-pending{color:#9a7ad1;}" +
   "#wg-progress{height:4px;background:#2a1650;border-radius:2px;margin:0 0 12px;overflow:hidden;}" +
   "#wg-progress-bar{height:100%;background:#7C3AED;border-radius:2px;transition:width .3s ease;}" +
   // A real tab bar for episodes - the currently-active episode reads as
@@ -621,18 +601,23 @@ const RING_CSS =
   "#wg-panel .wg-expected-heading{color:#ffcf7a;}" +
   "#wg-panel .wg-expected-reason{font:600 12.5px/1.5 system-ui,sans-serif;background:#2a2410;" +
   "color:#ffe6ae;border-radius:8px;padding:10px;margin:0 0 8px;}" +
-  // Hide / Show chrome: collapsed = compact "N / M · block" pill (not empty chrome).
+  // Hide / Show chrome: collapsed = compact "N / M · block" pill + Next (manual).
   "#wg-panel .wg-chrome{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:0 0 8px;}" +
   "#wg-panel .wg-chrome-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
-  "letter-spacing:.04em;text-transform:uppercase;}" +
-  "#wg-panel button.wg-hide-btn{margin:0;padding:4px 10px;font:600 11px system-ui,sans-serif;" +
+  "letter-spacing:.04em;text-transform:uppercase;flex:1;min-width:0;}" +
+  "#wg-panel .wg-chrome-actions{display:flex;align-items:center;gap:6px;flex-shrink:0;}" +
+  "#wg-panel button.wg-hide-btn,#wg-panel button.wg-mini-next{margin:0;padding:4px 10px;font:600 11px system-ui,sans-serif;" +
   "background:#3a2a60;color:#e8dcff;border:1px solid #5b3aa8;border-radius:6px;cursor:pointer;}" +
-  "#wg-panel button.wg-hide-btn:hover{background:#4b2a80;}" +
+  "#wg-panel button.wg-hide-btn:hover,#wg-panel button.wg-mini-next:hover{background:#4b2a80;}" +
+  "#wg-panel button.wg-mini-next{background:#2a9d6f;border-color:#22855e;color:#fff;display:none;}" +
+  "#wg-panel button.wg-mini-next:hover{background:#22855e;}" +
+  "#wg-panel button.wg-mini-next:disabled{opacity:.55;cursor:default;}" +
   "#wg-panel.wg-collapsed{width:auto;max-width:92vw;padding:8px 12px;max-height:none;overflow:hidden;}" +
   "#wg-panel.wg-collapsed .wg-body{display:none;}" +
   "#wg-panel.wg-collapsed .wg-chrome{margin:0;}" +
   "#wg-panel.wg-collapsed .wg-chrome-title{font:700 13px/1.25 system-ui,sans-serif;color:#fff;" +
   "letter-spacing:0;text-transform:none;}" +
+  "#wg-panel.wg-collapsed button.wg-mini-next.wg-mini-next-show{display:inline-block;}" +
   "@media (max-width:640px){" +
   "#wg-panel{left:8px;right:8px;bottom:8px;transform:none;max-width:none;width:auto;" +
   "max-height:min(55vh,calc(100vh - 16px));padding:12px 14px;border-radius:12px;}" +
@@ -640,6 +625,7 @@ const RING_CSS =
   "#wg-episodes{overflow-x:auto;-webkit-overflow-scrolling:touch;flex-wrap:nowrap;}" +
   "#wg-panel .wg-narration{font-size:13px;}" +
   "#wg-panel button{width:100%;}" +
+  "#wg-panel.wg-collapsed button.wg-mini-next,#wg-panel.wg-collapsed button.wg-hide-btn{width:auto;}" +
   "#wg-panel .wg-error-actions{flex-direction:column;}" +
   "#wg-banner{max-width:min(92vw,320px);font-size:13px;}" +
   "}";
@@ -675,11 +661,6 @@ async function installOverlay(page, title) {
         } catch {
           /* private mode / blocked storage - falls back to manual gating */
         }
-        if (!document.getElementById("wg-focus-veil")) {
-          const veil = document.createElement("div");
-          veil.id = "wg-focus-veil";
-          document.documentElement.appendChild(veil);
-        }
         if (!document.getElementById("wg-ring")) {
           const ring = document.createElement("div");
           ring.id = "wg-ring";
@@ -710,10 +691,7 @@ async function installOverlay(page, title) {
         window.__wgMoveCursorTo = (x, y, ms, instant) => {
           const cursor = document.getElementById("wg-cursor");
           if (!cursor) return;
-          const travel = ms || 600;
-          window.__wgCursorPos = { x: Number(x) || 0, y: Number(y) || 0 };
-          window.__wgCursorTravelUntil = Date.now() + (instant ? 0 : travel) + 40;
-          cursor.style.setProperty("--wg-cursor-ms", travel + "ms");
+          cursor.style.setProperty("--wg-cursor-ms", (ms || 600) + "ms");
           if (instant) {
             const prev = cursor.style.transition;
             cursor.style.transition = "none";
@@ -732,7 +710,6 @@ async function installOverlay(page, title) {
         window.__wgPositionRing = (box, label, tone, style) => {
           const ring = document.getElementById("wg-ring");
           const ringLabel = document.getElementById("wg-ring-label");
-          const veil = document.getElementById("wg-focus-veil");
           if (!ring || !ringLabel) return;
           const raw = (tone || "planned") + "";
           const t =
@@ -750,15 +727,14 @@ async function installOverlay(page, title) {
           ring.dataset.size = size;
           ringLabel.dataset.size = size;
           ringLabel.dataset.weight = weight;
-          ring.dataset.focus = st.focus ? "1" : "0";
           const pad = size === "sm" ? 3 : size === "lg" ? 10 : 6;
           const margin = 6;
           const vw = window.innerWidth;
           const vh = window.innerHeight;
           let left = box.x - pad;
           let top = box.y - pad;
-          const width = Math.max(0, box.width + pad * 2);
-          const height = Math.max(0, box.height + pad * 2);
+          const width = box.width + pad * 2;
+          const height = box.height + pad * 2;
           if (left < margin) left = margin;
           if (top < margin) top = margin;
           if (left + width > vw - margin) left = Math.max(margin, vw - margin - width);
@@ -768,92 +744,21 @@ async function installOverlay(page, title) {
           ring.style.width = width + "px";
           ring.style.height = height + "px";
           ring.style.opacity = "1";
-          if (veil) {
-            veil.style.left = left + "px";
-            veil.style.top = top + "px";
-            veil.style.width = width + "px";
-            veil.style.height = height + "px";
-            const br = size === "sm" ? "8px" : size === "lg" ? "12px" : "10px";
-            veil.style.borderRadius = br;
-            if (st.focus) veil.classList.add("wg-focus-on");
-            else veil.classList.remove("wg-focus-on");
-          }
           ringLabel.textContent = label;
           ringLabel.style.opacity = "1";
-          const capColor = st.color || st.labelColor || st.textColor;
-          if (capColor) ringLabel.style.color = String(capColor);
-          else ringLabel.style.removeProperty("color");
+          // Measure the label's own natural width/height (its real
+          // rendered size, unchanged) before deciding where it fits.
           const lw = ringLabel.offsetWidth;
           const lh = ringLabel.offsetHeight;
           let labelLeft = left;
           let labelTop = top + height + 8;
-          if (labelTop + lh > vh - margin) labelTop = top - lh - 8;
+          if (labelTop + lh > vh - margin) labelTop = top - lh - 8; // flip above if it'd overflow the bottom
           if (labelTop < margin) labelTop = margin;
           if (labelLeft + lw > vw - margin) labelLeft = Math.max(margin, vw - margin - lw);
           if (labelLeft < margin) labelLeft = margin;
           ringLabel.style.left = labelLeft + "px";
           ringLabel.style.top = labelTop + "px";
         };
-        window.__wgHideFocusVeil = () => {
-          const veil = document.getElementById("wg-focus-veil");
-          if (veil) veil.classList.remove("wg-focus-on");
-        };
-        window.__wgStartHighlightTrack = (opts) => {
-          if (window.__wgStopHighlightTrack) window.__wgStopHighlightTrack();
-          const sel = opts.sel;
-          const label = opts.label;
-          const tone = opts.tone || "planned";
-          const size = opts.size || "md";
-          const weight = opts.weight || "normal";
-          const focus = !!opts.focus;
-          const color = opts.color || "";
-          const zoom = opts.zoom != null && opts.zoom > 1 ? opts.zoom : 1;
-          const camMs = opts.camMs != null ? opts.camMs : 700;
-          const style = { size, weight, focus, color };
-          // Auto-center only. Never chase the host mouse (that fights the
-          // camera). Playwright's real mouse is driven separately by the CLI.
-          window.__wgIgnoreHostMouse = true;
-          const tick = () => {
-            const el = document.querySelector(sel);
-            if (el && window.__wgPositionRing) {
-              const r = el.getBoundingClientRect();
-              window.__wgPositionRing(
-                { x: r.left, y: r.top, width: r.width, height: r.height },
-                label,
-                tone,
-                style,
-              );
-            }
-            window.__wgRingRaf = requestAnimationFrame(tick);
-          };
-          if (zoom > 1 && window.__wgSetCamera) {
-            const el0 = document.querySelector(sel);
-            if (el0) {
-              const already =
-                window.__wgCamera && window.__wgCamera.scale > 1.001;
-              const dur = already ? Math.min(camMs, 420) : camMs;
-              const pt = window.__wgElDocPoint
-                ? window.__wgElDocPoint(el0)
-                : {
-                    x: el0.getBoundingClientRect().left + el0.getBoundingClientRect().width / 2,
-                    y: el0.getBoundingClientRect().top + el0.getBoundingClientRect().height / 2,
-                  };
-              // Lock for the whole ring - host mouse cannot steer.
-              window.__wgCameraLock = true;
-              window.__wgSetCamera(pt.x, pt.y, zoom, dur);
-            }
-          }
-          window.__wgRingRaf = requestAnimationFrame(tick);
-          // Do NOT listen to host mousemove - it was steering the camera.
-          window.__wgRingTrack = null;
-          window.__wgStopHighlightTrack = () => {
-            if (window.__wgRingRaf) {
-              cancelAnimationFrame(window.__wgRingRaf);
-              window.__wgRingRaf = null;
-            }
-            window.__wgStopHighlightTrack = null;
-          };
-        };
         window.__wgClickPulse = (x, y, tone) => {
           const pulse = document.getElementById("wg-click-pulse");
           if (!pulse) return;
@@ -878,124 +783,31 @@ async function installOverlay(page, title) {
           const ringLabel = document.getElementById("wg-ring-label");
           if (ring) ring.style.opacity = "0";
           if (ringLabel) ringLabel.style.opacity = "0";
-          if (window.__wgHideFocusVeil) window.__wgHideFocusVeil();
-          // Do NOT clear camera zoom here - zoomOut:false keeps scale between
-          // rings; only resetCameraZoom / teardown call __wgClearZoom.
-        };
-        // Screen Studio-style camera: scale <body>, keep overlays on <html> fixed.
-        // Focus (cx,cy) is DOCUMENT space (pre-transform). Viewport mouse/rects
-        // must go through __wgViewportToDoc before SetCamera.
-        window.__wgCamera = {
-          scale: 1,
-          cx: window.innerWidth / 2,
-          cy: window.innerHeight / 2,
-        };
-        window.__wgCameraLock = false;
-        window.__wgViewportToDoc = (vx, vy) => {
-          const cam = window.__wgCamera || {
-            scale: 1,
-            cx: window.innerWidth / 2,
-            cy: window.innerHeight / 2,
-          };
-          const s = cam.scale > 1.001 ? cam.scale : 1;
-          if (s <= 1.001) return { x: vx, y: vy };
-          return {
-            x: (vx - window.innerWidth / 2) / s + cam.cx,
-            y: (vy - window.innerHeight / 2) / s + cam.cy,
-          };
-        };
-        window.__wgElDocPoint = (el) => {
-          const r = el.getBoundingClientRect();
-          return window.__wgViewportToDoc(
-            r.left + r.width / 2,
-            r.top + r.height / 2,
-          );
-        };
-        window.__wgSetCamera = (fx, fy, scale, ms) => {
-          const body = document.body;
-          if (!body) return;
-          const s = Math.max(1, Math.min(Number(scale) || 1, 2.75));
-          const vw = window.innerWidth;
-          const vh = window.innerHeight;
-          window.__wgCamera = { scale: s, cx: fx, cy: fy };
-          const dur = ms != null && Number(ms) >= 0 ? Number(ms) : 650;
-          body.style.transition =
-            dur <= 0
-              ? "none"
-              : "transform " + dur / 1000 + "s cubic-bezier(.22,1,.36,1)";
-          body.style.transformOrigin = "0 0";
-          if (s <= 1.001) {
-            body.style.transform = "";
-            return;
-          }
-          // One transform: scale AND bring focus to viewport center.
-          body.style.transform =
-            "translate(" + vw / 2 + "px," + vh / 2 + "px) scale(" + s + ") translate(" + -fx + "px," + -fy + "px)";
-        };
-        window.__wgSetTodos = (todos) => {
-          let modal = document.getElementById("wg-todo-modal");
-          if (!todos || !todos.length) {
-            if (modal) {
-              modal.classList.remove("wg-todo-on");
-              modal.innerHTML = "";
-            }
-            return;
-          }
-          if (!modal) {
-            modal = document.createElement("div");
-            modal.id = "wg-todo-modal";
-            document.documentElement.appendChild(modal);
-          }
-          const esc = (s) =>
-            String(s)
-              .replace(/&/g, "&amp;")
-              .replace(/</g, "&lt;")
-              .replace(/>/g, "&gt;");
-          const rows = todos
-            .map((t) => {
-              const cls = t.current
-                ? "wg-todo-current"
-                : t.done
-                  ? "wg-todo-done"
-                  : "wg-todo-pending";
-              const mark = t.done
-                ? String.fromCharCode(0x2713)
-                : t.current
-                  ? String.fromCharCode(0x2192)
-                  : String.fromCharCode(0x25cb);
-              return (
-                '<li class="' +
-                cls +
-                '"><span class="wg-todo-mark">' +
-                mark +
-                '</span><span>' +
-                esc(t.text || "") +
-                '</span></li>'
-              );
-            })
-            .join("");
-          modal.innerHTML =
-            '<div class="wg-todo-head">Checklist</div><ul>' + rows + '</ul>';
-          modal.classList.add("wg-todo-on");
-        };
-        window.__wgResetCamera = () => {
-          window.__wgSetCamera(window.innerWidth / 2, window.innerHeight / 2, 1);
+          if (window.__wgClearZoom) window.__wgClearZoom();
         };
         window.__wgClearZoom = () => {
-          if (window.__wgResetCamera) window.__wgResetCamera();
+          document.querySelectorAll("[data-wg-zoomed=\\"1\\"]").forEach((el) => {
+            el.style.removeProperty("transform");
+            el.style.removeProperty("transform-origin");
+            el.style.removeProperty("transition");
+            el.style.removeProperty("z-index");
+            el.style.removeProperty("position");
+            delete el.dataset.wgZoomed;
+          });
         };
-        window.__wgSetBannerTitle = (title) => {
-          const banner = document.getElementById("wg-banner");
-          if (!banner) return;
-          let textEl = null;
-          for (const sp of banner.querySelectorAll("span")) {
-            if (!sp.classList.contains("wg-banner-tag")) { textEl = sp; break; }
-          }
-          if (!textEl) {
-            textEl = document.createElement("span");
-            banner.appendChild(textEl);
-          }
-          textEl.textContent = String(title || "");
+        window.__wgApplyZoom = (sel, scale) => {
+          if (window.__wgClearZoom) window.__wgClearZoom();
+          const n = Number(scale);
+          if (!Number.isFinite(n) || n <= 1.001) return;
+          const el = document.querySelector(sel);
+          if (!el) return;
+          const st = getComputedStyle(el);
+          if (st.position === "static") el.style.position = "relative";
+          el.style.zIndex = "2147483645";
+          el.style.transition = "transform .35s ease";
+          el.style.transformOrigin = "center center";
+          el.style.transform = "scale(" + n + ")";
+          el.dataset.wgZoomed = "1";
         };
         const POSITIONS = ["left", "center", "right"];
         const applyPos = (el, pos) => {
@@ -1047,32 +859,82 @@ async function installOverlay(page, title) {
         }
         if (iconLink.href !== favicon) iconLink.href = favicon;
         // Hide/Show for #wg-panel - call after every panel.innerHTML refresh.
-        // Collapsed title shows "N / M · block" (compact progress). forceCollapsed
-        // is for auto-next navs / video - does not overwrite the user's Hide preference.
+        // Collapsed = "N / M · block" + Next (when not auto). Never pass
+        // forceCollapsed:false - omit so Hide/localStorage wins.
         window.__wgWirePanelChrome = (panel, storageKey, chromeTitle, opts) => {
           if (!panel) return;
           opts = opts || {};
-          if (!panel.querySelector(":scope > .wg-chrome")) {
-            const body = document.createElement("div");
-            body.className = "wg-body";
-            while (panel.firstChild) body.appendChild(panel.firstChild);
-            const chrome = document.createElement("div");
-            chrome.className = "wg-chrome";
-            const titleEl = document.createElement("span");
-            titleEl.className = "wg-chrome-title";
-            titleEl.textContent = chromeTitle || "waygraph demo";
-            const btn = document.createElement("button");
-            btn.type = "button";
-            btn.className = "wg-hide-btn";
-            btn.setAttribute("data-wg-toggle", "1");
-            btn.textContent = "Hide";
-            chrome.appendChild(titleEl);
-            chrome.appendChild(btn);
-            panel.appendChild(chrome);
-            panel.appendChild(body);
-          }
+          const ensureChrome = () => {
+            let chrome = panel.querySelector(":scope > .wg-chrome");
+            if (!chrome) {
+              const body = document.createElement("div");
+              body.className = "wg-body";
+              while (panel.firstChild) body.appendChild(panel.firstChild);
+              chrome = document.createElement("div");
+              chrome.className = "wg-chrome";
+              const titleEl = document.createElement("span");
+              titleEl.className = "wg-chrome-title";
+              titleEl.textContent = chromeTitle || "waygraph demo";
+              const actions = document.createElement("div");
+              actions.className = "wg-chrome-actions";
+              const nextBtn = document.createElement("button");
+              nextBtn.type = "button";
+              nextBtn.className = "wg-mini-next";
+              nextBtn.setAttribute("data-wg-mini-next", "1");
+              nextBtn.textContent = "Next \u25B6";
+              const btn = document.createElement("button");
+              btn.type = "button";
+              btn.className = "wg-hide-btn";
+              btn.setAttribute("data-wg-toggle", "1");
+              btn.textContent = "Hide";
+              actions.appendChild(nextBtn);
+              actions.appendChild(btn);
+              chrome.appendChild(titleEl);
+              chrome.appendChild(actions);
+              panel.appendChild(chrome);
+              panel.appendChild(body);
+              return;
+            }
+            // Yap slides ship a bare chrome - ensure actions + mini Next exist.
+            let actions = chrome.querySelector(".wg-chrome-actions");
+            if (!actions) {
+              actions = document.createElement("div");
+              actions.className = "wg-chrome-actions";
+              const hide = chrome.querySelector("[data-wg-toggle]");
+              if (hide) actions.appendChild(hide);
+              chrome.appendChild(actions);
+            }
+            if (!actions.querySelector("[data-wg-mini-next]")) {
+              const nextBtn = document.createElement("button");
+              nextBtn.type = "button";
+              nextBtn.className = "wg-mini-next";
+              nextBtn.setAttribute("data-wg-mini-next", "1");
+              nextBtn.textContent = "Next \u25B6";
+              actions.insertBefore(nextBtn, actions.firstChild);
+            }
+          };
+          ensureChrome();
           const stepLabel = opts.stepLabel || panel.dataset.wgStepLabel || "";
           if (stepLabel) panel.dataset.wgStepLabel = stepLabel;
+          const syncMiniNext = (hidden) => {
+            const miniNext = panel.querySelector("[data-wg-mini-next]");
+            if (!miniNext) return;
+            let auto = false;
+            try {
+              auto = localStorage.getItem("wg-autoplay") === "1";
+            } catch {
+              /* ignore */
+            }
+            const runBtn = document.getElementById("wg-run");
+            const show = !!hidden && !auto && !!runBtn;
+            miniNext.classList.toggle("wg-mini-next-show", show);
+            if (runBtn) {
+              miniNext.textContent = runBtn.textContent || "Next \u25B6";
+              miniNext.disabled = !!runBtn.disabled;
+            } else {
+              miniNext.disabled = true;
+            }
+          };
           const apply = (hidden, persist) => {
             panel.classList.toggle("wg-collapsed", hidden);
             const t = panel.querySelector("[data-wg-toggle]");
@@ -1084,6 +946,7 @@ async function installOverlay(page, title) {
                 : (chromeTitle || "waygraph demo");
             }
             if (t) t.textContent = hidden ? "Show" : "Hide";
+            syncMiniNext(hidden);
             if (persist !== false) {
               try {
                 localStorage.setItem(storageKey, hidden ? "1" : "0");
@@ -1095,8 +958,6 @@ async function installOverlay(page, title) {
           let hidden = false;
           if (opts.forceCollapsed === true) {
             hidden = true;
-          } else if (opts.forceCollapsed === false) {
-            hidden = false;
           } else {
             try {
               hidden = localStorage.getItem(storageKey) === "1";
@@ -1104,6 +965,7 @@ async function installOverlay(page, title) {
               /* ignore */
             }
           }
+          // force mini does not overwrite Hide preference in storage.
           apply(hidden, opts.forceCollapsed === true ? false : true);
           const toggle = panel.querySelector("[data-wg-toggle]");
           if (toggle && !toggle.dataset.wgWired) {
@@ -1113,6 +975,26 @@ async function installOverlay(page, title) {
               apply(!panel.classList.contains("wg-collapsed"), true);
             });
           }
+          const miniNext = panel.querySelector("[data-wg-mini-next]");
+          if (miniNext && !miniNext.dataset.wgWired) {
+            miniNext.dataset.wgWired = "1";
+            miniNext.addEventListener("click", (e) => {
+              e.stopPropagation();
+              const runBtn = document.getElementById("wg-run");
+              if (runBtn && !runBtn.disabled) {
+                runBtn.click();
+                return;
+              }
+              if (typeof window.__wgNext === "function") window.__wgNext({});
+            });
+          }
+          const autoCb = document.getElementById("wg-autoplay-cb");
+          if (autoCb && !autoCb.dataset.wgMiniWired) {
+            autoCb.dataset.wgMiniWired = "1";
+            autoCb.addEventListener("change", () => {
+              syncMiniNext(panel.classList.contains("wg-collapsed"));
+            });
+          }
           const cur = panel.querySelector("#wg-modules .wg-mod-current");
           if (cur && typeof cur.scrollIntoView === "function") {
             try {
@@ -1167,7 +1049,7 @@ async function renderBeforeStep(page, info) {
       // active, the episode 2 tab is inactive"). Absent entirely for an ad
       // hoc block chain with no named Flows.
       const episodesHtml = info.allEpisodes && info.allEpisodes.length > 0
-        ? "<div id=\\\"wg-episodes\\\">" +
+        ? "<div id=\\"wg-episodes\\">" +
           info.allEpisodes
             .map((e) => {
               const cls = e.episodeNumber < info.episodeNumber ? "wg-ep-done"
@@ -1178,7 +1060,7 @@ async function renderBeforeStep(page, info) {
               const enteredCls = info.justEnteredEpisode && e.episodeNumber === info.episodeNumber
                 ? " wg-ep-entered"
                 : "";
-              return "<span class=\\\"wg-ep-tab " + cls + enteredCls + "\\\">Episode " + e.episodeNumber + ": " +
+              return "<span class=\\"wg-ep-tab " + cls + enteredCls + "\\">Episode " + e.episodeNumber + ": " +
                 esc(e.episodeTitle || "") + "</span>";
             })
             .join("") +
@@ -1194,66 +1076,40 @@ async function renderBeforeStep(page, info) {
         .map((name, idx) => {
           const cls = idx < info.moduleIndex ? "wg-mod-done" : idx === info.moduleIndex ? "wg-mod-current" : "wg-mod-upcoming";
           const desc = info.allDescriptions && info.allDescriptions[idx];
-          const titleAttr = desc ? " title=\\\"" + esc(desc) + "\\\"" : "";
-          return "<span class=\\\"wg-mod " + cls + "\\\"" + titleAttr + ">" + name + "</span>";
+          const titleAttr = desc ? " title=\\"" + esc(desc) + "\\"" : "";
+          return "<span class=\\"wg-mod " + cls + "\\"" + titleAttr + ">" + name + "</span>";
         })
         .join("");
       const narrationHtml = info.description
-        ? "<div class=\\\"wg-narration\\\">" + esc(info.description) + "</div>"
+        ? "<div class=\\"wg-narration\\">" + esc(info.description) + "</div>"
         : "";
       const paceHtml =
         info.paceBadge || info.paceLabel
-          ? "<div class=\\\"wg-pace\\\" data-pace-kind=\\\"" +
+          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
             esc(info.paceKind || "normal") +
-            "\\\"><span class=\\\"wg-pace-badge\\\">" +
+            "\\"><span class=\\"wg-pace-badge\\">" +
             esc(info.paceBadge || "1x") +
             "</span><span>" +
             esc(info.paceLabel || "") +
             "</span></div>"
           : "";
       let html =
-        "<div id=\\\"wg-progress\\\"><div id=\\\"wg-progress-bar\\\" style=\\\"width:" + pct + "%\\\"></div></div>" +
+        "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
         paceHtml +
-        "<div id=\\\"wg-modules\\\" class=\\\"" + modulesClass + "\\\">" + modulesHtml + "</div>" +
+        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
         narrationHtml +
-        ((() => {
-          const list = info.todos || [];
-          if (!list.length) return "";
-          return (
-            '<ul id="wg-todos">' +
-            list
-              .map((t) => {
-                const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
-                const mark = t.done
-                  ? String.fromCharCode(0x2713)
-                  : t.current
-                    ? String.fromCharCode(0x2192)
-                    : String.fromCharCode(0x25cb);
-                return (
-                  '<li class="' +
-                  cls +
-                  '"><span class="wg-todo-mark">' +
-                  mark +
-                  '</span><span>' +
-                  esc(t.text || "") +
-                  '</span></li>'
-                );
-              })
-              .join("") +
-            '</ul>'
-          );
-        })());
+        todosHtmlFromInfo(info, esc);
       if (info.keys.length === 0) {
-        html += "<div class=\\\"wg-key\\\">(no MemKeys required)</div>";
+        html += "<div class=\\"wg-key\\">(no MemKeys required)</div>";
       }
       for (const k of info.keys) {
         html +=
-          "<div class=\\\"wg-key\\\"><label>" + k.name + "</label>" +
-          "<textarea data-key=\\\"" + k.name + "\\\" rows=\\\"2\\\">" +
+          "<div class=\\"wg-key\\"><label>" + k.name + "</label>" +
+          "<textarea data-key=\\"" + k.name + "\\" rows=\\"2\\">" +
           k.value.replace(/</g, "&lt;") + "</textarea>" +
-          "<div class=\\\"wg-key-pretty\\\" data-pretty-for=\\\"" + esc(k.name) + "\\\"></div>" +
+          "<div class=\\"wg-key-pretty\\" data-pretty-for=\\"" + esc(k.name) + "\\"></div>" +
           "</div>";
       }
       let autoNow = false;
@@ -1263,12 +1119,12 @@ async function renderBeforeStep(page, info) {
         /* private mode / blocked storage - defaults to manual */
       }
       html +=
-        "<div class=\\\"wg-autoplay-row\\\"><label><input type=\\\"checkbox\\\" id=\\\"wg-autoplay-cb\\\"" +
+        "<div class=\\"wg-autoplay-row\\"><label><input type=\\"checkbox\\" id=\\"wg-autoplay-cb\\"" +
         (autoNow ? " checked" : "") +
         "> Auto-advance</label></div>" +
-        "<div id=\\\"wg-gate-manual\\\"" + (autoNow ? " style=\\\"display:none\\\"" : "") +
-        "><button id=\\\"wg-run\\\">Run this step \\u25B6</button></div>" +
-        "<div id=\\\"wg-gate-auto\\\" class=\\\"wg-auto\\\"" + (autoNow ? "" : " style=\\\"display:none\\\"") +
+        "<div id=\\"wg-gate-manual\\"" + (autoNow ? " style=\\"display:none\\"" : "") +
+        "><button id=\\"wg-run\\">Run this step \\u25B6</button></div>" +
+        "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" + (autoNow ? "" : " style=\\"display:none\\"") +
         ">Auto-advancing...</div>";
       panel.innerHTML = html;
       if (isNewPanel) {
@@ -1278,7 +1134,7 @@ async function renderBeforeStep(page, info) {
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
           stepLabel: miniStepLabel(info),
-          forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
+          forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
       // Live, human-readable preview of what a MemKey's raw JSON will
@@ -1301,7 +1157,7 @@ async function renderBeforeStep(page, info) {
         return Object.entries(parsed)
           .map(([field, value]) => {
             const label = field.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/^./, (c) => c.toUpperCase());
-            return "<div class=\\\"wg-key-pretty-row\\\"><span class=\\\"wg-key-pretty-label\\\">" +
+            return "<div class=\\"wg-key-pretty-row\\"><span class=\\"wg-key-pretty-label\\">" +
               esc(label) + ":</span> " + esc(String(value)) + "</div>";
           })
           .join("");
@@ -1310,7 +1166,7 @@ async function renderBeforeStep(page, info) {
         const prettyOn = window.__wgPretty !== false;
         panel.querySelectorAll("textarea[data-key]").forEach((ta) => {
           const key = ta.getAttribute("data-key");
-          const previewEl = panel.querySelector(".wg-key-pretty[data-pretty-for=\\\"" + key + "\\\"]");
+          const previewEl = panel.querySelector(".wg-key-pretty[data-pretty-for=\\"" + key + "\\"]");
           if (!previewEl) return;
           previewEl.style.display = prettyOn ? "" : "none";
           if (prettyOn) previewEl.innerHTML = prettyMemValue(ta.value);
@@ -1356,25 +1212,6 @@ async function renderBeforeStep(page, info) {
 
 async function ensureSelectorInView(page, selector) {
   try {
-    // Body-scale camera + scrollIntoView = teleport / "outside viewport" loop.
-    // When zoomed, pan the camera to the target instead of scrolling the document.
-    const zoomed = await page
-      .evaluate(() => !!(window.__wgCamera && window.__wgCamera.scale > 1.001))
-      .catch(() => false);
-    if (zoomed) {
-      await page
-        .evaluate((sel) => {
-          const el = document.querySelector(sel);
-          if (!el || !window.__wgSetCamera || !window.__wgElDocPoint) return;
-          const cam = window.__wgCamera;
-          const pt = window.__wgElDocPoint(el);
-          window.__wgCameraLock = true;
-          window.__wgSetCamera(pt.x, pt.y, cam.scale > 1 ? cam.scale : 1.4, 320);
-        }, selector)
-        .catch(() => {});
-      await new Promise((res) => setTimeout(res, 340));
-      return;
-    }
     const loc = page.locator(selector).first();
     await loc.scrollIntoViewIfNeeded().catch(() => {});
     await page
@@ -1441,54 +1278,48 @@ async function ensureSelectorInView(page, selector) {
   }
 }
 
-async function applyCameraZoom(page, box, zoom, ms) {
-  const z = zoom != null && Number(zoom) > 1 ? Number(zoom) : 1;
-  if (!box || z <= 1) {
+async function applyHighlightZoom(page, selector, zoom) {
+  const z = Number(zoom);
+  if (!Number.isFinite(z) || z <= 1.001) {
     await page.evaluate(() => {
-      if (window.__wgResetCamera) window.__wgResetCamera();
+      if (window.__wgClearZoom) window.__wgClearZoom();
     }).catch(() => {});
     return;
   }
-  const vx = box.x + box.width / 2;
-  const vy = box.y + box.height / 2;
-  const dur = ms != null ? ms : 650;
-  await page
-    .evaluate(({ vx, vy, scale, dur }) => {
-      if (!window.__wgSetCamera) return;
-      const pt = window.__wgViewportToDoc
-        ? window.__wgViewportToDoc(vx, vy)
-        : { x: vx, y: vy };
-      window.__wgSetCamera(pt.x, pt.y, scale, dur);
-    }, { vx, vy, scale: z, dur })
-    .catch(() => {});
-}
-
-async function setDemoTodos(page, todos) {
-  await page
-    .evaluate((list) => {
-      if (window.__wgSetTodos) window.__wgSetTodos(list || []);
-    }, todos && todos.length ? todos : [])
-    .catch(() => {});
-}
-
-async function resetCameraZoom(page) {
   await page
-    .evaluate(() => {
-      if (window.__wgResetCamera) window.__wgResetCamera();
-    })
+    .evaluate(
+      ({ sel, scale }) => {
+        if (window.__wgApplyZoom) window.__wgApplyZoom(sel, scale);
+      },
+      { sel: selector, scale: z },
+    )
     .catch(() => {});
 }
 
-async function setDemoBannerTitle(page, title) {
-  if (title == null || title === "") return;
-  await page
-    .evaluate((t) => {
-      if (window.__wgSetBannerTitle) window.__wgSetBannerTitle(t);
-    }, String(title))
-    .catch(() => {});
+function todosHtmlFromInfo(info, escFn) {
+  const list = info.todos || [];
+  if (!list.length) return "";
+  return (
+    "<ul id=\\"wg-todos\\">" +
+    list
+      .map((t) => {
+        const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
+        const mark = t.done ? "\\u2713" : t.current ? "\\u2192" : "\\u25CB";
+        return (
+          "<li class=\\"" +
+          cls +
+          "\\"><span class=\\"wg-todo-mark\\">" +
+          mark +
+          "</span><span>" +
+          escFn(t.text || "") +
+          "</span></li>"
+        );
+      })
+      .join("") +
+    "</ul>"
+  );
 }
 
-/** Collapsed chrome title: Ep N / i / n / block / pace. */
 function miniStepLabel(info) {
   const ep =
     info.episodeNumber !== undefined && info.episodeNumber !== null
@@ -1506,174 +1337,94 @@ function miniStepLabel(info) {
 
 async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   const list = highlights || [];
+  // defaultHoldMs: when set (fail path), use instead of legacy 900/200 so BUG
+  // rings stay visible ~2s before the error panel (PIA stubOnError RFC).
   const defaultHoldMs = opts && opts.defaultHoldMs != null ? opts.defaultHoldMs : null;
   const pace = opts && opts.pace !== undefined ? opts.pace : undefined;
-  const fadeMs = 320;
-  const n = list.length;
-  const baseStepLabel = (opts && opts.stepLabel) || "";
-
-  const updateHlProgress = async (i) => {
-    if (n <= 0) return;
-    const tag = "[" + (i + 1) + "/" + n + "]";
-    await page
-      .evaluate(
-        ({ tag, baseStepLabel, i, n }) => {
-          const panel = document.getElementById("wg-panel");
-          if (!panel) return;
-          panel.dataset.wgHlIdx = String(i + 1);
-          panel.dataset.wgHlN = String(n);
-          const titleEl = panel.querySelector(".wg-chrome-title");
-          if (titleEl) {
-            const base = panel.dataset.wgStepLabel || baseStepLabel || "waygraph demo";
-            if (panel.classList.contains("wg-collapsed")) {
-              titleEl.textContent = base + " " + tag;
-            }
-          }
-          let span = document.getElementById("wg-hl-idx");
-          const h3 = panel.querySelector("h3");
-          if (h3) {
-            if (!span) {
-              span = document.createElement("span");
-              span.id = "wg-hl-idx";
-              span.style.marginLeft = "8px";
-              span.style.color = "#c9a6ff";
-              span.style.fontWeight = "700";
-              h3.appendChild(span);
-            }
-            span.textContent = tag;
-          }
-        },
-        { tag, baseStepLabel, i, n },
-      )
-      .catch(() => {});
-  };
-
-  const stopLiveFollow = async () => {
-    await page
-      .evaluate(() => {
-        if (window.__wgStopHighlightTrack) window.__wgStopHighlightTrack();
-        if (window.__wgRingRaf) {
-          cancelAnimationFrame(window.__wgRingRaf);
-          window.__wgRingRaf = null;
-        }
-        if (window.__wgRingTrack) {
-          window.removeEventListener("mousemove", window.__wgRingTrack);
-          window.removeEventListener("resize", window.__wgRingTrack);
-          window.removeEventListener("scroll", window.__wgRingTrack, true);
-          window.__wgRingTrack = null;
-        }
-        if (window.__wgHideFocusVeil) window.__wgHideFocusVeil();
-      })
-      .catch(() => {});
-  };
-
   for (let i = 0; i < list.length; i++) {
     const h = list[i];
     try {
-      await stopLiveFollow();
       await ensureSelectorInView(page, h.selector);
+      await applyHighlightZoom(page, h.selector, h.zoom);
       const box = await page.locator(h.selector).first().boundingBox();
-      if (!box) continue;
-      await updateHlProgress(i);
-      if (opts && opts.todos && opts.todos.length) {
-        const rows = opts.todos.map((t, ti) => ({
-          text: t.text,
-          done: ti < i,
-          current: ti === i,
-        }));
-        await setDemoTodos(page, rows);
-      } else if (h.todos && h.todos.length) {
-        await setDemoTodos(page, normalizeTodos(h.todos, h.todoIndex));
-      }
-      const z = h.zoom != null && Number(h.zoom) > 1 ? Number(h.zoom) : 1;
-      const camMs = 700;
-      // Camera auto-centers on the ring target. Host mouse never steers.
-      await page
-        .evaluate(
-          ({ sel, label, tone, size, weight, focus, color, zoom, camMs }) => {
-            if (window.__wgStartHighlightTrack) {
-              window.__wgStartHighlightTrack({
-                sel,
-                label,
-                tone,
-                size,
-                weight,
-                focus,
-                color,
-                zoom,
-                camMs,
-              });
-            }
-          },
-          {
-            sel: h.selector,
-            label: h.label,
-            tone: h.tone || "planned",
-            size: h.size || "md",
-            weight: h.weight || "normal",
-            focus: !!h.focus,
-            color: h.color || h.labelColor || h.textColor || "",
-            zoom: z,
-            camMs,
-          },
-        )
-        .catch(() => {});
-      const alreadyZoomed = await page
-        .evaluate(() => !!(window.__wgCamera && window.__wgCamera.scale > 1.001))
-        .catch(() => false);
-      const waitMs = alreadyZoomed ? Math.min(camMs, 420) : camMs;
-      await new Promise((res) => setTimeout(res, waitMs));
-      if (h.cursor !== false) {
-        // Park Playwright real mouse + demo cursor on the LIVE centered target.
-        const live = await page
-          .evaluate((sel) => {
-            const el = document.querySelector(sel);
-            if (!el) return null;
-            const r = el.getBoundingClientRect();
-            return { x: r.left, y: r.top, width: r.width, height: r.height };
-          }, h.selector)
-          .catch(() => null);
-        if (live) {
-          await moveCursorTo(page, live, Math.min(280, camMs), { keepLock: true });
+      if (box) {
+        await showRing(page, box, h.label, h.tone || "planned", {
+          size: h.size,
+          weight: h.weight,
+        });
+        if ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length)) {
+          const rows =
+            opts && opts.todos && opts.todos.length
+              ? opts.todos
+              : normalizeTodos(h.todos, h.todoIndex);
+          await page
+            .evaluate((todos) => {
+              const ul = document.getElementById("wg-todos");
+              if (!ul) return;
+              ul.innerHTML = todos
+                .map((t) => {
+                  const cls = t.current
+                    ? "wg-todo-current"
+                    : t.done
+                      ? "wg-todo-done"
+                      : "wg-todo-pending";
+                  const mark = t.done ? "\\u2713" : t.current ? "\\u2192" : "\\u25CB";
+                  const esc = (s) =>
+                    String(s)
+                      .replace(/&/g, "&amp;")
+                      .replace(/</g, "&lt;")
+                      .replace(/>/g, "&gt;");
+                  return (
+                    "<li class=\\"" +
+                    cls +
+                    "\\"><span class=\\"wg-todo-mark\\">" +
+                    mark +
+                    "</span><span>" +
+                    esc(t.text || "") +
+                    "</span></li>"
+                  );
+                })
+                .join("");
+            }, rows)
+            .catch(() => {});
         }
+        const authored = resolveFixtureDwellMs(h, { gatesFast, pace });
+        const legacyMs = i === list.length - 1 ? 200 : 900;
+        const holdMs =
+          authored != null ? authored : defaultHoldMs != null ? defaultHoldMs : legacyMs;
+        await new Promise((res) => setTimeout(res, holdMs));
       }
-      // Appear settle
-      await new Promise((res) => setTimeout(res, fadeMs));
-      const authored = resolveFixtureDwellMs(h, { gatesFast, pace });
-      const legacyMs = 1100;
-      const holdMs =
-        authored != null ? authored : defaultHoldMs != null ? defaultHoldMs : legacyMs;
-      await new Promise((res) => setTimeout(res, holdMs));
-      // Disappear before next. zoomOut:false keeps camera for the next ring.
-      await stopLiveFollow();
-      await hideRing(page);
-      const doZoomOut = h.zoomOut !== false;
-      if (doZoomOut) await resetCameraZoom(page);
-      await new Promise((res) => setTimeout(res, doZoomOut ? fadeMs : 120));
     } catch {
-      /* best-effort */
+      // best-effort - a selector that doesn't resolve just gets skipped
     }
   }
-  await stopLiveFollow();
-  // Keep camera if the last ring (or phase default) asked zoomOut:false.
-  const last = list.length > 0 ? list[list.length - 1] : null;
-  if (!last || last.zoomOut !== false) {
-    await resetCameraZoom(page);
-  } else {
-    // Hold lock into the upcoming act click so follow/scroll cannot yank
-    // the camera off the already-centered target (cart teleport bug).
+  if (list.length > 0) {
+    const last = list[list.length - 1];
     await page
-      .evaluate(() => {
-        window.__wgCameraLock = true;
-      })
+      .evaluate((h) => {
+        if (!window.__wgPositionRing) return;
+        const reposition = () => {
+          const el = document.querySelector(h.selector);
+          if (!el) {
+            if (window.__wgHideRing) window.__wgHideRing();
+            return;
+          }
+          window.__wgPositionRing(el.getBoundingClientRect(), h.label, h.tone || "planned", {
+            size: h.size || "md",
+            weight: h.weight || "normal",
+          });
+        };
+        reposition();
+        window.__wgRingTrack = reposition;
+        window.addEventListener("resize", reposition);
+        window.addEventListener("scroll", reposition, true);
+      }, last)
       .catch(() => {});
-  }
-  if (list.length === 0) {
+  } else {
     await hideRing(page);
   }
 }
 
-
 async function renderAfterStep(page, info) {
   await installOverlay(page, info.title);
   // Clear any tracker from a previous highlight before cycling through this
@@ -1717,8 +1468,8 @@ async function renderAfterStep(page, info) {
         .map((name, idx) => {
           const cls = idx <= info.moduleIndex ? "wg-mod-done" : "wg-mod-upcoming";
           const desc = info.allDescriptions && info.allDescriptions[idx];
-          const titleAttr = desc ? " title=\\\"" + escA(desc) + "\\\"" : "";
-          return "<span class=\\\"wg-mod " + cls + "\\\"" + titleAttr + ">" + name + "</span>";
+          const titleAttr = desc ? " title=\\"" + escA(desc) + "\\"" : "";
+          return "<span class=\\"wg-mod " + cls + "\\"" + titleAttr + ">" + name + "</span>";
         })
         .join("");
       // QA-friendly by default ("LoginSuccess" -> "Login Success") - raw
@@ -1729,13 +1480,13 @@ async function renderAfterStep(page, info) {
         .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2") || info.resultTag;
       const pretty = window.__wgPretty !== false;
       const resultHtml =
-        "<div class=\\\"wg-toggle\\\">" +
-        "<button class=\\\"wg-toggle-btn" + (pretty ? " wg-active" : "") + "\\\" data-mode=\\\"pretty\\\">Pretty</button>" +
-        "<button class=\\\"wg-toggle-btn" + (pretty ? "" : " wg-active") + "\\\" data-mode=\\\"json\\\">JSON</button>" +
+        "<div class=\\"wg-toggle\\">" +
+        "<button class=\\"wg-toggle-btn" + (pretty ? " wg-active" : "") + "\\" data-mode=\\"pretty\\">Pretty</button>" +
+        "<button class=\\"wg-toggle-btn" + (pretty ? "" : " wg-active") + "\\" data-mode=\\"json\\">JSON</button>" +
         "</div>" +
-        "<div class=\\\"wg-result wg-result-pretty\\\" style=\\\"display:" + (pretty ? "block" : "none") + "\\\">" +
+        "<div class=\\"wg-result wg-result-pretty\\" style=\\"display:" + (pretty ? "block" : "none") + "\\">" +
         prettyText + "</div>" +
-        "<div class=\\\"wg-result wg-result-json\\\" style=\\\"display:" + (pretty ? "none" : "block") + "\\\">" +
+        "<div class=\\"wg-result wg-result-json\\" style=\\"display:" + (pretty ? "none" : "block") + "\\">" +
         info.resultTag + "</div>";
       let autoNow = false;
       try {
@@ -1744,21 +1495,21 @@ async function renderAfterStep(page, info) {
         /* private mode / blocked storage - defaults to manual */
       }
       const gateHtml =
-        "<div class=\\\"wg-autoplay-row\\\"><label><input type=\\\"checkbox\\\" id=\\\"wg-autoplay-cb\\\"" +
+        "<div class=\\"wg-autoplay-row\\"><label><input type=\\"checkbox\\" id=\\"wg-autoplay-cb\\"" +
         (autoNow ? " checked" : "") +
         "> Auto-advance</label></div>" +
-        "<div id=\\\"wg-gate-manual\\\"" + (autoNow ? " style=\\\"display:none\\\"" : "") +
-        "><button id=\\\"wg-run\\\">" + buttonLabel + "</button></div>" +
-        "<div id=\\\"wg-gate-auto\\\" class=\\\"wg-auto\\\"" + (autoNow ? "" : " style=\\\"display:none\\\"") +
+        "<div id=\\"wg-gate-manual\\"" + (autoNow ? " style=\\"display:none\\"" : "") +
+        "><button id=\\"wg-run\\">" + buttonLabel + "</button></div>" +
+        "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" + (autoNow ? "" : " style=\\"display:none\\"") +
         ">Auto-advancing...</div>";
       const episodesHtml = info.allEpisodes && info.allEpisodes.length > 0
-        ? "<div id=\\\"wg-episodes\\\">" +
+        ? "<div id=\\"wg-episodes\\">" +
           info.allEpisodes
             .map((e) => {
               const cls = e.episodeNumber < info.episodeNumber ? "wg-ep-done"
                 : e.episodeNumber === info.episodeNumber ? "wg-ep-current"
                 : "wg-ep-upcoming";
-              return "<span class=\\\"wg-ep-tab " + cls + "\\\">Episode " + e.episodeNumber + ": " +
+              return "<span class=\\"wg-ep-tab " + cls + "\\">Episode " + e.episodeNumber + ": " +
                 escA(e.episodeTitle || "") + "</span>";
             })
             .join("") +
@@ -1766,47 +1517,21 @@ async function renderAfterStep(page, info) {
         : "";
       const paceHtml =
         info.paceBadge || info.paceLabel
-          ? "<div class=\\\"wg-pace\\\" data-pace-kind=\\\"" +
+          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
             escA(info.paceKind || "normal") +
-            "\\\"><span class=\\\"wg-pace-badge\\\">" +
+            "\\"><span class=\\"wg-pace-badge\\">" +
             escA(info.paceBadge || "1x") +
             "</span><span>" +
             escA(info.paceLabel || "") +
             "</span></div>"
           : "";
       panel.innerHTML =
-        "<div id=\\\"wg-progress\\\"><div id=\\\"wg-progress-bar\\\" style=\\\"width:" + pct + "%\\\"></div></div>" +
+        "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
         paceHtml +
-        "<div id=\\\"wg-modules\\\" class=\\\"" + modulesClass + "\\\">" + modulesHtml + "</div>" +
+        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
-        ((() => {
-          const list = info.todos || [];
-          if (!list.length) return "";
-          return (
-            '<ul id="wg-todos">' +
-            list
-              .map((t) => {
-                const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
-                const mark = t.done
-                  ? String.fromCharCode(0x2713)
-                  : t.current
-                    ? String.fromCharCode(0x2192)
-                    : String.fromCharCode(0x25cb);
-                return (
-                  '<li class="' +
-                  cls +
-                  '"><span class="wg-todo-mark">' +
-                  mark +
-                  '</span><span>' +
-                  escA(t.text || "") +
-                  '</span></li>'
-                );
-              })
-              .join("") +
-            '</ul>'
-          );
-        })()) +
+        todosHtmlFromInfo(info, escA) +
         resultHtml +
         gateHtml;
       if (isNewPanel) {
@@ -1816,7 +1541,7 @@ async function renderAfterStep(page, info) {
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
           stepLabel: miniStepLabel(info),
-          forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
+          forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
       panel.querySelectorAll(".wg-toggle-btn").forEach((btn) => {
@@ -1873,13 +1598,13 @@ async function renderStepError(page, info) {
       if (!isNewPanel) panel.classList.add("wg-in");
       const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
       const episodesHtml = info.allEpisodes && info.allEpisodes.length > 0
-        ? "<div id=\\\"wg-episodes\\\">" +
+        ? "<div id=\\"wg-episodes\\">" +
           info.allEpisodes
             .map((e) => {
               const cls = e.episodeNumber < info.episodeNumber ? "wg-ep-done"
                 : e.episodeNumber === info.episodeNumber ? "wg-ep-current"
                 : "wg-ep-upcoming";
-              return "<span class=\\\"wg-ep-tab " + cls + "\\\">Episode " + e.episodeNumber + ": " +
+              return "<span class=\\"wg-ep-tab " + cls + "\\">Episode " + e.episodeNumber + ": " +
                 esc(e.episodeTitle || "") + "</span>";
             })
             .join("") +
@@ -1890,8 +1615,8 @@ async function renderStepError(page, info) {
         .map((name, idx) => {
           const cls = idx === info.moduleIndex ? "wg-mod-current" : idx < info.moduleIndex ? "wg-mod-done" : "wg-mod-upcoming";
           const desc = info.allDescriptions && info.allDescriptions[idx];
-          const titleAttr = desc ? " title=\\\"" + esc(desc) + "\\\"" : "";
-          return "<span class=\\\"wg-mod " + cls + "\\\"" + titleAttr + ">" + name + "</span>";
+          const titleAttr = desc ? " title=\\"" + esc(desc) + "\\"" : "";
+          return "<span class=\\"wg-mod " + cls + "\\"" + titleAttr + ">" + name + "</span>";
         })
         .join("");
       const retryLabel = info.episodeNumber !== undefined ? "Retry Episode " + info.episodeNumber : "Retry";
@@ -1899,17 +1624,17 @@ async function renderStepError(page, info) {
         ? "Expected outcome - Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " failed as intended"
         : "Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " threw";
       const reasonHtml = isExpected
-        ? "<div class=\\\"wg-expected-reason\\\">" + esc(info.expectedFailureReason) + "</div>"
+        ? "<div class=\\"wg-expected-reason\\">" + esc(info.expectedFailureReason) + "</div>"
         : "";
       panel.innerHTML =
         episodesHtml +
-        "<div id=\\\"wg-modules\\\" class=\\\"" + modulesClass + "\\\">" + modulesHtml + "</div>" +
-        "<h3 class=\\\"" + (isExpected ? "wg-expected-heading" : "wg-error-heading") + "\\\">" + headingText + "</h3>" +
+        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
+        "<h3 class=\\"" + (isExpected ? "wg-expected-heading" : "wg-error-heading") + "\\">" + headingText + "</h3>" +
         reasonHtml +
-        "<div class=\\\"wg-error-msg\\\">" + esc(info.message) + "</div>" +
-        "<div class=\\\"wg-error-actions\\\">" +
-        "<button id=\\\"wg-error-retry\\\" class=\\\"wg-error-retry\\\">" + esc(retryLabel) + "</button>" +
-        "<button id=\\\"wg-run\\\" class=\\\"wg-error-stop\\\">Stop</button>" +
+        "<div class=\\"wg-error-msg\\">" + esc(info.message) + "</div>" +
+        "<div class=\\"wg-error-actions\\">" +
+        "<button id=\\"wg-error-retry\\" class=\\"wg-error-retry\\">" + esc(retryLabel) + "</button>" +
+        "<button id=\\"wg-run\\" class=\\"wg-error-stop\\">Stop</button>" +
         "</div>";
       if (isNewPanel) {
         document.documentElement.appendChild(panel);
@@ -1918,7 +1643,7 @@ async function renderStepError(page, info) {
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
           stepLabel: miniStepLabel(info),
-          forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
+          forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
       const runBtn = document.getElementById("wg-run");
@@ -2041,6 +1766,11 @@ async function markStepRunning(page, _opts) {
         const titleEl = panel.querySelector(".wg-chrome-title");
         const label = panel.dataset.wgStepLabel;
         if (titleEl && label) titleEl.textContent = label;
+        const miniNext = panel.querySelector("[data-wg-mini-next]");
+        if (miniNext) {
+          miniNext.disabled = true;
+          miniNext.classList.remove("wg-mini-next-show");
+        }
       }
     })
     .catch(() => {});
@@ -2049,16 +1779,14 @@ async function markStepRunning(page, _opts) {
 async function showRing(page, box, label, tone, style) {
   const size = normalizeHighlightSize(style && style.size);
   const weight = normalizeHighlightWeight(style && style.weight);
-  const focus = !!(style && style.focus);
-  const color = (style && (style.color || style.labelColor || style.textColor)) || "";
   await page
     .evaluate(
-      ({ box, label, tone, size, weight, focus, color }) => {
+      ({ box, label, tone, size, weight }) => {
         if (window.__wgPositionRing) {
-          window.__wgPositionRing(box, label, tone || "planned", { size, weight, focus, color });
+          window.__wgPositionRing(box, label, tone || "planned", { size, weight });
         }
       },
-      { box, label, tone: tone || "planned", size, weight, focus, color },
+      { box, label, tone: tone || "planned", size, weight },
     )
     .catch(() => {});
 }
@@ -2148,10 +1876,7 @@ async function presentSlides(page, slides, _gate, opts) {
     if (s.selector) {
       try {
         await ensureSelectorInView(page, s.selector);
-        {
-          const zb = await page.locator(s.selector).first().boundingBox().catch(() => null);
-          await applyCameraZoom(page, zb, s.zoom);
-        }
+        await applyHighlightZoom(page, s.selector, s.zoom);
         const box = await page.locator(s.selector).first().boundingBox();
         if (box) await showRing(page, box, caption, slideTone, slideStyle);
       } catch {
@@ -2168,30 +1893,32 @@ async function presentSlides(page, slides, _gate, opts) {
           panel = document.createElement("div");
           panel.id = "wg-panel";
         }
-        panel.classList.remove("wg-collapsed", "wg-error", "wg-expected");
+        panel.classList.remove("wg-error", "wg-expected");
+        // Do not clear wg-collapsed - WirePanelChrome honors Hide (localStorage)
+        // unless forceCollapsed:true (--mini / --video).
         const esc = (t) =>
           String(t).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
         const episodeLine =
           info.episodeNumber !== undefined && info.episodeNumber !== null
-            ? "<div class=\\\"wg-episode\\\">Episode " +
+            ? "<div class=\\"wg-episode\\">Episode " +
               info.episodeNumber +
               (info.episodeTitle ? ": " + esc(info.episodeTitle) : "") +
               " · yap slides</div>"
             : "";
         const paceHtml =
           info.paceBadge || info.paceLabel
-            ? "<div class=\\\"wg-pace\\\" data-pace-kind=\\\"" +
+            ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
               esc(info.paceKind || "normal") +
-              "\\\"><span class=\\\"wg-pace-badge\\\">" +
+              "\\"><span class=\\"wg-pace-badge\\">" +
               esc(info.paceBadge || "1x") +
               "</span><span>" +
               esc(info.paceLabel || "") +
               "</span></div>"
             : "";
         panel.innerHTML =
-          "<div class=\\\"wg-chrome\\\"><span class=\\\"wg-chrome-title\\\">waygraph demo</span>" +
-          "<button type=\\\"button\\\" class=\\\"wg-hide-btn\\\" data-wg-toggle=\\\"1\\\">Hide</button></div>" +
-          "<div class=\\\"wg-body\\\">" +
+          "<div class=\\"wg-chrome\\"><span class=\\"wg-chrome-title\\">waygraph demo</span>" +
+          "<button type=\\"button\\" class=\\"wg-hide-btn\\" data-wg-toggle=\\"1\\">Hide</button></div>" +
+          "<div class=\\"wg-body\\">" +
           episodeLine +
           paceHtml +
           "<h3>Slide " +
@@ -2201,35 +1928,35 @@ async function presentSlides(page, slides, _gate, opts) {
           (info.blockName ? " · " + esc(info.blockName) : "") +
           "</h3>" +
           (info.tag
-            ? "<div style=\\\"border:none;padding:0;margin:0 0 6px;font-size:11px;color:#c9a6ff\\\">" +
+            ? "<div style=\\"border:none;padding:0;margin:0 0 6px;font-size:11px;color:#c9a6ff\\">" +
               esc(info.tag) +
               "</div>"
             : "") +
-          "<div class=\\\"wg-narration\\\">" +
+          "<div class=\\"wg-narration\\">" +
           esc(info.caption) +
           "</div>" +
           (info.detail
-            ? "<div class=\\\"wg-result-pretty\\\" style=\\\"margin:0 0 12px;color:#f0e8ff\\\">" +
+            ? "<div class=\\"wg-result-pretty\\" style=\\"margin:0 0 12px;color:#f0e8ff\\">" +
               esc(info.detail) +
               "</div>"
             : "") +
           (info.dwellMs != null
-            ? "<div class=\\\"wg-auto\\\" id=\\\"wg-dwell-hint\\\" style=\\\"margin:0 0 8px\\\">Hold " +
+            ? "<div class=\\"wg-auto\\" id=\\"wg-dwell-hint\\" style=\\"margin:0 0 8px\\">Hold " +
               (info.dwellMs / 1000).toFixed(1) +
               "s before next...</div>"
             : "") +
-          "<div class=\\\"wg-autoplay-row\\\"><label><input type=\\\"checkbox\\\" id=\\\"wg-autoplay-cb\\\"" +
+          "<div class=\\"wg-autoplay-row\\"><label><input type=\\"checkbox\\" id=\\"wg-autoplay-cb\\"" +
           (info.autoNow ? " checked" : "") +
           "> Auto-advance</label></div>" +
-          "<div id=\\\"wg-gate-manual\\\"" +
-          (info.autoNow ? " style=\\\"display:none\\\"" : "") +
-          "><button type=\\\"button\\\" id=\\\"wg-run\\\"" +
+          "<div id=\\"wg-gate-manual\\"" +
+          (info.autoNow ? " style=\\"display:none\\"" : "") +
+          "><button type=\\"button\\" id=\\"wg-run\\"" +
           (info.dwellMs != null ? " disabled" : "") +
           ">" +
           (info.isLast ? "Continue \\u25B6" : "Next slide \\u25B6") +
           "</button></div>" +
-          "<div id=\\\"wg-gate-auto\\\" class=\\\"wg-auto\\\"" +
-          (info.autoNow ? "" : " style=\\\"display:none\\\"") +
+          "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" +
+          (info.autoNow ? "" : " style=\\"display:none\\"") +
           ">Auto-advancing...</div>" +
           "</div>";
         if (isNew) {
@@ -2247,7 +1974,8 @@ async function presentSlides(page, slides, _gate, opts) {
               " / " +
               info.total +
               (info.blockName ? " \\u00b7 " + info.blockName : ""),
-            forceCollapsed: false,
+            // Video / --mini: compact pill. Else omit so Hide sticks.
+            forceCollapsed: info.forceCollapsed === true ? true : undefined,
           });
         }
         let autoNow = false;
@@ -2317,6 +2045,12 @@ async function presentSlides(page, slides, _gate, opts) {
         paceBadge: formatDemoPaceBadge(demoPace, baseAutoplay),
         paceLabel: formatDemoPaceLabel(demoPace, baseAutoplay),
         paceKind: demoPaceKind(demoPace),
+        forceCollapsed:
+          !!process.env.WAYGRAPH_VIDEO ||
+          process.env.WAYGRAPH_MINI === "1" ||
+          process.env.WAYGRAPH_STEPPER_MINI === "1"
+            ? true
+            : undefined,
       },
     );
     const started = Date.now();
@@ -2394,8 +2128,7 @@ async function teardownOverlay(page) {
         window.__wgRingTrack = null;
       }
       window.__wgNarrateOwnsRing = false;
-      if (window.__wgClearZoom) window.__wgClearZoom();
-      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner", "wg-todo-modal", "wg-focus-veil"]) {
+      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner"]) {
         const el = document.getElementById(id);
         if (el) el.remove();
       }
@@ -2403,53 +2136,24 @@ async function teardownOverlay(page) {
     .catch(() => {});
 }
 
-async function moveCursorTo(page, box, ms, opts) {
+async function moveCursorTo(page, box, ms) {
   const x = box.x + box.width / 2;
   const y = box.y + box.height / 2;
   const travel = Math.max(0, Number(ms) || 0);
-  const keepLock = !!(opts && opts.keepLock);
-  // Camera stays locked; demo cursor + Playwright real mouse move together.
-  // Host OS mouse is ignored (no mousemove camera steer).
   await page
     .evaluate(({ x, y, ms }) => {
-      window.__wgCameraLock = true;
-      window.__wgIgnoreHostMouse = true;
       if (window.__wgMoveCursorTo) window.__wgMoveCursorTo(x, y, ms);
     }, { x, y, ms: travel })
     .catch(() => {});
-  try {
-    if (travel > 0) {
-      const steps = Math.max(1, Math.min(30, Math.round(travel / 20)));
-      await page.mouse.move(x, y, { steps });
-    } else {
-      await page.mouse.move(x, y);
-    }
-  } catch {
-    /* headed / detached - demo cursor still moved */
-  }
+  // CSS transition is async - wait the full travel so the cursor is ON the
+  // target before ring/pulse/real click (NavBlock click nav was skipping
+  // this and looked like a teleport).
   if (travel > 0) {
-    await new Promise((res) => setTimeout(res, Math.min(80, travel)));
-  }
-  if (!keepLock) {
-    await page
-      .evaluate(() => {
-        window.__wgCameraLock = false;
-      })
-      .catch(() => {});
+    await new Promise((res) => setTimeout(res, travel));
   }
   return { x, y };
 }
 
-/** Live viewport center of a locator (after camera transform) - no scroll. */
-async function liveCenterOf(locator) {
-  return locator
-    .evaluate((el) => {
-      const r = el.getBoundingClientRect();
-      return { x: r.left + r.width / 2, y: r.top + r.height / 2, w: r.width, h: r.height };
-    })
-    .catch(() => null);
-}
-
 async function clickPulseAt(page, x, y, tone) {
   await page
     .evaluate(({ x, y, tone }) => {
@@ -2574,47 +2278,17 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
     proto.click = async function (options) {
       let clickPoint = null;
       let clickTone = "auto";
-      let keptCameraLock = false;
       try {
         await installOverlay(page);
+        // Wait until the target is visible BEFORE measuring - otherwise
+        // defineNavBlock({ click }) (and any slow-to-appear control) skips
+        // the cursor entirely: boundingBox was null, then originalClick
+        // waited and clicked with no demo animation.
         await this.waitFor({
           state: "visible",
           timeout: (options && options.timeout) || 30000,
         }).catch(() => {});
-        const zoomed = await page
-          .evaluate(() => !!(window.__wgCamera && window.__wgCamera.scale > 1.001))
-          .catch(() => false);
-        if (zoomed) {
-          // Re-auto-center on this target, then lock - no host mouse, no scroll.
-          await page
-            .evaluate(() => {
-              window.__wgCameraLock = true;
-              window.__wgIgnoreHostMouse = true;
-            })
-            .catch(() => {});
-          keptCameraLock = true;
-          const handle = await this.elementHandle().catch(() => null);
-          if (handle) {
-            await page
-              .evaluate(
-                (el) => {
-                  if (!el || !window.__wgSetCamera || !window.__wgElDocPoint) return;
-                  const cam = window.__wgCamera || { scale: 1.4 };
-                  const pt = window.__wgElDocPoint(el);
-                  const s = cam.scale > 1.001 ? cam.scale : 1.4;
-                  window.__wgSetCamera(pt.x, pt.y, s, 280);
-                },
-                handle,
-              )
-              .catch(() => {});
-            await handle.dispose().catch(() => {});
-            await new Promise((res) => setTimeout(res, 300));
-          }
-        }
-        const live = await liveCenterOf(this);
-        const box = live
-          ? { x: live.x - live.w / 2, y: live.y - live.h / 2, width: live.w, height: live.h }
-          : await this.boundingBox();
+        const box = await this.boundingBox();
         const narrated = box ? await wasJustNarrated(page) : false;
         if (box && !narrated) {
           let fallback = "click";
@@ -2622,8 +2296,10 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
             const text = (await this.textContent())?.trim();
             if (text && text.length > 0 && text.length <= 30) fallback = text;
           } catch {
-            /* ignore */
+            // element has no simple text (an icon button, say) - generic label is fine
           }
+          // Prefer "nav: …" when this locator is a NavBlock click target
+          // (set on page by runStepMode just before act).
           try {
             const navLabel = await page.evaluate(() => window.__wgPendingNavClickLabel || null);
             if (navLabel) fallback = String(navLabel);
@@ -2633,80 +2309,39 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
           const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
           const cap = await captionForLocator(page, this, stubs, fallback);
           clickTone = cap.tone;
-          const travel = zoomed ? cursorMs(200) : cursorMs(600);
-          const again = (await liveCenterOf(this)) || live;
-          const aim = again
-            ? { x: again.x - again.w / 2, y: again.y - again.h / 2, width: again.w, height: again.h }
-            : box;
-          clickPoint = await moveCursorTo(page, aim, travel, { keepLock: zoomed });
-          const liveBox = aim;
-          clickPoint = {
-            x: liveBox.x + liveBox.width / 2,
-            y: liveBox.y + liveBox.height / 2,
-          };
-          await showRing(page, liveBox, cap.label, cap.tone, {
+          clickPoint = await moveCursorTo(page, box, cursorMs(600));
+          await showRing(page, box, cap.label, cap.tone, {
             size: cap.size,
             weight: cap.weight,
           });
           await dwellMatchedStub(page, this, stubs, pacing);
+          // "pop for a few seconds" - Dan's own phrase, matching the
+          // zsign demo-engine's ring-before-click pattern in
+          // services/help-center-clip-engine's video-pipeline.
           await new Promise((res) => setTimeout(res, clickPrePop()));
         } else if (box) {
-          const travel = zoomed ? cursorMs(120) : cursorMs(200);
-          clickPoint = await moveCursorTo(page, box, travel, { keepLock: zoomed });
+          // Ring/caption already handled by narrate() - still move the
+          // cursor + pulse the click point, just skip re-showing the ring.
+          clickPoint = await moveCursorTo(page, box, cursorMs(200));
           clickTone = "planned";
         }
       } catch {
-        /* best-effort */
+        // best-effort - the real click below still runs either way
       }
       if (clickPoint) {
         await clickPulseAt(page, clickPoint.x, clickPoint.y, clickTone);
+        // clickPulseAt only triggers the CSS animation class - it doesn't
+        // wait for it. Without a pause here, the real click (and any
+        // resulting navigation/DOM change) fires while the ripple is still
+        // mid-animation, sometimes cutting it off before it's even visible.
+        // Wait out the same .5s the "@keyframes wg-pulse" rule uses, so the
+        // mock click visually completes before the real one fires.
         await new Promise((res) => setTimeout(res, skipTheater() ? 0 : 500));
       }
-      const zoomedClick = await page
-        .evaluate(() => !!(window.__wgCamera && window.__wgCamera.scale > 1.001))
-        .catch(() => false);
-      try {
-        let result;
-        if (zoomedClick || keptCameraLock) {
-          // Real Playwright mouse at live visual center - never scrollIntoView.
-          const pt =
-            clickPoint ||
-            (await liveCenterOf(this)) ||
-            null;
-          if (pt && Number.isFinite(pt.x) && Number.isFinite(pt.y)) {
-            await page.mouse.click(pt.x, pt.y);
-            result = undefined;
-          } else {
-            const handle = await this.elementHandle().catch(() => null);
-            if (handle) {
-              await handle.evaluate((el) => {
-                if (el && typeof el.click === "function") el.click();
-              });
-              await handle.dispose().catch(() => {});
-              result = undefined;
-            } else {
-              result = await originalClick.call(this, {
-                ...(options || {}),
-                force: true,
-                timeout: (options && options.timeout) || 5000,
-              });
-            }
-          }
-        } else {
-          result = await originalClick.call(this, options);
-        }
-        await new Promise((res) => setTimeout(res, clickPostPop()));
-        await hideRing(page);
-        return result;
-      } finally {
-        if (keptCameraLock) {
-          await page
-            .evaluate(() => {
-              window.__wgCameraLock = false;
-            })
-            .catch(() => {});
-        }
-      }
+      const result = await originalClick.call(this, options);
+      await new Promise((res) => setTimeout(res, clickPostPop()));
+      await hideRing(page);
+      return result;
     };
   }
 
@@ -3020,10 +2655,13 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     const stubBeforeTodos = stubBeforePhase.todos || [];
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
-    // Video recording: keep chrome compact. Live auto-next used to force-collapse
-    // every NavBlock and hid the stepper (todos / modules) - only collapse while
-    // act() runs (markStepRunning) so Playwright clicks hit the page, not the panel.
-    const forceCollapsed = !!process.env.WAYGRAPH_VIDEO;
+    // Video / --mini: compact pill. Never pass false - Hide/localStorage wins.
+    const forceCollapsed =
+      !!process.env.WAYGRAPH_VIDEO ||
+      process.env.WAYGRAPH_MINI === "1" ||
+      process.env.WAYGRAPH_STEPPER_MINI === "1"
+        ? true
+        : undefined;
     const requires = r.block.requires ?? [];
     const keys = requires.map((k) => {
       let value = "<not yet set>";
@@ -3067,7 +2705,6 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       todos: stubBeforeTodos,
       ...paceSpeak,
     });
-    await setDemoTodos(page, stubBeforeTodos);
     const edits = await gate();
     for (const k of requires) {
       if (edits[k.name] !== undefined) {
@@ -3079,40 +2716,6 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       }
     }
     const recordingVideo = !!process.env.WAYGRAPH_VIDEO;
-    // Sequential stubBefore queue (appear -> dwell -> fade) before act.
-    if (stubBeforeRef.current && stubBeforeRef.current.length) {
-      await setDemoBannerTitle(page, stubBeforePhase.title);
-      const beforeRings = stubBeforeRef.current.map((h) => {
-        const styled = applyHighlightStyleDefaults(h, flowStyle);
-        return {
-          selector: styled.selector,
-          label: formatHighlightCaption(styled),
-          duration: styled.duration,
-          fastMode: styled.fastMode,
-          tone: styled.tone,
-          size: styled.size,
-          weight: styled.weight,
-          zoom: styled.zoom,
-          focus: styled.focus,
-          color: styled.color,
-          cursor: styled.cursor,
-          zoomOut: styled.zoomOut,
-        };
-      });
-      await cycleHighlightRings(page, beforeRings, !!pacing.gatesFast, {
-        pace: pacing.demoPace,
-        todos: stubBeforeTodos,
-        stepLabel: miniStepLabel({
-          index: i,
-          total: resolved.length,
-          blockName: r.block.name,
-          episodeNumber: r.episodeNumber,
-          paceBadge: paceSpeak.paceBadge,
-        }),
-      });
-    } else if (stubBeforePhase && stubBeforePhase.title) {
-      await setDemoBannerTitle(page, stubBeforePhase.title);
-    }
     await markStepRunning(page, {});
     // NavBlock click-nav: label the upcoming Locator.click demo cursor as
     // "nav: <block>" so pia/demo watchers see cursor+pulse on click nav
@@ -3162,7 +2765,6 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           fixtures: fixturesOnError,
           error: err,
         });
-        await setDemoBannerTitle(page, errPhase.title);
         const errHighlights = errPhase.highlights.map((h) => {
           const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
           return {
@@ -3174,10 +2776,6 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
             size: styled.size,
             weight: styled.weight,
             zoom: styled.zoom,
-            focus: styled.focus,
-            color: styled.color,
-            cursor: styled.cursor,
-            zoomOut: styled.zoomOut,
           };
         });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
@@ -3204,7 +2802,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         episodeTitle: r.episodeTitle,
         expectedFailureReason: r.expectedFailureReason,
         stepperMode,
-        forceCollapsed: false,
+        // Omit forceCollapsed on errors so Hide is not stomped.
       });
       const errEdits = await gate();
       if (errEdits && errEdits.__wgRetry) {
@@ -3256,8 +2854,6 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         fixtures: fixturesAfter,
       });
       stubAfterTodos = afterPhase.todos || [];
-      await setDemoBannerTitle(page, afterPhase.title);
-      await setDemoTodos(page, afterPhase.todos || []);
       highlights = afterPhase.highlights.map((h) => {
         const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
         return {
@@ -3269,10 +2865,6 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           size: styled.size,
           weight: styled.weight,
           zoom: styled.zoom,
-          focus: styled.focus,
-          color: styled.color,
-          cursor: styled.cursor,
-          zoomOut: styled.zoomOut,
         };
       });
     } else {
@@ -3300,7 +2892,12 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeTitle: r.episodeTitle,
       stepperMode,
       todos: stubAfterTodos,
-      forceCollapsed: !!process.env.WAYGRAPH_VIDEO,
+      forceCollapsed:
+        !!process.env.WAYGRAPH_VIDEO ||
+        process.env.WAYGRAPH_MINI === "1" ||
+        process.env.WAYGRAPH_STEPPER_MINI === "1"
+          ? true
+          : undefined,
     });
     await gate();
   }
@@ -4315,6 +3912,9 @@ function parseRunFlags(argv) {
         else if (a === "--full") {
             out.fullStepper = true;
         }
+        else if (a === "--mini" || a === "--stepper-mini") {
+            out.miniStepper = true;
+        }
         else if (a === "--ff-expand") {
             out.ffExpand = true;
         }
@@ -4435,8 +4035,8 @@ function applyRunFlags(flags, opts) {
             process.env.WAYGRAPH_HEADED = "0";
         }
     }
-    if ((flags.fast || flags.fullStepper) && !opts?.allowDemoUi) {
-        console.error("waygraph: --fast / --full are demo-only flags");
+    if ((flags.fast || flags.fullStepper || flags.miniStepper) && !opts?.allowDemoUi) {
+        console.error("waygraph: --fast / --full / --mini are demo-only flags");
         process.exit(1);
     }
     if (flags.step === true) {
@@ -4480,6 +4080,9 @@ function applyRunFlags(flags, opts) {
     if (flags.fullStepper) {
         process.env.WAYGRAPH_STEPPER = "full";
     }
+    if (flags.miniStepper) {
+        process.env.WAYGRAPH_MINI = "1";
+    }
     if (flags.ffExpand) {
         process.env.WAYGRAPH_FF_EXPAND = "1";
     }
@@ -4644,6 +4247,7 @@ Primary (less is more):
                  --auto-next               Auto-advance steps (alias: --autoplay)
                  --fast                    Shorter auto-next / Next gates (keeps smooth cursor)
                  --full                    Classic wrap-all block chips (default: carousel)
+                 --mini                    Force compact mini panel (Hide pill + Next); alias --stepper-mini
                  --ff-expand               Expand fastForwardComposeBlock inners as separate steps
                  --ff-disabled             Dispute: expand FF (alias --no-ff); blitz kept on those inners
                  --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless by default
@@ -5038,7 +4642,7 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                 console.error("waygraph demo: missing flow/spec — e.g.\n" +
                     "  waygraph demo src/flows/shop.flow.ts\n" +
                     "  waygraph demo --blocks shopFlow\n" +
-                    "  Flags: --blocks --data --auto-next --fast --full --ff-expand --ff-disabled --auto-play-video --title --base-url --video");
+                    "  Flags: --blocks --data --auto-next --fast --full --mini --ff-expand --ff-disabled --auto-play-video --title --base-url --video");
                 process.exit(1);
             }
             const proj = flags.blocks