waygraph 0.15.51 → 0.15.52

package/templates/scaffold/src/flows/hoppscotch-get.flow.ts

@@ -0,0 +1,23 @@
+import { Engine } from "waygraph";
+import config from "../../config/waygraph.config.js";
+import { NavHoppscotchSettingsBlock } from "../map/(external)/hoppscotch/settings/_nav.block.js";
+import { PickExtensionInterceptorBlock } from "../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
+import { NavHoppscotchRestBlock } from "../map/(external)/hoppscotch/_nav.block.js";
+import { SetUrlBlock } from "../map/(external)/hoppscotch/_methods/set-url.method.block.js";
+import { SendRequestBlock } from "../map/(external)/hoppscotch/_methods/send-request.method.block.js";
+import { AssertStatusBlock } from "../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
+import "../map/(external)/hoppscotch/_page.block.js";
+
+const engine = new Engine(config);
+
+/** GET a URL and check the status. Needs `extensions: ["hoppscotch"]` in waygraph.config.ts. */
+export const hoppscotchGetFlow = engine
+  .map()
+  .start()
+  .gotoExternal(NavHoppscotchSettingsBlock)
+  .method(PickExtensionInterceptorBlock)
+  .gotoExternal(NavHoppscotchRestBlock)
+  .method(SetUrlBlock)
+  .method(SendRequestBlock)
+  .assert(AssertStatusBlock)
+  .end({ title: "Scaffold: Hoppscotch GET" });

package/templates/scaffold/src/flows/hoppscotch-post.flow.ts

