waygraph 0.15.53 → 0.16.0

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

@@ -1,4 +1,5 @@
-import { Engine, withTitle } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.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";
@@ -13,65 +14,71 @@ import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-o
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 import { LoginSel } from "../blocks/saucedemo-web/methods/login.sel.js";
 
-const engine = new Engine({ headless: false, slowMo: 250 });
-
-/**
- * Owner checkout via map() + .ffStart/.ffEnd (no separate FfOwnerAuthBlock,
- * no HighlightFixtureMap). Auth collapses to one blitz step; post-login
- * blocks keep their own ctx stubBefore/stubAfter. Call-site decorate example
- * on fill-username when --ff-expand shows inners again.
- */
-export const checkoutFlow = withTitle(
-  engine
-    .map()
-    .start()
-    .ffStart("ff-owner-auth")
-    .gotoPage(NavLoginBlock)
-    .method(
-      FillUsernameBlock.stubBefore((ctx) => {
-        ctx.ring("username", {
-          selector: LoginSel.username,
-          label: "Demo user",
-          detail: "standard_user from Mem - library block stays neutral underneath",
-          tag: "AC",
-          duration: true,
-          focus: true,
-        });
-      }),
-    )
-    .method(
-      FillPasswordBlock.stubBefore((ctx) => {
-        ctx.ring("password", {
-          selector: LoginSel.password,
-          label: "Password",
-          detail: "Filled from Mem credentials.",
-          duration: 1500,
-          focus: true,
-        });
-      }),
-    )
-    .method(
-      SubmitLoginForFlow.stubBefore((ctx) => {
-        ctx.ring("submit", {
-          selector: LoginSel.loginButton,
-          label: "Sign in",
-          tag: "GATE",
-          duration: true,
-          fastMode: 500,
-          focus: true,
-          weight: "bold",
-        });
-      }),
-    )
-    .ffEnd()
-    .method(AddToCartBlock)
-    .gotoPage(NavCartBlock)
-    .gotoPage(NavCheckoutInfoBlock)
-    .method(FillFirstNameBlock)
-    .method(FillLastNameBlock)
-    .method(FillPostalCodeBlock)
-    .method(SubmitCheckoutInfoBlock)
-    .method(FinishOrderBlock)
-    .end(),
-  "Owner: Full Checkout",
-);
+export const checkoutFlow = engine
+  .map({ memStub: true })
+  .start()
+  .gotoPage(NavLoginBlock, { ff: true })
+  .method(
+    FillUsernameBlock.stubBefore((ctx) => {
+      ctx.ring("username", {
+        selector: LoginSel.username,
+        label: "Demo user",
+        detail:
+          "standard_user from Mem - library block stays neutral underneath",
+        tag: "AC",
+        duration: true,
+        focus: true,
+      });
+    }),
+    { ff: true },
+  )
+  .method(
+    FillPasswordBlock.stubBefore((ctx) => {
+      ctx.ring("password", {
+        selector: LoginSel.password,
+        label: "Password",
+        detail: "Filled from Mem credentials.",
+        duration: 1500,
+        focus: true,
+      });
+    }),
+    { ff: true },
+  )
+  .method(
+    SubmitLoginForFlow.stubBefore((ctx) => {
+      ctx.ring("submit", {
+        selector: LoginSel.loginButton,
+        label: "Sign in",
+        tag: "GATE",
+        duration: true,
+        fastMode: 500,
+        focus: true,
+        weight: "bold",
+      });
+    }),
+    { ff: true },
+  )
+  .method(AddToCartBlock.stubBefore((ctx) => ctx.title("Owner: Full Checkout")))
+  .gotoPage(NavCartBlock)
+  .gotoPage(NavCheckoutInfoBlock)
+  .method(
+    FillFirstNameBlock.stubBefore((ctx) => {
+      ctx.caption("Enter the first name on the order");
+      ctx.titlePos("left");
+    }),
+  )
+  .method(
+    FillLastNameBlock.stubBefore((ctx) => {
+      ctx.caption("Enter the last name on the order");
+      ctx.titlePos("center");
+    }),
+  )
+  .method(
+    FillPostalCodeBlock.stubBefore((ctx) => {
+      ctx.caption("Enter a postal code to calculate shipping");
+      ctx.titlePos("right");
+    }),
+  )
+  .method(SubmitCheckoutInfoBlock.stubBefore((ctx) => ctx.hideCaption()))
+  .method(FinishOrderBlock)
+  .end();

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

