waygraph 0.13.7 → 0.15.0

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.ts

@@ -0,0 +1,22 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
+ *
+ * Fills the first name field only - self-loop on CheckoutInfoPage. Continue
+ * is its own Block (submit-checkout-info.method.block.ts).
+ */
+export const FillFirstNameBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+  name: "fill-first-name",
+  description: "Fills the first name field on the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(CheckoutInfoSel.firstName).fill("Ada");
+    },
+    resolve: () => checkpoint("CheckoutInfoPage"),
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.ts

@@ -0,0 +1,21 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
+ *
+ * Fills the last name field only - self-loop on CheckoutInfoPage.
+ */
+export const FillLastNameBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+  name: "fill-last-name",
+  description: "Fills the last name field on the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(CheckoutInfoSel.lastName).fill("Lovelace");
+    },
+    resolve: () => checkpoint("CheckoutInfoPage"),
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.ts

@@ -0,0 +1,21 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
+ *
+ * Fills the postal code field only - self-loop on CheckoutInfoPage.
+ */
+export const FillPostalCodeBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+  name: "fill-postal-code",
+  description: "Fills the postal code field on the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(CheckoutInfoSel.postalCode).fill("1000");
+    },
+    resolve: () => checkpoint("CheckoutInfoPage"),
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.ts