@@ -0,0 +1,33 @@
+import { Engine } from "waygraph";
+import config from "../../config/waygraph.config.js";
+import { NavHoppscotchSettingsBlock } from "../map/(external)/hoppscotch/settings/_nav.block.js";
+import { PickExtensionInterceptorBlock } from "../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
+import { NavHoppscotchRestBlock } from "../map/(external)/hoppscotch/_nav.block.js";
+import { SetMethodBlock } from "../map/(external)/hoppscotch/_methods/set-method.method.block.js";
+import { SetUrlBlock } from "../map/(external)/hoppscotch/_methods/set-url.method.block.js";
+import { SetHeadersBlock } from "../map/(external)/hoppscotch/_methods/set-headers.method.block.js";
+import { SetJsonBodyBlock } from "../map/(external)/hoppscotch/_methods/set-json-body.method.block.js";
+import { SendRequestBlock } from "../map/(external)/hoppscotch/_methods/send-request.method.block.js";
+import { AssertStatusBlock } from "../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
+import { ReadResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/read-response-body.method.block.js";
+import { AssertResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/assert-response-body.method.block.js";
+import "../map/(external)/hoppscotch/_page.block.js";
+
+const engine = new Engine(config);
+
+/** POST JSON with a header, check the status and the response body. Needs `extensions: ["hoppscotch"]`. */
+export const hoppscotchPostFlow = engine
+  .map()
+  .start()
+  .gotoExternal(NavHoppscotchSettingsBlock)
+  .method(PickExtensionInterceptorBlock)
+  .gotoExternal(NavHoppscotchRestBlock)
+  .method(SetMethodBlock)
+  .method(SetUrlBlock)
+  .method(SetHeadersBlock)
+  .method(SetJsonBodyBlock)
+  .method(SendRequestBlock)
+  .assert(AssertStatusBlock)
+  .method(ReadResponseBodyBlock)
+  .assert(AssertResponseBodyBlock)
+  .end({ title: "Scaffold: Hoppscotch POST with header and JSON body" });

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

@@ -1,4 +1,5 @@
-import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
+import { Engine } from "waygraph";
+import config from "../../config/waygraph.config.js";
 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";
@@ -8,78 +9,38 @@ import { NavVerificationLinkBlock } from "../map/(app_base)/home/nav-verificatio
 import "../map/(external)/mailpit/_page.block.js";
 import { MailpitSel } from "../map/(external)/mailpit/_sel.js";
 
-const engine = new Engine();
+const engine = new Engine(config);
 
-/**
- * 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",
-        },
-      },
-    },
-  },
-);
+/** Needs a Mailpit at WAYGRAPH_MAIL_URL (default http://127.0.0.1:8025); tests/mail-verify.spec.ts starts one. */
+export const mailVerifyFlow = engine
+  .map()
+  .start()
+  .gotoExternal(NavMailpitInboxBlock)
+  .assert(
+    AssertEmailReceivedBlock.stubAfter((ctx) => {
+      ctx.ring("note", {
+        selector: MailpitSel.messageRow,
+        label: "AC · email arrived",
+        detail: "Confirmed before opening anything.",
+        tag: "AC",
+      });
+    }),
+  )
+  .method(OpenMessageBlock)
+  .assert(
+    AssertEmailContentBlock.stubAfter((ctx) => {
+      ctx.ring("note", { selector: MailpitSel.previewIframe, label: "AC · email body matches expected copy", tag: "AC" });
+    }),
+  )
+  .method(
+    ExtractEmailLinkBlock.stubAfter((ctx) => {
+      ctx.ring("note", {
+        selector: MailpitSel.previewIframe,
+        label: "AC · link found",
+        detail: "Read from the message preview iframe.",
+        tag: "AC",
+      });
+    }),
+  )
+  .gotoPage(NavVerificationLinkBlock)
+  .end({ title: "Scaffold: Cross-origin mail verification (QA-rich)" });

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

@@ -1,74 +1,50 @@
-import {
-  Engine,
-  start,
-  end,
-  withTitle,
-  withHighlightFixtures,
-  withSessionReset,
-  withMemStub,
-  registerMemStub,
-} from "waygraph";
+import { Engine } from "waygraph";
+import config from "../../config/waygraph.config.js";
+import { DemoSel } from "../map/(app_base)/home/_sel.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 { SelectedItem } from "../states/demo.mem-keys.js";
+import "../states/demo.mem-stubs.js";
 import "../map/(app_base)/home/_page.block.js";
 
-const engine = new Engine();
+const engine = new Engine(config);
 
-/**
- * memStub: a real fixture row (`alpha`/`Alpha`), registered once so this Flow never needs
- * --data at all. Still override-able - `--data '{"demo.selectedItem":{"id":"beta",...}}'`
- * wins over this registration, same as any other memStub (see docs/REFERENCE.md's own
- * "memStub - fake values for requires" section).
- */
-registerMemStub(SelectedItem.key, () => ({ id: "alpha", name: "Alpha" }));
+// `memStub: true` fills SelectedItem (alpha) from src/states/demo.mem-stubs.ts; --data overrides it.
+const AddShown = AddItemBlock.stubBefore((ctx) => {
+  ctx.ring("add", { selector: DemoSel.catalog, label: "Catalog" });
+})
+  .stubAfter((ctx) => {
+    ctx.ring("cart", {
+      selector: DemoSel.cartCount,
+      label: "AC · item in cart",
+      detail: "Cart count bumped after Add.",
+      tag: "AC",
+      duration: true,
+    });
+  })
+  .stubOnError((ctx) => {
+    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart at failure", tag: "FAIL" });
+  });
 
-/**
- * Effect + Method demo. `requires: [SelectedItem.key]` (on `add-item`) is filled automatically
- * by the memStub registration above - no --data needed. Override it with real data, or use
- * `waygraph auto` which fills SelectedItem via instanceOptions instead:
- *
- *   waygraph demo --blocks shopFlow                                    # memStub fills it
- *   waygraph demo --blocks shopFlow --data '{"demo.selectedItem":{"id":"beta","name":"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 = withMemStub(
-  withHighlightFixtures(
-    withTitle(
-      withSessionReset(
-        engine.defineFlow([
-          start,
-          NavHomeBlock,
-          AddItemBlock,
-          AssertItemAddedBlock,
-          RemoveItemBlock,
-          AddItemBlock,
-          ClearCartBlock,
-          end,
-        ]),
-      ),
-      "Scaffold: Shop (Effect + clear)",
-    ),
-    {
-      "add-item": {
-        stubAfter: {
-          cart: {
-            label: "AC · item in cart",
-            detail: "Cart count bumped after Add.",
-            tag: "AC",
-            duration: true,
-          },
-        },
-      },
-    },
-  ),
-);
+const RemoveShown = RemoveItemBlock.stubAfter((ctx) => {
+  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
+});
+
+const ClearShown = ClearCartBlock.stubBefore((ctx) => {
+  ctx.ring("clear", { selector: DemoSel.clear, label: "Clear cart" });
+}).stubAfter((ctx) => {
+  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Empty cart", duration: true });
+});
+
+export const shopFlow = engine
+  .map()
+  .start()
+  .gotoPage(NavHomeBlock)
+  .method(AddShown)
+  .assert(AssertItemAddedBlock)
+  .method(RemoveShown)
+  .method(AddShown)
+  .method(ClearShown)
+  .end({ title: "Scaffold: Shop (Effect + clear)", sessionReset: true, memStub: true });

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

@@ -2,15 +2,6 @@ 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 shape as home/ (its own file:// page, no server) - lives
- * under (app_base), not (external). See docs/REFERENCE.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).",

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

@@ -2,11 +2,6 @@ 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.",

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

@@ -1,4 +1,4 @@
-// Relative to playwright.config.ts's baseURL (the (app_base) folder, set by `waygraph init`).
+// Relative to baseUrl in config/waygraph.config.ts (the (app_base) folder, set by `waygraph init`).
 export const DOCS_URL = "docs/index.html";
 
 export const DocsSel = {

package/templates/scaffold/src/map/(app_base)/home/_methods/add-item.effect.block.ts

@@ -7,14 +7,7 @@ import type { CanAddItem, ItemInCart } from "../../../../states/demo.states.js";
 import { SelectedItem } from "../../../../states/demo.mem-keys.js";
 import { DemoSel } from "../_sel.js";
 
-/**
- * Kind: Effect
- * Helper: defineEffectBlock
- * Route: demo-web/methods/
- *
- * Mutates one catalog row from mem. `waygraph auto` lists one "Add …" row per
- * live Add button via instanceOptions.
- */
+/** `waygraph auto` lists one "Add …" row per live Add button via `instanceOptions`. */
 export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
   name: "add-item",
   description: "Adds the mem-selected catalog item to the cart.",
@@ -36,7 +29,7 @@ export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
     ],
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
-    const buttons = page.locator("button.add:not([hidden])");
+    const buttons = page.locator(DemoSel.addButtons);
     const n = await buttons.count();
     const out: WaygraphInstanceOption[] = [];
     for (let i = 0; i < n; i++) {
@@ -55,13 +48,4 @@ export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
     }
     return out;
   },
