waygraph 0.12.39 → 0.12.41

package/dist/cli.d.ts

@@ -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

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
@@ -808,59 +808,11 @@ async function installOverlay(page, title) {
           const focus = !!opts.focus;
           const color = opts.color || "";
           const zoom = opts.zoom != null && opts.zoom > 1 ? opts.zoom : 1;
-          const followMouse = opts.followMouse !== false && zoom > 1;
           const camMs = opts.camMs != null ? opts.camMs : 700;
-          let settled = zoom <= 1;
-          const settleAt = Date.now() + camMs;
           const style = { size, weight, focus, color };
-          // Screen Studio / Screenify: dead zone follow (see followTick).
-          const deadFrac = 0.5;
-          let lastPanAt = 0;
-          const readCursorViewport = () => {
-            const cursor = document.getElementById("wg-cursor");
-            if (cursor && cursor.style.opacity !== "0") {
-              const r = cursor.getBoundingClientRect();
-              if (r.width || r.height || r.left || r.top) {
-                return { x: r.left, y: r.top };
-              }
-            }
-            if (window.__wgCursorPos) return window.__wgCursorPos;
-            return null;
-          };
-          const followTick = () => {
-            if (!followMouse || !settled || window.__wgCameraLock) return;
-            if (!window.__wgSetCamera || !window.__wgViewportToDoc) return;
-            const cam = window.__wgCamera;
-            if (!cam || !(cam.scale > 1.001)) return;
-            // Skip while the demo cursor is mid CSS travel - reading a
-            // mid-lerp rect makes the camera chase noise and teleport.
-            if (window.__wgCursorTravelUntil && Date.now() < window.__wgCursorTravelUntil) {
-              return;
-            }
-            const pos = readCursorViewport();
-            if (!pos) return;
-            const vw = window.innerWidth;
-            const vh = window.innerHeight;
-            const dx = pos.x - vw / 2;
-            const dy = pos.y - vh / 2;
-            const deadX = (vw * deadFrac) / 2;
-            const deadY = (vh * deadFrac) / 2;
-            let ox = 0;
-            let oy = 0;
-            if (dx > deadX) ox = dx - deadX;
-            else if (dx < -deadX) ox = dx + deadX;
-            if (dy > deadY) oy = dy - deadY;
-            else if (dy < -deadY) oy = dy + deadY;
-            if (ox === 0 && oy === 0) return;
-            const now = Date.now();
-            if (now - lastPanAt < 120) return;
-            lastPanAt = now;
-            // Partial gain - never yank the full overflow in one pan.
-            const gain = 0.35;
-            const nx = cam.cx + (ox / cam.scale) * gain;
-            const ny = cam.cy + (oy / cam.scale) * gain;
-            window.__wgSetCamera(nx, ny, cam.scale, 280);
-          };
+          // 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) {
@@ -872,8 +824,6 @@ async function installOverlay(page, title) {
                 style,
               );
             }
-            if (!settled && Date.now() >= settleAt) settled = true;
-            followTick();
             window.__wgRingRaf = requestAnimationFrame(tick);
           };
           if (zoom > 1 && window.__wgSetCamera) {
@@ -882,41 +832,25 @@ async function installOverlay(page, title) {
               const already =
                 window.__wgCamera && window.__wgCamera.scale > 1.001;
               const dur = already ? Math.min(camMs, 420) : camMs;
-              // Focus must be document-space, not raw getBoundingClientRect
-              // (viewport) - otherwise already-zoomed pans fight the cursor.
               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);
-              // Unlock for dead-zone follow only when explicitly allowed.
-              // zoomOut:false / cart-edge targets stay locked through dwell+click.
-              if (followMouse && opts.allowFollow) {
-                setTimeout(() => {
-                  window.__wgCameraLock = false;
-                }, dur + 40);
-              }
             }
           }
           window.__wgRingRaf = requestAnimationFrame(tick);
