waygraph 0.12.27 → 0.12.29

package/dist/cli.js

@@ -412,7 +412,17 @@ 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 .3s ease,border-color .15s,box-shadow .15s;}" +
+  "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.
@@ -431,7 +441,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 .3s ease,background .15s,color .15s;}" +
+  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .32s ease,left .28s ease,top .28s 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;}" +
@@ -685,7 +695,8 @@ async function installOverlay(page, title) {
         window.__wgMoveCursorTo = (x, y, ms, instant) => {
           const cursor = document.getElementById("wg-cursor");
           if (!cursor) return;
-          cursor.style.setProperty("--wg-cursor-ms", (ms || 600) + "ms");
+          const travel = ms || 600;
+          cursor.style.setProperty("--wg-cursor-ms", travel + "ms");
           if (instant) {
             const prev = cursor.style.transition;
             cursor.style.transition = "none";
@@ -696,6 +707,11 @@ async function installOverlay(page, title) {
             cursor.style.transform = "translate(" + x + "px," + y + "px)";
           }
           cursor.style.opacity = "1";
+          // Screen Studio: pan the zoomed camera with the cursor.
+          const cam = window.__wgCamera;
+          if (cam && cam.scale > 1.001 && window.__wgSetCamera) {
+            window.__wgSetCamera(x, y, cam.scale, instant ? 0 : travel);
+          }
         };
         window.__wgHideCursor = () => {
           const cursor = document.getElementById("wg-cursor");
@@ -721,6 +737,7 @@ 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;
@@ -740,6 +757,9 @@ async function installOverlay(page, title) {
           ring.style.opacity = "1";
           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;
@@ -779,29 +799,44 @@ async function installOverlay(page, title) {
           if (ringLabel) ringLabel.style.opacity = "0";
           if (window.__wgClearZoom) window.__wgClearZoom();
         };
+        // Screen Studio-style camera: scale <body>, keep overlays on <html> fixed.
+        window.__wgCamera = { scale: 1, cx: 0, cy: 0 };
+        window.__wgSetCamera = (cx, cy, scale, ms) => {
+          const body = document.body;
+          if (!body) return;
+          const s = Math.max(1, Math.min(Number(scale) || 1, 2.75));
+          window.__wgCamera = { scale: s, cx, cy };
+          const dur = ms != null && Number(ms) >= 0 ? Number(ms) : 500;
+          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;
+          }
+          body.style.transform =
+            "translate(" + cx + "px," + cy + "px) scale(" + s + ") translate(" + -cx + "px," + -cy + "px)";
+        };
+        window.__wgResetCamera = () => {
+          window.__wgSetCamera(window.innerWidth / 2, window.innerHeight / 2, 1);
+        };
         window.__wgClearZoom = () => {
-          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;
-          });
+          if (window.__wgResetCamera) window.__wgResetCamera();
         };
-        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";
+        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 || "");
         };
         const POSITIONS = ["left", "center", "right"];
         const applyPos = (el, pos) => {
@@ -1202,153 +1237,233 @@ async function ensureSelectorInView(page, selector) {
   }
 }
 