-})
-  .stubBefore((ctx) => {
-    ctx.ring("add", { selector: DemoSel.catalog, label: "Catalog" });
-  })
-  .stubAfter((ctx) => {
-    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
-  })
-  .stubOnError((ctx) => {
-    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart at failure", tag: "FAIL" });
-  });
+});

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

@@ -2,15 +2,7 @@ import { defineAssertBlock, Trait } from "waygraph";
 import type { Home } from "../../../../states/demo.states.js";
 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.
- */
+/** Heading still shows after arrival; the slide is a YAP caption for the demo overlay. */
 export const AssertHelloBlock = defineAssertBlock<Home>({
   name: "assert-hello",
   description: "Confirms the hello heading is still visible after arrival.",
@@ -25,19 +17,4 @@ export const AssertHelloBlock = defineAssertBlock<Home>({
       duration: true,
     },
   ],
-})
-  .stubBefore((ctx) => {
-    ctx.ring("title", { selector: DemoSel.title, label: "Heading about to check" });
-  })
-  .stubAfter((ctx) => {
-    ctx.ring("title", {
-      selector: DemoSel.title,
-      label: "Hello confirmed",
-      detail: "Offline scaffold proof point.",
-      duration: true,
-    });
-    ctx.ring("sub", { selector: DemoSel.sub, label: "Subcopy", duration: 1500 });
-  })
-  .stubOnError((ctx) => {
-    ctx.ring("title", { selector: DemoSel.title, label: "Heading at failure", tag: "FAIL" });
-  });
+});

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

@@ -3,11 +3,7 @@ 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.
- */
+// Reads mem at check time, so it follows whichever item add-item acted on.
 const removeButtonVisibleForSelectedItem: TraitType = {
   name: "remove-button-visible-for-selected-item",
   async check(page, mem) {
@@ -16,20 +12,7 @@ const removeButtonVisibleForSelectedItem: TraitType = {
   },
 };
 
-/**
- * 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).
- */
+/** The mem-selected item's own Remove button appeared and the cart count reflects it. */
 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.",

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

@@ -2,16 +2,6 @@ import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { ItemInCart, CartEmpty } from "../../../../states/demo.states.js";
 import { DemoSel } from "../_sel.js";
 
-/**
- * Kind: Method
- * Helper: defineMethodBlock
- * 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<ItemInCart, CartEmpty>({
   name: "clear-cart",
   description: "Clears every item via the Clear cart control.",
@@ -22,10 +12,4 @@ export const ClearCartBlock = defineMethodBlock<ItemInCart, CartEmpty>({
     resolve: () => checkpoint("CartEmpty"),
     verify: [Trait.text(DemoSel.cartCount, "0")],
   },
-})
-  .stubBefore((ctx) => {
-    ctx.ring("clear", { selector: DemoSel.clear, label: "Clear cart" });
-  })
-  .stubAfter((ctx) => {
-    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Empty cart", duration: true });
-  });
+});

package/templates/scaffold/src/map/(app_base)/home/_methods/remove-item.effect.block.ts

@@ -7,13 +7,6 @@ import type { CartEmpty, ItemInCart } from "../../../../states/demo.states.js";
 import { SelectedItem } from "../../../../states/demo.mem-keys.js";
 import { DemoSel } from "../_sel.js";
 
-/**
- * Kind: Effect
- * Helper: defineEffectBlock
- * Route: demo-web/methods/
- *
- * Removes one in-cart row. Auto menus one row per visible Remove button.
- */
 export const RemoveItemBlock = defineEffectBlock<ItemInCart, CartEmpty>({
   name: "remove-item",
   description: "Removes the mem-selected catalog item from the cart.",
@@ -35,7 +28,7 @@ export const RemoveItemBlock = defineEffectBlock<ItemInCart, CartEmpty>({
     ],
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
-    const buttons = page.locator("button.remove:not([hidden])");
+    const buttons = page.locator(DemoSel.removeButtons);
     const n = await buttons.count();
     const out: WaygraphInstanceOption[] = [];
     for (let i = 0; i < n; i++) {
@@ -54,6 +47,4 @@ export const RemoveItemBlock = defineEffectBlock<ItemInCart, CartEmpty>({
     }
     return out;
   },
-}).stubAfter((ctx) => {
-  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
 });

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

@@ -2,21 +2,10 @@ import { defineNavBlock, Trait } from "waygraph";
 import type { Home } from "../../../states/demo.states.js";
 import { DemoSel, HOME_URL } from "./_sel.js";
 
-/**
- * Kind: Nav
- * Helper: defineNavBlock
- * Route: (app_base)/home/  (synthetic "/")
- */
 export const NavHomeBlock = defineNavBlock<Home>({
   name: "nav-home",
   description: "Opens the offline catalog page (file://, no server).",
   checkpoint: "Home",
   url: HOME_URL,
   verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.catalog)],
-})
-  .stubAfter((ctx) => {
-    ctx.ring("title", { selector: DemoSel.title, label: "Home heading", duration: true });
-  })
-  .stubOnError((ctx) => {
-    ctx.ring("title", { selector: DemoSel.title, label: "Home heading at failure" });
-  });
+});

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

