waygraph 0.13.7 → 0.15.0

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

@@ -0,0 +1,85 @@
+import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
+import { NavMailpitInboxBlock } from "../map/(external)/mailpit/_nav.block.js";
+import { AssertEmailReceivedBlock } from "../map/(external)/mailpit/_methods/assert-email-received.method.block.js";
+import { OpenMessageBlock } from "../map/(external)/mailpit/_methods/open-message.method.block.js";
+import { AssertEmailContentBlock } from "../map/(external)/mailpit/_methods/assert-email-content.method.block.js";
+import { ExtractEmailLinkBlock } from "../map/(external)/mailpit/_methods/extract-email-link.method.block.js";
+import { NavVerificationLinkBlock } from "../map/(app_base)/home/nav-verification-link.block.js";
+import "../map/(external)/mailpit/_page.block.js";
+import { MailpitSel } from "../map/(external)/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",
+        },
+      },
+    },
+  },
+);

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

@@ -6,10 +6,12 @@ import {
   withHighlightFixtures,
   withSessionReset,
 } from "waygraph";
-import { NavHomeBlock } from "../blocks/demo-web/nav-home.block.js";
-import { AddItemBlock } from "../blocks/demo-web/methods/add-item.effect.block.js";
-import { ClearCartBlock } from "../blocks/demo-web/methods/clear-cart.method.block.js";
-import "../blocks/demo-web/home.page.block.js";
+import { NavHomeBlock } from "../map/(app_base)/home/_nav.block.js";
+import { AddItemBlock } from "../map/(app_base)/home/_methods/add-item.effect.block.js";
+import { AssertItemAddedBlock } from "../map/(app_base)/home/_methods/assert-item-added.method.block.js";
+import { RemoveItemBlock } from "../map/(app_base)/home/_methods/remove-item.effect.block.js";
+import { ClearCartBlock } from "../map/(app_base)/home/_methods/clear-cart.method.block.js";
+import "../map/(app_base)/home/_page.block.js";
 
 const engine = new Engine();
 
@@ -18,12 +20,27 @@ const engine = new Engine();
  * fills SelectedItem via instanceOptions).
  *
  *   waygraph demo --blocks shopFlow --data '{"demo.selectedItem":{"id":"alpha","name":"Alpha"}}'
