waygraph 0.15.51 → 0.15.53

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],
+});

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

@@ -0,0 +1,20 @@
+import { defineAssertBlock, type Trait } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { ExpectedStatus } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+const statusMatches: Trait = {
+  name: "response-status-matches",
+  async check(page, mem) {
+    const text = (await page.locator(HoppscotchSel.status).first().textContent()) ?? "";
+    return Number(text.match(/Status:\s*(\d+)/)?.[1]) === mem.get(ExpectedStatus);
+  },
+};
+
+export const AssertStatusBlock = defineAssertBlock<HoppscotchRest>({
+  name: "assert-status",
+  description: "Confirms the response status code equals the mem-supplied one.",
+  checkpoint: "HoppscotchRest",
+  requires: [ExpectedStatus],
+  verify: [statusMatches],
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.ts

@@ -0,0 +1,18 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchSettings } from "../../../../states/demo.states.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const PickExtensionInterceptorBlock = defineMethodBlock<HoppscotchSettings, HoppscotchSettings>({
+  name: "pick-extension-interceptor",
+  description: "Routes Hoppscotch's requests through the browser extension, which skips CORS.",
+  instruction: {
+    async act(page) {
+      const radio = page.locator(HoppscotchSel.extensionInterceptor);
+      await radio.waitFor({ timeout: 10_000 }).catch(() => {
+        throw new Error('Hoppscotch extension not loaded - add extensions: ["hoppscotch"] to waygraph.config.ts');
+      });
+      await radio.click();
+    },
+    resolve: () => checkpoint("HoppscotchSettings"),
+  },
+});

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

@@ -0,0 +1,21 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { ResponseBody } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const ReadResponseBodyBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "read-response-body",
+  description: "Reads the raw response body into mem.",
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.rawTab).click();
+      const body = page.locator(HoppscotchSel.responseEditor);
+      await body.waitFor();
+      mem.set(ResponseBody, (await body.innerText()).trim());
+      // Raw is the reliable place to read from; go back to the formatted JSON view so a recording ends on it.
+      const json = page.locator(HoppscotchSel.responseJsonTab);
+      if (await json.count()) await json.click();
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

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

@@ -0,0 +1,21 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { ResponseHeaders } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const ReadResponseHeadersBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "read-response-headers",
+  description: "Reads the response headers (lower-cased names) into mem.",
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.responseHeadersTab).click();
+      const cells = page.locator(HoppscotchSel.responseHeaderCell);
+      await cells.first().waitFor();
+      const texts = (await cells.allInnerTexts()).map((t) => t.trim());
+      const headers: Record<string, string> = {};
+      for (let i = 0; i + 1 < texts.length; i += 2) headers[texts[i]!.toLowerCase()] = texts[i + 1]!;
+      mem.set(ResponseHeaders, headers);
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/send-request.method.block.ts

@@ -0,0 +1,15 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const SendRequestBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "send-request",
+  description: "Sends the request and waits for the response status to appear.",
+  instruction: {
+    async act(page) {
+      await page.locator(HoppscotchSel.send).click();
+      await page.locator(HoppscotchSel.status).waitFor({ timeout: 20_000 });
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/set-bearer-token.method.block.ts

@@ -0,0 +1,20 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { RequestBearerToken } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const SetBearerTokenBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "set-bearer-token",
+  description: "Sets the Authorization tab to Bearer and types the mem-supplied token.",
+  requires: [RequestBearerToken],
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.tab("Authorization")).click();
+      await page.locator(HoppscotchSel.authTypeMenu).click();
+      await page.locator(HoppscotchSel.menuItem("Bearer")).click();
+      await page.locator(HoppscotchSel.bearerToken).locator(HoppscotchSel.editor).click();
+      await page.keyboard.type(mem.get(RequestBearerToken));
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/set-headers.method.block.ts

@@ -0,0 +1,23 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { RequestHeaders } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const SetHeadersBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "set-headers",
+  description: "Adds each mem-supplied header (name -> value) on the Headers tab.",
+  requires: [RequestHeaders],
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.tab("Headers")).click();
+      const headers = Object.entries(mem.get(RequestHeaders));
+      for (const [i, [name, value]] of headers.entries()) {
+        await page.locator(HoppscotchSel.keyCell).nth(i).locator(HoppscotchSel.editor).click();
+        await page.keyboard.type(name);
+        await page.locator(HoppscotchSel.valueCell).nth(i).locator(HoppscotchSel.editor).click();
+        await page.keyboard.type(value);
+      }
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

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