-async function applyHighlightZoom(page, selector, zoom) {
-  const z = Number(zoom);
-  if (!Number.isFinite(z) || z <= 1.001) {
+async function applyCameraZoom(page, box, zoom) {
+  const z = zoom != null && Number(zoom) > 1 ? Number(zoom) : 1;
+  if (!box) {
     await page.evaluate(() => {
-      if (window.__wgClearZoom) window.__wgClearZoom();
+      if (window.__wgResetCamera) window.__wgResetCamera();
     }).catch(() => {});
     return;
   }
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
   await page
-    .evaluate(
-      ({ sel, scale }) => {
-        if (window.__wgApplyZoom) window.__wgApplyZoom(sel, scale);
-      },
-      { sel: selector, scale: z },
-    )
+    .evaluate(({ cx, cy, scale }) => {
+      if (window.__wgSetCamera) window.__wgSetCamera(cx, cy, scale);
+    }, { cx, cy, scale: z })
     .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>"
-  );
+async function resetCameraZoom(page) {
+  await page
+    .evaluate(() => {
+      if (window.__wgResetCamera) window.__wgResetCamera();
+    })
+    .catch(() => {});
 }
 
-function miniStepLabel(info) {
-  const ep =
-    info.episodeNumber !== undefined && info.episodeNumber !== null
-      ? "Ep " + info.episodeNumber + " \\u00b7 "
-      : "";
-  return (
-    ep +
-    (info.index + 1) +
-    " / " +
-    info.total +
-    (info.blockName ? " \\u00b7 " + info.blockName : "") +
-    (info.paceBadge ? " \\u00b7 " + info.paceBadge : "")
-  );
+async function setDemoBannerTitle(page, title) {
+  if (title == null || title === "") return;
+  await page
+    .evaluate((t) => {
+      if (window.__wgSetBannerTitle) window.__wgSetBannerTitle(t);
+    }, String(title))
+    .catch(() => {});
 }
 
+
 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.__wgRingRaf) {
+          cancelAnimationFrame(window.__wgRingRaf);
+          window.__wgRingRaf = null;
+        }
+        if (window.__wgRingTrack) {
+          window.removeEventListener("resize", window.__wgRingTrack);
+          window.removeEventListener("scroll", window.__wgRingTrack, true);
+          window.__wgRingTrack = null;
+        }
+      })
+      .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) {
-        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));
+      if (!box) continue;
+      await updateHlProgress(i);
+      await applyCameraZoom(page, box, h.zoom);
+      const useCursor = h.cursor !== false;
+      if (useCursor) {
+        const cx = box.x + box.width / 2;
+        const cy = box.y + box.height / 2;
+        await page
+          .evaluate(({ cx, cy }) => {
+            if (window.__wgMoveCursorTo) window.__wgMoveCursorTo(cx, cy, 500, false);
+          }, { cx, cy })
+          .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,
+      });
+      // Live follow while this ring is up (seamless, not taped).
+      await page
+        .evaluate(({ sel, label, tone, size, weight, focus, color, zoom }) => {
+          const tick = () => {
+            const el = document.querySelector(sel);
+            if (!el) {
+              window.__wgRingRaf = requestAnimationFrame(tick);
+              return;
+            }
+            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 });
+            }
+            if (zoom && zoom > 1 && window.__wgSetCamera) {
+              // Prefer cursor tip when visible (Screen Studio follow-mouse);
+              // else keep the ring target centered.
+              let cx = box.x + box.width / 2;
+              let cy = box.y + box.height / 2;
+              const cur = document.getElementById("wg-cursor");
+              if (cur && cur.style.opacity !== "0") {
+                const m = /translate\(([-\d.]+)px,\s*([-\d.]+)px\)/.exec(cur.style.transform || "");
+                if (m) {
+                  cx = Number(m[1]);
+                  cy = Number(m[2]);
+                }
+              }
+              window.__wgSetCamera(cx, cy, zoom, 0);
+            }
+            window.__wgRingRaf = requestAnimationFrame(tick);
+          };
+          window.__wgRingRaf = requestAnimationFrame(tick);
+          const onScroll = () => {};
+          window.__wgRingTrack = onScroll;
+        }, {
+          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: h.zoom != null && h.zoom > 1 ? h.zoom : 0,
+        })
+        .catch(() => {});
+
+      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(() => {});
       }
+
+      // 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 (respect fade)
+      await stopLiveFollow();
+      await hideRing(page);
+      await resetCameraZoom(page);
+      await new Promise((res) => setTimeout(res, fadeMs));
     } catch {
-      // best-effort - a selector that doesn't resolve just gets skipped
+      /* best-effort */
     }
   }
-  if (list.length > 0) {
-    const last = list[list.length - 1];
-    await page
-      .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(() => {});
-  } else {
+  await stopLiveFollow();
+  await resetCameraZoom(page);
+  if (list.length === 0) {
     await hideRing(page);
   }
 }
 