- *   waygraph auto   # after landing on home, pick Add Alpha / Add Beta / …
+ *   waygraph auto   # after landing on home, pick Add Alpha / Add Beta / Remove ...
+ *
+ * Add -> assert it actually landed (mem-matched Remove button + cart count,
+ * only provable from the method's real effect, not a static page state) ->
+ * Remove that same row (per-item Effect, `remove-item`) -> Add again ->
+ * Clear cart (bulk Method, `clear-cart`) - keeps both the per-item and bulk
+ * clear paths atomic and each wired into a real flow, not orphaned.
  */
 export const shopFlow = withHighlightFixtures(
   withTitle(
     withSessionReset(
-      engine.defineFlow([start, NavHomeBlock, AddItemBlock, ClearCartBlock, end]),
+      engine.defineFlow([
+        start,
+        NavHomeBlock,
+        AddItemBlock,
+        AssertItemAddedBlock,
+        RemoveItemBlock,
+        AddItemBlock,
+        ClearCartBlock,
+        end,
+      ]),
     ),
     "Scaffold: Shop (Effect + clear)",
   ),

package/templates/scaffold/src/map/(app_base)/docs/_nav.block.ts

@@ -0,0 +1,20 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { Docs } from "../../../states/demo.states.js";
+import { DocsSel, DOCS_URL } from "./_sel.js";
+
+/**
+ * Kind: Nav
+ * Route: (app_base)/docs/
+ *
+ * Same origin as home/ (same fixture server, different HTML file) - lives
+ * under (app_base), not (external). See README.md "Waygraph Map" and
+ * openspec/changes/waygraph-map. `(app_base)` is purely organizational
+ * (Next.js route-group style) - never part of the Checkpoint tag.
+ */
+export const NavDocsBlock = defineNavBlock<Docs>({
+  name: "nav-docs",
+  description: "Opens the docs page (Waygraph Map convention demo).",
+  checkpoint: "Docs",
+  url: DOCS_URL,
+  verify: [Trait.visible(DocsSel.heading)],
+});

package/templates/scaffold/src/map/(app_base)/docs/_page.block.ts

@@ -0,0 +1,15 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { Docs } from "../../../states/demo.states.js";
+import { DocsSel } from "./_sel.js";
+
+/**
+ * Kind: Page
+ * Route: (app_base)/docs/
+ * Arrival-only (nav.block.ts already landed on Docs).
+ */
+export const DocsPageBlock = definePageBlock<Docs>({
+  name: "page-docs",
+  description: "Docs hub - Waygraph Map convention demo.",
+  checkpoint: "Docs",
+  verify: [Trait.visible(DocsSel.heading)],
+});

package/templates/scaffold/src/map/(app_base)/docs/_sel.ts

@@ -0,0 +1,7 @@
+export const DOCS_URL =
+  process.env.WAYGRAPH_DOCS_URL ??
+  `http://${process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1"}:${process.env.WAYGRAPH_FIXTURE_PORT || "4177"}/docs.html`;
+
+export const DocsSel = {
+  heading: "#docs-heading",
+} as const;

package/templates/scaffold/src/map/(app_base)/docs/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/methods → map/(app_base)/home/_methods}/add-item.effect.block.ts

@@ -4,9 +4,9 @@ import {
   type Checkpoint,
   type WaygraphInstanceOption,
 } from "waygraph";
-import type { ItemInCart } from "../../../states/demo.states.js";
-import { SelectedItem } from "../../../states/demo.mem-keys.js";
-import { DemoSel } from "../demo-sel.js";
+import type { ItemInCart } from "../../../../states/demo.states.js";
+import { SelectedItem } from "../../../../states/demo.mem-keys.js";
+import { DemoSel } from "../_sel.js";
 
 /**
  * Kind: Effect

package/templates/scaffold/src/map/(app_base)/home/_methods/assert-hello.method.block.ts

@@ -0,0 +1,46 @@
+import { defineAssertBlock, Trait } from "waygraph";
+import { DemoSel } from "../_sel.js";
+
+/**
+ * Kind: Assert
+ * Helper: defineAssertBlock
+ * Route: demo-web/methods/
+ *
+ * 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 = defineAssertBlock({
+  name: "assert-hello",
+  description: "Confirms the hello heading is still visible after arrival.",
+  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,
+    },
+    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,
+    },
+  ],
+});

package/templates/scaffold/src/map/(app_base)/home/_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 "../_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/methods → map/(app_base)/home/_methods}/clear-cart.method.block.ts

@@ -1,12 +1,18 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
-import { DemoSel } from "../demo-sel.js";
+import type { ItemInCart, CartEmpty } from "../../../../states/demo.states.js";
+import { DemoSel } from "../_sel.js";
 
 /**
  * Kind: Method
  * Helper: defineMethodBlock
- * Route: demo-web/methods/
+ * Route: (app_base)/home/_methods/
+ *
+ * Real, pre-existing bug found live while verifying the Waygraph Map
+ * rename: this Block had no explicit <In, Out> generic at all, so static
+ * discovery (`waygraph graph`) always skipped it silently ("no ...generic
+ * call found") - present before this move, not caused by it.
  */
-export const ClearCartBlock = defineMethodBlock({
+export const ClearCartBlock = defineMethodBlock<ItemInCart, CartEmpty>({
   name: "clear-cart",
   description: "Clears every item via the Clear cart control.",
   instruction: {

package/templates/scaffold/src/{blocks/demo-web/methods → map/(app_base)/home/_methods}/remove-item.effect.block.ts

@@ -4,9 +4,9 @@ import {
   type Checkpoint,
   type WaygraphInstanceOption,
 } from "waygraph";
-import type { CartEmpty } from "../../../states/demo.states.js";
-import { SelectedItem } from "../../../states/demo.mem-keys.js";
-import { DemoSel } from "../demo-sel.js";
+import type { CartEmpty } from "../../../../states/demo.states.js";
+import { SelectedItem } from "../../../../states/demo.mem-keys.js";
+import { DemoSel } from "../_sel.js";
 
 /**
  * Kind: Effect

package/templates/scaffold/src/{blocks/demo-web/nav-home.block.ts → map/(app_base)/home/_nav.block.ts}

@@ -1,10 +1,10 @@
 import { defineNavBlock, Trait } from "waygraph";
-import { DemoSel, HOME_URL } from "./demo-sel.js";
+import { DemoSel, HOME_URL } from "./_sel.js";
 
 /**
  * Kind: Nav
  * Helper: defineNavBlock
- * Route: demo-web/  (synthetic "/")
+ * Route: (app_base)/home/  (synthetic "/")
  */
 export const NavHomeBlock = defineNavBlock({
   name: "nav-home",

package/templates/scaffold/src/{blocks/demo-web/home.page.block.ts → map/(app_base)/home/_page.block.ts}

@@ -1,15 +1,15 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { Home } from "../../states/demo.states.js";
-import { DemoSel } from "./demo-sel.js";
-import { AddItemBlock } from "./methods/add-item.effect.block.js";
-import { RemoveItemBlock } from "./methods/remove-item.effect.block.js";
-import { ClearCartBlock } from "./methods/clear-cart.method.block.js";
-import { AssertHelloBlock } from "./methods/assert-hello.method.block.js";
+import type { Home } from "../../../states/demo.states.js";
+import { DemoSel } from "./_sel.js";
+import { AddItemBlock } from "./_methods/add-item.effect.block.js";
+import { RemoveItemBlock } from "./_methods/remove-item.effect.block.js";
+import { ClearCartBlock } from "./_methods/clear-cart.method.block.js";
+import { AssertHelloBlock } from "./_methods/assert-hello.method.block.js";
 
 /**
  * Kind: Page
  * Helper: definePageBlock
- * Route: demo-web/
+ * Route: (app_base)/home/
  *
  * Hub for the offline home screen. Methods hang here for docs/auto grouping;
  * edges in flows still reference the method Blocks directly.

package/templates/scaffold/src/{blocks/demo-web/demo-sel.ts → map/(app_base)/home/_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 → map/(app_base)/home}/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/map/(app_base)/home/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 "./_sel.js";
+
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: (app_base)/home/
+ *
+ * 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/map/(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 "../_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/map/(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 "../_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/map/(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 "../_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/map/(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 "../_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/map/(external)/mailpit/_nav.block.ts

@@ -0,0 +1,20 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { MailpitInbox } from "../../../states/demo.states.js";
+
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: (external)/mailpit/  (cross-origin - a real Mailpit web UI, not this app)
+ *
+ * Cross-origin tooling lives under (external)/, never (app_base)/ - 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: "/" })],
+});