waygraph 0.15.53 → 0.16.0

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

@@ -1,11 +1,13 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { ResponseBody } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { ResponseBody } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const ReadResponseBodyBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const ReadResponseBodyBlock = defineMethodBlock({
   name: "read-response-body",
   description: "Reads the raw response body into mem.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   instruction: {
     async act(page, _in, mem) {
       await page.locator(HoppscotchSel.rawTab).click();
@@ -16,6 +18,5 @@ export const ReadResponseBodyBlock = defineMethodBlock<HoppscotchRest, Hoppscotc
       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

@@ -1,11 +1,13 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { ResponseHeaders } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { ResponseHeaders } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const ReadResponseHeadersBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const ReadResponseHeadersBlock = defineMethodBlock({
   name: "read-response-headers",
   description: "Reads the response headers (lower-cased names) into mem.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   instruction: {
     async act(page, _in, mem) {
       await page.locator(HoppscotchSel.responseHeadersTab).click();
@@ -16,6 +18,5 @@ export const ReadResponseHeadersBlock = defineMethodBlock<HoppscotchRest, Hoppsc
       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

@@ -1,15 +1,16 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const SendRequestBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const SendRequestBlock = defineMethodBlock({
   name: "send-request",
   description: "Sends the request and waits for the response status to appear.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   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

@@ -1,11 +1,13 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { RequestBearerToken } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { RequestBearerToken } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const SetBearerTokenBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const SetBearerTokenBlock = defineMethodBlock({
   name: "set-bearer-token",
   description: "Sets the Authorization tab to Bearer and types the mem-supplied token.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   requires: [RequestBearerToken],
   instruction: {
     async act(page, _in, mem) {
@@ -15,6 +17,5 @@ export const SetBearerTokenBlock = defineMethodBlock<HoppscotchRest, HoppscotchR
       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

@@ -1,11 +1,13 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { RequestHeaders } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { RequestHeaders } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const SetHeadersBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const SetHeadersBlock = defineMethodBlock({
   name: "set-headers",
   description: "Adds each mem-supplied header (name -> value) on the Headers tab.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   requires: [RequestHeaders],
   instruction: {
     async act(page, _in, mem) {
@@ -18,6 +20,5 @@ export const SetHeadersBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>
         await page.keyboard.type(value);
       }
     },
-    resolve: () => checkpoint("HoppscotchRest"),
   },
 });

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

@@ -1,6 +1,6 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { RequestBody } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { RequestBody } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
 const spansLines = (text: string): boolean => {
@@ -11,9 +11,11 @@ const spansLines = (text: string): boolean => {
   }
 };
 
-export const SetJsonBodyBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const SetJsonBodyBlock = defineMethodBlock({
   name: "set-json-body",
   description: "Sets the content type to application/json and types the mem-supplied body, prettified.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   requires: [RequestBody],
   instruction: {
     async act(page, _in, mem) {
@@ -31,6 +33,5 @@ export const SetJsonBodyBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest
         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

@@ -1,17 +1,18 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { RequestMethod } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { RequestMethod } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const SetMethodBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const SetMethodBlock = defineMethodBlock({
   name: "set-method",
   description: "Picks the HTTP method (GET, POST, PUT, PATCH, DELETE, ...) from the request bar.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   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

@@ -1,11 +1,13 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { RequestParams } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { RequestParams } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const SetQueryParamsBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const SetQueryParamsBlock = defineMethodBlock({
   name: "set-query-params",
   description: "Adds each mem-supplied query parameter (name -> value) on the Parameters tab.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   requires: [RequestParams],
   instruction: {
     async act(page, _in, mem) {
@@ -17,6 +19,5 @@ export const SetQueryParamsBlock = defineMethodBlock<HoppscotchRest, HoppscotchR
         await page.keyboard.type(value);
       }
     },
-    resolve: () => checkpoint("HoppscotchRest"),
   },
 });

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

@@ -1,11 +1,13 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { HoppscotchRest } from "../../../../states/demo.states.js";
-import { RequestUrl } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { HoppscotchRest } from "../_states.js";
+import { RequestUrl } from "../_keys.js";
 import { HoppscotchSel } from "../_sel.js";
 
-export const SetUrlBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
+export const SetUrlBlock = defineMethodBlock({
   name: "set-url",
   description: "Types the request URL into the request bar.",
+  from: HoppscotchRest,
+  to: HoppscotchRest,
   requires: [RequestUrl],
   instruction: {
     async act(page, _in, mem) {
@@ -13,6 +15,5 @@ export const SetUrlBlock = defineMethodBlock<HoppscotchRest, HoppscotchRest>({
       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

@@ -1,10 +1,10 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { HoppscotchRest } from "../../../states/demo.states.js";
+import { HoppscotchRest } from "./_states.js";
 import { HoppscotchSel } from "./_sel.js";
 
-export const NavHoppscotchRestBlock = defineNavBlock<HoppscotchRest>({
+export const NavHoppscotchRestBlock = defineNavBlock({
   name: "nav-hoppscotch-rest",
-  checkpoint: "HoppscotchRest",
+  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

@@ -1,5 +1,5 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { HoppscotchRest } from "../../../states/demo.states.js";
+import { HoppscotchRest } from "./_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";
@@ -14,10 +14,10 @@ import { ReadResponseHeadersBlock } from "./_methods/read-response-headers.metho
 import { AssertResponseHeaderBlock } from "./_methods/assert-response-header.method.block.js";
 import { HoppscotchSel } from "./_sel.js";
 
-export const HoppscotchRestPageBlock = definePageBlock<HoppscotchRest>({
+export const HoppscotchRestPageBlock = definePageBlock({
   name: "page-hoppscotch-rest",
   description: "Hoppscotch REST client - build a request, send it, check the response.",
-  checkpoint: "HoppscotchRest",
+  checkpoint: HoppscotchRest,
   verify: [Trait.visible(HoppscotchSel.send)],
   methods: {
     setMethod: () => SetMethodBlock,

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

@@ -0,0 +1,6 @@
+import { checkpoint } from "waygraph";
+
+export const HoppscotchSettings = checkpoint("HoppscotchSettings");
+export type HoppscotchSettings = typeof HoppscotchSettings;
+export const HoppscotchRest = checkpoint("HoppscotchRest");
+export type HoppscotchRest = typeof HoppscotchRest;

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

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

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

@@ -0,0 +1,13 @@
+import { key, keyGroup } from "waygraph";
+
+/** The link read out of the opened message - set by extract-email-link. */
+export const EmailLink = keyGroup<{ url: string }>("mailpit.emailLink");
+
+/** Matched by email, not inbox position, so one inbox can hold several recipients' mail. */
+export const ExpectedRecipient = keyGroup<{ email: string }>("mailpit.expectedRecipient");
+
+/** Substring the link's `href` must contain; mem varies per scenario, the Blocks do not. */
+export const ExpectedLinkPattern = key<string>("mailpit.expectedLinkPattern");
+
+/** Substring the open message's body must contain. */
+export const ExpectedEmailContent = key<string>("mailpit.expectedEmailContent");

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

@@ -1,6 +1,6 @@
 import { defineAssertBlock, type Trait } from "waygraph";
-import type { MailpitMessageOpen } from "../../../../states/demo.states.js";
-import { ExpectedEmailContent } from "../../../../states/demo.mem-keys.js";
+import { MailpitMessageOpen } from "../_states.js";
+import { ExpectedEmailContent } from "../_keys.js";
 import { MailpitSel } from "../_sel.js";
 
 // Reads the expected copy from mem, so one Block serves any email template.
@@ -14,10 +14,10 @@ const bodyContainsExpectedText: Trait = {
 };
 
 /** The open message says what the scenario expects (copy comes from mem). */
-export const AssertEmailContentBlock = defineAssertBlock<MailpitMessageOpen>({
+export const AssertEmailContentBlock = defineAssertBlock({
   name: "assert-email-content",
   description: "Confirms the open message's body contains the mem-supplied expected copy.",
-  checkpoint: "MailpitMessageOpen",
+  checkpoint: MailpitMessageOpen,
   requires: [ExpectedEmailContent],
   verify: [bodyContainsExpectedText],
 });

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

@@ -1,6 +1,6 @@
 import { defineAssertBlock, type Trait } from "waygraph";
-import type { MailpitInbox } from "../../../../states/demo.states.js";
-import { ExpectedRecipient } from "../../../../states/demo.mem-keys.js";
+import { MailpitInbox } from "../_states.js";
+import { ExpectedRecipient } from "../_keys.js";
 import { MailpitSel } from "../_sel.js";
 
 // Mem-aware: which recipient to look for is only known at run time.
@@ -21,10 +21,10 @@ const emailReceived: Trait = {
 };
 
 /** A message for the expected recipient has arrived; nothing is opened or consumed. */
-export const AssertEmailReceivedBlock = defineAssertBlock<MailpitInbox>({
+export const AssertEmailReceivedBlock = defineAssertBlock({
   name: "assert-email-received",
   description: "Confirms a message addressed to the expected recipient has arrived.",
-  checkpoint: "MailpitInbox",
+  checkpoint: MailpitInbox,
   requires: [ExpectedRecipient.key],
   verify: [emailReceived],
 });

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

@@ -1,12 +1,14 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { MailpitMessageOpen } from "../../../../states/demo.states.js";
-import { EmailLink, ExpectedLinkPattern } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { MailpitMessageOpen } from "../_states.js";
+import { EmailLink, ExpectedLinkPattern } from "../_keys.js";
 import { MailpitSel } from "../_sel.js";
 
 /** Reads the link matching `ExpectedLinkPattern` out of the preview into mem; going there is a separate Nav. */
-export const ExtractEmailLinkBlock = defineMethodBlock<MailpitMessageOpen, MailpitMessageOpen>({
+export const ExtractEmailLinkBlock = defineMethodBlock({
   name: "extract-email-link",
   description: "Reads the link matching the mem-supplied pattern out of the open message's preview.",
+  from: MailpitMessageOpen,
+  to: MailpitMessageOpen,
   requires: [ExpectedLinkPattern],
   instruction: {
     async act(page, _in, mem) {
@@ -18,6 +20,5 @@ export const ExtractEmailLinkBlock = defineMethodBlock<MailpitMessageOpen, Mailp
       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

@@ -1,13 +1,15 @@
 // waygraph-ignore: empty-verify (confirmed by AssertEmailContentBlock right after it in mail-verify.flow.ts)
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { MailpitInbox, MailpitMessageOpen } from "../../../../states/demo.states.js";
-import { ExpectedRecipient } from "../../../../states/demo.mem-keys.js";
+import { defineMethodBlock } from "waygraph";
+import { MailpitInbox, MailpitMessageOpen } from "../_states.js";
+import { ExpectedRecipient } from "../_keys.js";
 import { MailpitSel } from "../_sel.js";
 
 /** Opens the newest message for the expected recipient (matched by email, not position). */
-export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOpen>({
+export const OpenMessageBlock = defineMethodBlock({
   name: "open-message",
   description: "Opens the newest message addressed to the expected recipient.",
+  from: MailpitInbox,
+  to: MailpitMessageOpen,
   requires: [ExpectedRecipient.key],
   instruction: {
     async act(page, _in, mem) {
@@ -25,6 +27,5 @@ export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOp
         timeout: 15_000,
       });
     },
-    resolve: () => checkpoint("MailpitMessageOpen"),
   },
 });

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

@@ -1,12 +1,12 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { MailpitInbox } from "../../../states/demo.states.js";
+import { MailpitInbox } from "./_states.js";
 
 // 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>({
+export const NavMailpitInboxBlock = defineNavBlock({
   name: "nav-mailpit-inbox",
-  checkpoint: "MailpitInbox",
+  checkpoint: MailpitInbox,
   url: mailpitUrl,
   verify: [Trait.url({ pathname: "/" })],
 });

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

@@ -1,14 +1,14 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { MailpitInbox } from "../../../states/demo.states.js";
+import { MailpitInbox } from "./_states.js";
 import { AssertEmailReceivedBlock } from "./_methods/assert-email-received.method.block.js";
 import { OpenMessageBlock } from "./_methods/open-message.method.block.js";
 import { AssertEmailContentBlock } from "./_methods/assert-email-content.method.block.js";
 import { ExtractEmailLinkBlock } from "./_methods/extract-email-link.method.block.js";
 
-export const MailpitInboxPageBlock = definePageBlock<MailpitInbox>({
+export const MailpitInboxPageBlock = definePageBlock({
   name: "page-mailpit-inbox",
   description: "Mailpit dev inbox hub - confirm arrival/content, open the expected message, read its link.",
-  checkpoint: "MailpitInbox",
+  checkpoint: MailpitInbox,
   verify: [Trait.url({ pathname: "/" })],
   methods: {
     assertEmailReceived: () => AssertEmailReceivedBlock,

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

@@ -0,0 +1,9 @@
+import { checkpoint } from "waygraph";
+
+/** Mailpit inbox UI reached; message list visible. */
+export const MailpitInbox = checkpoint("MailpitInbox");
+export type MailpitInbox = typeof MailpitInbox;
+
+/** The message addressed to the expected recipient is open; preview iframe visible. */
+export const MailpitMessageOpen = checkpoint("MailpitMessageOpen");
+export type MailpitMessageOpen = typeof MailpitMessageOpen;

package/templates/scaffold/src/map/README.md

@@ -24,6 +24,13 @@ real URL. `waygraph map`/`waygraph check` fail loudly if a page folder's real UR
 matching its own name - that's the point of this layout: drift becomes a build failure, not a
 silent surprise months later.
 
+## A group that owns its states: a map package
+
+A folder with its own `_states.ts` (and `_keys.ts`), like `(external)/hoppscotch/`, is a self-contained map: its files
+import only `waygraph` and each other (`waygraph check` warns otherwise). `waygraph map pack hoppscotch` compiles it into
+`.waygraph/packages/hoppscotch` - publish that, `npm i` it in another project, and its Blocks show up there in `graph`,
+`auto`, the manifest and flows (`import { SetUrlBlock } from "waygraph-map-hoppscotch"`).
+
 ## Adding a page
 
 Copy an existing page folder, keep the four fixed names, update `_nav`/`_page`/`_sel` for the

package/templates/scaffold/src/states/README.md

@@ -3,7 +3,7 @@
 Checkpoint types and Mem keys - the typed vocabulary every Block in `src/map/` is written
 against. Nothing here drives the browser; this is pure data shape.
 
-- `*.states.ts` - `type X = Checkpoint<"X">` declarations. One per real app state
+- `*.states.ts` - Checkpoint values: `export const X = checkpoint("X"); export type X = typeof X;`. One per real app state
   (`LoginPage`, `LoggedIn`), never `Checkpoint<string>` (a wildcard - `waygraph check` warns
   on it; a Block should say exactly which states it moves between).
 - `*.mem-keys.ts` - `key<T>("...")` / `keyGroup<T>("...")` declarations. A Mem key stores a
@@ -13,3 +13,6 @@ against. Nothing here drives the browser; this is pure data shape.
 
 Add a new Checkpoint or Mem key here before writing the Block that needs it - Blocks import
 from this directory, this directory never imports from `src/map/`.
+
+A tool on another origin (`src/map/(external)/mailpit/`, `.../hoppscotch/`) keeps its own Checkpoints and keys in its
+folder (`_states.ts`, `_keys.ts`) instead, so the folder can be packed and reused: `waygraph map pack mailpit`.

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

@@ -1,32 +1,4 @@
-import { key, keyGroup } from "waygraph";
+import { keyGroup } from "waygraph";
 
 /** 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");
-
-/** 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; mem varies per scenario, the Blocks do not. */
-export const ExpectedLinkPattern = key<string>("demo.expectedLinkPattern");
-
-/** 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.states.ts

@@ -1,23 +1,17 @@
-import type { Checkpoint } from "waygraph";
+import { checkpoint } from "waygraph";
 
-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/) ---
-
-/** Mailpit inbox UI reached; message list visible. */
-export type MailpitInbox = Checkpoint<"MailpitInbox">;
+export const Home = checkpoint("Home");
+export type Home = typeof Home;
+export const HomeVerified = checkpoint("HomeVerified");
+export type HomeVerified = typeof HomeVerified;
+export const ItemInCart = checkpoint("ItemInCart");
+export type ItemInCart = typeof ItemInCart;
+export const CartEmpty = checkpoint("CartEmpty");
+export type CartEmpty = typeof CartEmpty;
 
-/** The message addressed to the expected recipient is open; preview iframe visible. */
-export type MailpitMessageOpen = Checkpoint<"MailpitMessageOpen">;
-
-// --- Hoppscotch (external API client, src/map/(external)/hoppscotch/) ---
-
-export type HoppscotchSettings = Checkpoint<"HoppscotchSettings">;
-export type HoppscotchRest = Checkpoint<"HoppscotchRest">;
+/** Anywhere an item can be added from: fresh on Home, or after the cart was emptied. */
+export const CanAddItem = [Home, CartEmpty] as const;
+export type CanAddItem = (typeof CanAddItem)[number];
 
-export type Docs = Checkpoint<"Docs">;
+export const Docs = checkpoint("Docs");
+export type Docs = typeof Docs;

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

@@ -5,17 +5,7 @@ import config from "../config/waygraph.config.js";
 import { hoppscotchGetFlow } from "../src/flows/(external)/hoppscotch/get.flow.js";
 import { hoppscotchAuthFlow } from "../src/flows/(external)/hoppscotch/auth.flow.js";
 import { hoppscotchPostFlow } from "../src/flows/(external)/hoppscotch/post.flow.js";
-import {
-  ExpectedResponseHeader,
-  ExpectedResponseText,
-  ExpectedStatus,
-  RequestBearerToken,
-  RequestBody,
-  RequestHeaders,
-  RequestMethod,
-  RequestParams,
-  RequestUrl,
-} from "../src/states/demo.mem-keys.js";
+import { ExpectedResponseHeader, ExpectedResponseText, ExpectedStatus, RequestBearerToken, RequestBody, RequestHeaders, RequestMethod, RequestParams, RequestUrl } from "../src/map/(external)/hoppscotch/_keys.js";
 
 // The API under test: no CORS headers, so only the extension can reach it from hoppscotch.io.
 let server: Server;

package/templates/scaffold/tests/mail-verify.spec.ts

@@ -3,7 +3,7 @@ import { spawnSync } from "node:child_process";
 import net from "node:net";
 import { MemPage, checkpoint } from "waygraph";
 import { emailVerificationFlow } from "../src/flows/(user-stories)/email-verification.flow.js";
-import { ExpectedRecipient, ExpectedLinkPattern, ExpectedEmailContent } from "../src/states/demo.mem-keys.js";
+import { ExpectedRecipient, ExpectedLinkPattern, ExpectedEmailContent } from "../src/map/(external)/mailpit/_keys.js";
 import { HOME_URL } from "../src/map/(app_base)/home/_sel.js";
 
 // Plays "the app sent a verification email": starts a throwaway Mailpit container, sends a real SMTP message,
@@ -144,7 +144,7 @@ test("assert-email-received fails loud, naming itself, when no email ever arrive
     mem.set(ExpectedRecipient({ email: "nobody-sent-this-one@example.com" }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
-    // A defineFlow chain's verify-failure error names the whole path taken so
+    // A flow's verify-failure error names the whole path taken so
     // far (each composed Block's own name accumulates through connect()),
     // not just the leaf Block - real, useful QA context, not a bug - so this
     // matches the accumulated name ending at assert-email-received, not an

package/templates/skills/waygraph-blind-pilot.skill.md

@@ -52,12 +52,8 @@ Session control works as `browser …` or `auto …` with the same `<sessionId>`
   Block file can simply vanish from the graph with no error printed anywhere obvious - if a
   Block you just wrote doesn't show up after `browser reload`, check `waygraph graph`'s own
   `skipped` list and the file's syntax directly, don't assume it just needs more time.
-- **`defineAssertBlock` needs no `<In, Out>` generic to type-check** (`checkpoint: "X"` alone
-  is enough for TypeScript to infer it) - but older/naive static-graph discovery logic may
-  rely on parsing an explicit generic from source text. If a freshly-written
-  `defineAssertBlock` Block is missing from `waygraph graph`'s edges (silently, no error),
-  check whether this package's own `graph.ts` has the matching-marker fix for it, or add an
-  explicit generic type argument as a workaround.
+- **Pass Checkpoint values** (`checkpoint: X`, `from: X, to: Y`) so a freshly-written Block shows up in the graph from its
+  runtime route. The graph reads routes at runtime, never from source text.
 - **A `<p>`/text-based selector often needs scoping**, not just a class name - a sibling
   "chat list item" and "message preview" frequently share the exact same CSS classes in real
   apps, distinguished only by DOM position (first vs second child of a specific wrapper).