waygraph 0.12.31 → 0.12.33

package/dist/cli.js

@@ -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]);
   }
@@ -413,19 +413,11 @@ 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,left .28s ease,top .28s ease,width .28s ease,height .28s ease,border-color .15s,box-shadow .32s ease;}" +
-  // Unquoted [data-focus=1]: this lives inside CHAIN_RUNNER_SCRIPT's template
-  // literal - a \" here would be eaten by the outer template and break the
-  // generated .mjs. CSS allows unquoted attr values for identifiers.
-  "#wg-ring[data-focus=1]{box-shadow:0 0 0 4px rgba(124,58,237,.2),0 0 0 9999px rgba(15,6,32,.55);}" +
-  "#wg-ring[data-tone=auto][data-focus=1]{box-shadow:0 0 0 4px rgba(156,163,175,.28),0 0 0 9999px rgba(15,6,32,.55);}" +
-  "#wg-ring[data-tone=info][data-focus=1]{box-shadow:0 0 0 4px rgba(59,130,246,.22),0 0 0 9999px rgba(15,6,32,.55);}" +
-  "#wg-ring[data-tone=warning][data-focus=1]{box-shadow:0 0 0 4px rgba(234,179,8,.22),0 0 0 9999px rgba(15,6,32,.55);}" +
-  "#wg-ring[data-tone=danger][data-focus=1]{box-shadow:0 0 0 4px rgba(239,68,68,.22),0 0 0 9999px rgba(15,6,32,.55);}" +
-  "#wg-ring[data-tone=success][data-focus=1]{box-shadow:0 0 0 4px rgba(34,197,94,.22),0 0 0 9999px rgba(15,6,32,.55);}" +
-  // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
-  // Automation (verify fallback, unmatched fill/click) = gray - operators
-  // can ignore engine checks and watch purple + semantic tones.
+  "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;}" +
   "#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);}" +
@@ -441,7 +433,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,left .28s ease,top .28s ease,background .15s,color .15s;}" +
+  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .32s 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;}" +
@@ -683,6 +675,11 @@ 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";
@@ -733,6 +730,7 @@ 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 =
@@ -757,8 +755,8 @@ async function installOverlay(page, title) {
           const vh = window.innerHeight;
           let left = box.x - pad;
           let top = box.y - pad;
-          const width = box.width + pad * 2;
-          const height = box.height + pad * 2;
+          const width = Math.max(0, box.width + pad * 2);
+          const height = Math.max(0, 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,24 +766,100 @@ 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; // flip above if it'd overflow the bottom
+          if (labelTop + lh > vh - margin) labelTop = top - lh - 8;
           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 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 };
+          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,
+              );
+            }
+            if (!settled && Date.now() >= settleAt) settled = true;
+            window.__wgRingRaf = requestAnimationFrame(tick);
+          };
+          if (zoom > 1 && window.__wgSetCamera) {
+            const el0 = document.querySelector(sel);
+            if (el0) {
+              const r0 = el0.getBoundingClientRect();
+              window.__wgSetCamera(
+                r0.left + r0.width / 2,
+                r0.top + r0.height / 2,
+                zoom,
+                camMs,
+              );
+            }
+          }
+          window.__wgRingRaf = requestAnimationFrame(tick);
+          const onMove = (ev) => {
+            if (!followMouse || !settled) return;
+            if (!window.__wgSetCamera) return;
+            const cam = window.__wgCamera;
+            const scale = (cam && cam.scale > 1 ? cam.scale : zoom) || zoom;
+            if (!(scale > 1)) return;
+            window.__wgSetCamera(ev.clientX, ev.clientY, scale, 140);
+          };
+          window.addEventListener("mousemove", onMove, { passive: true });
+          window.__wgRingTrack = onMove;
+          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;
+          };
+        };
         window.__wgClickPulse = (x, y, tone) => {
           const pulse = document.getElementById("wg-click-pulse");
           if (!pulse) return;
@@ -810,6 +884,7 @@ 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();
           if (window.__wgClearZoom) window.__wgClearZoom();
         };
         // Screen Studio-style camera: scale <body>, keep overlays on <html> fixed.
