waygraph 0.12.32 → 0.12.34

package/dist/cli.js

@@ -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.
@@ -1431,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(() => {});
   };
@@ -1462,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 }) => {
@@ -1475,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));
@@ -2255,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/examples/saucedemo/package.json

@@ -8,9 +8,9 @@
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
     "flows": "waygraph list",
-    "demo": "waygraph demo --blocks shopFlow",
-    "demo:step": "waygraph demo --blocks shopFlow --title \"Shop demo\"",
-    "demo:auto-next": "waygraph demo --blocks shopFlow --auto-next --title \"Shop demo\"",
+    "demo": "waygraph demo --blocks \"loginFlow then shopFlow\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
+    "demo:step": "waygraph demo --blocks \"loginFlow then shopFlow\" --title \"Shop demo\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
+    "demo:auto-next": "waygraph demo --blocks \"loginFlow then shopFlow\" --auto-next --title \"Product then cart\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
     "auto": "waygraph auto",
     "auto:cli": "waygraph auto --cli --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
     "prove:auto-cli": "node scripts/drive-auto-cli.mjs",

package/examples/saucedemo/src/blocks/saucedemo-web/cart/nav-cart.block.ts

@@ -1,5 +1,6 @@
 import { defineNavClickBlock, Trait } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
+import { InventorySel } from "../inventory/methods/inventory-items.js";
 
 /**
  * Kind: Nav
@@ -14,4 +15,36 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   checkpoint: "CartPage",
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
+  // Demo: zoom cart chrome, then the cart line items after landing.
+  stubBefore: (ctx) => {
+    ctx.title("Open cart");
+    ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+    ctx.todoIndex(2);
+    ctx.zoom(1.4);
+    ctx.highlights({
+      cart: {
+        selector: ".shopping_cart_link",
+        label: "Cart",
+        detail: "Zoom cart chrome",
+        focus: true,
+        color: "#c9a6ff",
+        zoom: 1.55,
+        followMouse: true,
+        weight: "bold",
+      },
+    });
+  },
+  stubAfter: (ctx) => {
+    ctx.banner("Your cart");
+    ctx.ring("items", {
+      selector: InventorySel.cartItem,
+      label: "Cart items",
+      detail: "Product landed in cart",
+      focus: true,
+      color: "#86efac",
+      zoom: 1.4,
+      followMouse: true,
+      duration: true,
+    });
+  },
 });

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

@@ -3,6 +3,9 @@ import type { ItemInCart } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectAddableItems, InventorySel } from "./inventory-items.js";
 
+/** Showcase product for headed demos (matches shopFlow --data selectedItem). */
+const DEMO_PRODUCT_ID = "sauce-labs-backpack";
+
 /**
  * Kind: Effect
  * Helper: defineEffectBlock
@@ -30,13 +33,46 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    stubBefore: {},
-    stubAfter: {
-      badge: {
+    // Demo path: zoom the product, then the add button, then (after) the cart badge.
+    stubBefore: (ctx) => {
+      ctx.title("Pick a product");
+      ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+      ctx.todoIndex(0);
+      ctx.zoom(1.35);
+      ctx.highlights({
+        product: {
+          selector: InventorySel.title(DEMO_PRODUCT_ID),
+          label: "Sauce Labs Backpack",
+          detail: "Zoom the product",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.45,
+          followMouse: true,
+        },
+        add: {
+          selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
+          label: "Add to cart",
+          focus: true,
+          color: "#86efac",
+          zoom: 1.5,
+          weight: "bold",
+        },
+      });
+    },
+    stubAfter: (ctx) => {
+      ctx.banner("In the cart");
+      ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+      ctx.todoIndex(1);
+      ctx.ring("badge", {
         selector: InventorySel.cartBadge,
         label: "Cart badge",
-        detail: "Item is in the cart",
-      },
+        detail: "Item count updated",
+        focus: true,
+        color: "#86efac",
+        zoom: 1.6,
+        followMouse: true,
+        duration: true,
+      });
     },
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {

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

@@ -81,14 +81,14 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       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 + camera zoom",
+      // Landed on inventory - hand off to shopFlow for product -> cart zoom.
+      ctx.ring("shelf", {
+        selector: ".inventory_list",
+        label: "Product shelf",
+        detail: "Ready to shop",
         focus: true,
-        color: "#86efac",
-        zoom: 1.45,
+        color: "#c9a6ff",
+        zoom: 1.25,
         duration: true,
       });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.32",
+  "version": "0.12.34",
   "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/cart/nav-cart.block.ts

@@ -1,5 +1,6 @@
 import { defineNavClickBlock, Trait } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
+import { InventorySel } from "../inventory/methods/inventory-items.js";
 
 /**
  * Kind: Nav
@@ -14,4 +15,36 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   checkpoint: "CartPage",
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
+  // Demo: zoom cart chrome, then the cart line items after landing.
+  stubBefore: (ctx) => {
+    ctx.title("Open cart");
+    ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+    ctx.todoIndex(2);
+    ctx.zoom(1.4);
+    ctx.highlights({
+      cart: {
+        selector: ".shopping_cart_link",
+        label: "Cart",
+        detail: "Zoom cart chrome",
+        focus: true,
+        color: "#c9a6ff",
+        zoom: 1.55,
+        followMouse: true,
+        weight: "bold",
+      },
+    });
+  },
+  stubAfter: (ctx) => {
+    ctx.banner("Your cart");
+    ctx.ring("items", {
+      selector: InventorySel.cartItem,
+      label: "Cart items",
+      detail: "Product landed in cart",
+      focus: true,
+      color: "#86efac",
+      zoom: 1.4,
+      followMouse: true,
+      duration: true,
+    });
+  },
 });

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

@@ -3,6 +3,9 @@ import type { ItemInCart } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectAddableItems, InventorySel } from "./inventory-items.js";
 
+/** Showcase product for headed demos (matches shopFlow --data selectedItem). */
+const DEMO_PRODUCT_ID = "sauce-labs-backpack";
+
 /**
  * Kind: Effect
  * Helper: defineEffectBlock
@@ -30,13 +33,46 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    stubBefore: {},
-    stubAfter: {
-      badge: {
+    // Demo path: zoom the product, then the add button, then (after) the cart badge.
+    stubBefore: (ctx) => {
+      ctx.title("Pick a product");
+      ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+      ctx.todoIndex(0);
+      ctx.zoom(1.35);
+      ctx.highlights({
+        product: {
+          selector: InventorySel.title(DEMO_PRODUCT_ID),
+          label: "Sauce Labs Backpack",
+          detail: "Zoom the product",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.45,
+          followMouse: true,
+        },
+        add: {
+          selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
+          label: "Add to cart",
+          focus: true,
+          color: "#86efac",
+          zoom: 1.5,
+          weight: "bold",
+        },
+      });
+    },
+    stubAfter: (ctx) => {
+      ctx.banner("In the cart");
+      ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+      ctx.todoIndex(1);
+      ctx.ring("badge", {
         selector: InventorySel.cartBadge,
         label: "Cart badge",
-        detail: "Item is in the cart",
-      },
+        detail: "Item count updated",
+        focus: true,
+        color: "#86efac",
+        zoom: 1.6,
+        followMouse: true,
+        duration: true,
+      });
     },
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {

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

@@ -81,14 +81,14 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       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 + camera zoom",
+      // Landed on inventory - hand off to shopFlow for product -> cart zoom.
+      ctx.ring("shelf", {
+        selector: ".inventory_list",
+        label: "Product shelf",
+        detail: "Ready to shop",
         focus: true,
-        color: "#86efac",
-        zoom: 1.45,
+        color: "#c9a6ff",
+        zoom: 1.25,
         duration: true,
       });
     },