waygraph 0.13.7 → 0.14.0

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

@@ -1,6 +1,8 @@
 import { Engine, start, end } from "waygraph";
 import type { LoginPage, LoggedIn, ItemInCart } 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";
 
@@ -10,17 +12,21 @@ const engine = new Engine();
 // 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."/"SubmitLoginActionBlock." in an editor - not a free function
+// "NavLoginBlock."/"SubmitLoginForFlow." in an editor - not a free function
 // you have to already know exists.
 //
-// Explicit <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 B/C/D purely from three 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.
-export const smokeFlow = engine.defineFlow<LoginPage, LoggedIn, ItemInCart>([
+// 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,

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

@@ -1,6 +1,8 @@
 import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.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";
 
 const engine = new Engine();
 
@@ -22,7 +24,9 @@ const engine = new Engine();
 // "expected outcome" panel (branching no longer throws).
 export const viewerBlockedFlow = withExpectedFailure(
   withTitle(
-    withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
+    withSessionReset(
+      engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]),
+    ),
     "Viewer: Blocked Login Attempt",
   ),
   "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",

package/templates/quickstart/tests/chain-flow.spec.ts

@@ -38,16 +38,23 @@ test("chainFlow blocks() lists the flattened episode chain in order", () => {
   const blocks = chainFlow(loginFlow, shopFlow, viewerBlockedFlow).blocks();
   expect(blocks.map((b) => b.name)).toEqual([
     "nav-login",
+    "fill-username",
+    "fill-password",
     "submit-login",
     "add-to-cart",
     "nav-cart",
     "nav-checkout-info",
+    "fill-first-name",
+    "fill-last-name",
+    "fill-postal-code",
     "submit-checkout-info",
     "finish-order",
     "nav-login",
+    "fill-username",
+    "fill-password",
     "submit-login",
   ]);
-  expect(blocks.every((b, i) => (i === 7 ? b.resetSessionBefore === true : !b.resetSessionBefore))).toBe(
+  expect(blocks.every((b, i) => (i === 12 ? b.resetSessionBefore === true : !b.resetSessionBefore))).toBe(
     true,
   );
 });

package/templates/scaffold/STRUCTURE.md

@@ -25,9 +25,16 @@ Docs: [docs/scaffold.html](../../docs/scaffold.html)
 │   ├── states/
 │   │   ├── demo.states.ts
 │   │   └── demo.mem-keys.ts  # SelectedItem for Effect / auto
-│   └── flows/
-│       ├── example.flow.ts   # nav + assert (smoke)
-│       └── shop.flow.ts      # nav + add-item + clear (Effect path)
+│   ├── flows/
+│   │   ├── example.flow.ts   # nav + assert (smoke)
+│   │   ├── shop.flow.ts      # nav + add-item + clear (Effect path)
+│   │   └── routes-demo.flow.ts  # Home (manual mode) -> Docs (Map convention)
+│   └── routes/                       # Waygraph Map convention - see README.md
+│       └── (external)/
+│           └── docs/
+│               ├── docs.sel.ts
+│               ├── nav.block.ts      # fixed name - every page-slug folder's Nav
+│               └── page.block.ts     # fixed name - every page-slug folder's arrival hub
 ├── scripts/
 │   ├── fixture-server.mjs    # serves home.html on :4177
 │   └── with-fixture.mjs      # start server + run waygraph auto/demo/run
@@ -59,3 +66,16 @@ npm run auto:cli    # same menus in the terminal
 ```
 
 After `nav-home`, Effect blocks expose one menu row per visible Add/Remove button.
+
+## Two authoring modes
+
+`src/blocks/` (`demo-web/`, `demo-external/`) is **manual mode** - freeform, developer-chosen
+file layout, the default this whole scaffold otherwise uses.
+
+`src/routes/` is the **Waygraph Map** convention - `(group)/<page-slug>/page.block.ts` +
+`nav.block.ts` + `methods/*.block.ts`, one Checkpoint per folder, `(group)` purely
+organizational (parens, Next.js route-group style - never part of the Checkpoint tag). Same
+Block helpers, same execution - only where files live and what they're named changes. A
+project can adopt it folder by folder; `routes-demo.flow.ts` proves both modes compose in one
+flow (`nav-home` from `blocks/`, `nav-docs` from `routes/`). See the main package's own
+`README.md` "Waygraph Map" section and `openspec/changes/waygraph-map/`.

package/templates/scaffold/src/blocks/demo-external/mailpit/mailpit-inbox.page.block.ts

@@ -0,0 +1,30 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { MailpitInbox } from "../../../states/demo.states.js";
+import { AssertEmailReceivedBlock } from "./methods/assert-email-received.method.block.js";
+import { OpenMessageBlock } from "./methods/open-message.method.block.js";
+import { AssertEmailContentBlock } from "./methods/assert-email-content.method.block.js";
+import { ExtractEmailLinkBlock } from "./methods/extract-email-link.method.block.js";
+
+/**
+ * Kind: Page
+ * Helper: definePageBlock
+ * Route: demo-external/mailpit/  (= http://127.0.0.1:8025/ by default)
+ *
+ * Hub for the Mailpit dev-inbox screen. Arrival-only (no url/click) -
+ * nav-mailpit-inbox owns the goto. Methods: confirm the email arrived, open
+ * it, confirm its content, then read its link - all mem-driven (recipient,
+ * link pattern, expected content), so this one page's methods serve any
+ * number of different email scenarios, not just one.
+ */
+export const MailpitInboxPageBlock = definePageBlock<MailpitInbox>({
+  name: "page-mailpit-inbox",
+  description: "Mailpit dev inbox hub - confirm arrival/content, open the expected message, read its link.",
+  checkpoint: "MailpitInbox",
+  verify: [Trait.url({ pathname: "/" })],
+  methods: {
+    assertEmailReceived: () => AssertEmailReceivedBlock,
+    openMessage: () => OpenMessageBlock,
+    assertEmailContent: () => AssertEmailContentBlock,
+    extractEmailLink: () => ExtractEmailLinkBlock,
+  },
+});

package/templates/scaffold/src/blocks/demo-external/mailpit/mailpit-sel.ts

@@ -0,0 +1,5 @@
+/** Selectors confirmed against a real running `axllent/mailpit` container's web UI. */
+export const MailpitSel = {
+  messageRow: "a.message",
+  previewIframe: "#preview-html",
+} as const;

package/templates/scaffold/src/blocks/demo-external/mailpit/methods/assert-email-content.method.block.ts

@@ -0,0 +1,48 @@
+import { defineAssertBlock, type Trait } from "waygraph";
+import type { MailpitMessageOpen } from "../../../../states/demo.states.js";
+import { ExpectedEmailContent } from "../../../../states/demo.mem-keys.js";
+import { MailpitSel } from "../mailpit-sel.js";
+
+/**
+ * Mem-aware Trait: the expected copy varies per email scenario, so it can't
+ * be a static `Trait.frameContains(...)` call (which bakes its expected
+ * string in at Block-definition time) - a Trait's own `check(page, mem)`
+ * already receives mem, so a bespoke Trait reads it at check time instead.
+ * This is what lets one Block serve any number of different email templates.
+ */
+const bodyContainsExpectedText: Trait = {
+  name: "body-contains-expected-text",
+  async check(page, mem) {
+    const expected = mem.get(ExpectedEmailContent);
+    const text = await page.frameLocator(MailpitSel.previewIframe).locator("body").textContent();
+    return (text ?? "").includes(expected);
+  },
+};
+
+/**
+ * Kind: Assert
+ * Helper: defineAssertBlock
+ * Route: demo-external/mailpit/methods/
+ *
+ * "Does the email actually say what it's supposed to" - not just "does a
+ * link exist somewhere in it." Reads the message body straight out of the
+ * preview iframe (the top-level page's own `Trait.text`/`Trait.visible`
+ * can't see inside an iframe at all - see README's "Mail adapters" section).
+ * Self-loop on MailpitMessageOpen - no state change, verify only.
+ *
+ * Deliberately named for what it does, not for one scenario: the expected
+ * copy comes from mem (`ExpectedEmailContent`), not a hardcoded string in
+ * this file, so this one Block serves any number of different email
+ * scenarios - a Block named "assert-verification-email-content" would
+ * wrongly imply it only ever checks verification-email copy.
+ *
+ * Explicit `<MailpitMessageOpen>` type argument - see the same note on
+ * `assert-email-received.method.block.ts` for why this can't be inferred.
+ */
+export const AssertEmailContentBlock = defineAssertBlock<MailpitMessageOpen>({
+  name: "assert-email-content",
+  description: "Confirms the open message's body contains the mem-supplied expected copy.",
+  checkpoint: "MailpitMessageOpen",
+  requires: [ExpectedEmailContent],
+  verify: [bodyContainsExpectedText],
+});

package/templates/scaffold/src/blocks/demo-external/mailpit/methods/assert-email-received.method.block.ts

@@ -0,0 +1,49 @@
+import { defineAssertBlock, type Trait } from "waygraph";
+import type { MailpitInbox } from "../../../../states/demo.states.js";
+import { ExpectedRecipient } from "../../../../states/demo.mem-keys.js";
+import { MailpitSel } from "../mailpit-sel.js";
+
+/**
+ * Mem-aware Trait: the selector depends on which recipient this run expects,
+ * so it can't be a static `Trait.visible(...)` string - a Trait's own
+ * `check(page, mem)` already receives mem, so a bespoke Trait object reads it
+ * directly instead of needing a new engine primitive.
+ */
+const emailReceived: Trait = {
+  name: "email-received",
+  async check(page, mem) {
+    const { email } = mem.get(ExpectedRecipient.key);
+    try {
+      await page.locator(MailpitSel.messageRow, { hasText: email }).first().waitFor({
+        state: "visible",
+        timeout: 10_000,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+/**
+ * Kind: Assert
+ * Helper: defineAssertBlock
+ * Route: demo-external/mailpit/methods/
+ *
+ * "Did the email even arrive" - a lightweight existence check that does not
+ * open or consume the message, so it's safe to run before deciding to open
+ * anything. Self-loop on MailpitInbox - no state change, verify only.
+ *
+ * Explicit `<MailpitInbox>` type argument: `defineAssertBlock` defaults to
+ * wildcard `Checkpoint<string>` on both sides when uninferred, which only
+ * "works" when the assert sits last in a chain (nothing downstream narrows
+ * it) - this one sits between two specifically-typed Blocks, so it must be
+ * parameterized explicitly or `defineFlow`'s tuple typing breaks.
+ */
+export const AssertEmailReceivedBlock = defineAssertBlock<MailpitInbox>({
+  name: "assert-email-received",
+  description: "Confirms a message addressed to the expected recipient has arrived.",
+  checkpoint: "MailpitInbox",
+  requires: [ExpectedRecipient.key],
+  verify: [emailReceived],
+});

package/templates/scaffold/src/blocks/demo-external/mailpit/methods/extract-email-link.method.block.ts

@@ -0,0 +1,41 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { MailpitMessageOpen } from "../../../../states/demo.states.js";
+import { EmailLink, ExpectedLinkPattern } from "../../../../states/demo.mem-keys.js";
+import { MailpitSel } from "../mailpit-sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: demo-external/mailpit/methods/
+ *
+ * Reads a link straight out of the open message's HTML preview iframe via a
+ * real DOM read (getAttribute) - no mail-catcher REST API - and stores it in
+ * mem. A separate NavBlock does the actual navigation: folding "read the
+ * link" and "go there" into one Block would repeat the exact compound-action
+ * anti-pattern `waygraph check` flags elsewhere.
+ *
+ * Deliberately named for what it does, not for one scenario: the
+ * link-matching substring comes from mem (`ExpectedLinkPattern`), not a
+ * hardcoded string, so this one Block serves any number of different email
+ * scenarios in a project (a signup confirmation, a password reset, a magic
+ * link, ...) by varying mem per run, not by writing a new Block per
+ * scenario - a Block named "extract-verification-link" would wrongly imply
+ * it only ever handles verification emails.
+ */
+export const ExtractEmailLinkBlock = defineMethodBlock<MailpitMessageOpen, MailpitMessageOpen>({
+  name: "extract-email-link",
+  description: "Reads the link matching the mem-supplied pattern out of the open message's preview.",
+  requires: [ExpectedLinkPattern],
+  instruction: {
+    async act(page, _in, mem) {
+      const pattern = mem.get(ExpectedLinkPattern);
+      const frame = page.frameLocator(MailpitSel.previewIframe);
+      const link = frame.locator(`a[href*="${pattern}"]`).first();
+      await link.waitFor({ state: "visible", timeout: 15_000 });
+      const href = await link.getAttribute("href");
+      if (!href) throw new Error(`extract-email-link: no link matching "${pattern}" in message preview`);
+      mem.set(EmailLink({ url: href }));
+    },
+    resolve: () => checkpoint("MailpitMessageOpen"),
+  },
+});

package/templates/scaffold/src/blocks/demo-external/mailpit/methods/open-message.method.block.ts

@@ -0,0 +1,39 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { MailpitInbox, MailpitMessageOpen } from "../../../../states/demo.states.js";
+import { ExpectedRecipient } from "../../../../states/demo.mem-keys.js";
+import { MailpitSel } from "../mailpit-sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: demo-external/mailpit/methods/
+ *
+ * Opens the newest inbox row addressed to the mem-set recipient (not bare
+ * inbox position - a prior run's leftover mail for a different recipient
+ * would otherwise pick the wrong row). UI click only, no mail-catcher REST
+ * API - the row itself is a real link (`page.waitForURL` sees the client-side
+ * route change the same as any other in-page navigation).
+ */
+export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOpen>({
+  name: "open-message",
+  description: "Opens the newest message addressed to the expected recipient.",
+  requires: [ExpectedRecipient.key],
+  instruction: {
+    async act(page, _in, mem) {
+      const { email } = mem.get(ExpectedRecipient.key);
+      const row = page.locator(MailpitSel.messageRow, { hasText: email }).first();
+      try {
+        await row.waitFor({ state: "visible", timeout: 30_000 });
+      } catch {
+        throw new Error(`open-message: no email arrived for "${email}" within 30s`);
+      }
+      await row.click();
+      await page.waitForURL(/\/view\//, { timeout: 15_000 });
+      await page.frameLocator(MailpitSel.previewIframe).locator("body").waitFor({
+        state: "attached",
+        timeout: 15_000,
+      });
+    },
+    resolve: () => checkpoint("MailpitMessageOpen"),
+  },
+});

package/templates/scaffold/src/blocks/demo-external/mailpit/nav-mailpit-inbox.block.ts

@@ -0,0 +1,20 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { MailpitInbox } from "../../../states/demo.states.js";
+
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: demo-external/mailpit/  (cross-origin - a real Mailpit web UI, not this app)
+ *
+ * Cross-origin tooling lives under demo-external/, never demo-web/ - this is
+ * a dev-inbox screen, not part of the app under test. `WAYGRAPH_MAIL_URL`
+ * defaults to Mailpit's own usual local port.
+ */
+const mailpitUrl = (): string => process.env.WAYGRAPH_MAIL_URL ?? "http://127.0.0.1:8025";
+
+export const NavMailpitInboxBlock = defineNavBlock<MailpitInbox>({
+  name: "nav-mailpit-inbox",
+  checkpoint: "MailpitInbox",
+  url: mailpitUrl,
+  verify: [Trait.url({ pathname: "/" })],
+});

package/templates/scaffold/src/blocks/demo-web/demo-sel.ts

@@ -11,4 +11,5 @@ export const DemoSel = {
   clear: "[data-test=clear-cart]",
   addBtn: (id: string) => `[data-test=add-${id}]`,
   removeBtn: (id: string) => `[data-test=remove-${id}]`,
+  verifiedBanner: "#verified-banner",
 } as const;

package/templates/scaffold/src/blocks/demo-web/docs.html

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+<head><title>Scaffold - docs (Waygraph Map convention demo)</title></head>
+<body>
+  <h1 id="docs-heading">Docs</h1>
+  <a id="go-home" href="/home.html">Back home</a>
+</body>
+</html>

package/templates/scaffold/src/blocks/demo-web/home.html

@@ -14,6 +14,7 @@
   <body>
     <h1>Hello Waygraph</h1>
     <p id="sub">Scaffold demo - Effect / auto / Page hub</p>
+    <p id="verified-banner" hidden>Email verified!</p>
     <div id="cart">Cart: <span data-test="cart-count">0</span></div>
     <ul id="catalog">
       <li class="item" data-id="alpha">
@@ -34,6 +35,9 @@
     </ul>
     <button type="button" data-test="clear-cart" id="clear">Clear cart</button>
     <script>
+      if (new URLSearchParams(location.search).get("verified") === "1") {
+        document.getElementById("verified-banner").hidden = false;
+      }
       const countEl = document.querySelector("[data-test=cart-count]");
       const sync = () => {
         const n = document.querySelectorAll(".remove:not([hidden])").length;

package/templates/scaffold/src/blocks/demo-web/methods/assert-hello.method.block.ts

@@ -1,50 +1,46 @@
-import { defineMethodBlock, checkpoint, Trait } from "waygraph";
+import { defineAssertBlock, Trait } from "waygraph";
 import { DemoSel } from "../demo-sel.js";
 
 /**
- * Kind: Method
- * Helper: defineMethodBlock
+ * Kind: Assert
+ * Helper: defineAssertBlock
  * Route: demo-web/methods/
  *
- * Same-URL assert after nav - stubs + fixtures + YAP slide.
+ * Self-loop-only "verify what's already on the page" check - no hand-written
+ * act/resolve to accidentally do a second thing. Same-URL assert after nav,
+ * with stubs + fixtures + a YAP slide.
  */
-export const AssertHelloBlock = defineMethodBlock({
+export const AssertHelloBlock = defineAssertBlock({
   name: "assert-hello",
   description: "Confirms the hello heading is still visible after arrival.",
-  instruction: {
-    async act(_page) {},
-    async observe(page) {
-      await page.locator(DemoSel.title).first().waitFor({ state: "visible", timeout: 5_000 });
-      return "ok" as const;
-    },
-    resolve: () => checkpoint("HomeVerified"),
-    verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.sub)],
-    stubBefore: {
-      title: { selector: DemoSel.title, label: "Heading about to check" },
-    },
-    stubAfter: {
-      title: {
-        selector: DemoSel.title,
-        label: "Hello confirmed",
-        detail: "Offline scaffold proof point.",
-        duration: true,
-      },
-      sub: { selector: DemoSel.sub, label: "Subcopy", duration: 1500 },
+  checkpoint: "HomeVerified",
+  waitForHeading: "Hello Waygraph",
+  verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.sub)],
+  stubBefore: {
+    title: { selector: DemoSel.title, label: "Heading about to check" },
+  },
+  stubAfter: {
+    title: {
+      selector: DemoSel.title,
+      label: "Hello confirmed",
+      detail: "Offline scaffold proof point.",
+      duration: true,
     },
-    stubOnError: {
-      title: {
-        selector: DemoSel.title,
-        label: "Heading at failure",
-        tag: "FAIL",
-      },
+    sub: { selector: DemoSel.sub, label: "Subcopy", duration: 1500 },
+  },
+  stubOnError: {
+    title: {
+      selector: DemoSel.title,
+      label: "Heading at failure",
+      tag: "FAIL",
     },
-    slides: [
-      {
-        caption: "Scaffold covers auto + narration",
-        detail: "Page hub, Effect instanceOptions, stubs, fixtures, YAP.",
-        tag: "YAP",
-        duration: true,
-      },
-    ],
   },
+  slides: [
+    {
+      caption: "Scaffold covers auto + narration",
+      detail: "Page hub, Effect instanceOptions, stubs, fixtures, YAP.",
+      tag: "YAP",
+      duration: true,
+    },
+  ],
 });

package/templates/scaffold/src/blocks/demo-web/methods/assert-item-added.method.block.ts

@@ -0,0 +1,38 @@
+import { defineAssertBlock, Trait, type Trait as TraitType } from "waygraph";
+import type { ItemInCart } from "../../../states/demo.states.js";
+import { SelectedItem } from "../../../states/demo.mem-keys.js";
+import { DemoSel } from "../demo-sel.js";
+
+/**
+ * Mem-aware Trait: which item's Remove button should be visible depends on
+ * which row add-item just acted on (mem, not a static selector) - a Trait's
+ * own `check(page, mem)` already receives mem, so this reads it directly.
+ */
+const removeButtonVisibleForSelectedItem: TraitType = {
+  name: "remove-button-visible-for-selected-item",
+  async check(page, mem) {
+    const { id } = mem.get(SelectedItem.key);
+    return page.locator(DemoSel.removeBtn(id)).isVisible();
+  },
+};
+
+/**
+ * Kind: Assert
+ * Helper: defineAssertBlock
+ * Route: demo-web/methods/
+ *
+ * "Did add-item actually work" - provable only after the fact, from the
+ * method's real effect on the page: the specific row's own Remove button
+ * appeared (mem-matched, not just "some" row), AND the aggregate cart count
+ * reflects it. Self-loop on ItemInCart - no state change, verify only.
+ *
+ * Explicit `<ItemInCart>` type argument - `defineAssertBlock` defaults to
+ * wildcard `Checkpoint<string>` when uninferred, which only "works" when the
+ * assert sits last in a chain; this one sits mid-chain (see shop.flow.ts).
+ */
+export const AssertItemAddedBlock = defineAssertBlock<ItemInCart>({
+  name: "assert-item-added",
+  description: "Confirms the mem-selected item's own Remove button appeared and the cart count reflects it.",
+  checkpoint: "ItemInCart",
+  verify: [removeButtonVisibleForSelectedItem, Trait.text(DemoSel.cartCount, "1")],
+});

package/templates/scaffold/src/blocks/demo-web/nav-verification-link.block.ts

@@ -0,0 +1,34 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { HomeVerified } from "../../states/demo.states.js";
+import { EmailLink } from "../../states/demo.mem-keys.js";
+import { DemoSel } from "./demo-sel.js";
+
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: demo-web/
+ *
+ * Navigates back into the app to the link extract-email-link read out of
+ * the real Mailpit message, then confirms the page actually reflects it
+ * (the verified banner only appears when the exact `verified=1` link was
+ * followed, not just any URL). This particular check is app-specific (this
+ * scaffold's own verification landing route) even though the mail-reading
+ * Blocks feeding it are scenario-agnostic - a real project would have one
+ * such Nav per distinct landing route, same as any other app screen.
+ *
+ * Deliberately no `requires: [EmailLink.key]` here: `requires` means "the
+ * caller must seed this externally before the flow starts" (preflight
+ * checks the whole chain's requires up front) - `EmailLink` is instead
+ * produced by an earlier Block in this very chain, so declaring it as a
+ * requirement would make preflight fail before the flow ever gets the
+ * chance to produce it. Engine support for declaring a mem key as "produced
+ * by an earlier Block in this chain" (vs. externally supplied) is a
+ * separate, not-yet-built roadmap item - see ROADMAP.md's "Split requires"
+ * row.
+ */
+export const NavVerificationLinkBlock = defineNavBlock<HomeVerified>({
+  name: "nav-verification-link",
+  checkpoint: "HomeVerified",
+  url: (mem) => mem.get(EmailLink.key).url,
+  verify: [Trait.visible(DemoSel.verifiedBanner)],
+});

package/templates/scaffold/src/flows/mail-verify.flow.ts

@@ -0,0 +1,85 @@
+import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
+import { NavMailpitInboxBlock } from "../blocks/demo-external/mailpit/nav-mailpit-inbox.block.js";
+import { AssertEmailReceivedBlock } from "../blocks/demo-external/mailpit/methods/assert-email-received.method.block.js";
+import { OpenMessageBlock } from "../blocks/demo-external/mailpit/methods/open-message.method.block.js";
+import { AssertEmailContentBlock } from "../blocks/demo-external/mailpit/methods/assert-email-content.method.block.js";
+import { ExtractEmailLinkBlock } from "../blocks/demo-external/mailpit/methods/extract-email-link.method.block.js";
+import { NavVerificationLinkBlock } from "../blocks/demo-web/nav-verification-link.block.js";
+import "../blocks/demo-external/mailpit/mailpit-inbox.page.block.js";
+import { MailpitSel } from "../blocks/demo-external/mailpit/mailpit-sel.js";
+
+const engine = new Engine();
+
+/**
+ * Cross-origin mail demo, QA-rich: navigate to a real Mailpit inbox (a real,
+ * separate web UI - not this app), confirm the email actually arrived,
+ * open it, confirm its body says what it's supposed to, read a link
+ * straight out of the DOM, then navigate back into the app with it - six
+ * atomic Blocks, no mail-catcher REST API anywhere.
+ *
+ * The four mail-reading Blocks (`assert-email-received`, `open-message`,
+ * `assert-email-content`, `extract-email-link`) are reusable across any
+ * number of different email scenarios in a project (signup confirmation,
+ * password reset, magic link, ...) with zero new Blocks per scenario - only
+ * mem varies per run: `ExpectedRecipient` (who), `ExpectedLinkPattern`
+ * (which link in the body to follow), `ExpectedEmailContent` (what the body
+ * should say). This particular flow wires them to this scaffold's own
+ * "verified" landing route (`nav-verification-link`, app-specific by
+ * nature - a different scenario would use a different landing Nav) - see
+ * tests/mail-verify.spec.ts for two different scenarios driven through the
+ * same four mail-reading Blocks.
+ *
+ * Needs a real Mailpit instance reachable at WAYGRAPH_MAIL_URL (default
+ * http://127.0.0.1:8025) with a message already waiting for
+ * ExpectedRecipient's email - see tests/mail-verify.spec.ts for how the test
+ * drives this end to end (spins up a real Mailpit container, sends a real
+ * email, then runs this exact flow) - including the negative cases: no email
+ * arriving, or content that doesn't match, each fail loud, naming
+ * themselves, not a silent pass.
+ */
+export const mailVerifyFlow = withHighlightFixtures(
+  withTitle(
+    engine.defineFlow([
+      start,
+      NavMailpitInboxBlock,
+      AssertEmailReceivedBlock,
+      OpenMessageBlock,
+      AssertEmailContentBlock,
+      ExtractEmailLinkBlock,
+      NavVerificationLinkBlock,
+      end,
+    ]),
+    "Scaffold: Cross-origin mail verification (QA-rich)",
+  ),
+  {
+    "assert-email-received": {
+      stubAfter: {
+        note: {
+          selector: MailpitSel.messageRow,
+          label: "AC · email arrived",
+          detail: "Confirmed before opening anything.",
+          tag: "AC",
+        },
+      },
+    },
+    "assert-email-content": {
+      stubAfter: {
+        note: {
+          selector: MailpitSel.previewIframe,
+          label: "AC · email body matches expected copy",
+          tag: "AC",
+        },
+      },
+    },
+    "extract-email-link": {
+      stubAfter: {
+        note: {
+          selector: MailpitSel.previewIframe,
+          label: "AC · link found",
+          detail: "Read from the message preview iframe.",
+          tag: "AC",
+        },
+      },
+    },
+  },
+);