waygraph 0.12.46 → 0.12.48

package/dist/cli.js

@@ -1724,6 +1724,23 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   // 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;
+  let dock = opts && opts.todoDock;
+  const advanceTodos = !(opts && opts.advanceTodos === false);
+  // Push stubAfter/before dock before the first ring so Method after-panels
+  // show the updated checklist immediately (not only after the ring cycle).
+  if (dock) {
+    await page
+      .evaluate((d) => {
+        if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "set", dock: d });
+      }, dock)
+      .catch(() => {});
+  } else if (opts && opts.todoSync === "clear") {
+    await page
+      .evaluate(() => {
+        if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "clear" });
+      })
+      .catch(() => {});
+  }
   for (let i = 0; i < list.length; i++) {
     const h = list[i];
     try {
@@ -1735,7 +1752,18 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           size: h.size,
           weight: h.weight,
         });
-        if ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length)) {
+        // Do NOT advanceTodoDock by ring index after stubAfter already set
+        // progress - that reset current back to 0 and the next block looked
+        // blank. Mid-act Method advance still uses syncTodoDockAdvance.
+        if (dock && advanceTodos) {
+          dock = advanceTodoDock(dock, i);
+          if (opts && opts.todoDockRef) opts.todoDockRef.current = dock;
+          await page
+            .evaluate((d) => {
+              if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "set", dock: d });
+            }, dock)
+            .catch(() => {});
+        } else if (!dock && ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length))) {
           const rows =
             opts && opts.todos && opts.todos.length
               ? opts.todos
@@ -1743,7 +1771,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           await page
             .evaluate((todos) => {
               if (window.__wgSyncTodos) {
-                window.__wgSyncTodos(todos);
+                window.__wgSyncTodos({ sync: "set", list: todos });
                 return;
               }
               // Fallback for pages that never got installOverlay sync helper.
@@ -1836,7 +1864,17 @@ async function renderAfterStep(page, info) {
   await cycleHighlightRings(page, highlights, gatesFast, {
     pace: info.pace,
     stepLabel: miniStepLabel(info),
+    todoDock: info.todoDock,
+    todos: info.todos,
+    todoSync: info.todoSync,
+    todoDockRef: info.todoDockRef,
+    // stubAfter already authored progress - do not re-index by ring 0..n
+    advanceTodos: false,
   });
+  // After-ring advances may have moved the dock - surface latest for caller.
+  if (info.todoDockRef && info.todoDockRef.current) {
+    info.todoDock = info.todoDockRef.current;
+  }
   const afterPayload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
@@ -2246,6 +2284,46 @@ async function matchStubForLocator(page, locator, stubs) {
   return null;
 }
 
+/** 0-based stub index for Method fill/click todo advance; -1 if none. */
+async function matchStubIndexForLocator(page, locator, stubs) {
+  if (!stubs || stubs.length === 0) return -1;
+  const box = await locator.boundingBox().catch(() => null);
+  if (!box) return -1;
+  for (let i = 0; i < stubs.length; i++) {
+    const s = stubs[i];
+    try {
+      const b = await page.locator(s.selector).first().boundingBox();
+      if (
+        b &&
+        Math.abs(b.x - box.x) < 4 &&
+        Math.abs(b.y - box.y) < 4 &&
+        Math.abs(b.width - box.width) < 8
+      ) {
+        return i;
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return -1;
+}
+
+/** Advance sequential todo dock to stubIndex and push to the page (Method act). */
+async function syncTodoDockAdvance(page, todoDockRef, stubIndex) {
+  if (!todoDockRef || stubIndex < 0) return;
+  const prev = todoDockRef.current;
+  if (!prev) return;
+  const advanced = advanceTodoDock(prev, stubIndex);
+  todoDockRef.current = advanced;
+  await page
+    .evaluate((dock) => {
+      if (window.__wgSyncTodos) {
+        window.__wgSyncTodos({ sync: "set", dock });
+      }
+    }, advanced)
+    .catch(() => {});
+}
+
 async function captionForLocator(page, locator, stubs, fallback) {
   const matched = await matchStubForLocator(page, locator, stubs);
   if (matched) {
@@ -2619,7 +2697,7 @@ async function wasJustNarrated(page) {
     .catch(() => false);
 }
 
-function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef) {
+function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef) {
   // Playwright's own slowMo ALREADY pauses after every single low-level
   // action it dispatches - and pressSequentially() fires one such action
   // PER CHARACTER. Also giving pressSequentially its own fixed delay
@@ -2675,6 +2753,8 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
             : "writing from mem";
           const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
           const cap = await captionForLocator(page, this, stubs, fallback);
+          const stubIdx = await matchStubIndexForLocator(page, this, stubs);
+          await syncTodoDockAdvance(page, todoDockRef, stubIdx);
           await moveCursorTo(page, box, cursorMs(500));
           await showRing(page, box, cap.label, cap.tone, {
             size: cap.size,
@@ -2749,6 +2829,8 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
           }
           const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
           const cap = await captionForLocator(page, this, stubs, fallback);
+          const stubIdx = await matchStubIndexForLocator(page, this, stubs);
+          await syncTodoDockAdvance(page, todoDockRef, stubIdx);
           clickTone = cap.tone;
           clickPoint = await moveCursorTo(page, box, cursorMs(600));
           await showRing(page, box, cap.label, cap.tone, {
@@ -2887,7 +2969,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   const stepperMode = process.env.WAYGRAPH_STEPPER === "full" ? "full" : "carousel";
   const pacing = { gatesFast: demoFast, gatesSlow: false, skipTheater: false, demoPace: "normal" };
   const stubBeforeRef = { current: [] };
-  instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef);
+  /** Live todo dock for Method fill/click advance (same carry as lastTodoDock). */
+  const todoDockRef = { current: undefined };
+  instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef);
   // Force the panel checkbox from this process's flags/env at run start.
   // installOverlay only seeds localStorage when the key is null (so mid-run
   // checkbox clicks survive navigations). Without this, a prior --autoplay
@@ -3108,6 +3192,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       todoPos: stubBeforePhase.todoPos,
     });
     lastTodoDock = appliedBefore.dock;
+    todoDockRef.current = lastTodoDock;
     const stubBeforeTodos =
       (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
       stubBeforePhase.todos ||
@@ -3265,6 +3350,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       })
       .catch(() => {});
     result = stepOutcome.result;
+    // Mid-act Method fill/click advances live on todoDockRef - fold that
+    // back into lastTodoDock before stubAfter / next-block keep, or the
+    // next step reverts to the pre-act (blank / index-0) checklist.
+    if (todoDockRef.current) lastTodoDock = todoDockRef.current;
     // withExpectedFailure last block that SUCCEEDS on the intentional fail
     // branch (e.g. submit-login -> LoginPage + error banner). Still show
     // stubOnError rings + amber "expected outcome" panel - branching no
@@ -3341,6 +3430,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         todoPos: afterPhase.todoPos,
       });
       lastTodoDock = appliedAfter.dock;
+      todoDockRef.current = lastTodoDock;
       stubAfterTodos =
         (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
         afterPhase.todos ||
@@ -3392,6 +3482,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       todoDock: lastTodoDock,
       todoSync: appliedAfter.sync,
       todoId: lastTodoDock && lastTodoDock.id,
+      todoDockRef,
       forceCollapsed:
         !!process.env.WAYGRAPH_VIDEO ||
         process.env.WAYGRAPH_MINI === "1" ||
@@ -3399,6 +3490,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           ? true
           : undefined,
     });
+    // Ring cycle / stubAfter may have advanced the dock - persist for next block.
+    if (todoDockRef.current) lastTodoDock = todoDockRef.current;
     await gate();
   }
   await teardownOverlay(page);

package/examples/saucedemo/package-lock.json

@@ -17,7 +17,7 @@
       }
     },
     "../..": {
-      "version": "0.12.46",
+      "version": "0.12.47",
       "license": "MIT",
       "dependencies": {
         "tsx": "^4.0.0"

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

@@ -1,4 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
+import type { StubCtx } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
 import { InventorySel } from "../inventory/methods/inventory-items.js";
 
@@ -15,7 +16,7 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   checkpoint: "CartPage",
   click: ".shopping_cart_link",
   verify: [Trait.url({ pathname: "/cart.html" })],
-  stubBefore: (ctx) => {
+  stubBefore: (ctx: StubCtx) => {
     ctx.title("Open cart");
     ctx.todoId("saucedemo-cart");
     ctx.todos([
@@ -40,7 +41,7 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
       },
     });
   },
-  stubAfter: (ctx) => {
+  stubAfter: (ctx: StubCtx) => {
     ctx.banner("Your cart");
     ctx.zoomOut(false);
     ctx.ring("items", {

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

@@ -1,4 +1,5 @@
 import { defineEffectBlock, checkpoint, type Checkpoint, type WaygraphInstanceOption } from "waygraph";
+import type { StubCtx } from "waygraph";
 import type { ItemInCart } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectAddableItems, InventorySel } from "./inventory-items.js";
@@ -34,7 +35,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
       },
     ],
     // Demo: zoom product -> add (stay zoomed), then badge after act.
-    stubBefore: (ctx) => {
+    stubBefore: (ctx: StubCtx) => {
       ctx.title("Pick a product");
       ctx.todoId("saucedemo-cart");
       ctx.todos([
@@ -66,7 +67,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       });
     },
-    stubAfter: (ctx) => {
+    stubAfter: (ctx: StubCtx) => {
       ctx.banner("In the cart");
       ctx.todoId("saucedemo-cart");
       ctx.todos([

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

@@ -1,4 +1,4 @@
-import { defineMethodBlock, checkpoint, Trait } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait, type StubCtx } from "waygraph";
 import type { LoginPage, LoginSubmitOutcome } from "../../../states/checkout.states.js";
 import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 
@@ -9,8 +9,10 @@ type LoginObserve = "success" | "failure";
  * Helper: defineMethodBlock
  * Route: saucedemo-web/methods/  (page URL /)
  *
- * Fills credentials and submits - never page.goto (nav-login owns that).
+ * Fills credentials and submits - never page.goto (nav-login Page hub owns that).
  * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
+ * stubBefore/stubAfter drive the floating todo dock (Method fill/click advances
+ * todoIndex mid-act; stubAfter marks complete / fail).
  */
 export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
@@ -47,7 +49,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         : [Trait.visible('[data-test="error"]')],
     // Open lifecycle: banner title, todos, Screen Studio camera zoom,
     // sequential highlight queue (appear / dwell / fade), focus + color.
-    stubBefore: (ctx) => {
+    stubBefore: (ctx: StubCtx) => {
       ctx.title("Signing in");
       ctx.todoId("saucedemo-login");
       ctx.todos([
@@ -82,18 +84,18 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         },
       });
     },
-    stubAfter: (ctx) => {
+    stubAfter: (ctx: StubCtx) => {
       // Fail branch lands on LoginPage with Epic sadface - do not ring the
       // inventory shelf. Success (LoggedIn) hands off to shopFlow.
       if (ctx.out && ctx.out.__state === "LoginPage") {
         ctx.title("Login blocked");
         ctx.todoId("saucedemo-login");
         ctx.todos([
-          { id: "login-user", text: "Enter username" },
-          { id: "login-pass", text: "Enter password" },
-          { id: "login-submit", text: "Click Login" },
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Click Login", done: true },
         ]);
-        ctx.todoIndex(2);
+        ctx.todoStyle("checklist");
         ctx.ring("error", {
           selector: '[data-test="error"]',
           label: "Login error banner",
@@ -123,7 +125,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         duration: true,
       });
     },
-    stubOnError: (ctx) => {
+    stubOnError: (ctx: StubCtx) => {
       ctx.title("Login failed");
       ctx.ring("error", {
         selector: '[data-test="error"]',

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

@@ -1,17 +1,23 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { definePageBlock, Trait } from "waygraph";
 import type { LoginPage } from "../../states/checkout.states.js";
+import { SubmitLoginActionBlock } from "./methods/submit-login.method.block.js";
 
 /**
- * Kind: Nav
- * Helper: defineNavBlock
+ * Kind: Page
+ * Helper: definePageBlock
  * Route: saucedemo-web/  (= /)
  *
- * page.goto to the login form lives here only. submit-login Action never navigates.
+ * Login screen hub. Deep-link via url; method submit-login hangs off this
+ * page (stubBefore/stubAfter todos live on the Method). Name stays
+ * `nav-login` so existing flows / chain specs keep working.
  */
-export const NavLoginBlock = defineNavBlock<LoginPage>({
+export const NavLoginBlock = definePageBlock<LoginPage>({
   name: "nav-login",
   description: "Goes to the Swag Labs login page.",
   checkpoint: "LoginPage",
   url: "/",
   verify: [Trait.visible("#login-button")],
+  methods: {
+    submitLogin: () => SubmitLoginActionBlock,
+  },
 });

package/package.json

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

@@ -17,7 +17,12 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   verify: [Trait.url({ pathname: "/cart.html" })],
   stubBefore: (ctx) => {
     ctx.title("Open cart");
-    ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+    ctx.todoId("saucedemo-cart");
+    ctx.todos([
+      { id: "cart-find", text: "Find the product" },
+      { id: "cart-add", text: "Add to cart" },
+      { id: "cart-open", text: "Open cart" },
+    ]);
     ctx.todoIndex(2);
     ctx.zoom(1.4);
     ctx.zoomOut(false);

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

@@ -36,7 +36,12 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     // 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.todoId("saucedemo-cart");
+      ctx.todos([
+        { id: "cart-find", text: "Find the product" },
+        { id: "cart-add", text: "Add to cart" },
+        { id: "cart-open", text: "Open cart" },
+      ]);
       ctx.todoIndex(0);
       ctx.zoom(1.35);
       ctx.zoomOut(false);
@@ -63,7 +68,12 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     },
     stubAfter: (ctx) => {
       ctx.banner("In the cart");
-      ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+      ctx.todoId("saucedemo-cart");
+      ctx.todos([
+        { id: "cart-find", text: "Find the product" },
+        { id: "cart-add", text: "Add to cart" },
+        { id: "cart-open", text: "Open cart" },
+      ]);
       ctx.todoIndex(1);
       ctx.zoomOut(false);
       ctx.ring("badge", {

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

@@ -1,4 +1,4 @@
-import { defineMethodBlock, checkpoint, Trait } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait, type StubCtx } from "waygraph";
 import type { LoginPage, LoginSubmitOutcome } from "../../../states/checkout.states.js";
 import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 
@@ -9,8 +9,10 @@ type LoginObserve = "success" | "failure";
  * Helper: defineMethodBlock
  * Route: saucedemo-web/methods/  (page URL /)
  *
- * Fills credentials and submits - never page.goto (nav-login owns that).
+ * Fills credentials and submits - never page.goto (nav-login Page hub owns that).
  * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
+ * stubBefore/stubAfter drive the floating todo dock (Method fill/click advances
+ * todoIndex mid-act; stubAfter marks complete / fail).
  */
 export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
@@ -47,9 +49,14 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         : [Trait.visible('[data-test="error"]')],
     // Open lifecycle: banner title, todos, Screen Studio camera zoom,
     // sequential highlight queue (appear / dwell / fade), focus + color.
-    stubBefore: (ctx) => {
+    stubBefore: (ctx: StubCtx) => {
       ctx.title("Signing in");
-      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoId("saucedemo-login");
+      ctx.todos([
+        { id: "login-user", text: "Enter username" },
+        { id: "login-pass", text: "Enter password" },
+        { id: "login-submit", text: "Click Login" },
+      ]);
       ctx.todoIndex(0);
       ctx.zoom(1.35);
       ctx.highlights({
@@ -77,13 +84,18 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         },
       });
     },
-    stubAfter: (ctx) => {
+    stubAfter: (ctx: StubCtx) => {
       // Fail branch lands on LoginPage with Epic sadface - do not ring the
       // inventory shelf. Success (LoggedIn) hands off to shopFlow.
       if (ctx.out && ctx.out.__state === "LoginPage") {
         ctx.title("Login blocked");
-        ctx.todos(["Enter username", "Enter password", "Click Login"]);
-        ctx.todoIndex(2);
+        ctx.todoId("saucedemo-login");
+        ctx.todos([
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Click Login", done: true },
+        ]);
+        ctx.todoStyle("checklist");
         ctx.ring("error", {
           selector: '[data-test="error"]',
           label: "Login error banner",
@@ -95,7 +107,12 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         return;
       }
       ctx.banner("Inventory");
-      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoId("saucedemo-login");
+      ctx.todos([
+        { id: "login-user", text: "Enter username" },
+        { id: "login-pass", text: "Enter password" },
+        { id: "login-submit", text: "Click Login" },
+      ]);
       ctx.todoIndex(2);
       // Landed on inventory - hand off to shopFlow for product -> cart zoom.
       ctx.ring("shelf", {
@@ -108,7 +125,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         duration: true,
       });
     },
-    stubOnError: (ctx) => {
+    stubOnError: (ctx: StubCtx) => {
       ctx.title("Login failed");
       ctx.ring("error", {
         selector: '[data-test="error"]',

package/templates/quickstart/src/blocks/saucedemo-web/nav-login.block.ts

@@ -1,17 +1,23 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { definePageBlock, Trait } from "waygraph";
 import type { LoginPage } from "../../states/checkout.states.js";
+import { SubmitLoginActionBlock } from "./methods/submit-login.method.block.js";
 
 /**
- * Kind: Nav
- * Helper: defineNavBlock
+ * Kind: Page
+ * Helper: definePageBlock
  * Route: saucedemo-web/  (= /)
  *
- * page.goto to the login form lives here only. submit-login Action never navigates.
+ * Login screen hub. Deep-link via url; method submit-login hangs off this
+ * page (stubBefore/stubAfter todos live on the Method). Name stays
+ * `nav-login` so existing flows / chain specs keep working.
  */
-export const NavLoginBlock = defineNavBlock<LoginPage>({
+export const NavLoginBlock = definePageBlock<LoginPage>({
   name: "nav-login",
   description: "Goes to the Swag Labs login page.",
   checkpoint: "LoginPage",
   url: "/",
   verify: [Trait.visible("#login-button")],
+  methods: {
+    submitLogin: () => SubmitLoginActionBlock,
+  },
 });