@@ -1,23 +1,22 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
 
 /**
  * Kind: Method
  * Helper: defineMethodBlock
  * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
  *
- * Fills shipping form and continues - never navigates itself
- * (nav-checkout-info already got here).
+ * Clicks Continue only - fields are filled by fill-first-name /
+ * fill-last-name / fill-postal-code (each its own Block). One Block, one
+ * action: submit.
  */
 export const SubmitCheckoutInfoBlock = defineMethodBlock<CheckoutInfoPage, CheckoutOverviewPage>({
   name: "submit-checkout-info",
-  description: "Fills in the shipping info form and continues to the order overview.",
+  description: "Continues from the shipping info form to the order overview.",
   instruction: {
     async act(page) {
-      await page.locator("#first-name").fill("Ada");
-      await page.locator("#last-name").fill("Lovelace");
-      await page.locator("#postal-code").fill("1000");
-      await page.locator("#continue").click();
+      await page.locator(CheckoutInfoSel.continueBtn).click();
     },
     resolve: () => checkpoint("CheckoutOverviewPage"),
     verify: [Trait.url({ pathname: "/checkout-step-two.html" })],

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/NAV.md

@@ -15,7 +15,9 @@ Order overview / finish page.
 | File | Kind | Notes |
 |------|------|-------|
 | `methods/finish-order.method.block.ts` | Method | Finish -> thank-you / OrderComplete |
+| `methods/checkout-overview.sel.ts` | helper | `CheckoutOverviewSel` (not a Block) |
 
 ## Related mem keys / checkpoints
 
 - Checkpoints: `CheckoutOverviewPage`, `OrderComplete`
+- Sel: `CheckoutOverviewSel` (`methods/checkout-overview.sel.ts`) - DOM only, not mem

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/methods/checkout-overview.sel.ts

@@ -0,0 +1,9 @@
+/**
+ * DOM selectors for the order overview / completion page
+ * (`/checkout-step-two.html`). Convention: DOM strings live in `*Sel` next
+ * to the page, not inlined in each Block.
+ */
+export const CheckoutOverviewSel = {
+  finishBtn: "#finish",
+  completeHeader: ".complete-header",
+};

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

@@ -1,5 +1,6 @@
 import { defineMethodBlock, checkpoint, Trait, narrate } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
+import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
 
 /**
  * Kind: Method
@@ -13,17 +14,17 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
   description: "Places the order and confirms the 'Thank you for your order!' completion page.",
   instruction: {
     async act(page) {
-      const finishButton = page.locator("#finish");
+      const finishButton = page.locator(CheckoutOverviewSel.finishBtn);
       await narrate(finishButton, "Placing the order", () => finishButton.click());
     },
     resolve: () => checkpoint("OrderComplete"),
-    verify: [Trait.text(".complete-header", "Thank you for your order!")],
+    verify: [Trait.text(CheckoutOverviewSel.completeHeader, "Thank you for your order!")],
     stubBefore: {
-      finish: { selector: "#finish", label: "Finish" },
+      finish: { selector: CheckoutOverviewSel.finishBtn, label: "Finish" },
     },
     stubAfter: {
       thanks: {
-        selector: ".complete-header",
+        selector: CheckoutOverviewSel.completeHeader,
         label: "Order confirmed",
         detail: "Thank you for your order!",
         duration: true,
@@ -42,7 +43,7 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Completion page is the durable proof",
         detail: "The thank-you header is what verify asserts on.",
         tag: "YAP",
-        selector: ".complete-header",
+        selector: CheckoutOverviewSel.completeHeader,
         duration: 2500,
         fastMode: 700,
       },
@@ -50,7 +51,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",
-        selector: ".complete-header",
+        selector: CheckoutOverviewSel.completeHeader,
         duration: true,
         fastMode: 500,
       },

package/templates/quickstart/src/blocks/saucedemo-web/ff-owner-auth.block.ts

@@ -1,5 +1,7 @@
 import { fastForwardComposeBlock } from "waygraph";
 import { NavLoginBlock } from "./nav-login.block.js";
+import { FillUsernameBlock } from "./methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "./methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "./methods/submit-login-for-flow.js";
 
 /**
@@ -7,11 +9,14 @@ import { SubmitLoginForFlow } from "./methods/submit-login-for-flow.js";
  * Helper: fastForwardComposeBlock
  * Route: saucedemo-web/  (auth prefix)
  *
- * Collapses nav-login + submit-login into one opaque demo/run step so
- * checkout demos skip watching auth. Use --ff-expand to gate inners again.
+ * Collapses nav-login + fill-username + fill-password + submit-login into
+ * one opaque demo/run step so checkout demos skip watching auth. Use
+ * --ff-expand to gate inners again (they show as 4 separate steps).
  * loginFlow stays expanded for Sign In episode narration.
  */
 export const FfOwnerAuthBlock = fastForwardComposeBlock("ff-owner-auth", [
   NavLoginBlock,
+  FillUsernameBlock,
+  FillPasswordBlock,
   SubmitLoginForFlow,
 ]);

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

@@ -37,16 +37,20 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     // Demo: zoom product -> add (stay zoomed), then badge after act.
     stubBefore: (ctx: StubCtx) => {
       ctx.title("Pick a product · tablet");
-      // Device showcase: tablet portrait (toast + lerp from mobile landscape).
       ctx.device("tablet");
       ctx.portrait();
-      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.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Tap Login", done: true },
+          { id: "cart-find", text: "Find the product" },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 3 },
+      );
       ctx.zoom(1.35);
       ctx.zoomOut(false);
       ctx.highlights({
@@ -72,13 +76,18 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     },
     stubAfter: (ctx: StubCtx) => {
       ctx.banner("In the 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.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Tap Login", done: true },
+          { id: "cart-find", text: "Find the product", done: true },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 4 },
+      );
       ctx.zoomOut(false);
       ctx.ring("badge", {
         selector: InventorySel.cartBadge,
@@ -86,7 +95,6 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         detail: "Item count updated",
         focus: true,
         color: "#86efac",
-        zoom: 1.6,
         zoomOut: false,
         duration: true,
       });

package/templates/quickstart/src/blocks/saucedemo-web/inventory/nav-item-detail.block.ts

@@ -3,7 +3,7 @@ import type { ItemDetailPage } from "../../../states/checkout.states.js";
 import { SelectedItem } from "../../../states/checkout.mem-keys.js";
 import {
   collectInventoryItems,
-  inventoryItemTitleSelector,
+  InventorySel,
 } from "./methods/inventory-items.js";
 
 /**
@@ -19,7 +19,7 @@ export const NavItemDetailBlock = defineMemNavBlock<ItemDetailPage>({
   description: "Opens the product named by mem (saucedemo.selectedItem) on its detail page.",
   checkpoint: "ItemDetailPage",
   requires: [SelectedItem.key],
-  click: (mem) => inventoryItemTitleSelector(mem.get(SelectedItem.key).id),
+  click: (mem) => InventorySel.title(mem.get(SelectedItem.key).id),
   verify: [Trait.url({ pathname: "/inventory-item.html" })],
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
     const items = await collectInventoryItems(page);
@@ -28,7 +28,7 @@ export const NavItemDetailBlock = defineMemNavBlock<ItemDetailPage>({
       label: `Open "${item.name}" details`,
       key: SelectedItem.key,
       value: item,
-      highlight: inventoryItemTitleSelector(item.id),
+      highlight: InventorySel.title(item.id),
     }));
   },
 });

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/NAV.md

@@ -23,3 +23,4 @@ Single product detail page, plus nav edges that return to catalog
 ## Related mem keys / checkpoints
 
 - Checkpoints: `ItemDetailPage`, `LoggedIn` (after back / continue), `OrderComplete` (from for back-to-products)
+- Sel: `ItemDetailSel` (`item-detail.sel.ts`) - DOM only, not mem

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/item-detail.sel.ts

@@ -0,0 +1,9 @@
+/**
+ * DOM selectors for the item detail page (`/inventory-item.html`) and the
+ * order-complete page's equivalent nav control. Convention: DOM strings
+ * live in `*Sel` next to the page, not inlined in each Block.
+ */
+export const ItemDetailSel = {
+  continueShoppingBtn: "#continue-shopping",
+  backToProductsBtn: "#back-to-products",
+};

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-back-to-inventory.block.ts

@@ -1,5 +1,6 @@
 import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
+import { ItemDetailSel } from "./item-detail.sel.js";
 
 /**
  * Kind: Nav
@@ -13,6 +14,6 @@ export const NavBackToInventoryBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-back-to-inventory",
   description: "Clicks 'Back to products' on the item detail page.",
   checkpoint: "LoggedIn",
-  click: "#back-to-products",
+  click: ItemDetailSel.backToProductsBtn,
   verify: [Trait.url({ pathname: "/inventory.html" })],
 });

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-back-to-products.block.ts

@@ -1,5 +1,6 @@
 import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
+import { ItemDetailSel } from "./item-detail.sel.js";
 
 /**
  * Kind: Nav
@@ -13,6 +14,6 @@ export const NavBackToProductsBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-back-to-products",
   description: "Clicks 'Back Home' on the order confirmation page.",
   checkpoint: "LoggedIn",
-  click: "#back-to-products",
+  click: ItemDetailSel.backToProductsBtn,
   verify: [Trait.url({ pathname: "/inventory.html" })],
 });

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-continue-shopping.block.ts

@@ -1,5 +1,6 @@
 import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
+import { ItemDetailSel } from "./item-detail.sel.js";
 
 /**
  * Kind: Nav
@@ -12,6 +13,6 @@ export const NavContinueShoppingBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-continue-shopping",
   description: "Clicks 'Continue Shopping' on the cart page.",
   checkpoint: "LoggedIn",
-  click: "#continue-shopping",
+  click: ItemDetailSel.continueShoppingBtn,
   verify: [Trait.url({ pathname: "/inventory.html" })],
 });

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

@@ -0,0 +1,51 @@
+import { defineMethodBlock, checkpoint, type StubCtx } from "waygraph";
+import type { LoginPage } from "../../../states/checkout.states.js";
+import { LoginCreds } from "../../../states/checkout.mem-keys.js";
+import { LoginSel } from "./login.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/methods/  (page URL /)
+ *
+ * Fills the password field only - self-loop on LoginPage. See
+ * fill-username.method.block.ts for why this is split from submit.
+ */
+export const FillPasswordBlock = defineMethodBlock<LoginPage, LoginPage>({
+  name: "fill-password",
+  description: "Fills the password field on the login form.",
+  requires: [LoginCreds.key],
+  instruction: {
+    async act(page, _input, mem) {
+      const { password } = mem.get(LoginCreds.key);
+      await page.locator(LoginSel.password).fill(password);
+    },
+    resolve: () => checkpoint("LoginPage"),
+    stubBefore: (ctx: StubCtx) => {
+      ctx.highlights({
+        password: {
+          selector: LoginSel.password,
+          label: "Password",
+          todo: "login-pass",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.4,
+        },
+      });
+    },
+    stubAfter: (ctx: StubCtx) => {
+      ctx.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Tap Login" },
+          { id: "cart-find", text: "Find the product" },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 2 },
+      );
+    },
+  },
+});

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