@@ -0,0 +1,36 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { RequestBody } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+const spansLines = (text: string): boolean => {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2).includes("\n");
+  } catch {
+    return false;
+  }
+};
+
+export const SetJsonBodyBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "set-json-body",
+  description: "Sets the content type to application/json and types the mem-supplied body, prettified.",
+  requires: [RequestBody],
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.tab("Body")).click();
+      await page.locator(HoppscotchSel.contentTypeMenu).click();
+      await page.locator(HoppscotchSel.menuItem("application/json")).click();
+      const editor = page.locator(HoppscotchSel.visibleEditor).last();
+      await editor.click();
+      const body = mem.get(RequestBody);
+      await page.keyboard.type(body);
+      if (!spansLines(body)) return;
+      // Prettify is the third toolbar button (Clear, Wrap lines, Prettify); typed JSON stays on one line otherwise.
+      await page.locator(HoppscotchSel.bodyToolbarButton).nth(2).click();
+      if ((await editor.locator(HoppscotchSel.bodyLine).count()) < 2) {
+        throw new Error("set-json-body: Hoppscotch's Prettify button was not found, so the body stayed on one line");
+      }
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

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

@@ -0,0 +1,17 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { RequestMethod } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const SetMethodBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "set-method",
+  description: "Picks the HTTP method (GET, POST, PUT, PATCH, DELETE, ...) from the request bar.",
+  requires: [RequestMethod],
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.methodInput).click();
+      await page.locator(HoppscotchSel.menuItem(mem.get(RequestMethod))).click();
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/set-query-params.method.block.ts

@@ -0,0 +1,22 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { RequestParams } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const SetQueryParamsBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "set-query-params",
+  description: "Adds each mem-supplied query parameter (name -> value) on the Parameters tab.",
+  requires: [RequestParams],
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.tab("Parameters")).click();
+      for (const [i, [name, value]] of Object.entries(mem.get(RequestParams)).entries()) {
+        await page.locator(HoppscotchSel.keyCell).nth(i).locator(HoppscotchSel.editor).click();
+        await page.keyboard.type(name);
+        await page.locator(HoppscotchSel.valueCell).nth(i).locator(HoppscotchSel.editor).click();
+        await page.keyboard.type(value);
+      }
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_methods/set-url.method.block.ts

@@ -0,0 +1,18 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { RequestUrl } from "../../../../states/demo.mem-keys.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const SetUrlBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+  name: "set-url",
+  description: "Types the request URL into the request bar.",
+  requires: [RequestUrl],
+  instruction: {
+    async act(page, _in, mem) {
+      await page.locator(HoppscotchSel.urlInput).first().click();
+      await page.keyboard.press("Control+A");
+      await page.keyboard.type(mem.get(RequestUrl));
+    },
+    resolve: () => checkpoint("HoppscotchRest"),
+  },
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_nav.block.ts