+
 async function renderAfterStep(page, info) {
   await installOverlay(page, info.title);
   // Clear any tracker from a previous highlight before cycling through this
@@ -1698,14 +1813,16 @@ 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 }) => {
+      ({ box, label, tone, size, weight, focus, color }) => {
         if (window.__wgPositionRing) {
-          window.__wgPositionRing(box, label, tone || "planned", { size, weight });
+          window.__wgPositionRing(box, label, tone || "planned", { size, weight, focus, color });
         }
       },
-      { box, label, tone: tone || "planned", size, weight },
+      { box, label, tone: tone || "planned", size, weight, focus, color },
     )
     .catch(() => {});
 }
@@ -1795,7 +1912,10 @@ async function presentSlides(page, slides, _gate, opts) {
     if (s.selector) {
       try {
         await ensureSelectorInView(page, s.selector);
-        await applyHighlightZoom(page, s.selector, s.zoom);
+        {
+          const zb = await page.locator(s.selector).first().boundingBox().catch(() => null);
+          await applyCameraZoom(page, zb, s.zoom);
+        }
         const box = await page.locator(s.selector).first().boundingBox();
         if (box) await showRing(page, box, caption, slideTone, slideStyle);
       } catch {
@@ -2623,6 +2743,39 @@ 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,
+        };
+      });
+      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
@@ -2672,6 +2825,7 @@ 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 {
@@ -2683,6 +2837,9 @@ 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,
           };
         });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
@@ -2761,6 +2918,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         fixtures: fixturesAfter,
       });
       stubAfterTodos = afterPhase.todos || [];