@@ -1,32 +1,31 @@
-import { Engine, start, end, withTitle } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.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 { deviceShowcase as d } from "../stubs/device-showcase.js";
 
-const engine = new Engine();
-
-/**
- * Short device/orientation showcase (0.13.3+):
- *   login mobile portrait -> land on inventory landscape ->
- *   add-to-cart tablet portrait -> open cart tablet landscape -> desktop
- *
- * Run:
- *   npm run demo:device
- *   npm run demo:device:video
- */
-export const deviceShowcaseFlow = withTitle(
-  engine.defineFlow([
-    start,
-    NavLoginBlock,
-    FillUsernameBlock,
-    FillPasswordBlock,
-    SubmitLoginForFlow,
-    AddToCartBlock,
-    NavCartBlock,
-    end,
-  ]),
-  "Device showcase",
-);
+/** Sign in on a phone, shop on a tablet, open the cart in landscape: the device and zoom narration in src/stubs/device-showcase.ts. */
+export const deviceShowcaseFlow = engine
+  .map({ memStub: true })
+  .start()
+  .gotoPage(NavLoginBlock)
+  .method(
+    FillUsernameBlock.stubBefore(d.username.before).stubAfter(d.username.after),
+  )
+  .method(
+    FillPasswordBlock.stubBefore(d.password.before).stubAfter(d.password.after),
+  )
+  .method(
+    SubmitLoginForFlow.stubBefore(d.submit.before).stubAfter(d.submit.after),
+  )
+  .method(
+    AddToCartBlock.stubBefore(d.addToCart.before).stubAfter(d.addToCart.after),
+  )
+  .gotoPage(
+    NavCartBlock.stubBefore(d.openCart.before).stubAfter(d.openCart.after),
+  )
+  .end();

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

@@ -1,23 +1,16 @@
-import { Engine, withTitle } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.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";
 
-const engine = new Engine();
-
-// The step-mode overlay prepends "Episode N: " itself - the title here is
-// just the label, not the full heading.
-// map() + ctx stubs on the Method blocks (see fill-username / fill-password /
-// submit-login) - no HighlightFixtureMap.
-export const loginFlow = withTitle(
-  engine
-    .map()
-    .start()
-    .gotoPage(NavLoginBlock)
-    .method(FillUsernameBlock)
-    .method(FillPasswordBlock)
-    .method(SubmitLoginForFlow)
-    .end(),
-  "Sign In",
-);
+/** Standard user signs in. Credentials come from the memStub in src/states/checkout.mem-stubs.ts unless --data / mem set them. */
+export const loginFlow = engine
+  .map({ memStub: true })
+  .start()
+  .gotoPage(NavLoginBlock.stubBefore((ctx) => ctx.title("Sign In")))
+  .method(FillUsernameBlock)
+  .method(FillPasswordBlock)
+  .method(SubmitLoginForFlow)
+  .end();

package/templates/quickstart/src/flows/mem-stub-demo.flow.ts

@@ -0,0 +1,12 @@
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.js";
+import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+
+/** memStub: the credentials are never supplied; src/states/checkout.mem-stubs.ts fills them. */
+export const memStubDemoFlow = engine
+  .map({ memStub: true })
+  .start()
+  .gotoPage(NavLoginBlock)
+  .method(FillUsernameBlock)
+  .end();

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

@@ -1,4 +1,5 @@
-import { Engine, withTitle } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.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";
@@ -8,22 +9,16 @@ import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/m
 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();
-
-// Episode-2 half of chainFlow(loginFlow, shopFlow) - assumes already LoggedIn
-// (AddToCartBlock's In is the Checkpoint<string> wildcard).
-export const shopFlow = withTitle(
-  engine
-    .map()
-    .start()
-    .method(AddToCartBlock)
-    .gotoPage(NavCartBlock)
-    .gotoPage(NavCheckoutInfoBlock)
-    .method(FillFirstNameBlock)
-    .method(FillLastNameBlock)
-    .method(FillPostalCodeBlock)
-    .method(SubmitCheckoutInfoBlock)
-    .method(FinishOrderBlock)
-    .end(),
-  "Shop & Checkout",
-);
+/** Add the selected item, check out and place the order. Starts signed in (run it after loginFlow). */
+export const shopFlow = engine
+  .map({ memStub: true })
+  .start()
+  .method(AddToCartBlock.stubBefore((ctx) => ctx.title("Shop & Checkout")))
+  .gotoPage(NavCartBlock)
+  .gotoPage(NavCheckoutInfoBlock)
+  .method(FillFirstNameBlock)
+  .method(FillLastNameBlock)
+  .method(FillPostalCodeBlock)
+  .method(SubmitCheckoutInfoBlock)
+  .method(FinishOrderBlock)
+  .end();

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

