waygraph 0.15.50 → 0.15.52

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.",

package/templates/scaffold/src/map/(external)/mailpit/_methods/open-message.method.block.ts

@@ -4,17 +4,7 @@ import type { MailpitInbox, MailpitMessageOpen } from "../../../../states/demo.s
 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).
- */
+/** Opens the newest message for the expected recipient (matched by email, not position). */
 export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOpen>({
   name: "open-message",
   description: "Opens the newest message addressed to the expected recipient.",

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

@@ -1,15 +1,7 @@
 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.
- */
+// Cross-origin, so it lives under (external)/ and the URL is a function.
 const mailpitUrl = (): string => process.env.WAYGRAPH_MAIL_URL ?? "http://127.0.0.1:8025";
 
 export const NavMailpitInboxBlock = defineNavBlock<MailpitInbox>({

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

@@ -5,17 +5,6 @@ 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: (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.",

package/templates/scaffold/src/states/demo.mem-keys.ts

@@ -1,31 +1,32 @@
 import { key, keyGroup } from "waygraph";
 
-/**
- * Which catalog row `add-item` / `remove-item` act on.
- * `waygraph auto` fills this via Effect `instanceOptions` (one menu row per live button).
- */
+/** The catalog row `add-item` / `remove-item` act on; `waygraph auto` fills it from `instanceOptions`. */
 export const SelectedItem = keyGroup<{ id: string; name: string }>("demo.selectedItem");
 
 /** The link read out of the opened message - set by extract-email-link. */
 export const EmailLink = keyGroup<{ url: string }>("demo.emailLink");
 
-/**
- * The recipient open-message looks for in the inbox. Mailpit lists newest
- * first, but `.first()` alone picks the wrong row once more than one
- * recipient's mail is sitting in the same inbox - match by mem, not position.
- */
+/** Matched by email, not inbox position, so one inbox can hold several recipients' mail. */
 export const ExpectedRecipient = keyGroup<{ email: string }>("demo.expectedRecipient");
 
-/**
- * Substring the link's `href` must contain - lets the same extract-email-link
- * Block serve any number of different email templates/scenarios in one
- * project without a new Block per scenario. Only the mem values change per
- * run, not the Blocks.
- */
+/** Substring the link's `href` must contain; mem varies per scenario, the Blocks do not. */
 export const ExpectedLinkPattern = key<string>("demo.expectedLinkPattern");
 
-/**
- * The substring the open message's body must contain - same reuse reasoning
- * as ExpectedLinkPattern: one Block, many scenarios, driven by mem.
- */
+/** Substring the open message's body must contain. */
 export const ExpectedEmailContent = key<string>("demo.expectedEmailContent");
+
+export const RequestMethod = key<string>("demo.requestMethod");
+export const RequestUrl = key<string>("demo.requestUrl");
+export const RequestHeaders = key<Record<string, string>>("demo.requestHeaders");
+export const RequestParams = key<Record<string, string>>("demo.requestParams");
+export const RequestBearerToken = key<string>("demo.requestBearerToken");
+/** Raw JSON text typed into the request body editor. */
+export const RequestBody = key<string>("demo.requestBody");
+export const ExpectedStatus = key<number>("demo.expectedStatus");
+/** Substring the response body must contain. */
+export const ExpectedResponseText = key<string>("demo.expectedResponseText");
+/** The raw response body, set by read-response-body. */
+export const ResponseBody = key<string>("demo.responseBody");
+/** Response headers (lower-cased names), set by read-response-headers. */
+export const ResponseHeaders = key<Record<string, string>>("demo.responseHeaders");
+export const ExpectedResponseHeader = keyGroup<{ name: string; value: string }>("demo.expectedResponseHeader");

package/templates/scaffold/src/states/demo.mem-stubs.ts

@@ -0,0 +1,4 @@
+import { registerMemStub } from "waygraph";
+import { SelectedItem } from "./demo.mem-keys.js";
+
+registerMemStub(SelectedItem.key, () => ({ id: "alpha", name: "Alpha" }));

package/templates/scaffold/src/states/demo.states.ts

@@ -4,6 +4,8 @@ export type Home = Checkpoint<"Home">;
 export type HomeVerified = Checkpoint<"HomeVerified">;
 export type ItemInCart = Checkpoint<"ItemInCart">;
 export type CartEmpty = Checkpoint<"CartEmpty">;
+/** Anywhere an item can be added from: fresh on Home, or after the cart was emptied. */
+export type CanAddItem = Home | CartEmpty;
 
 // --- Mailpit (external tool surface, src/map/(external)/mailpit/) ---
 
@@ -13,5 +15,9 @@ export type MailpitInbox = Checkpoint<"MailpitInbox">;
 /** The message addressed to the expected recipient is open; preview iframe visible. */
 export type MailpitMessageOpen = Checkpoint<"MailpitMessageOpen">;
 
-/** Reached via src/map/(app_base)/docs/ - see openspec/changes/waygraph-map. */
+// --- Hoppscotch (external API client, src/map/(external)/hoppscotch/) ---
+
+export type HoppscotchSettings = Checkpoint<"HoppscotchSettings">;
+export type HoppscotchRest = Checkpoint<"HoppscotchRest">;
+
 export type Docs = Checkpoint<"Docs">;

package/templates/scaffold/tests/README.md

@@ -2,8 +2,9 @@
 
 Real `@playwright/test` specs, run through `waygraph test` (an alias for `playwright test`,
 plus `waygraph test ui`/`report`/`show-trace` for Playwright's own UI Mode/HTML report/trace
-viewer). These run against the offline fixture server (see `scripts/README.md`), not a live
-network - that's what makes `npm test` green immediately after `waygraph init`.
+viewer). These run against the offline fixture pages under `src/map/` (opened directly via `file://`,
+no server), not a live network - that's what makes `npm test` green immediately after
+`waygraph init`.
 
 A spec here typically runs a `*.flow.ts` from `src/flows/` and asserts on its result, rather
 than driving the page directly - the flow already encodes the real path and its own `verify`

package/templates/scaffold/tests/example.spec.ts

@@ -1,8 +1,7 @@
 import { test, expect } from "@playwright/test";
-import { MemPage, checkpoint } from "waygraph";
+import { MemPage, checkpoint, seedMemStub } from "waygraph";
 import { exampleFlow } from "../src/flows/example.flow.js";
 import { shopFlow } from "../src/flows/shop.flow.js";
-import { SelectedItem } from "../src/states/demo.mem-keys.js";
 
 test("example flow reaches Docs (home -> assert -> sibling docs/ page)", async ({ context }) => {
   const result = await exampleFlow.run(context, new MemPage());
@@ -11,7 +10,7 @@ test("example flow reaches Docs (home -> assert -> sibling docs/ page)", async (
 
 test("shop flow adds then clears (Effect + Method)", async ({ context }) => {
   const mem = new MemPage();
-  mem.set(SelectedItem.key, { id: "alpha", name: "Alpha" });
+  seedMemStub(mem, shopFlow);
   const result = await shopFlow.run(context, mem);
   expect(result).toEqual(checkpoint("CartEmpty"));
 });