+      await setDemoBannerTitle(page, afterPhase.title);
       highlights = afterPhase.highlights.map((h) => {
         const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
         return {
@@ -2772,6 +2930,9 @@ 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,
         };
       });
     } else {

package/dist/highlights.d.ts

@@ -45,8 +45,13 @@ export type StubPhaseFixtures = {
     todos?: readonly WaygraphTodoInput[];
     /** Which todo is current (0-based). Rows before = done, after = pending. */
     todoIndex?: number;
-    /** Default zoom for rings that omit their own zoom. */
+    /**
+     * Camera zoom (Screen Studio style) - scales the page toward the target /
+     * cursor. Not element CSS zoom. Typical `1.25` .. `2`.
+     */
     zoom?: number;
+    /** Top demo banner title (the purple "waygraph demo" card). */
+    title?: string;
 };
 /** One named highlight slot on a block (selector + caption). */
 export interface WaygraphHighlightStub extends FixtureDurationFields {
@@ -75,14 +80,28 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      */
     weight?: HighlightWeight;
     /**
-     * Magnify this target while its ring is shown (e.g. `1.35`).
-     * Cleared when the ring hides / next highlight starts. `1` or omit = off.
+     * Camera zoom while this ring is up (Screen Studio style - page scales toward
+     * the target / cursor). Typical `1.25` .. `2`. Cleared when the ring hides.
      * Episode default: {@link StubCtx.zoom}.
      */
     zoom?: number;
+    /**
+     * Spotlight: dim the rest of the page, keep this target as the focal point.
+     */
+    focus?: boolean;
+    /**
+     * Caption text color (CSS color). Overrides tone label color when set.
+     * Aliases accepted at runtime: `color`, `labelColor`, `textColor`.
+     */
+    color?: string;
+    /**
+     * Move the demo cursor to the target while this ring is up (default true
+     * for authored stub queues; set false to keep cursor hidden).
+     */
+    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"> & FixtureDurationFields;
+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 HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 /**
  * Open stub lifecycle context. Authors set rings + episode fixtures freely —
@@ -118,8 +137,12 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     todos(items: readonly WaygraphTodoInput[]): void;
     /** Current checklist index (bump for sequential plans). */
     todoIndex(n: number): void;
-    /** Default zoom for rings without their own zoom. */
+    /** Default camera zoom for rings without their own zoom. */
     zoom(n: number): void;
+    /** Top banner title (waygraph demo card). */
+    title(text: string): void;
+    /** Alias for {@link StubCtx.title}. */
+    banner(text: string): void;
     /** Batch-set rings + episode fixtures. */
     set(partial: {
         highlights?: HighlightStubPhase;
@@ -139,6 +162,7 @@ export type StubPhaseResult = {
     todos: WaygraphTodoItem[];
     todoIndex?: number;
     zoom?: number;
+    title?: string;
 };
 /**
  * One yap/slide in a multi-step demo caption sequence.
@@ -154,7 +178,7 @@ export interface WaygraphSlide extends FixtureDurationFields {
     tone?: HighlightTone;
     size?: HighlightSize;
     weight?: HighlightWeight;
-    /** Magnify selector target while this slide is showing (same as stub zoom). */
+    /** Magnify via camera (Screen Studio) while this slide is showing. */
     zoom?: number;
 }
 /**

package/dist/highlights.js

@@ -324,12 +324,26 @@ function pickZoom(base, patch) {
         return { zoom };
     return {};
 }
+function pickFxFields(base, patch) {
+    const out = {};
+    const focus = patch?.focus !== undefined ? patch.focus : base?.focus;
+    const color = patch?.color !== undefined ? patch.color : base?.color;
+    const cursor = patch?.cursor !== undefined ? patch.cursor : base?.cursor;
+    if (focus !== undefined)
+        out.focus = !!focus;
+    if (color !== undefined && String(color).trim())
+        out.color = String(color).trim();
+    if (cursor !== undefined)
+        out.cursor = !!cursor;
+    return out;
+}
 function mergeSlot(base, patch) {
     if (!base && !patch)
         return null;
     const dwell = pickDurationFields(base, patch);
     const style = pickStyleFields(base, patch);
     const zoom = pickZoom(base, patch);
+    const fx = pickFxFields(base, patch);
     if (!base && patch) {
         if (!patch.selector)
             return null;
@@ -341,6 +355,7 @@ function mergeSlot(base, patch) {
             ...style,
             ...dwell,
             ...zoom,
+            ...fx,
         };
     }
     if (base && !patch) {
@@ -350,6 +365,7 @@ function mergeSlot(base, patch) {
             ...(base.size ? { size: normalizeHighlightSize(base.size) } : {}),
             ...(base.weight ? { weight: normalizeHighlightWeight(base.weight) } : {}),
             ...pickZoom(base, undefined),
+            ...pickFxFields(base, undefined),
         };
     }
     return {
@@ -364,6 +380,7 @@ function mergeSlot(base, patch) {
         ...style,
         ...dwell,
         ...zoom,
+        ...fx,
     };
 }
 function createStubCtx(bag, opts) {
@@ -386,6 +403,12 @@ function createStubCtx(bag, opts) {
             if (Number.isFinite(n) && n > 0)
                 bag.zoom = n;
         },
+        title(text) {
+            bag.title = String(text ?? "");
+        },
+        banner(text) {
+            bag.title = String(text ?? "");
+        },
         set(partial) {
             if (partial.highlights)
                 bag.highlights = { ...partial.highlights };
@@ -396,6 +419,8 @@ function createStubCtx(bag, opts) {
             if (partial.zoom !== undefined && Number.isFinite(partial.zoom) && partial.zoom > 0) {
                 bag.zoom = partial.zoom;
             }
+            if (partial.title !== undefined)
+                bag.title = String(partial.title ?? "");
         },
     };
 }
@@ -527,6 +552,7 @@ export async function runStubPhase(block, phase, opts) {
         todos,
         ...(bag.todoIndex !== undefined ? { todoIndex: bag.todoIndex } : {}),
         ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
+        ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
     };
 }
 /**

package/examples/saucedemo/src/blocks/saucedemo-web/methods/submit-login.method.block.ts

@@ -45,34 +45,61 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
         : [Trait.visible('[data-test="error"]')],
-    // Open lifecycle: todos + zoom; stubAfter rings a lower inventory item
-    // so smooth auto-scroll is visible after login.
+    // Open lifecycle: banner title, todos, Screen Studio camera zoom,
+    // sequential highlight queue (appear / dwell / fade), focus + color.
     stubBefore: (ctx) => {
+      ctx.title("Signing in");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(0);
-      ctx.zoom(1.25);
+      ctx.zoom(1.35);
       ctx.highlights({
-        username: { selector: "#user-name", label: "Username", zoom: 1.3 },
-        password: { selector: "#password", label: "Password", zoom: 1.3 },
-        submit: { selector: "#login-button", label: "Login", zoom: 1.45 },
+        username: {
+          selector: "#user-name",
+          label: "Username",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.4,
+        },
+        password: {
+          selector: "#password",
+          label: "Password",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.4,
+        },
+        submit: {
+          selector: "#login-button",
+          label: "Login",
+          focus: true,
+          color: "#86efac",
+          zoom: 1.55,
+          weight: "bold",
+        },
       });
     },
     stubAfter: (ctx) => {
+      ctx.banner("Inventory");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(2);
-      // Inventory is tall - fleece sits lower; demo smooth-scrolls + zooms it.
+      // Fleece sits lower - demo smooth-scrolls + Screen Studio zooms to it.
       ctx.ring("fleece", {
         selector: '[data-test="add-to-cart-sauce-labs-fleece-jacket"]',
         label: "Fleece jacket",
-        detail: "Smooth scroll + zoom",
-        zoom: 1.4,
+        detail: "Smooth scroll + camera zoom",
+        focus: true,
+        color: "#86efac",
+        zoom: 1.45,
         duration: true,
       });
     },
     stubOnError: (ctx) => {
+      ctx.title("Login failed");
       ctx.ring("error", {
         selector: '[data-test="error"]',
         label: "Login error banner",
+        tone: "danger",
+        focus: true,
+        color: "#f87171",
         duration: true,
       });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.27",
+  "version": "0.12.29",
   "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/methods/submit-login.method.block.ts

@@ -45,31 +45,61 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
         : [Trait.visible('[data-test="error"]')],
+    // Open lifecycle: banner title, todos, Screen Studio camera zoom,
+    // sequential highlight queue (appear / dwell / fade), focus + color.
     stubBefore: (ctx) => {
+      ctx.title("Signing in");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(0);
-      ctx.zoom(1.25);
+      ctx.zoom(1.35);
       ctx.highlights({
-        username: { selector: "#user-name", label: "Username", zoom: 1.3 },
-        password: { selector: "#password", label: "Password", zoom: 1.3 },
-        submit: { selector: "#login-button", label: "Login", zoom: 1.45 },
+        username: {
+          selector: "#user-name",
+          label: "Username",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.4,
+        },
+        password: {
+          selector: "#password",
+          label: "Password",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.4,
+        },
+        submit: {
+          selector: "#login-button",
+          label: "Login",
+          focus: true,
+          color: "#86efac",
+          zoom: 1.55,
+          weight: "bold",
+        },
       });
     },
     stubAfter: (ctx) => {
+      ctx.banner("Inventory");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(2);
+      // Fleece sits lower - demo smooth-scrolls + Screen Studio zooms to it.
       ctx.ring("fleece", {
         selector: '[data-test="add-to-cart-sauce-labs-fleece-jacket"]',
         label: "Fleece jacket",
-        detail: "Smooth scroll + zoom",
-        zoom: 1.4,
+        detail: "Smooth scroll + camera zoom",
+        focus: true,
+        color: "#86efac",
+        zoom: 1.45,
         duration: true,
       });
     },
     stubOnError: (ctx) => {
+      ctx.title("Login failed");
       ctx.ring("error", {
         selector: '[data-test="error"]',
         label: "Login error banner",
+        tone: "danger",
+        focus: true,
+        color: "#f87171",
         duration: true,
       });
     },