@@ -1,33 +1,18 @@
-import { Engine, start, end } from "waygraph";
-import type { LoginPage, LoggedIn, ItemInCart } from "../states/checkout.states.js";
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.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";
 
-const engine = new Engine();
-
-// The QA case: a smoke test only cares that it was able to navigate this far -
-// it doesn't need the same DOM confirmation the real checkout.flow.ts wants.
-// Same Blocks, same act/resolve, zero duplication - only verify differs.
-// .withVerify([]) reads from the Block itself, discoverable by typing
-// "NavLoginBlock."/"SubmitLoginForFlow." in an editor - not a free function
-// you have to already know exists.
-//
-// Explicit <LoginPage, LoginPage, LoginPage, LoggedIn, ItemInCart> here -
-// AddToCartBlock's In is now the wildcard Checkpoint<string> (it's reused as
-// shopFlow's own entry block too), and inferring the chain purely from
-// several chained .withVerify([]) calls in one array trips TS's overload
-// resolution into unifying the wrong Out type partway through; pinning the
-// type args sidesteps it rather than fighting it. The two middle `LoginPage`
-// entries are fill-username / fill-password (self-loop Methods).
-export const smokeFlow = engine.defineFlow<LoginPage, LoginPage, LoginPage, LoggedIn, ItemInCart>([
-  start,
-  NavLoginBlock.withVerify([]),
-  FillUsernameBlock,
-  FillPasswordBlock,
-  SubmitLoginForFlow.withVerify([]),
-  AddToCartBlock.withVerify([]),
-  end,
-]);
+/** Smoke: the happy path with the Blocks' own verify lists switched off where a later step already proves the outcome. */
+export const smokeFlow = engine
+  .map()
+  .start()
+  .gotoPage(NavLoginBlock.withVerify([]))
+  .method(FillUsernameBlock)
+  .method(FillPasswordBlock)
+  .method(SubmitLoginForFlow.withVerify([]))
+  .method(AddToCartBlock.withVerify([]))
+  .end();

package/templates/quickstart/src/flows/stub-on-error.flow.ts