-          // Real mouse only seeds cursor pos; dead-zone follow runs in RAF.
-          const onMove = (ev) => {
-            window.__wgCursorPos = { x: ev.clientX, y: ev.clientY };
-          };
-          window.addEventListener("mousemove", onMove, { passive: true });
-          window.__wgRingTrack = onMove;
+          // 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;
             }
-            if (window.__wgRingTrack) {
-              window.removeEventListener("mousemove", window.__wgRingTrack);
-              window.__wgRingTrack = null;
-            }
             window.__wgStopHighlightTrack = null;
           };
         };
@@ -1113,8 +1047,9 @@ 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 title shows "N / M · block" (compact progress).
+        // forceCollapsed:true = force mini (--mini / --video). Omit otherwise so
+        // the user's Hide preference (localStorage) wins. Never pass false.
         window.__wgWirePanelChrome = (panel, storageKey, chromeTitle, opts) => {
           if (!panel) return;
           opts = opts || {};
@@ -1161,8 +1096,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";
@@ -1170,6 +1103,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) {
@@ -1211,6 +1145,8 @@ async function renderBeforeStep(page, info) {
       if (window.__wgHideCursor) window.__wgHideCursor();
     })
     .catch(() => {});
+  // miniStepLabel is Node-only — compute before evaluate (browser has no closure).
+  const payload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
       // Reused in place, not removed + recreated, every step - the old
@@ -1343,8 +1279,8 @@ 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,
+          stepLabel: info.stepLabel || "",
+          forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
       // Live, human-readable preview of what a MemKey's raw JSON will
@@ -1416,7 +1352,7 @@ async function renderBeforeStep(page, info) {
           if (auto) auto.style.display = cb.checked ? "" : "none";
         });
       }
-    }, info)
+    }, payload)
     .catch(() => {});
 }
 
@@ -1653,18 +1589,10 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
       }
       const z = h.zoom != null && Number(h.zoom) > 1 ? Number(h.zoom) : 1;
       const camMs = 700;
-      const followMouse =
-        h.followMouse !== undefined
-          ? !!h.followMouse
-          : h.follow !== undefined
-            ? !!h.follow
-            : z > 1;
-      // Track/zoom first, then park the demo cursor on the LIVE rect.
-      // Placing the cursor on a pre-zoom boundingBox leaves it stranded after
-      // body scale (html cursor is outside the transform).
+      // Camera auto-centers on the ring target. Host mouse never steers.
       await page
         .evaluate(
-          ({ sel, label, tone, size, weight, focus, color, zoom, followMouse, camMs, allowFollow }) => {
+          ({ sel, label, tone, size, weight, focus, color, zoom, camMs }) => {
             if (window.__wgStartHighlightTrack) {
               window.__wgStartHighlightTrack({
                 sel,
@@ -1675,9 +1603,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
                 focus,
                 color,
                 zoom,
-                followMouse,
                 camMs,
-                allowFollow,
               });
             }
           },
@@ -1690,11 +1616,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
             focus: !!h.focus,
             color: h.color || h.labelColor || h.textColor || "",
             zoom: z,
-            followMouse,
             camMs,
-            // Follow only while zoomed-out-between-rings is OK. zoomOut:false
-            // means hold the frame for the upcoming click - no chase.
-            allowFollow: followMouse && h.zoomOut !== false,
           },
         )
         .catch(() => {});
@@ -1704,19 +1626,18 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
       const waitMs = alreadyZoomed ? Math.min(camMs, 420) : camMs;
       await new Promise((res) => setTimeout(res, waitMs));
       if (h.cursor !== false) {
-        await page
-          .evaluate(({ sel, ms }) => {
+        // Park Playwright real mouse + demo cursor on the LIVE centered target.
+        const live = await page
+          .evaluate((sel) => {
             const el = document.querySelector(sel);
-            if (!el || !window.__wgMoveCursorTo) return;
-            window.__wgCameraLock = true;
+            if (!el) return null;
             const r = el.getBoundingClientRect();
-            window.__wgMoveCursorTo(r.left + r.width / 2, r.top + r.height / 2, ms, false);
-            setTimeout(() => {
-              window.__wgCameraLock = false;
-            }, ms + 40);
-          }, { sel: h.selector, ms: Math.min(280, camMs) })
-          .catch(() => {});
-        await new Promise((res) => setTimeout(res, Math.min(280, camMs)));
+            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 });
+        }
       }
       // Appear settle
       await new Promise((res) => setTimeout(res, fadeMs));
