waygraph 0.12.33 → 0.12.35

package/dist/cli.js

@@ -829,11 +829,15 @@ async function installOverlay(page, title) {
             const el0 = document.querySelector(sel);
             if (el0) {
               const r0 = el0.getBoundingClientRect();
+              const already =
+                window.__wgCamera && window.__wgCamera.scale > 1.001;
+              // Already zoomed (zoomOut:false chain): short pan, not full zoom-in.
+              const dur = already ? Math.min(camMs, 420) : camMs;
               window.__wgSetCamera(
                 r0.left + r0.width / 2,
                 r0.top + r0.height / 2,
                 zoom,
-                camMs,
+                dur,
               );
             }
           }
@@ -1590,7 +1594,11 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           },
         )
         .catch(() => {});
-      await new Promise((res) => setTimeout(res, camMs));
+      const alreadyZoomed = await page
+        .evaluate(() => !!(window.__wgCamera && window.__wgCamera.scale > 1.001))
+        .catch(() => false);
+      const waitMs = alreadyZoomed ? Math.min(camMs, 420) : camMs;
+      await new Promise((res) => setTimeout(res, waitMs));
 
       // Appear settle
       await new Promise((res) => setTimeout(res, fadeMs));
@@ -1599,11 +1607,12 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
       const holdMs =
         authored != null ? authored : defaultHoldMs != null ? defaultHoldMs : legacyMs;
       await new Promise((res) => setTimeout(res, holdMs));
-      // Disappear before next (respect fade)
+      // Disappear before next. zoomOut:false keeps camera for the next ring.
       await stopLiveFollow();
       await hideRing(page);
-      await resetCameraZoom(page);
-      await new Promise((res) => setTimeout(res, fadeMs));
+      const doZoomOut = h.zoomOut !== false;
+      if (doZoomOut) await resetCameraZoom(page);
+      await new Promise((res) => setTimeout(res, doZoomOut ? fadeMs : 120));
     } catch {
       /* best-effort */
     }
@@ -2939,6 +2948,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           focus: styled.focus,
           color: styled.color,
           cursor: styled.cursor,
+          zoomOut: styled.zoomOut,
         };
       });
       await cycleHighlightRings(page, beforeRings, !!pacing.gatesFast, {
@@ -3019,6 +3029,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
             focus: styled.focus,
             color: styled.color,
             cursor: styled.cursor,
+            zoomOut: styled.zoomOut,
           };
         });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
@@ -3113,6 +3124,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           focus: styled.focus,
           color: styled.color,
           cursor: styled.cursor,