@@ -0,0 +1,11 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { HoppscotchRest } from "../../../states/demo.states.js";
+import { HoppscotchSel } from "./_sel.js";
+
+export const NavHoppscotchRestBlock = defineNavBlock<HoppscotchRest>({
+  name: "nav-hoppscotch-rest",
+  checkpoint: "HoppscotchRest",
+  // Cross-origin, so a function: the Map folder rule only checks static URLs.
+  url: () => "https://hoppscotch.io/",
+  verify: [Trait.visible(HoppscotchSel.send)],
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_page.block.ts

@@ -0,0 +1,36 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { HoppscotchRest } from "../../../states/demo.states.js";
+import { SetMethodBlock } from "./_methods/set-method.method.block.js";
+import { SetUrlBlock } from "./_methods/set-url.method.block.js";
+import { SetHeadersBlock } from "./_methods/set-headers.method.block.js";
+import { SetJsonBodyBlock } from "./_methods/set-json-body.method.block.js";
+import { SendRequestBlock } from "./_methods/send-request.method.block.js";
+import { AssertStatusBlock } from "./_methods/assert-status.method.block.js";
+import { ReadResponseBodyBlock } from "./_methods/read-response-body.method.block.js";
+import { AssertResponseBodyBlock } from "./_methods/assert-response-body.method.block.js";
+import { SetQueryParamsBlock } from "./_methods/set-query-params.method.block.js";
+import { SetBearerTokenBlock } from "./_methods/set-bearer-token.method.block.js";
+import { ReadResponseHeadersBlock } from "./_methods/read-response-headers.method.block.js";
+import { AssertResponseHeaderBlock } from "./_methods/assert-response-header.method.block.js";
+import { HoppscotchSel } from "./_sel.js";
+
+export const HoppscotchRestPageBlock = definePageBlock<HoppscotchRest>({
+  name: "page-hoppscotch-rest",
+  description: "Hoppscotch REST client - build a request, send it, check the response.",
+  checkpoint: "HoppscotchRest",
+  verify: [Trait.visible(HoppscotchSel.send)],
+  methods: {
+    setMethod: () => SetMethodBlock,
+    setUrl: () => SetUrlBlock,
+    setHeaders: () => SetHeadersBlock,
+    setQueryParams: () => SetQueryParamsBlock,
+    setBearerToken: () => SetBearerTokenBlock,
+    setJsonBody: () => SetJsonBodyBlock,
+    sendRequest: () => SendRequestBlock,
+    assertStatus: () => AssertStatusBlock,
+    readResponseHeaders: () => ReadResponseHeadersBlock,
+    assertResponseHeader: () => AssertResponseHeaderBlock,
+    readResponseBody: () => ReadResponseBodyBlock,
+    assertResponseBody: () => AssertResponseBodyBlock,
+  },
+});

package/templates/scaffold/src/map/(external)/hoppscotch/_sel.ts

@@ -0,0 +1,27 @@
+// Structural selectors (roles, aria-labels), not bare text: waygraph's own demo overlay repeats page text.
+export const HoppscotchSel = {
+  urlInput: ".cm-content",
+  send: "#send",
+  methodInput: "input#method",
+  /** The request's tab; the response has its own Headers tab, so take the first match. */
+  tab: (name: string) => `button.tab[aria-label='${name}'] >> nth=0`,
+  menuItem: (name: string) => `button[role=menuitem]:has(:text-is("${name}"))`,
+  keyCell: '[placeholder^="Key"]:visible',
+  valueCell: '[placeholder^="Value"]:visible',
+  contentTypeMenu: "label:text-is('Content Type') + span button",
+  bearerToken: '[placeholder^="Your Bearer Token"]',
+  authTypeMenu: "label:text-is('Authorization Type') + span button",
+  /** The element holding "Status: 201 • Created". */
+  status: "*:has(> span.text-secondary:text-is('Status:'))",
+  responseHeadersTab: "button.tab[aria-label='Headers'] >> nth=-1",
+  responseHeaderCell: "*:has(> span.text-secondary:text-is('Status:')) >> xpath=following::span[contains(@class,'select-all')]",
+  responseJsonTab: "button.tab[aria-label='JSON']",
+  rawTab: "button.tab[aria-label='Raw']",
+  responseEditor: "div.flex-col:has(> div.sticky label:text-is('Response Body')) .cm-content",
+  bodyToolbarButton: "div.sticky:has(label:text-is('Raw Request Body')) button",
+  bodyLine: ".cm-line",
+  editor: ".cm-content",
+  visibleEditor: ".cm-content:visible",
+  interceptorHeading: "h4:text('Interceptor')",
+  extensionInterceptor: 'button:has-text("Browser extension: v")',
+} as const;

package/templates/scaffold/src/map/(external)/hoppscotch/settings/_nav.block.ts

@@ -0,0 +1,10 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { HoppscotchSettings } from "../../../../states/demo.states.js";
+import { HoppscotchSel } from "../_sel.js";
+
+export const NavHoppscotchSettingsBlock = defineNavBlock<HoppscotchSettings>({
+  name: "nav-hoppscotch-settings",
+  checkpoint: "HoppscotchSettings",
+  url: () => "https://hoppscotch.io/settings",
+  verify: [Trait.visible(HoppscotchSel.interceptorHeading)],
+});

package/templates/scaffold/src/map/(external)/mailpit/_methods/assert-email-content.method.block.ts

@@ -3,13 +3,7 @@ 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.
- */
+// Reads the expected copy from mem, so one Block serves any email template.
 const bodyContainsExpectedText: Trait = {
   name: "body-contains-expected-text",
   async check(page, mem) {
@@ -19,26 +13,7 @@ const bodyContainsExpectedText: Trait = {
   },
 };
 
-/**
- * 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 docs/REFERENCE.md "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.
- */
+/** The open message says what the scenario expects (copy comes from mem). */
 export const AssertEmailContentBlock = defineAssertBlock<MailpitMessageOpen>({
   name: "assert-email-content",
   description: "Confirms the open message's body contains the mem-supplied expected copy.",

package/templates/scaffold/src/map/(external)/mailpit/_methods/assert-email-received.method.block.ts

@@ -3,12 +3,7 @@ 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.
- */
+// Mem-aware: which recipient to look for is only known at run time.
 const emailReceived: Trait = {
   name: "email-received",
   async check(page, mem) {
@@ -25,21 +20,7 @@ const emailReceived: Trait = {
   },
 };
 
-/**
- * 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.
- */
+/** A message for the expected recipient has arrived; nothing is opened or consumed. */
 export const AssertEmailReceivedBlock = defineAssertBlock<MailpitInbox>({
   name: "assert-email-received",
   description: "Confirms a message addressed to the expected recipient has arrived.",

package/templates/scaffold/src/map/(external)/mailpit/_methods/extract-email-link.method.block.ts

@@ -3,25 +3,7 @@ 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.
- */
+/** Reads the link matching `ExpectedLinkPattern` out of the preview into mem; going there is a separate Nav. */
 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.",