@@ -0,0 +1,69 @@
+import { defineMethodBlock, checkpoint, type StubCtx } from "waygraph";
+import type { LoginPage } from "../../../states/checkout.states.js";
+import { LoginCreds } from "../../../states/checkout.mem-keys.js";
+import { LoginSel } from "./login.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/methods/  (page URL /)
+ *
+ * Fills the username field only - self-loop on LoginPage, no submit, no
+ * page.goto. Submit is its own Block (submit-login.method.block.ts) so the
+ * graph/demo show fill vs submit as real, distinct steps instead of one
+ * Block doing "input username and password and login at the same time".
+ */
+export const FillUsernameBlock = defineMethodBlock<LoginPage, LoginPage>({
+  name: "fill-username",
+  description: "Fills the username field on the login form.",
+  requires: [LoginCreds.key],
+  instruction: {
+    async act(page, _input, mem) {
+      const { username } = mem.get(LoginCreds.key);
+      await page.locator(LoginSel.username).fill(username);
+    },
+    resolve: () => checkpoint("LoginPage"),
+    stubBefore: (ctx: StubCtx) => {
+      ctx.title("Signing in · mobile");
+      ctx.device("mobile");
+      ctx.portrait();
+      ctx.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username" },
+          { id: "login-pass", text: "Enter password" },
+          { id: "login-submit", text: "Tap Login" },
+          { id: "cart-find", text: "Find the product" },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 0 },
+      );
+      ctx.zoom(1.35);
+      ctx.highlights({
+        username: {
+          selector: LoginSel.username,
+          label: "Username",
+          todo: "login-user",
+          focus: true,
+          color: "#c9a6ff",
+          zoom: 1.4,
+        },
+      });
+    },
+    stubAfter: (ctx: StubCtx) => {
+      ctx.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password" },
+          { id: "login-submit", text: "Tap Login" },
+          { id: "cart-find", text: "Find the product" },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 1 },
+      );
+    },
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/methods/login.sel.ts