@@ -861,23 +936,27 @@ async function installOverlay(page, title) {
                 : t.done
                   ? "wg-todo-done"
                   : "wg-todo-pending";
-              const mark = t.done ? "\u2713" : t.current ? "\u2192" : "\u25CB";
+              const mark = t.done
+                ? String.fromCharCode(0x2713)
+                : t.current
+                  ? String.fromCharCode(0x2192)
+                  : String.fromCharCode(0x25cb);
               return (
-                "<li class=\"" +
+                '<li class="' +
                 cls +
-                "\"><span class=\"wg-todo-mark\">" +
+                '"><span class="wg-todo-mark">' +
                 mark +
-                "</span><span>" +
+                '</span><span>' +
                 esc(t.text || "") +
-                "</span></li>"
+                '</span></li>'
               );
             })
             .join("");
           modal.innerHTML =
-            "<div class=\"wg-todo-head\">Checklist</div><ul>" + rows + "</ul>";
+            '<div class="wg-todo-head">Checklist</div><ul>' + rows + '</ul>';
           modal.classList.add("wg-todo-on");
         };
-        window.__wgResetCamera = () => {
+window.__wgResetCamera = () => {
           window.__wgSetCamera(window.innerWidth / 2, window.innerHeight / 2, 1);
         };
         window.__wgClearZoom = () => {
@@ -1066,7 +1145,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"
@@ -1077,7 +1156,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("") +
@@ -1093,62 +1172,66 @@ 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\">" +
+            '<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";
+                const mark = t.done
+                  ? String.fromCharCode(0x2713)
+                  : t.current
+                    ? String.fromCharCode(0x2192)
+                    : String.fromCharCode(0x25cb);
                 return (
-                  "<li class=\"" +
+                  '<li class="' +
                   cls +
-                  "\"><span class=\"wg-todo-mark\">" +
+                  '"><span class="wg-todo-mark">' +
                   mark +
-                  "</span><span>" +
+                  '</span><span>' +
                   esc(t.text || "") +
-                  "</span></li>"
+                  '</span></li>'
                 );
               })
               .join("") +
-            "</ul>"
+            '</ul>'
           );
         })());
       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;
@@ -1158,12 +1241,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) {
@@ -1196,7 +1279,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("");
@@ -1205,7 +1288,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);
@@ -1423,15 +1506,18 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   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(() => {});
   };
@@ -1454,12 +1540,16 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
       } else if (h.todos && h.todos.length) {
         await setDemoTodos(page, normalizeTodos(h.todos, h.todoIndex));
       }
-      const cx = box.x + box.width / 2;
-      const cy = box.y + box.height / 2;
       const z = h.zoom != null && Number(h.zoom) > 1 ? Number(h.zoom) : 1;
       const camMs = 700;
-      // One-shot camera: zoom + center together (no zoom-then-align).
-      await applyCameraZoom(page, box, z, camMs);
+      const followMouse =
+        h.followMouse !== undefined
+          ? !!h.followMouse
+          : h.follow !== undefined
+            ? !!h.follow
+            : z > 1;
+      const cx = box.x + box.width / 2;
+      const cy = box.y + box.height / 2;
       if (h.cursor !== false) {
         await page
           .evaluate(({ cx, cy, camMs }) => {
@@ -1467,41 +1557,40 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           }, { cx, cy, camMs })
           .catch(() => {});
       }
-      await showRing(page, box, h.label, h.tone || "planned", {
-        size: h.size,
-        weight: h.weight,
-        focus: !!h.focus,
-        color: h.color || h.labelColor || h.textColor,
-      });
-      await new Promise((res) => setTimeout(res, camMs));
-      // Live ring track only - camera stays locked (no per-frame re-pan).
+      // Track first: ring rides visual rect through the zoom (no re-adjust).
       await page