@@ -0,0 +1,31 @@
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.js";
+import { Trait } 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 { SubmitLoginBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
+import { loginFailed } from "../stubs/login.js";
+
+/**
+ * Forces a verify failure (locked_out_user is refused, but the verify demands the inventory page) to show `stubOnError` ringing
+ * the error banner before the failure panel. Needs locked_out_user credentials: `--data` or mem.
+ */
+export const stubOnErrorFlow = engine
+  .map({
+    expectedFailure:
+      "Intentional verify fail - stubOnError rings the error banner before the panel",
+  })
+  .start()
+  .gotoPage(
+    NavLoginBlock.stubBefore((ctx) =>
+      ctx.title("stubOnError: locked_out fail rings"),
+    ),
+  )
+  .method(FillUsernameBlock)
+  .method(FillPasswordBlock)
+  .method(SubmitLoginBlock.stubOnError(loginFailed))
+  .end()
+  .withBlockVerify("submit-login", [
+    Trait.url({ pathname: "/inventory.html" }),
+  ]);

package/templates/quickstart/src/flows/viewer-blocked.flow.ts

@@ -1,40 +1,32 @@
-import { Engine, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.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 { SubmitLoginBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
+import { loginRefused } from "../stubs/login.js";
 
-const engine = new Engine();
-
-// A genuinely DIFFERENT scenario from checkoutFlow - not the same steps
-// split in half. Same login blocks, different user, different outcome:
-// locked_out_user attempts the exact same login an Owner (standard_user,
-// checkoutFlow) just completed successfully, and is blocked -
-// saucedemo.com's real response, verified live: stays on "/", shows
-// "Epic sadface: Sorry, this user has been locked out."
-//
-// withSessionReset matters here for real, not cosmetically - entered right
-// after checkoutFlow's already-authenticated session, this needs its own
-// genuinely fresh cookies/storage, or the previous user's session would
-// still be live and this login attempt wouldn't mean anything.
-//
-// submit-login branches: observe sees no /inventory.html navigation,
-// resolve -> LoginPage, verify confirms the error banner. Demo still wraps
-// withExpectedFailure so step 9/9 shows stubOnError rings + amber
-// "expected outcome" panel (branching no longer throws).
-export const viewerBlockedFlow = withExpectedFailure(
-  withTitle(
-    withSessionReset(
-      engine
-        .map()
-        .start()
-        .gotoPage(NavLoginBlock)
-        .method(FillUsernameBlock)
-        .method(FillPasswordBlock)
-        .method(SubmitLoginBlock)
-        .end(),
+/**
+ * locked_out_user attempts the login a standard user just completed and is refused: the app stays on the login page and
+ * shows the error banner. Run it after another flow to see it needs a reset: `.flow(viewerBlockedFlow, { reset: true })`.
+ */
+export const viewerBlockedFlow = engine
+  .map({
+    sessionReset: true,
+    expectedFailure:
+      "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
+  })
+  .start()
+  .gotoPage(
+    NavLoginBlock.stubBefore((ctx) =>
+      ctx.title("Viewer: Blocked Login Attempt"),
     ),
-    "Viewer: Blocked Login Attempt",
-  ),
-  "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
-);
+  )
+  .method(FillUsernameBlock)
+  .method(FillPasswordBlock)
+  .method(
+    SubmitLoginBlock.stubAfter((ctx) => {
+      if (ctx.out?.__state === "LoginPage") loginRefused(ctx);
+    }),
+  )
+  .end();

package/templates/quickstart/src/states/checkout.mem-stubs.ts

@@ -0,0 +1,11 @@
+import { registerMemStub } from "waygraph";
+import { LoginCreds, SelectedItem } from "./checkout.mem-keys.js";
+
+registerMemStub(LoginCreds.key, () => ({
+  username: "standard_user",
+  password: "secret_sauce",
+}));
+registerMemStub(SelectedItem.key, () => ({
+  id: "sauce-labs-backpack",
+  name: "Sauce Labs Backpack",
+}));

package/templates/quickstart/src/states/checkout.states.ts

@@ -1,19 +1,29 @@
-import type { Checkpoint } from "waygraph";
+import { checkpoint } from "waygraph";
 
 // One Checkpoint per real state the target app can be in - kept together so the
 // whole checkout flow's state space reads in one place, the same reason a
 // backend keeps its models together instead of scattered across handlers.
 // `Start` is waygraph's own exported type, not redeclared here.
 
-export type LoginPage = Checkpoint<"LoginPage">;
-export type LoggedIn = Checkpoint<"LoggedIn">;
+export const LoginPage = checkpoint("LoginPage");
+export type LoginPage = typeof LoginPage;
+export const LoggedIn = checkpoint("LoggedIn");
+export type LoggedIn = typeof LoggedIn;
 /** submit-login: inventory on success, login form + error banner on auth failure. */
-export type LoginSubmitOutcome = LoggedIn | LoginPage;
-export type ItemInCart = Checkpoint<"ItemInCart">;
+export const LoginSubmitOutcome = [LoggedIn, LoginPage] as const;
+export type LoginSubmitOutcome = (typeof LoginSubmitOutcome)[number];
+export const ItemInCart = checkpoint("ItemInCart");
+export type ItemInCart = typeof ItemInCart;
 /** remove-from-cart: still has items → ItemInCart; empty cart → LoggedIn. */
-export type RemoveFromCartOutcome = ItemInCart | LoggedIn;
-export type CartPage = Checkpoint<"CartPage">;
-export type CheckoutInfoPage = Checkpoint<"CheckoutInfoPage">;
-export type CheckoutOverviewPage = Checkpoint<"CheckoutOverviewPage">;
-export type ItemDetailPage = Checkpoint<"ItemDetailPage">;
-export type OrderComplete = Checkpoint<"OrderComplete">;
+export const RemoveFromCartOutcome = [ItemInCart, LoggedIn] as const;
+export type RemoveFromCartOutcome = (typeof RemoveFromCartOutcome)[number];
+export const CartPage = checkpoint("CartPage");
+export type CartPage = typeof CartPage;
+export const CheckoutInfoPage = checkpoint("CheckoutInfoPage");
+export type CheckoutInfoPage = typeof CheckoutInfoPage;
+export const CheckoutOverviewPage = checkpoint("CheckoutOverviewPage");
+export type CheckoutOverviewPage = typeof CheckoutOverviewPage;
+export const ItemDetailPage = checkpoint("ItemDetailPage");
+export type ItemDetailPage = typeof ItemDetailPage;
+export const OrderComplete = checkpoint("OrderComplete");
+export type OrderComplete = typeof OrderComplete;