waygraph 0.12.34 → 0.12.36

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,
               );
             }
           }
@@ -885,7 +889,8 @@ async function installOverlay(page, title) {
           if (ring) ring.style.opacity = "0";
           if (ringLabel) ringLabel.style.opacity = "0";
           if (window.__wgHideFocusVeil) window.__wgHideFocusVeil();
-          if (window.__wgClearZoom) window.__wgClearZoom();
+          // Do NOT clear camera zoom here - zoomOut:false keeps scale between
+          // rings; only resetCameraZoom / teardown call __wgClearZoom.
         };
         // Screen Studio-style camera: scale <body>, keep overlays on <html> fixed.
         window.__wgCamera = { scale: 1, cx: 0, cy: 0 };
@@ -1590,7 +1595,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,17 +1608,22 @@ 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 */
     }
   }
   await stopLiveFollow();
-  await resetCameraZoom(page);
+  // Keep camera if the last ring (or phase default) asked zoomOut:false.
+  const last = list.length > 0 ? list[list.length - 1] : null;
+  if (!last || last.zoomOut !== false) {
+    await resetCameraZoom(page);
+  }
   if (list.length === 0) {
     await hideRing(page);
   }
@@ -2336,6 +2350,7 @@ async function teardownOverlay(page) {
         window.__wgRingTrack = null;
       }
       window.__wgNarrateOwnsRing = false;
+      if (window.__wgClearZoom) window.__wgClearZoom();
       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();
@@ -2939,6 +2954,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 +3035,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 +3130,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/src/blocks/saucedemo-web/cart/nav-cart.block.ts

@@ -15,12 +15,12 @@ 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.zoomOut(false);
     ctx.highlights({
       cart: {
         selector: ".shopping_cart_link",
@@ -29,6 +29,7 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
         focus: true,
         color: "#c9a6ff",
         zoom: 1.55,
+        zoomOut: false,
         followMouse: true,
         weight: "bold",
       },
@@ -36,6 +37,7 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   },
   stubAfter: (ctx) => {
     ctx.banner("Your cart");
+    ctx.zoomOut(false);
     ctx.ring("items", {
       selector: InventorySel.cartItem,
       label: "Cart items",

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

@@ -33,12 +33,13 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    // Demo path: zoom the product, then the add button, then (after) the cart 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),
@@ -47,6 +48,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
           focus: true,
           color: "#c9a6ff",
           zoom: 1.45,
+          zoomOut: false,
           followMouse: true,
         },
         add: {
@@ -55,6 +57,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
           focus: true,
           color: "#86efac",
           zoom: 1.5,
+          zoomOut: false,
           weight: "bold",
         },
       });
@@ -63,6 +66,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
       ctx.banner("In the cart");
       ctx.todos(["Find the product", "Add to cart", "Open cart"]);
       ctx.todoIndex(1);
+      ctx.zoomOut(false);
       ctx.ring("badge", {
         selector: InventorySel.cartBadge,
         label: "Cart badge",
@@ -70,6 +74,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         focus: true,
         color: "#86efac",
         zoom: 1.6,
+        zoomOut: false,
         followMouse: true,
         duration: true,
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.34",
+  "version": "0.12.36",
   "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

@@ -15,12 +15,12 @@ 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.zoomOut(false);
     ctx.highlights({
       cart: {
         selector: ".shopping_cart_link",
@@ -29,6 +29,7 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
         focus: true,
         color: "#c9a6ff",
         zoom: 1.55,
+        zoomOut: false,
         followMouse: true,
         weight: "bold",
       },
@@ -36,6 +37,7 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   },
   stubAfter: (ctx) => {
     ctx.banner("Your cart");
+    ctx.zoomOut(false);
     ctx.ring("items", {
       selector: InventorySel.cartItem,
       label: "Cart items",

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

@@ -33,12 +33,13 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    // Demo path: zoom the product, then the add button, then (after) the cart 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),
@@ -47,6 +48,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
           focus: true,
           color: "#c9a6ff",
           zoom: 1.45,
+          zoomOut: false,
           followMouse: true,
         },
         add: {
@@ -55,6 +57,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
           focus: true,
           color: "#86efac",
           zoom: 1.5,
+          zoomOut: false,
           weight: "bold",
         },
       });
@@ -63,6 +66,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
       ctx.banner("In the cart");
       ctx.todos(["Find the product", "Add to cart", "Open cart"]);
       ctx.todoIndex(1);
+      ctx.zoomOut(false);
       ctx.ring("badge", {
         selector: InventorySel.cartBadge,
         label: "Cart badge",
@@ -70,6 +74,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         focus: true,
         color: "#86efac",
         zoom: 1.6,
+        zoomOut: false,
         followMouse: true,
         duration: true,
       });