-        .evaluate(({ sel, label, tone, size, weight, focus, color }) => {
-          const tick = () => {
-            const el = document.querySelector(sel);
-            if (!el) {
-              window.__wgRingRaf = requestAnimationFrame(tick);
-              return;
+        .evaluate(
+          ({ sel, label, tone, size, weight, focus, color, zoom, followMouse, camMs }) => {
+            if (window.__wgStartHighlightTrack) {
+              window.__wgStartHighlightTrack({
+                sel,
+                label,
+                tone,
+                size,
+                weight,
+                focus,
+                color,
+                zoom,
+                followMouse,
+                camMs,
+              });
             }
-            const r = el.getBoundingClientRect();
-            const box = { x: r.left, y: r.top, width: r.width, height: r.height };
-            if (window.__wgPositionRing) {
-              window.__wgPositionRing(box, label, tone || "planned", { size, weight, focus, color });
-            }
-            window.__wgRingRaf = requestAnimationFrame(tick);
-          };
-          window.__wgRingRaf = requestAnimationFrame(tick);
-          window.__wgRingTrack = () => {};
-        }, {
-          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 || "",
-        })
+          },
+          {
+            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,
+            followMouse,
+            camMs,
+          },
+        )
         .catch(() => {});
+      await new Promise((res) => setTimeout(res, camMs));
 
       // Appear settle
       await new Promise((res) => setTimeout(res, fadeMs));
@@ -1570,8 +1659,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
@@ -1582,13 +1671,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 {
@@ -1597,21 +1686,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("") +
@@ -1619,41 +1708,45 @@ 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\">" +
+            '<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";
+                const mark = t.done
+                  ? String.fromCharCode(0x2713)
+                  : t.current
+                    ? String.fromCharCode(0x2192)
+                    : String.fromCharCode(0x25cb);
                 return (
-                  "<li class=\"" +
+                  '<li class="' +
                   cls +
-                  "\"><span class=\"wg-todo-mark\">" +
+                  '"><span class="wg-todo-mark">' +
                   mark +
-                  "</span><span>" +
+                  '</span><span>' +
                   escA(t.text || "") +
-                  "</span></li>"
+                  '</span></li>'
                 );
               })
               .join("") +
-            "</ul>"
+            '</ul>'
           );
         })()) +
         resultHtml +
@@ -1722,13 +1815,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("") +
@@ -1739,8 +1832,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";
@@ -1748,17 +1841,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);
@@ -2022,25 +2115,25 @@ async function presentSlides(page, slides, _gate, opts) {
           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 " +
@@ -2050,35 +2143,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) {
@@ -2243,7 +2336,7 @@ async function teardownOverlay(page) {
         window.__wgRingTrack = null;
       }
       window.__wgNarrateOwnsRing = false;
-      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner", "wg-todo-modal"]) {
+      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner", "wg-todo-modal", "wg-focus-veil"]) {
         const el = document.getElementById(id);
         if (el) el.remove();
       }

package/dist/highlights.d.ts

@@ -89,6 +89,14 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      * Spotlight: dim the rest of the page, keep this target as the focal point.
      */
     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`.
+     */
+    followMouse?: boolean;
+    /** Alias for {@link WaygraphHighlightStub.followMouse}. */
+    follow?: boolean;
     /**
      * Caption text color (CSS color). Overrides tone label color when set.
      * Aliases accepted at runtime: `color`, `labelColor`, `textColor`.
@@ -101,7 +109,7 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
     cursor?: boolean;
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "focus" | "color" | "cursor"> & FixtureDurationFields;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "focus" | "followMouse" | "follow" | "color" | "cursor"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 /**
  * Open stub lifecycle context. Authors set rings + episode fixtures freely —

package/package.json

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