waygraph 0.13.7 → 0.14.0

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>;

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

@@ -1,6 +1,6 @@
 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";
+import { LoginSel } from "./login.sel.js";
 
 type LoginObserve = "success" | "failure";
 
@@ -9,30 +9,26 @@ type LoginObserve = "success" | "failure";
  * Helper: defineMethodBlock
  * Route: saucedemo-web/methods/  (page URL /)
  *
- * Fills credentials and submits - never page.goto (nav-login Page hub owns that).
+ * Clicks Login only - never page.goto (nav-login Page hub owns that), never
+ * fills fields (fill-username.method.block.ts / fill-password.method.block.ts
+ * already did that). One Block, one action: submit.
  * 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>({
+export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
-  description: "Logs a user in when credentials are valid; stays on LoginPage when auth fails.",
-  requires: [LoginCreds.key],
+  description: "Submits the login form; stays on LoginPage when auth fails.",
   instruction: {
-    async act(page, _input, mem) {
-      const { username, password } = mem.get(LoginCreds.key);
-      await page.locator("#user-name").fill(username);
-      await page.locator("#password").fill(password);
+    async act(page) {
       // noWaitAfter: observe owns the inventory URL wait. Default click
       // navigation-wait can hang under waygraph auto's demo cursor patch.
-      await page.locator("#login-button").click({ noWaitAfter: true });
+      await page.locator(LoginSel.loginButton).click({ noWaitAfter: true });
     },
     async observe(page): Promise<LoginObserve> {
       // Race inventory nav vs error banner - locked_out / wrong password show
       // Epic sadface immediately; do not burn the full inventory timeout.
       const inventory = page.waitForURL(/\/inventory\.html/, { timeout: 8_000 }).then(() => "success" as const);
       const errorBanner = page
-        .locator('[data-test="error"]')
+        .locator(LoginSel.errorBanner)
         .first()
         .waitFor({ state: "visible", timeout: 8_000 })
         .then(() => "failure" as const);
@@ -46,40 +42,13 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     verify: (out) =>
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
-        : [Trait.visible('[data-test="error"]')],
-    // Open lifecycle: banner title, todos, Screen Studio camera zoom,
-    // sequential highlight queue (appear / dwell / fade), focus + color.
+        : [Trait.visible(LoginSel.errorBanner)],
     stubBefore: (ctx: StubCtx) => {
-      ctx.title("Signing in · mobile");
-      // 0.13.3: mobile portrait + touch; tap Login.
-      ctx.device("mobile");
-      ctx.portrait();
-      ctx.todoId("saucedemo-login");
-      ctx.todos([
-        { id: "login-user", text: "Enter username" },
-        { id: "login-pass", text: "Enter password" },
-        { id: "login-submit", text: "Tap Login" },
-      ]);
-      ctx.todoIndex(0);
-      ctx.zoom(1.35);
       ctx.highlights({
-        username: {
-          selector: "#user-name",
-          label: "Username",
-          focus: true,
-          color: "#c9a6ff",
-          zoom: 1.4,
-        },
-        password: {
-          selector: "#password",
-          label: "Password",
-          focus: true,
-          color: "#c9a6ff",
-          zoom: 1.4,
-        },
         submit: {
-          selector: "#login-button",
+          selector: LoginSel.loginButton,
           label: "Login",
+          todo: "login-submit",
           focus: true,
           color: "#86efac",
           zoom: 1.55,
@@ -89,19 +58,19 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       });
     },
     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", done: true },
-          { id: "login-pass", text: "Enter password", done: true },
-          { id: "login-submit", text: "Click Login", done: true },
-        ]);
-        ctx.todoStyle("checklist");
+        ctx.todos(
+          "saucedemo",
+          [
+            { id: "login-user", text: "Enter username", done: true },
+            { id: "login-pass", text: "Enter password", done: true },
+            { id: "login-submit", text: "Click Login", done: true },
+          ],
+          { title: "Sign in", style: "checklist" },
+        );
         ctx.ring("error", {
-          selector: '[data-test="error"]',
+          selector: LoginSel.errorBanner,
           label: "Login error banner",
           tone: "danger",
           focus: true,
@@ -111,16 +80,19 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         return;
       }
       ctx.banner("Inventory · landscape");
-      // Rotate mobile to landscape on the product shelf (toast + lerp).
       ctx.landscape();
-      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.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.ring("shelf", {
         selector: ".inventory_list",
         label: "Product shelf",
@@ -134,7 +106,7 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     stubOnError: (ctx: StubCtx) => {
       ctx.title("Login failed");
       ctx.ring("error", {
-        selector: '[data-test="error"]',
+        selector: LoginSel.errorBanner,
         label: "Login error banner",
         tone: "danger",
         focus: true,

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

@@ -1,5 +1,6 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
+import { LoginSel } from "./login.sel.js";
 
 /**
  * Kind: Method
@@ -13,10 +14,10 @@ export const SubmitLogoutBlock = defineMethodBlock<LoggedIn, LoginPage>({
   description: "Opens the burger menu and logs out.",
   instruction: {
     async act(page) {
-      await page.locator("#react-burger-menu-btn").click();
-      await page.locator("#logout_sidebar_link").click();
+      await page.locator(LoginSel.burgerMenuButton).click();
+      await page.locator(LoginSel.logoutLink).click();
     },
     resolve: () => checkpoint("LoginPage"),
-    verify: [Trait.visible("#login-button")],
+    verify: [Trait.visible(LoginSel.loginButton)],
   },
 });

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

@@ -1,23 +1,31 @@
 import { definePageBlock, Trait } from "waygraph";
 import type { LoginPage } from "../../states/checkout.states.js";
-import { SubmitLoginActionBlock } from "./methods/submit-login.method.block.js";
+import { FillUsernameBlock } from "./methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "./methods/fill-password.method.block.js";
+import { SubmitLoginBlock } from "./methods/submit-login.method.block.js";
+import { LoginSel } from "./methods/login.sel.js";
 
 /**
  * Kind: Page
  * Helper: definePageBlock
  * Route: saucedemo-web/  (= /)
  *
- * 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.
+ * Login screen hub. Deep-link via url; fill-username / fill-password /
+ * submit-login hang off this page as three atomic Methods - fill-* are
+ * self-loops (LoginPage -> LoginPage), submit-login owns the one real
+ * transition (LoginPage -> LoggedIn|LoginPage). No single Block both fills
+ * and submits. Name stays `nav-login` so existing flows / chain specs keep
+ * working.
  */
 export const NavLoginBlock = definePageBlock<LoginPage>({
   name: "nav-login",
   description: "Goes to the Swag Labs login page.",
   checkpoint: "LoginPage",
   url: "/",
-  verify: [Trait.visible("#login-button")],
+  verify: [Trait.visible(LoginSel.loginButton)],
   methods: {
-    submitLogin: () => SubmitLoginActionBlock,
+    fillUsername: () => FillUsernameBlock,
+    fillPassword: () => FillPasswordBlock,
+    submitLogin: () => SubmitLoginBlock,
   },
 });

package/templates/quickstart/src/flows/checkout-then-browse-again.flow.ts

@@ -9,10 +9,15 @@ import type {
   OrderComplete,
 } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 import { NavBackToProductsBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-products.block.js";
@@ -23,21 +28,31 @@ const engine = new Engine({ headless: false, slowMo: 250 });
 // (proves OrderComplete -> LoggedIn without a goto teleport).
 export const checkoutThenBrowseAgainFlow = withTitle(
   engine.defineFlow<
+    LoginPage,
+    LoginPage,
     LoginPage,
     LoggedIn,
     ItemInCart,
     CartPage,
     CheckoutInfoPage,
+    CheckoutInfoPage,
+    CheckoutInfoPage,
+    CheckoutInfoPage,
     CheckoutOverviewPage,
     OrderComplete,
     LoggedIn
   >([
     start,
     NavLoginBlock,
+    FillUsernameBlock,
+    FillPasswordBlock,
     SubmitLoginForFlow,
     AddToCartBlock,
     NavCartBlock,
     NavCheckoutInfoBlock,
+    FillFirstNameBlock,
+    FillLastNameBlock,
+    FillPostalCodeBlock,
     SubmitCheckoutInfoBlock,
     FinishOrderBlock,
     NavBackToProductsBlock,

package/templates/quickstart/src/flows/checkout.flow.ts

@@ -11,12 +11,23 @@ import { FfOwnerAuthBlock } from "../blocks/saucedemo-web/ff-owner-auth.block.js
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
 const engine = new Engine({ headless: false, slowMo: 250 });
 
-// Auth is one FFCompose step so demo pacing skips login; --ff-expand for inners.
+// Atomic nav/action per real URL after auth - the shape `waygraph auto` discovers.
+// Auth is one FFCompose step (ff-owner-auth) so demo pacing skips login yap;
+// use --ff-expand (or loginFlow) when you need per-step auth narration.
+//
+// Demo narration showcase (waygraph 0.11+ / FFCompose 0.12):
+// - FF opaque: one gate for auth; stubs on interesting post-login blocks
+// - Block stubs: add-to-cart / finish-order stubAfter
+// - Flow fixtures: ticket-style captions
+// - Slides on finish-order: multi-step yap with Next between slides
 export const checkoutFlow = withHighlightFixtures(
   withTitle(
     engine.defineFlow<
@@ -24,6 +35,9 @@ export const checkoutFlow = withHighlightFixtures(
       ItemInCart,
       CartPage,
       CheckoutInfoPage,
+      CheckoutInfoPage,
+      CheckoutInfoPage,
+      CheckoutInfoPage,
       CheckoutOverviewPage,
       OrderComplete
     >([
@@ -32,6 +46,9 @@ export const checkoutFlow = withHighlightFixtures(
       AddToCartBlock,
       NavCartBlock,
       NavCheckoutInfoBlock,
+      FillFirstNameBlock,
+      FillLastNameBlock,
+      FillPostalCodeBlock,
       SubmitCheckoutInfoBlock,
       FinishOrderBlock,
       end,
@@ -49,7 +66,9 @@ export const checkoutFlow = withHighlightFixtures(
         },
       },
     },
-    "submit-login": {
+    // Kept for --ff-expand (inners become separate steps again: nav-login,
+    // fill-username, fill-password, submit-login).
+    "fill-username": {
       stubBefore: {
         username: {
           label: "Demo user",
@@ -57,7 +76,15 @@ export const checkoutFlow = withHighlightFixtures(
           tag: "AC",
           duration: true,
         },
+      },
+    },
+    "fill-password": {
+      stubBefore: {
         password: { label: "Password", detail: "Filled from Mem credentials.", duration: 1500 },
+      },
+    },
+    "submit-login": {
+      stubBefore: {
         submit: { label: "Sign in", tag: "GATE", duration: true, fastMode: 500 },
       },
     },

package/templates/quickstart/src/flows/device-showcase.flow.ts

@@ -1,5 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
@@ -19,6 +21,8 @@ export const deviceShowcaseFlow = withTitle(
   engine.defineFlow([
     start,
     NavLoginBlock,
+    FillUsernameBlock,
+    FillPasswordBlock,
     SubmitLoginForFlow,
     AddToCartBlock,
     NavCartBlock,

package/templates/quickstart/src/flows/login.flow.ts

@@ -1,5 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 
 const engine = new Engine();
@@ -7,6 +9,6 @@ const engine = new Engine();
 // The step-mode overlay prepends "Episode N: " itself - the title here is
 // just the label, not the full heading.
 export const loginFlow = withTitle(
-  engine.defineFlow([start, NavLoginBlock, SubmitLoginForFlow, end]),
+  engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginForFlow, end]),
   "Sign In",
 );

package/templates/quickstart/src/flows/shop.flow.ts

@@ -2,6 +2,9 @@ import { Engine, start, end, withTitle } from "waygraph";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
@@ -15,6 +18,9 @@ export const shopFlow = withTitle(
     AddToCartBlock,
     NavCartBlock,
     NavCheckoutInfoBlock,
+    FillFirstNameBlock,
+    FillLastNameBlock,
+    FillPostalCodeBlock,
     SubmitCheckoutInfoBlock,
     FinishOrderBlock,
     end,