+          zoomOut: styled.zoomOut,
         };
       });
     } else {

package/dist/highlights.d.ts

@@ -50,6 +50,8 @@ export type StubPhaseFixtures = {
      * cursor. Not element CSS zoom. Typical `1.25` .. `2`.
      */
     zoom?: number;
+    /** Default zoomOut for rings (false = keep camera between rings). */
+    zoomOut?: boolean;
     /** Top demo banner title (the purple "waygraph demo" card). */
     title?: string;
 };
@@ -81,10 +83,15 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
     weight?: HighlightWeight;
     /**
      * 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}.
+     * the target / cursor). Typical `1.25` .. `2`. Cleared when the ring hides
+     * unless `zoomOut: false`. Episode default: {@link StubCtx.zoom}.
      */
     zoom?: number;
+    /**
+     * When false, keep the camera zoomed after this ring (pan to the next target
+     * instead of zooming out). Default true. Phase default: {@link StubCtx.zoomOut}.
+     */
+    zoomOut?: boolean;
     /**
      * Spotlight: dim the rest of the page, keep this target as the focal point.
      */
@@ -109,7 +116,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" | "followMouse" | "follow" | "color" | "cursor"> & FixtureDurationFields;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "zoomOut" | "focus" | "followMouse" | "follow" | "color" | "cursor"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 /**
  * Open stub lifecycle context. Authors set rings + episode fixtures freely —
@@ -147,6 +154,10 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     todoIndex(n: number): void;
     /** Default camera zoom for rings without their own zoom. */
     zoom(n: number): void;
+    /**
+     * Default zoomOut for rings in this phase. `false` = keep camera between rings.
+     */
+    zoomOut(keep: boolean): void;
     /** Top banner title (waygraph demo card). */
     title(text: string): void;
     /** Alias for {@link StubCtx.title}. */
@@ -170,6 +181,7 @@ export type StubPhaseResult = {
     todos: WaygraphTodoItem[];
     todoIndex?: number;
     zoom?: number;
+    zoomOut?: boolean;
     title?: string;
 };
 /**

package/dist/highlights.js

@@ -403,6 +403,9 @@ function createStubCtx(bag, opts) {
             if (Number.isFinite(n) && n > 0)
                 bag.zoom = n;
         },
+        zoomOut(keep) {
+            bag.zoomOut = !!keep;
+        },
         title(text) {
             bag.title = String(text ?? "");
         },
@@ -419,6 +422,8 @@ function createStubCtx(bag, opts) {
             if (partial.zoom !== undefined && Number.isFinite(partial.zoom) && partial.zoom > 0) {
                 bag.zoom = partial.zoom;
             }
+            if (partial.zoomOut !== undefined)
+                bag.zoomOut = !!partial.zoomOut;
             if (partial.title !== undefined)
                 bag.title = String(partial.title ?? "");
         },
@@ -443,6 +448,11 @@ function applyDefaultZoom(slots, defaultZoom) {
         return slots;
     return slots.map((h) => (h.zoom !== undefined && h.zoom > 0 ? h : { ...h, zoom: defaultZoom }));
 }
+function applyDefaultZoomOut(slots, defaultZoomOut) {
+    if (defaultZoomOut === undefined)
+        return slots;
+    return slots.map((h) => h.zoomOut !== undefined ? h : { ...h, zoomOut: defaultZoomOut });
+}
 function mergePhaseMaps(phaseMap, fixturePhase) {
     const slotIds = new Set([...Object.keys(phaseMap), ...Object.keys(fixturePhase || {})]);
     const ordered = [...slotIds].sort((a, b) => {
@@ -546,12 +556,14 @@ export async function runStubPhase(block, phase, opts) {
     const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
     let highlights = mergePhaseMaps(bag.highlights, fixturePhase);
     highlights = applyDefaultZoom(highlights, bag.zoom);
+    highlights = applyDefaultZoomOut(highlights, bag.zoomOut);
     const todos = normalizeTodos(bag.todos, bag.todoIndex);
     return {
         highlights,
         todos,
         ...(bag.todoIndex !== undefined ? { todoIndex: bag.todoIndex } : {}),
         ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
+        ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
     };
 }

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,37 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   checkpoint: "CartPage",
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
+  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,
+        zoomOut: false,
+        followMouse: true,
+        weight: "bold",
+      },
+    });
+  },
+  stubAfter: (ctx) => {
+    ctx.banner("Your cart");
+    ctx.zoomOut(false);
+    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,49 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    stubBefore: {},
-    stubAfter: {
-      badge: {
+    // Demo: zoom product -> add (stay zoomed), then badge after act.
+    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.zoomOut(false);
+      ctx.highlights({
+        product: {
+          selector: InventorySel.title(DEMO_PRODUCT_ID),
+          label: "Sauce Labs Backpack",
+          detail: "Zoom the product",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.45,
+          zoomOut: false,
+          followMouse: true,
+        },
+        add: {
+          selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
+          label: "Add to cart",
+          focus: true,
+          color: "#86efac",
+          zoom: 1.5,
+          zoomOut: false,
+          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.33",
+  "version": "0.12.35",
   "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,37 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   checkpoint: "CartPage",
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
+  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,
+        zoomOut: false,
+        followMouse: true,
+        weight: "bold",
+      },
+    });
+  },
+  stubAfter: (ctx) => {
+    ctx.banner("Your cart");
+    ctx.zoomOut(false);
+    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,49 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    stubBefore: {},
-    stubAfter: {
-      badge: {
+    // Demo: zoom product -> add (stay zoomed), then badge after act.
+    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.zoomOut(false);
+      ctx.highlights({
+        product: {
+          selector: InventorySel.title(DEMO_PRODUCT_ID),
+          label: "Sauce Labs Backpack",
+          detail: "Zoom the product",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.45,
+          zoomOut: false,
+          followMouse: true,
+        },
+        add: {
+          selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
+          label: "Add to cart",
+          focus: true,
+          color: "#86efac",
+          zoom: 1.5,
+          zoomOut: false,
+          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,
       });
     },