@@ -1777,7 +1698,9 @@ async function renderAfterStep(page, info) {
   // 900ms / 200ms holds when set.
   await cycleHighlightRings(page, highlights, gatesFast, {
     pace: info.pace,
+    stepLabel: miniStepLabel(info),
   });
+  const afterPayload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
       // Reused in place - see renderBeforeStep's own comment on this.
@@ -1896,8 +1819,8 @@ 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,
+          stepLabel: info.stepLabel || "",
+          forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
       panel.querySelectorAll(".wg-toggle-btn").forEach((btn) => {
@@ -1926,7 +1849,7 @@ async function renderAfterStep(page, info) {
           if (auto) auto.style.display = cb.checked ? "" : "none";
         });
       }
-    }, info)
+    }, afterPayload)
     .catch(() => {});
 }
 
@@ -1938,6 +1861,7 @@ async function renderAfterStep(page, info) {
  */
 async function renderStepError(page, info) {
   await installOverlay(page, info.title);
+  const errorPayload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
       // Reused in place - see renderBeforeStep's own comment on this.
@@ -1998,15 +1922,15 @@ 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,
+          stepLabel: info.stepLabel || "",
+          forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
       const runBtn = document.getElementById("wg-run");
       if (runBtn) runBtn.addEventListener("click", () => window.__wgNext({}));
       const retryBtn = document.getElementById("wg-error-retry");
       if (retryBtn) retryBtn.addEventListener("click", () => window.__wgNext({ __wgRetry: "1" }));
-    }, info)
+    }, errorPayload)
     .catch(() => {});
 }
 
@@ -2249,7 +2173,9 @@ 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 here - 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 =
@@ -2328,7 +2254,8 @@ async function presentSlides(page, slides, _gate, opts) {
               " / " +
               info.total +
               (info.blockName ? " \\u00b7 " + info.blockName : ""),
-            forceCollapsed: false,
+            // Video / --mini stays on the mini stepper (Ep N · step · block pill).
+            forceCollapsed: info.forceCollapsed === true ? true : undefined,
           });
         }
         let autoNow = false;
@@ -2398,6 +2325,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();
@@ -2489,19 +2422,27 @@ async function moveCursorTo(page, box, ms, opts) {
   const y = box.y + box.height / 2;
   const travel = Math.max(0, Number(ms) || 0);
   const keepLock = !!(opts && opts.keepLock);
-  // Freeze camera follow while the demo cursor travels - otherwise dead-zone
-  // pans fight the click target (esp. right-edge cart chrome).
+  // 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(() => {});
-  // 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).
+  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 */
+  }
   if (travel > 0) {
-    await new Promise((res) => setTimeout(res, travel));
+    await new Promise((res) => setTimeout(res, Math.min(80, travel)));
   }
   if (!keepLock) {
     await page
@@ -2513,6 +2454,16 @@ async function moveCursorTo(page, box, ms, opts) {
   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 }) => {
@@ -2640,29 +2591,44 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
       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(() => {});
-        // Body-scale camera + Playwright scrollIntoView = teleport storm.
-        // Lock the camera for the whole click when zoomed; force-click so
-        // Playwright does not try to scroll the transformed page.
         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 box = await this.boundingBox();
+        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 narrated = box ? await wasJustNarrated(page) : false;
         if (box && !narrated) {
           let fallback = "click";
@@ -2670,10 +2636,8 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
             const text = (await this.textContent())?.trim();
             if (text && text.length > 0 && text.length <= 30) fallback = text;
           } catch {
-            // element has no simple text (an icon button, say) - generic label is fine
+            /* ignore */
           }
-          // 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);
@@ -2683,13 +2647,13 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
           const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
           const cap = await captionForLocator(page, this, stubs, fallback);
           clickTone = cap.tone;
-          // Already centered from stubBefore zoom: short cursor, keep lock.
-          const travel = zoomed ? cursorMs(160) : cursorMs(600);
-          clickPoint = await moveCursorTo(page, box, travel, {
-            keepLock: zoomed,
-          });
-          // Re-measure after cursor settle - stale pre-travel box teleports the ring.
-          const liveBox = (await this.boundingBox()) || box;
+          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,
@@ -2699,30 +2663,17 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
             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) {
-          // Ring/caption already handled by narrate() - still move the
-          // cursor + pulse the click point, just skip re-showing the ring.
           const travel = zoomed ? cursorMs(120) : cursorMs(200);
-          clickPoint = await moveCursorTo(page, box, travel, {
-            keepLock: zoomed,
-          });
+          clickPoint = await moveCursorTo(page, box, travel, { keepLock: zoomed });
           clickTone = "planned";
         }
       } catch {
-        // best-effort - the real click below still runs either way
+        /* best-effort */
       }
       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
