waygraph 0.15.0 → 0.15.2

package/dist/cli.js

@@ -3809,6 +3809,62 @@ async function hideRing(page) {
     .catch(() => {});
 }
 
+/**
+ * Real navigation wipes document + overlay helpers. Reinstall and re-paint
+ * carried todos / device / optional stubBefore ring so keep-dock and nav
+ * highlights do not vanish until the next ctx.todos() / stubAfter (PIA #15).
+ */
+async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef) {
+  const needs =
+    (await page
+      .evaluate(() => !window.__wgSyncTodos || !document.getElementById("wg-ring"))
+      .catch(() => true)) || false;
+  if (!needs) {
+    // Overlay survived (SPA / no full document wipe) - still refresh dock
+    // if Node has a carry and the DOM lost .wg-todo-dock.
+    const hasDock = await page
+      .evaluate(() => !!document.querySelector(".wg-todo-dock, #wg-todo-dock"))
+      .catch(() => false);
+    if (hasDock || !todoDockRef || !todoDockRef.current) return;
+  }
+  await installOverlay(page);
+  const dock = todoDockRef && todoDockRef.current;
+  if (dock) {
+    await page
+      .evaluate((d) => {
+        if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "set", dock: d });
+      }, dock)
+      .catch(() => {});
+  }
+  if (deviceRef && deviceRef.current) {
+    await applyDeviceToPage(page, deviceRef.current, "set").catch(() => {});
+  }
+  // Re-show first matching stubBefore ring if selector still exists (sidebar
+  // nav targets often survive the route change).
+  const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+  for (const h of stubs) {
+    if (!h || !h.selector) continue;
+    const box = await page
+      .evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const r = el.getBoundingClientRect();
+        if (r.width < 2 || r.height < 2) return null;
+        return { x: r.x, y: r.y, width: r.width, height: r.height };
+      }, h.selector)
+      .catch(() => null);
+    if (box) {
+      await showRing(page, box, formatHighlightCaption(h), h.tone || "planned", {
+        size: h.size,
+        weight: h.weight,
+        selector: h.selector,
+        focus: !!h.focus,
+      }).catch(() => {});
+      break;
+    }
+  }
+}
+
 /**
  * Removes every overlay element (panel, ring, ring-label, cursor,
  * click-pulse, banner) and stops the live resize/scroll ring tracker, once
@@ -4542,6 +4598,7 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
       // of leaving it lit until the next Block's own before-panel clears
       // it - it was sticking around through the whole rest of the step.
       await hideRing(page);
+      await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
       return result;
     };
   }
@@ -4670,6 +4727,8 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
       }
       await new Promise((res) => setTimeout(res, clickPostPop()));
       await hideRing(page);
+      // Full document navigation drops #wg-todo-dock + rings; restore carry.
+      await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
       return result;
     };
   }
@@ -4921,17 +4980,21 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     if (sync === "set" && dock) {
       if (!parallel) todoDockById.clear();
       todoDockById.set(dockRegistryKey(dock), dock);
+      return;
+    }
+    // keep: refresh / re-seed so syncAllTodoDocks never sees an empty map
+    // while lastTodoDock still carries (nav wipe + mid-act advance).
+    if (sync === "keep" && dock) {
+      todoDockById.set(dockRegistryKey(dock), dock);
     }
   };
   const syncAllTodoDocks = async (opts) => {
     const docks = [...todoDockById.values()];
     const parallel = !!(opts && opts.parallel);
     if (!docks.length) {
-      await page
-        .evaluate(() => {
-          if (window.__wgSyncTodos) window.__wgSyncTodos({ sync: "clear" });
-        })
-        .catch(() => {});
+      // Empty registry: do NOT clear the DOM. renderBefore/After may have
+      // just painted from lastTodoDock (keep). Clearing here made todos
+      // vanish until the next ctx.todos() set (PIA #15).
       return;
     }
     await page

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

@@ -38,9 +38,9 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
       cart: {
         selector: CartSel.cartLink,
         label: "Cart",
-        detail: "Open cart",
+        detail: "tone: planned (purple) - open cart",
+        tone: "planned",
         focus: true,
-        color: "#c9a6ff",
         zoomOut: false,
         followMouse: false,
         weight: "bold",
@@ -56,9 +56,9 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
     ctx.ring("items", {
       selector: InventorySel.cartItem,
       label: "Cart items",
-      detail: "Product landed in cart",
+      detail: "tone: success (green) - product in cart",
+      tone: "success",
       focus: true,
-      color: "#86efac",
       zoomOut: true,
       followMouse: false,
       duration: true,

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts

@@ -20,13 +20,20 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
     resolve: () => checkpoint("OrderComplete"),
     verify: [Trait.text(CheckoutOverviewSel.completeHeader, "Thank you for your order!")],
     stubBefore: {
-      finish: { selector: CheckoutOverviewSel.finishBtn, label: "Finish" },
+      finish: {
+        selector: CheckoutOverviewSel.finishBtn,
+        label: "Finish",
+        detail: "tone: warning (yellow) - place order",
+        tone: "warning",
+        weight: "bold",
+      },
     },
     stubAfter: {
       thanks: {
         selector: CheckoutOverviewSel.completeHeader,
         label: "Order confirmed",
-        detail: "Thank you for your order!",
+        detail: "tone: success (green) - thank you!",
+        tone: "success",
         duration: true,
       },
     },
@@ -37,12 +44,14 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Checkout is a short pipeline",
         detail: "Cart -> info -> overview -> done. You just placed the order.",
         tag: "YAP",
+        tone: "info",
         duration: true,
       },
       {
         caption: "Completion page is the durable proof",
-        detail: "The thank-you header is what verify asserts on.",
+        detail: "tone: success - the thank-you header is what verify asserts on.",
         tag: "YAP",
+        tone: "success",
         selector: CheckoutOverviewSel.completeHeader,
         duration: 2500,
         fastMode: 700,
@@ -51,6 +60,7 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Episode continues after this yap",
         detail: "Next step rings the same banner, then you move on.",
         tag: "YAP",
+        tone: "planned",
         selector: CheckoutOverviewSel.completeHeader,
         duration: true,
         fastMode: 500,

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

@@ -57,17 +57,18 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         product: {
           selector: InventorySel.title(DEMO_PRODUCT_ID),
           label: "Sauce Labs Backpack",
-          detail: "Zoom the product",
+          detail: "tone: info (blue)",
+          tone: "info",
           focus: true,
-          color: "#c9a6ff",
           zoom: 1.45,
           zoomOut: false,
         },
         add: {
           selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
           label: "Add to cart",
+          detail: "tone: success (green)",
+          tone: "success",
           focus: true,
-          color: "#86efac",
           zoom: 1.5,
           zoomOut: false,
           weight: "bold",
@@ -92,9 +93,9 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
       ctx.ring("badge", {
         selector: InventorySel.cartBadge,
         label: "Cart badge",
-        detail: "Item count updated",
+        detail: "tone: success (green) - count updated",
+        tone: "success",
         focus: true,
-        color: "#86efac",
         zoomOut: false,
         duration: true,
       });

package/examples/saucedemo/src/blocks/saucedemo-web/methods/fill-password.method.block.ts

@@ -26,9 +26,10 @@ export const FillPasswordBlock = defineMethodBlock<LoginPage, LoginPage>({
         password: {
           selector: LoginSel.password,
           label: "Password",
+          detail: "tone: planned (purple)",
           todo: "login-pass",
+          tone: "planned",
           focus: true,
-          color: "#c9a6ff",
           zoom: 1.4,
         },
       });

package/examples/saucedemo/src/blocks/saucedemo-web/methods/fill-username.method.block.ts

@@ -44,9 +44,10 @@ export const FillUsernameBlock = defineMethodBlock<LoginPage, LoginPage>({
         username: {
           selector: LoginSel.username,
           label: "Username",
+          detail: "tone: info (blue)",
           todo: "login-user",
+          tone: "info",
           focus: true,
-          color: "#c9a6ff",
           zoom: 1.4,
         },
       });

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

@@ -48,9 +48,10 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
         submit: {
           selector: LoginSel.loginButton,
           label: "Login",
+          detail: "tone: warning (yellow)",
           todo: "login-submit",
+          tone: "warning",
           focus: true,
-          color: "#86efac",
           zoom: 1.55,
           weight: "bold",
           gesture: "tap",
@@ -72,9 +73,9 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
         ctx.ring("error", {
           selector: LoginSel.errorBanner,
           label: "Login error banner",
+          detail: "tone: danger (red)",
           tone: "danger",
           focus: true,
-          color: "#f87171",
           duration: true,
         });
         return;
@@ -96,9 +97,9 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
       ctx.ring("shelf", {
         selector: ".inventory_list",
         label: "Product shelf",
-        detail: "Ready to shop",
+        detail: "tone: success (green) - ready to shop",
+        tone: "success",
         focus: true,
-        color: "#c9a6ff",
         zoom: 1.25,
         duration: true,
       });
@@ -108,9 +109,9 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
       ctx.ring("error", {
         selector: LoginSel.errorBanner,
         label: "Login error banner",
+        detail: "tone: danger (red)",
         tone: "danger",
         focus: true,
-        color: "#f87171",
         duration: true,
       });
     },

package/package.json

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

@@ -38,9 +38,9 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
       cart: {
         selector: CartSel.cartLink,
         label: "Cart",
-        detail: "Open cart",
+        detail: "tone: planned (purple) - open cart",
+        tone: "planned",
         focus: true,
-        color: "#c9a6ff",
         zoomOut: false,
         followMouse: false,
         weight: "bold",
@@ -56,9 +56,9 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
     ctx.ring("items", {
       selector: InventorySel.cartItem,
       label: "Cart items",
-      detail: "Product landed in cart",
+      detail: "tone: success (green) - product in cart",
+      tone: "success",
       focus: true,
-      color: "#86efac",
       zoomOut: true,
       followMouse: false,
       duration: true,

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts

@@ -20,13 +20,20 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
     resolve: () => checkpoint("OrderComplete"),
     verify: [Trait.text(CheckoutOverviewSel.completeHeader, "Thank you for your order!")],
     stubBefore: {
-      finish: { selector: CheckoutOverviewSel.finishBtn, label: "Finish" },
+      finish: {
+        selector: CheckoutOverviewSel.finishBtn,
+        label: "Finish",
+        detail: "tone: warning (yellow) - place order",
+        tone: "warning",
+        weight: "bold",
+      },
     },
     stubAfter: {
       thanks: {
         selector: CheckoutOverviewSel.completeHeader,
         label: "Order confirmed",
-        detail: "Thank you for your order!",
+        detail: "tone: success (green) - thank you!",
+        tone: "success",
         duration: true,
       },
     },
@@ -37,12 +44,14 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Checkout is a short pipeline",
         detail: "Cart -> info -> overview -> done. You just placed the order.",
         tag: "YAP",
+        tone: "info",
         duration: true,
       },
       {
         caption: "Completion page is the durable proof",
-        detail: "The thank-you header is what verify asserts on.",
+        detail: "tone: success - the thank-you header is what verify asserts on.",
         tag: "YAP",
+        tone: "success",
         selector: CheckoutOverviewSel.completeHeader,
         duration: 2500,
         fastMode: 700,
@@ -51,6 +60,7 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Episode continues after this yap",
         detail: "Next step rings the same banner, then you move on.",
         tag: "YAP",
+        tone: "planned",
         selector: CheckoutOverviewSel.completeHeader,
         duration: true,
         fastMode: 500,

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

@@ -57,17 +57,18 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         product: {
           selector: InventorySel.title(DEMO_PRODUCT_ID),
           label: "Sauce Labs Backpack",
-          detail: "Zoom the product",
+          detail: "tone: info (blue)",
+          tone: "info",
           focus: true,
-          color: "#c9a6ff",
           zoom: 1.45,
           zoomOut: false,
         },
         add: {
           selector: InventorySel.addBtn(DEMO_PRODUCT_ID),
           label: "Add to cart",
+          detail: "tone: success (green)",
+          tone: "success",
           focus: true,
-          color: "#86efac",
           zoom: 1.5,
           zoomOut: false,
           weight: "bold",
@@ -92,9 +93,9 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
       ctx.ring("badge", {
         selector: InventorySel.cartBadge,
         label: "Cart badge",
-        detail: "Item count updated",
+        detail: "tone: success (green) - count updated",
+        tone: "success",
         focus: true,
-        color: "#86efac",
         zoomOut: false,
         duration: true,
       });

package/templates/quickstart/src/blocks/saucedemo-web/methods/fill-password.method.block.ts

@@ -26,9 +26,10 @@ export const FillPasswordBlock = defineMethodBlock<LoginPage, LoginPage>({
         password: {
           selector: LoginSel.password,
           label: "Password",
+          detail: "tone: planned (purple)",
           todo: "login-pass",
+          tone: "planned",
           focus: true,
-          color: "#c9a6ff",
           zoom: 1.4,
         },
       });

package/templates/quickstart/src/blocks/saucedemo-web/methods/fill-username.method.block.ts

@@ -44,9 +44,10 @@ export const FillUsernameBlock = defineMethodBlock<LoginPage, LoginPage>({
         username: {
           selector: LoginSel.username,
           label: "Username",
+          detail: "tone: info (blue)",
           todo: "login-user",
+          tone: "info",
           focus: true,
-          color: "#c9a6ff",
           zoom: 1.4,
         },
       });

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

@@ -48,9 +48,10 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
         submit: {
           selector: LoginSel.loginButton,
           label: "Login",
+          detail: "tone: warning (yellow)",
           todo: "login-submit",
+          tone: "warning",
           focus: true,
-          color: "#86efac",
           zoom: 1.55,
           weight: "bold",
           gesture: "tap",
@@ -72,9 +73,9 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
         ctx.ring("error", {
           selector: LoginSel.errorBanner,
           label: "Login error banner",
+          detail: "tone: danger (red)",
           tone: "danger",
           focus: true,
-          color: "#f87171",
           duration: true,
         });
         return;
@@ -96,9 +97,9 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
       ctx.ring("shelf", {
         selector: ".inventory_list",
         label: "Product shelf",
-        detail: "Ready to shop",
+        detail: "tone: success (green) - ready to shop",
+        tone: "success",
         focus: true,
-        color: "#c9a6ff",
         zoom: 1.25,
         duration: true,
       });
@@ -108,9 +109,9 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>
       ctx.ring("error", {
         selector: LoginSel.errorBanner,
         label: "Login error banner",
+        detail: "tone: danger (red)",
         tone: "danger",
         focus: true,
-        color: "#f87171",
         duration: true,
       });
     },