@@ -0,0 +1,13 @@
+/**
+ * DOM selectors for the login route (`/`) and its logout burger menu.
+ * Convention: DOM strings live in `*Sel` next to the page, not inlined in
+ * each Block.
+ */
+export const LoginSel = {
+  username: "#user-name",
+  password: "#password",
+  loginButton: "#login-button",
+  errorBanner: '[data-test="error"]',
+  burgerMenuButton: "#react-burger-menu-btn",
+  logoutLink: "#logout_sidebar_link",
+};

package/templates/quickstart/src/blocks/saucedemo-web/methods/submit-login-for-flow.ts

@@ -1,13 +1,13 @@
 import type { DefinedBlock } from "waygraph";
 import type { LoginPage, LoggedIn } from "../../../states/checkout.states.js";
-import { SubmitLoginActionBlock } from "./submit-login.method.block.js";
+import { SubmitLoginBlock } from "./submit-login.method.block.js";
 
 /**
  * Kind: helper (not a discoverable Block file)
- * Helper: typed alias over SubmitLoginActionBlock
+ * Helper: typed alias over SubmitLoginBlock
  * Route: saucedemo-web/methods/  (page URL /)
  *
  * DefinedBlock cast so linear Flows can chain .withVerify on Out=LoggedIn;
- * runtime still branches on bad credentials via SubmitLoginActionBlock.
+ * runtime still branches on bad credentials via SubmitLoginBlock.
  */
-export const SubmitLoginForFlow = SubmitLoginActionBlock as unknown as DefinedBlock<LoginPage, LoggedIn>;
+export const SubmitLoginForFlow = SubmitLoginBlock as unknown as DefinedBlock<LoginPage, LoggedIn>;