@@ -2731,21 +2682,29 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
       try {
         let result;
         if (zoomedClick || keptCameraLock) {
-          // Playwright scrollIntoView + body-scale camera = "outside viewport"
-          // retry storm. Click the element in-page with no scrolling.
-          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(() => {});
+          // 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 {
-            result = await originalClick.call(this, {
-              ...(options || {}),
-              force: true,
-              timeout: (options && options.timeout) || 5000,
-            });
+            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);
@@ -3075,10 +3034,15 @@ 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 "Ep N · step · block" pill only.
+    // Otherwise omit (undefined) so Hide/localStorage is honored - never pass false.
+    // WAYGRAPH_STEPPER_MINI=1 remains a compat env alias for WAYGRAPH_MINI.
+    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>";
@@ -3259,7 +3223,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 preference is not stomped.
       });
       const errEdits = await gate();
       if (errEdits && errEdits.__wgRetry) {
@@ -3355,7 +3319,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();
   }
@@ -4370,6 +4339,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;
         }
@@ -4490,8 +4462,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) {
@@ -4535,6 +4507,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";
     }
@@ -4699,6 +4674,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); 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
@@ -5093,7 +5069,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

package/dist/highlights.d.ts

@@ -97,12 +97,11 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      */
     focus?: boolean;
     /**
-     * After camera zoom settles, pan with the real mouse pointer (Screen Studio).
-     * Default: on when `zoom` > 1. Set false to lock the camera on the target.
-     * Alias: `follow`.
+     * Deprecated no-op. Camera auto-centers on the ring target; host mouse is
+     * ignored. Playwright's real mouse is driven to the centered target instead.
      */
     followMouse?: boolean;
-    /** Alias for {@link WaygraphHighlightStub.followMouse}. */
+    /** Alias for {@link WaygraphHighlightStub.followMouse} (no-op). */
     follow?: boolean;
     /**
      * Caption text color (CSS color). Overrides tone label color when set.

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -49,7 +49,6 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
           color: "#c9a6ff",
           zoom: 1.45,
           zoomOut: false,
-          followMouse: true,
         },
         add: {
           selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
@@ -75,7 +74,6 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         color: "#86efac",
         zoom: 1.6,
         zoomOut: false,
-        followMouse: true,
         duration: true,
       });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.39",
+  "version": "0.12.41",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/quickstart/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -49,7 +49,6 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
           color: "#c9a6ff",
           zoom: 1.45,
           zoomOut: false,
-          followMouse: true,
         },
         add: {
           selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
@@ -75,7 +74,6 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         color: "#86efac",
         zoom: 1.6,
         zoomOut: false,
-        followMouse: true,
         duration: true,
       });
     },