waygraph 0.15.54 → 0.16.0

package/templates/quickstart/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -1,14 +1,8 @@
-import {
-  defineEffectBlock,
-  checkpoint,
-  type Checkpoint,
-  type WaygraphInstanceOption,
-} from "waygraph";
-import type { ItemInCart } from "../../../../states/checkout.states.js";
+import { defineEffectBlock, type WaygraphInstanceOption } from "waygraph";
+import { ItemInCart } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectAddableItems, InventorySel } from "./inventory-items.js";
 
-
 /**
  * Kind: Effect
  * Helper: defineEffectBlock
@@ -17,40 +11,38 @@ import { collectAddableItems, InventorySel } from "./inventory-items.js";
  * Mutates cart for the mem-picked product. waygraph auto lists one
  * "Add ..." row per live Add button via instanceOptions.
  */
-export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
-  {
-    name: "add-to-cart",
-    description:
-      "Adds the item named by mem (saucedemo.selectedItem) to the cart.",
-    requires: [SelectedItem.key],
-    instruction: {
-      async act(page, _input, mem) {
-        const { id } = mem.get(SelectedItem.key);
-        await page.locator(InventorySel.addBtn(id)).click();
-      },
-      resolve: () => checkpoint("ItemInCart"),
-      verify: [
-        {
-          name: "item-added-to-cart",
-          async check(page, mem) {
-            const { id } = mem.get(SelectedItem.key);
-            return await page
-              .locator(InventorySel.removeBtn(id))
-              .first()
-              .isVisible();
-          },
-        },
-      ],
-    },
-    async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
-      const items = await collectAddableItems(page);
-      return items.map((item) => ({
-        id: item.id,
-        label: `Add "${item.name}" to cart`,
-        key: SelectedItem.key,
-        value: item,
-        highlight: InventorySel.addBtn(item.id),
-      }));
+export const AddToCartBlock = defineEffectBlock({
+  name: "add-to-cart",
+  description:
+    "Adds the item named by mem (saucedemo.selectedItem) to the cart.",
+  to: ItemInCart,
+  requires: [SelectedItem.key],
+  instruction: {
+    async act(page, _input, mem) {
+      const { id } = mem.get(SelectedItem.key);
+      await page.locator(InventorySel.addBtn(id)).click();
     },
+    verify: [
+      {
+        name: "item-added-to-cart",
+        async check(page, mem) {
+          const { id } = mem.get(SelectedItem.key);
+          return await page
+            .locator(InventorySel.removeBtn(id))
+            .first()
+            .isVisible();
+        },
+      },
+    ],
+  },
+  async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
+    const items = await collectAddableItems(page);
+    return items.map((item) => ({
+      id: item.id,
+      label: `Add "${item.name}" to cart`,
+      key: SelectedItem.key,
+      value: item,
+      highlight: InventorySel.addBtn(item.id),
+    }));
   },
-);
+});