@@ -6,15 +6,6 @@ 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: (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.
- * Arrival-only (nav-home already landed on Home).
- */
 export const HomePageBlock = definePageBlock<Home>({
   name: "page-home",
   description: "Offline home hub - add/remove effects, clear, assert-hello.",

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

@@ -1,4 +1,4 @@
-// Relative to playwright.config.ts's baseURL (the (app_base) folder, set by `waygraph init`).
+// Relative to baseUrl in config/waygraph.config.ts (the (app_base) folder, set by `waygraph init`).
 export const HOME_URL = "home/index.html";
 
 export const DemoSel = {
@@ -7,6 +7,8 @@ export const DemoSel = {
   cartCount: "[data-test=cart-count]",
   catalog: "#catalog",
   clear: "[data-test=clear-cart]",
+  addButtons: "button.add:not([hidden])",
+  removeButtons: "button.remove:not([hidden])",
   addBtn: (id: string) => `[data-test=add-${id}]`,
   removeBtn: (id: string) => `[data-test=remove-${id}]`,
   verifiedBanner: "#verified-banner",

package/templates/scaffold/src/map/(app_base)/home/nav-verification-link.block.ts

@@ -3,29 +3,7 @@ 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.
- */
+/** Follows the link `extract-email-link` put in mem. No `requires`: an earlier Block in the chain produces it. */
 export const NavVerificationLinkBlock = defineNavBlock<HomeVerified>({
   name: "nav-verification-link",
   checkpoint: "HomeVerified",

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/assert-response-body.method.block.ts

@@ -0,0 +1,21 @@
+import { defineAssertBlock, type Trait } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { ExpectedResponseText, ResponseBody } from "../../../../states/demo.mem-keys.js";
+
+// Hoppscotch pretty-prints JSON, so compare with whitespace removed from both sides.
+const squash = (text: string): string => text.replace(/\s+/g, "");
+
+const bodyContainsExpected: Trait = {
+  name: "response-body-contains-expected",
+  async check(_page, mem) {
+    return squash(mem.get(ResponseBody)).includes(squash(mem.get(ExpectedResponseText)));
+  },
+};
+
+export const AssertResponseBodyBlock = defineAssertBlock<HoppscotchRest>({
+  name: "assert-response-body",
+  description: "Confirms the response body read earlier contains the mem-supplied text (whitespace ignored).",
+  checkpoint: "HoppscotchRest",
+  requires: [ExpectedResponseText],
+  verify: [bodyContainsExpected],
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/assert-response-header.method.block.ts

@@ -0,0 +1,19 @@
+import { defineAssertBlock, type Trait } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { ExpectedResponseHeader, ResponseHeaders } from "../../../../states/demo.mem-keys.js";
+
+const headerMatches: Trait = {
+  name: "response-header-matches",
+  async check(_page, mem) {
+    const { name, value } = mem.get(ExpectedResponseHeader.key);
+    return mem.get(ResponseHeaders)[name.toLowerCase()] === value;
+  },
+};
+
+export const AssertResponseHeaderBlock = defineAssertBlock<HoppscotchRest>({
+  name: "assert-response-header",
+  description: "Confirms a response header read earlier has the mem-supplied value.",
+  checkpoint: "HoppscotchRest",
+  requires: [ExpectedResponseHeader.key],
+  verify: [headerMatches],
+});