package/templates/quickstart/src/blocks/saucedemo-web/inventory/methods/remove-all-from-cart.method.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint, type Checkpoint } from "waygraph";
-import type { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
+import { defineMethodBlock, checkpoint } from "waygraph";
+import { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
 import { collectRemovableItems, InventorySel } from "./inventory-items.js";
 
 type BulkObserve = "still-has-items" | "cart-empty";
@@ -14,12 +14,10 @@ type BulkObserve = "still-has-items" | "cart-empty";
  * single-item remove. Out: LoggedIn when cart empty; ItemInCart if anything
  * remains (partial failure / race).
  */
-export const RemoveAllFromCartBlock = defineMethodBlock<
-  Checkpoint<string>,
-  RemoveFromCartOutcome
->({
+export const RemoveAllFromCartBlock = defineMethodBlock({
   name: "remove-all-from-cart",
   description: "Removes every product still showing Remove on this page.",
+  to: RemoveFromCartOutcome,
   instruction: {
     async act(page) {
       const items = await collectRemovableItems(page);

package/templates/quickstart/src/blocks/saucedemo-web/inventory/methods/remove-from-cart.effect.block.ts

@@ -1,5 +1,5 @@
-import { defineEffectBlock, checkpoint, type Checkpoint, type WaygraphInstanceOption } from "waygraph";
-import type { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
+import { defineEffectBlock, checkpoint, type WaygraphInstanceOption } from "waygraph";
+import { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectRemovableItems, InventorySel } from "./inventory-items.js";
 
@@ -13,9 +13,10 @@ type RemoveObserve = "still-has-items" | "cart-empty";
  * Removes the mem-picked product. After Add, waygraph auto shows matching
  * "Remove ..." rows from live Remove buttons.
  */
-export const RemoveFromCartBlock = defineEffectBlock<Checkpoint<string>, RemoveFromCartOutcome>({
+export const RemoveFromCartBlock = defineEffectBlock({
   name: "remove-from-cart",
   description: "Removes the item named by mem (saucedemo.selectedItem) from the cart.",
+  to: RemoveFromCartOutcome,
   requires: [SelectedItem.key],
   instruction: {
     async act(page, _input, mem) {

package/templates/quickstart/src/blocks/saucedemo-web/inventory/nav-item-detail.block.ts

@@ -1,5 +1,5 @@
 import { defineMemNavBlock, Trait, type WaygraphInstanceOption } from "waygraph";
-import type { ItemDetailPage } from "../../../states/checkout.states.js";
+import { ItemDetailPage } from "../../../states/checkout.states.js";
 import { SelectedItem } from "../../../states/checkout.mem-keys.js";
 import {
   collectInventoryItems,
@@ -14,10 +14,10 @@ import {
  * Opens the mem-picked product detail page. waygraph auto lists one
  * "Open ... details" row per inventory card via instanceOptions.
  */
-export const NavItemDetailBlock = defineMemNavBlock<ItemDetailPage>({
+export const NavItemDetailBlock = defineMemNavBlock({
   name: "nav-item-detail",
   description: "Opens the product named by mem (saucedemo.selectedItem) on its detail page.",
-  checkpoint: "ItemDetailPage",
+  checkpoint: ItemDetailPage,
   requires: [SelectedItem.key],
   click: (mem) => InventorySel.title(mem.get(SelectedItem.key).id),
   verify: [Trait.url({ pathname: "/inventory-item.html" })],

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-back-to-inventory.block.ts

@@ -1,5 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
-import type { LoggedIn } from "../../../states/checkout.states.js";
+import { LoggedIn } from "../../../states/checkout.states.js";
 import { ItemDetailSel } from "./item-detail.sel.js";
 
 /**
@@ -10,10 +10,10 @@ import { ItemDetailSel } from "./item-detail.sel.js";
  * click, not url - detail page "Back to products". Separate Block from
  * nav-back-to-products (different From Checkpoint; atomic convention).
  */
-export const NavBackToInventoryBlock = defineNavClickBlock<LoggedIn>({
+export const NavBackToInventoryBlock = defineNavClickBlock({
   name: "nav-back-to-inventory",
   description: "Clicks 'Back to products' on the item detail page.",
-  checkpoint: "LoggedIn",
+  checkpoint: LoggedIn,
   click: ItemDetailSel.backToProductsBtn,
   verify: [Trait.url({ pathname: "/inventory.html" })],
 });

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-back-to-products.block.ts

@@ -1,5 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
-import type { LoggedIn } from "../../../states/checkout.states.js";
+import { LoggedIn } from "../../../states/checkout.states.js";
 import { ItemDetailSel } from "./item-detail.sel.js";
 
 /**
@@ -10,10 +10,10 @@ import { ItemDetailSel } from "./item-detail.sel.js";
  * click, not url - order-complete "Back Home" proves the button path
  * (a url NavBlock would teleport without exercising the control).
  */
-export const NavBackToProductsBlock = defineNavClickBlock<LoggedIn>({
+export const NavBackToProductsBlock = defineNavClickBlock({
   name: "nav-back-to-products",
   description: "Clicks 'Back Home' on the order confirmation page.",
-  checkpoint: "LoggedIn",
+  checkpoint: LoggedIn,
   click: ItemDetailSel.backToProductsBtn,
   verify: [Trait.url({ pathname: "/inventory.html" })],
 });

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-continue-shopping.block.ts

@@ -1,5 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
-import type { LoggedIn } from "../../../states/checkout.states.js";
+import { LoggedIn } from "../../../states/checkout.states.js";
 import { ItemDetailSel } from "./item-detail.sel.js";
 
 /**
@@ -9,10 +9,10 @@ import { ItemDetailSel } from "./item-detail.sel.js";
  *
  * click, not url - cart page "Continue Shopping" proves the app's own path.
  */
-export const NavContinueShoppingBlock = defineNavClickBlock<LoggedIn>({
+export const NavContinueShoppingBlock = defineNavClickBlock({
   name: "nav-continue-shopping",
   description: "Clicks 'Continue Shopping' on the cart page.",
-  checkpoint: "LoggedIn",
+  checkpoint: LoggedIn,
   click: ItemDetailSel.continueShoppingBtn,
   verify: [Trait.url({ pathname: "/inventory.html" })],
 });

package/templates/quickstart/src/blocks/saucedemo-web/methods/fill-password.method.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { LoginPage } from "../../../states/checkout.states.js";
+import { defineMethodBlock } from "waygraph";
+import { LoginPage } from "../../../states/checkout.states.js";
 import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 import { LoginSel } from "./login.sel.js";
 
@@ -11,15 +11,16 @@ import { LoginSel } from "./login.sel.js";
  * Fills the password field only - self-loop on LoginPage. See
  * fill-username.method.block.ts for why this is split from submit.
  */
-export const FillPasswordBlock = defineMethodBlock<LoginPage, LoginPage>({
+export const FillPasswordBlock = defineMethodBlock({
   name: "fill-password",
   description: "Fills the password field on the login form.",
+  from: LoginPage,
+  to: LoginPage,
   requires: [LoginCreds.key],
   instruction: {
     async act(page, _input, mem) {
       const { password } = mem.get(LoginCreds.key);
       await page.locator(LoginSel.password).fill(password);
     },
-    resolve: () => checkpoint("LoginPage"),
   },
 });

package/templates/quickstart/src/blocks/saucedemo-web/methods/fill-username.method.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { LoginPage } from "../../../states/checkout.states.js";
+import { defineMethodBlock } from "waygraph";
+import { LoginPage } from "../../../states/checkout.states.js";
 import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 import { LoginSel } from "./login.sel.js";
 
@@ -13,15 +13,16 @@ import { LoginSel } from "./login.sel.js";
  * graph/demo show fill vs submit as real, distinct steps instead of one
  * Block doing "input username and password and login at the same time".
  */
-export const FillUsernameBlock = defineMethodBlock<LoginPage, LoginPage>({
+export const FillUsernameBlock = defineMethodBlock({
   name: "fill-username",
   description: "Fills the username field on the login form.",
+  from: LoginPage,
+  to: LoginPage,
   requires: [LoginCreds.key],
   instruction: {
     async act(page, _input, mem) {
       const { username } = mem.get(LoginCreds.key);
       await page.locator(LoginSel.username).fill(username);
     },
-    resolve: () => checkpoint("LoginPage"),
   },
 });

package/templates/quickstart/src/blocks/saucedemo-web/methods/submit-login.method.block.ts

@@ -1,5 +1,5 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
-import type {
+import {
   LoginPage,
   LoginSubmitOutcome,
 } from "../../../states/checkout.states.js";
@@ -17,12 +17,11 @@ type LoginObserve = "success" | "failure";
  * already did that). One Block, one action: submit.
  * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
  */
-export const SubmitLoginBlock = defineMethodBlock<
-  LoginPage,
-  LoginSubmitOutcome
->({
+export const SubmitLoginBlock = defineMethodBlock({
   name: "submit-login",
   description: "Submits the login form; stays on LoginPage when auth fails.",
+  from: LoginPage,
+  to: LoginSubmitOutcome,
   instruction: {
     async act(page) {
       // noWaitAfter: observe owns the inventory URL wait. Default click

package/templates/quickstart/src/blocks/saucedemo-web/methods/submit-logout.method.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint, Trait } from "waygraph";
-import type { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
+import { defineMethodBlock, Trait } from "waygraph";
+import { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
 import { LoginSel } from "./login.sel.js";
 
 /**
@@ -9,15 +9,16 @@ import { LoginSel } from "./login.sel.js";
  *
  * Burger menu Logout - real cycle back to LoginPage (same Checkpoint nav-login lands on).
  */
-export const SubmitLogoutBlock = defineMethodBlock<LoggedIn, LoginPage>({
+export const SubmitLogoutBlock = defineMethodBlock({
   name: "submit-logout",
   description: "Opens the burger menu and logs out.",
+  from: LoggedIn,
+  to: LoginPage,
   instruction: {
     async act(page) {
       await page.locator(LoginSel.burgerMenuButton).click();
       await page.locator(LoginSel.logoutLink).click();
     },
-    resolve: () => checkpoint("LoginPage"),
     verify: [Trait.visible(LoginSel.loginButton)],
   },
 });

package/templates/quickstart/src/blocks/saucedemo-web/nav-login.block.ts

@@ -1,5 +1,5 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { LoginPage } from "../../states/checkout.states.js";
+import { LoginPage } from "../../states/checkout.states.js";
 import { FillUsernameBlock } from "./methods/fill-username.method.block.js";
 import { FillPasswordBlock } from "./methods/fill-password.method.block.js";
 import { SubmitLoginBlock } from "./methods/submit-login.method.block.js";
@@ -17,10 +17,10 @@ import { LoginSel } from "./methods/login.sel.js";
  * and submits. Name stays `nav-login` so existing flows / chain specs keep
  * working.
  */
-export const NavLoginBlock = definePageBlock<LoginPage>({
+export const NavLoginBlock = definePageBlock({
   name: "nav-login",
   description: "Goes to the Swag Labs login page.",
-  checkpoint: "LoginPage",
+  checkpoint: LoginPage,
   url: "/",
   verify: [Trait.visible(LoginSel.loginButton)],
   methods: {

package/templates/quickstart/src/flows/api-demo.flow.ts

@@ -1,5 +1,4 @@
 import { checkpoint, defineApiBlock } from "waygraph";
-import type { Checkpoint, StubCtx } from "waygraph";
 import { engine } from "../../config/waygraph.config.js";
 import { loginFlow } from "./login.flow.js";
 
@@ -15,24 +14,27 @@ import { loginFlow } from "./login.flow.js";
  * hits a well-known public REST test API (jsonplaceholder) purely to prove
  * the mechanism - a real project would point `call` at its own backend.
  */
-export type BackendHealthy = Checkpoint<"BackendHealthy">;
-export type BackendDown = Checkpoint<"BackendDown">;
+export const BackendHealthy = checkpoint("BackendHealthy");
+export type BackendHealthy = typeof BackendHealthy;
+export const BackendDown = checkpoint("BackendDown");
+export type BackendDown = typeof BackendDown;
 
-const CheckBackendHealth = defineApiBlock<any, BackendHealthy | BackendDown>({
+const CheckBackendHealth = defineApiBlock({
   name: "check-backend-health",
+  to: [BackendHealthy, BackendDown],
   call: ({ request }) =>
     request.get("https://jsonplaceholder.typicode.com/todos/1"),
-  resolve: (result) =>
-    result.ok ? checkpoint("BackendHealthy") : checkpoint("BackendDown"),
-  stubBefore: (ctx: StubCtx<BackendHealthy | BackendDown>) => {
-    ctx.title("Checking backend health · real HTTP request, no browser");
-  },
+  resolve: (result) => (result.ok ? BackendHealthy : BackendDown),
 });
 
 export const apiDemoEpisode = engine
   .map()
   .start()
-  .method(CheckBackendHealth)
+  .method(
+    CheckBackendHealth.stubBefore((ctx) => {
+      ctx.title("Checking backend health · real HTTP request, no browser");
+    }),
+  )
   .end();
 
 export const apiDemoFlow = engine

package/templates/quickstart/src/states/checkout.states.ts

@@ -1,19 +1,29 @@
-import type { Checkpoint } from "waygraph";
+import { checkpoint } from "waygraph";
 
 // One Checkpoint per real state the target app can be in - kept together so the
 // whole checkout flow's state space reads in one place, the same reason a
 // backend keeps its models together instead of scattered across handlers.
 // `Start` is waygraph's own exported type, not redeclared here.
 
-export type LoginPage = Checkpoint<"LoginPage">;
-export type LoggedIn = Checkpoint<"LoggedIn">;
+export const LoginPage = checkpoint("LoginPage");
+export type LoginPage = typeof LoginPage;
+export const LoggedIn = checkpoint("LoggedIn");
+export type LoggedIn = typeof LoggedIn;
 /** submit-login: inventory on success, login form + error banner on auth failure. */
-export type LoginSubmitOutcome = LoggedIn | LoginPage;
-export type ItemInCart = Checkpoint<"ItemInCart">;
+export const LoginSubmitOutcome = [LoggedIn, LoginPage] as const;
+export type LoginSubmitOutcome = (typeof LoginSubmitOutcome)[number];
+export const ItemInCart = checkpoint("ItemInCart");
+export type ItemInCart = typeof ItemInCart;
 /** remove-from-cart: still has items → ItemInCart; empty cart → LoggedIn. */
-export type RemoveFromCartOutcome = ItemInCart | LoggedIn;
-export type CartPage = Checkpoint<"CartPage">;
-export type CheckoutInfoPage = Checkpoint<"CheckoutInfoPage">;
-export type CheckoutOverviewPage = Checkpoint<"CheckoutOverviewPage">;
-export type ItemDetailPage = Checkpoint<"ItemDetailPage">;
-export type OrderComplete = Checkpoint<"OrderComplete">;
+export const RemoveFromCartOutcome = [ItemInCart, LoggedIn] as const;
+export type RemoveFromCartOutcome = (typeof RemoveFromCartOutcome)[number];
+export const CartPage = checkpoint("CartPage");
+export type CartPage = typeof CartPage;
+export const CheckoutInfoPage = checkpoint("CheckoutInfoPage");
+export type CheckoutInfoPage = typeof CheckoutInfoPage;
+export const CheckoutOverviewPage = checkpoint("CheckoutOverviewPage");
+export type CheckoutOverviewPage = typeof CheckoutOverviewPage;
+export const ItemDetailPage = checkpoint("ItemDetailPage");
+export type ItemDetailPage = typeof ItemDetailPage;
+export const OrderComplete = checkpoint("OrderComplete");
+export type OrderComplete = typeof OrderComplete;

package/templates/quickstart/src/stubs/device-showcase.ts

@@ -40,7 +40,7 @@ export const deviceShowcase = {
     before: (ctx: StubCtx) => {
       ctx.title("Signing in · mobile");
       ctx.device("mobile");
-      ctx.portrait();
+      ctx.orientation("portrait");
       ctx.todos("saucedemo", ...checklist(0, 0));
       ctx.zoom(1.35);
       const fromMem = ctx.mem?.get(LoginCreds.key)?.username;
@@ -93,8 +93,8 @@ export const deviceShowcase = {
       });
     },
     after: (ctx: StubCtx) => {
-      ctx.banner("Inventory · landscape");
-      ctx.landscape();
+      ctx.title("Inventory · landscape");
+      ctx.orientation("landscape");
       ctx.todos("saucedemo", ...checklist(3, 3));
       ctx.ring("shelf", {
         selector: ".inventory_list",
@@ -111,7 +111,7 @@ export const deviceShowcase = {
     before: (ctx: StubCtx) => {
       ctx.title("Pick a product · tablet");
       ctx.device("tablet");
-      ctx.portrait();
+      ctx.orientation("portrait");
       ctx.todos("saucedemo", ...checklist(3, 3));
       ctx.zoom(1.35);
       ctx.zoomOut(false);
@@ -138,7 +138,7 @@ export const deviceShowcase = {
       });
     },
     after: (ctx: StubCtx) => {
-      ctx.banner("In the cart");
+      ctx.title("In the cart");
       ctx.todos("saucedemo", ...checklist(4, 4));
       ctx.zoomOut(false);
       ctx.ring("badge", {
@@ -155,7 +155,7 @@ export const deviceShowcase = {
   openCart: {
     before: (ctx: StubCtx) => {
       ctx.title("Open cart · landscape");
-      ctx.landscape();
+      ctx.orientation("landscape");
       ctx.todos("saucedemo", ...checklist(5, 5));
       ctx.zoom(1.4);
       ctx.zoomOut(false);
@@ -167,15 +167,14 @@ export const deviceShowcase = {
           tone: "planned",
           focus: true,
           zoomOut: false,
-          followMouse: false,
           weight: "bold",
           gesture: "tap",
         },
       });
     },
     after: (ctx: StubCtx) => {
-      ctx.banner("Your cart · desktop");
-      ctx.clearDevice();
+      ctx.title("Your cart · desktop");
+      ctx.hideDevice();
       ctx.hideTodos();
       ctx.zoomOut(true);
       ctx.ring("items", {
@@ -185,7 +184,6 @@ export const deviceShowcase = {
         tone: "success",
         focus: true,
         zoomOut: true,
-        followMouse: false,
         duration: true,
       });
     },

package/templates/scaffold/README.md

@@ -29,6 +29,7 @@ Change each `_nav.block.ts`'s `url` from the local `file://` path to a real one,
 `package.json`'s `"waygraph"` field - see the main docs' "Project config" section). That file also
 holds the test settings (`testDir`, `webServer`, `playwright: { workers, timeout, ... }`), so the
 project needs no `playwright.config.ts`. Keep each
-`src/map/` folder matching the URL it represents (`waygraph map` enforces this).
+`src/map/` folder matching the URL it represents (`waygraph map` enforces this). `(external)/hoppscotch` and
+`(external)/mailpit` keep their own `_states.ts` / `_keys.ts`, so `waygraph map pack <group>` can turn either into a package.
 
 Docs: https://deviate-dv8.github.io/waygraph/

package/templates/scaffold/STRUCTURE.md

@@ -24,9 +24,9 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 │   │   │   │       ├── assert-hello.method.block.ts   # + stubs + YAP slide
 │   │   │   │       └── assert-item-added.method.block.ts
 │   │   │   └── docs/                  # a second page, same shape
-│   │   ├── (external)/mailpit/        # a different origin (mail catcher)
-│   │   └── (external)/hoppscotch/     # API client, REST client, needs the hoppscotch extension
-│   ├── states/                        # Checkpoint types + mem keys
+│   │   ├── (external)/mailpit/        # a different origin (mail catcher); owns _states.ts + _keys.ts
+│   │   └── (external)/hoppscotch/     # API client, needs the hoppscotch extension; owns _states.ts + _keys.ts
+│   ├── states/                        # the app's Checkpoints + mem keys
 │   └── flows/                         # use cases, one file per scenario (see flows/README.md)
 │       ├── home/                      #   a page: hello, cart
 │       ├── (user-stories)/            #   flows that cross pages
@@ -45,9 +45,10 @@ page folder uses, so any agent or teammate knows where to look without asking.
 | Add an action on a page | one file in that page's `_methods/` |
 | Verify a state (button disabled, error shown) | `defineAssertBlock` + `Trait.disabled` / `Trait.enabled` |
 | Define a use case (success, failed, bad input) | one `*.flow.ts` in `src/flows/<page>/`, or `(user-stories)/` for one that crosses pages |
-| Give a flow fake data | `registerMemStub(key, fake)` + `memStub: true` in the flow's options (docs: docs/REFERENCE.md, "memStub") |
+| Give a flow fake data | `registerMemStub(key, fake)` in a `*.mem-stubs.ts` file + `memStub: true` in the flow's options; live sessions use the same fakes as defaults (docs: the reference, Engine features, "memStub") |
 | Explore by hand | `npm run auto` (headed) or `npm run auto:cli` |
 | Check your work | `npm run check`, `npm run graph`, `waygraph map` |
+| Share a tool's map with another project | `waygraph map pack hoppscotch`, then publish `.waygraph/packages/hoppscotch` |
 
 `waygraph map` fails if a folder path stops matching the real URL it claims to represent.
 Full convention: https://deviate-dv8.github.io/waygraph/consumer.html

package/templates/scaffold/config/waygraph.config.ts

@@ -26,6 +26,7 @@ const config = defineConfig(({ env }) => ({
   //   video: { viewport: "1920x1080" },
   // },
   // webServer: { command: "npm start", port: 3000 },   // started around test / run / demo / auto
+  // runLog: false,                          // each run is logged to .waygraph/runs/ (what Waygraph UI shows)
 
   // Another config for another environment: config/waygraph.staging.config.ts, chosen with `waygraph test --config staging`.
 

package/templates/scaffold/gitignore

@@ -3,3 +3,4 @@ dist/
 test-results/
 playwright-report/
 .waygraph-videos/
+.waygraph/

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

@@ -32,8 +32,8 @@ src/flows/
 
 ## Writing one
 
-- Build it with `engine.map({ memStub })…end()`; nest another with `.flow(sub, { reset: true })`. No `defineFlow([...])`,
-  no nested `withTitle(withMemStub(...))`, and `.end()` takes nothing.
+- Build it with `engine.map({ memStub })…end()`; nest another with `.flow(sub, { reset: true })`;
+  `.end()` takes nothing.
 - The flow's name and narration are ctx stubs chained on the Block where they apply: `ctx.title("…")`, `ctx.ring(…)`.
 - A flow expected to fail (a locked-out user) says so in `map({ expectedFailure: "…" })`.
 - A step's speed in the demo is `{ pace }`: `.method(FillBlock, { pace: "blitz" })`.

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

@@ -1,11 +1,11 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { Docs } from "../../../states/demo.states.js";
+import { Docs } from "../../../states/demo.states.js";
 import { DocsSel, DOCS_URL } from "./_sel.js";
 
-export const NavDocsBlock = defineNavBlock<Docs>({
+export const NavDocsBlock = defineNavBlock({
   name: "nav-docs",
   description: "Opens the docs page (Waygraph Map convention demo).",
-  checkpoint: "Docs",
+  checkpoint: Docs,
   url: DOCS_URL,
   verify: [Trait.visible(DocsSel.heading)],
 });

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

@@ -1,10 +1,10 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { Docs } from "../../../states/demo.states.js";
+import { Docs } from "../../../states/demo.states.js";
 import { DocsSel } from "./_sel.js";
 
-export const DocsPageBlock = definePageBlock<Docs>({
+export const DocsPageBlock = definePageBlock({
   name: "page-docs",
   description: "Docs hub - Waygraph Map convention demo.",
-  checkpoint: "Docs",
+  checkpoint: Docs,
   verify: [Trait.visible(DocsSel.heading)],
 });

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

@@ -1,23 +1,23 @@
 import {
   defineEffectBlock,
-  checkpoint,
   type WaygraphInstanceOption,
 } from "waygraph";
-import type { CanAddItem, ItemInCart } from "../../../../states/demo.states.js";
+import { CanAddItem, ItemInCart } from "../../../../states/demo.states.js";
 import { SelectedItem } from "../../../../states/demo.mem-keys.js";
 import { DemoSel } from "../_sel.js";
 
 /** `waygraph auto` lists one "Add …" row per live Add button via `instanceOptions`. */
-export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
+export const AddItemBlock = defineEffectBlock({
   name: "add-item",
   description: "Adds the mem-selected catalog item to the cart.",
+  from: CanAddItem,
+  to: ItemInCart,
   requires: [SelectedItem.key],
   instruction: {
     async act(page, _input, mem) {
       const { id } = mem.get(SelectedItem.key);
       await page.locator(DemoSel.addBtn(id)).click();
     },
-    resolve: () => checkpoint("ItemInCart"),
     verify: [
       {
         name: "item-added",

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

@@ -1,12 +1,12 @@
 import { defineAssertBlock, Trait } from "waygraph";
-import type { Home } from "../../../../states/demo.states.js";
+import { Home } from "../../../../states/demo.states.js";
 import { DemoSel } from "../_sel.js";
 
 /** Heading still shows after arrival; the slide is a YAP caption for the demo overlay. */
-export const AssertHelloBlock = defineAssertBlock<Home>({
+export const AssertHelloBlock = defineAssertBlock({
   name: "assert-hello",
   description: "Confirms the hello heading is still visible after arrival.",
-  checkpoint: "Home",
+  checkpoint: Home,
   waitForHeading: "Hello Waygraph",
   verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.sub)],
   slides: [