waygraph 0.7.14 → 0.7.16

package/dist/auto-explore.js

@@ -249,7 +249,7 @@ export async function buildExploreMenu(page, graph, library, here) {
     else {
         if (forward.length > 0) {
             sections.push({
-                title: `Forward from ${here}`,
+                title: `Actions from ${here}`,
                 edges: forward.sort((a, b) => a.block.localeCompare(b.block)),
             });
         }

package/dist/engine.d.ts

@@ -536,9 +536,37 @@ export type NavBlockOptions<Out extends Checkpoint<string>> = {
  * hand.
  * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
  * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
- * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * @example defineNavClickBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * For click-nav in app code prefer {@link defineNavClickBlock} (url stays here).
  */
 export declare function defineNavBlock<Out extends Checkpoint<string>>(options: NavBlockOptions<Out>): NavBlock<Out>;
+/**
+ * Click-only {@link NavBlock}. Same runtime as {@link defineNavBlock} with
+ * `click` - use this in app code so you never wonder whether a Nav is url or
+ * click (no `__waygraphNavClick` sniffing at author time). Prefer
+ * {@link defineNavBlock} only for `url` / `goto` deep links.
+ */
+export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
+    name: string;
+    description?: string;
+    checkpoint: Out["__state"];
+    click: string | ((mem: MemPage) => string);
+    requires?: readonly MemKey<any>[];
+    verify?: Trait[] | ((out: Out) => Trait[]);
+    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
+    instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
+};
+export type NavClickBlock<Out extends Checkpoint<string>> = NavBlock<Out>;
+/** @see {@link NavClickBlockOptions} */
+export declare function defineNavClickBlock<Out extends Checkpoint<string>>(options: NavClickBlockOptions<Out>): NavClickBlock<Out>;
+/**
+ * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps
+ * (submit, finish, logout). Same runtime Block; marks `__waygraphSalt = "action"`
+ * so auto/docs can tell Action from bare {@link defineBlock} (tests / unsure).
+ * Does not force `instanceOptions` - use {@link defineEffectBlock} for that.
+ */
+export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = DefinedBlock<In, Out>;
+export declare function defineActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): ActionBlock<In, Out>;
 /**
  * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
  * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu

package/dist/engine.js

@@ -634,7 +634,8 @@ export function defineBlock(base) {
  * hand.
  * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
  * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
- * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * @example defineNavClickBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * For click-nav in app code prefer {@link defineNavClickBlock} (url stays here).
  */
 export function defineNavBlock(options) {
     const built = defineBlock({
@@ -682,6 +683,28 @@ export function defineNavBlock(options) {
     }
     return built;
 }
+/** @see {@link NavClickBlockOptions} */
+export function defineNavClickBlock(options) {
+    return defineNavBlock({
+        name: options.name,
+        checkpoint: options.checkpoint,
+        click: options.click,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        ...(options.verify ? { verify: options.verify } : {}),
+        ...(options.highlights ? { highlights: options.highlights } : {}),
+        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
+    });
+}
+export function defineActionBlock(base) {
+    const built = defineBlock(base);
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "action",
+        enumerable: false,
+        configurable: false,
+    });
+    return built;
+}
 /**
  * {@link defineBlock} constrained for effect-style instance menus: `requires` +
  * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /
@@ -695,6 +718,11 @@ export function defineEffectBlock(base) {
         enumerable: false,
         configurable: false,
     });
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "effect",
+        enumerable: false,
+        configurable: false,
+    });
     return built;
 }
 /** @deprecated Prefer {@link defineEffectBlock} - identical helper. */

package/dist/graph.js

@@ -98,7 +98,7 @@ export async function findOrphanBlocks(projectDir) {
             const exportName = m[1];
             if (referenced.has(exportName))
                 continue;
-            if (!/defineBlock|defineNavBlock/.test(src))
+            if (!/defineBlock|defineActionBlock|defineEffectBlock|defineMemEffectBlock|defineNavBlock|defineNavClickBlock|defineMemNavBlock/.test(src))
                 continue;
             let block = exportNameToBlockName(exportName);
             try {
@@ -234,14 +234,17 @@ function resolveGenericArg(blockFilePath, arg) {
         return [inline[1]];
     return resolveTypeToTags(blockFilePath, arg);
 }
-/** Every `defineBlock<In, Out>(` call site in a file's own source, in order. */
+/** Every `defineBlock` / `defineEffectBlock` / `defineMemEffectBlock` `<In, Out>` call site. */
 function extractDefineBlockGenerics(src) {
     // Each argument is either a plain identifier or an inline `Checkpoint<...>`
-    // (its own angle brackets, so the outer defineBlock<...> pair alone won't
+    // (its own angle brackets, so the outer defineX<...> pair alone won't
     // balance correctly against a naive greedy match) - captured as a single
     // alternation so both shapes come out of the same two capture groups.
+    // Effect helpers are TypeScript salt over defineBlock - same In/Out edges.
     const arg = String.raw `(Checkpoint<[^>]*>|[A-Za-z_$][\w]*)`;
-    const re = new RegExp(String.raw `defineBlock<\s*${arg}\s*,\s*${arg}\s*>`, "g");
+    const re = new RegExp(String.raw `define(?:(?:Mem)?Effect|Action)?Block<\s*${arg}\s*,\s*${arg}\s*>`, "g");
+    // Matches: defineBlock | defineActionBlock | defineEffectBlock | defineMemEffectBlock
+    // (Nav / NavClick use runtime markers, not this regex.)
     const calls = [];
     let m;
     while ((m = re.exec(src)) !== null) {
@@ -301,7 +304,11 @@ export async function discoverGraph(projectDir) {
             }
             const call = calls[callIndex++];
             if (!call) {
-                skipped.push({ block: blockName, file: relFile, reason: "no defineBlock<In, Out> generic call found" });
+                skipped.push({
+                    block: blockName,
+                    file: relFile,
+                    reason: "no defineBlock/defineEffectBlock<In, Out> generic call found",
+                });
                 continue;
             }
             const fromTags = resolveGenericArg(file, call.in);

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
-export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineActionBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, ActionBlock, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineActionBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/examples/saucedemo/docs/HELPERS.md

@@ -0,0 +1,42 @@
+# Block helpers (convention)
+
+Runtime is always a `Block`. Helpers are TypeScript salt + clear intent.
+
+| Helper | Use when | File |
+|--------|----------|------|
+| `defineNavBlock` | URL / `goto` only | `nav-*.block.ts` |
+| `defineNavClickBlock` | Click-to-navigate only | `nav-*.block.ts` |
+| `defineMemNavBlock` | Nav + per-row `instanceOptions` | `nav-*.block.ts` |
+| `defineActionBlock` | One-shot non-nav app step | `*.action.block.ts` |
+| `defineEffectBlock` | Instance mutate + auto menu rows | `*.effect.block.ts` |
+| `defineBlock` | Escape hatch: tests, unsure, probes | any |
+
+`defineNavBlock({ click })` still works (compat) - prefer `defineNavClickBlock` in app code.
+
+## Branching (not Mem)
+
+Mem / `instanceOptions` = pick *which instance* before run.
+
+Conditional outcomes = `observe` + union `Out` (already supported, not a new Block kind):
+
+```ts
+defineActionBlock<LoginPage, LoggedIn | LoginPage>({
+  name: "submit-login",
+  instruction: {
+    async act(page, _in, mem) { /* fill + click */ },
+    async observe(page) {
+      try {
+        await page.waitForURL(/\/inventory\.html/, { timeout: 8000 });
+        return "success";
+      } catch {
+        return "failure";
+      }
+    },
+    resolve: (o) => checkpoint(o === "success" ? "LoggedIn" : "LoginPage"),
+  },
+});
+```
+
+Graph expands the union Out into two edges. Optional flow routing: `branch(block, { LoggedIn: next, LoginPage: null })`.
+
+No breaking change for atomics - document observe/resolve (+ optional `branch`) as the Branch pattern.

package/examples/saucedemo/src/blocks/saucedemo-web/actions/submit-login.action.block.ts

@@ -1,4 +1,4 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
+import { defineActionBlock, checkpoint, Trait } from "waygraph";
 import type { LoginPage, LoginSubmitOutcome } from "../../../states/checkout.states.js";
 import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 
@@ -6,13 +6,13 @@ type LoginObserve = "success" | "failure";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/actions/  (page URL /)
  *
  * Fills credentials and submits - never page.goto (nav-login owns that).
  * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
  */
-export const SubmitLoginActionBlock = defineBlock<LoginPage, LoginSubmitOutcome>({
+export const SubmitLoginActionBlock = defineActionBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
   description: "Logs a user in when credentials are valid; stays on LoginPage when auth fails.",
   requires: [LoginCreds.key],

package/examples/saucedemo/src/blocks/saucedemo-web/actions/submit-logout.action.block.ts

@@ -1,14 +1,14 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
+import { defineActionBlock, checkpoint, Trait } from "waygraph";
 import type { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/actions/  (page URL / after logout)
  *
  * Burger menu Logout - real cycle back to LoginPage (same Checkpoint nav-login lands on).
  */
-export const SubmitLogoutBlock = defineBlock<LoggedIn, LoginPage>({
+export const SubmitLogoutBlock = defineActionBlock<LoggedIn, LoginPage>({
   name: "submit-logout",
   description: "Opens the burger menu and logs out.",
   instruction: {

package/examples/saucedemo/src/blocks/saucedemo-web/cart/nav-cart.block.ts

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/cart/  (= /cart.html)
  *
  * click, not url - header cart link from inventory-adjacent pages.
  */
-export const NavCartBlock = defineNavBlock<CartPage>({
+export const NavCartBlock = defineNavClickBlock<CartPage>({
   name: "nav-cart",
   description: "Clicks the cart link in the header.",
   checkpoint: "CartPage",

package/examples/saucedemo/src/blocks/saucedemo-web/cart/nav-checkout-info.block.ts

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { CheckoutInfoPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/cart/  (click leaves /cart.html -> /checkout-step-one.html)
  *
  * Cart page "Checkout" button - owns the nav into step one.
  */
-export const NavCheckoutInfoBlock = defineNavBlock<CheckoutInfoPage>({
+export const NavCheckoutInfoBlock = defineNavClickBlock<CheckoutInfoPage>({
   name: "nav-checkout-info",
   description: "Clicks 'Checkout' on the cart page.",
   checkpoint: "CheckoutInfoPage",

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-one/actions/submit-checkout-info.action.block.ts

@@ -1,15 +1,15 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
+import { defineActionBlock, checkpoint, Trait } from "waygraph";
 import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/checkout-step-one/actions/  (= /checkout-step-one.html)
  *
  * Fills shipping form and continues - never navigates itself
  * (nav-checkout-info already got here).
  */
-export const SubmitCheckoutInfoBlock = defineBlock<CheckoutInfoPage, CheckoutOverviewPage>({
+export const SubmitCheckoutInfoBlock = defineActionBlock<CheckoutInfoPage, CheckoutOverviewPage>({
   name: "submit-checkout-info",
   description: "Fills in the shipping info form and continues to the order overview.",
   instruction: {

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-two/actions/finish-order.action.block.ts

@@ -1,14 +1,14 @@
-import { defineBlock, checkpoint, Trait, narrate } from "waygraph";
+import { defineActionBlock, checkpoint, Trait, narrate } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/checkout-step-two/actions/  (= /checkout-step-two.html)
  *
  * Places the order on the overview page - form/finish click, not a NavBlock.
  */
-export const FinishOrderBlock = defineBlock<CheckoutOverviewPage, OrderComplete>({
+export const FinishOrderBlock = defineActionBlock<CheckoutOverviewPage, OrderComplete>({
   name: "finish-order",
   description: "Places the order and confirms the 'Thank you for your order!' completion page.",
   instruction: {

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

@@ -1,15 +1,15 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/inventory-item/  (= /inventory-item.html From)
  *
  * click, not url - detail page "Back to products". Separate Block from
  * nav-back-to-products (different From Checkpoint; atomic convention).
  */
-export const NavBackToInventoryBlock = defineNavBlock<LoggedIn>({
+export const NavBackToInventoryBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-back-to-inventory",
   description: "Clicks 'Back to products' on the item detail page.",
   checkpoint: "LoggedIn",

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

@@ -1,15 +1,15 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/inventory-item/  (lands on /inventory.html)
  *
  * click, not url - order-complete "Back Home" proves the button path
  * (a url NavBlock would teleport without exercising the control).
  */
-export const NavBackToProductsBlock = defineNavBlock<LoggedIn>({
+export const NavBackToProductsBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-back-to-products",
   description: "Clicks 'Back Home' on the order confirmation page.",
   checkpoint: "LoggedIn",

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

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/inventory-item/  (lands on /inventory.html)
  *
  * click, not url - cart page "Continue Shopping" proves the app's own path.
  */
-export const NavContinueShoppingBlock = defineNavBlock<LoggedIn>({
+export const NavContinueShoppingBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-continue-shopping",
   description: "Clicks 'Continue Shopping' on the cart page.",
   checkpoint: "LoggedIn",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/quickstart/docs/HELPERS.md

@@ -0,0 +1,42 @@
+# Block helpers (convention)
+
+Runtime is always a `Block`. Helpers are TypeScript salt + clear intent.
+
+| Helper | Use when | File |
+|--------|----------|------|
+| `defineNavBlock` | URL / `goto` only | `nav-*.block.ts` |
+| `defineNavClickBlock` | Click-to-navigate only | `nav-*.block.ts` |
+| `defineMemNavBlock` | Nav + per-row `instanceOptions` | `nav-*.block.ts` |
+| `defineActionBlock` | One-shot non-nav app step | `*.action.block.ts` |
+| `defineEffectBlock` | Instance mutate + auto menu rows | `*.effect.block.ts` |
+| `defineBlock` | Escape hatch: tests, unsure, probes | any |
+
+`defineNavBlock({ click })` still works (compat) - prefer `defineNavClickBlock` in app code.
+
+## Branching (not Mem)
+
+Mem / `instanceOptions` = pick *which instance* before run.
+
+Conditional outcomes = `observe` + union `Out` (already supported, not a new Block kind):
+
+```ts
+defineActionBlock<LoginPage, LoggedIn | LoginPage>({
+  name: "submit-login",
+  instruction: {
+    async act(page, _in, mem) { /* fill + click */ },
+    async observe(page) {
+      try {
+        await page.waitForURL(/\/inventory\.html/, { timeout: 8000 });
+        return "success";
+      } catch {
+        return "failure";
+      }
+    },
+    resolve: (o) => checkpoint(o === "success" ? "LoggedIn" : "LoginPage"),
+  },
+});
+```
+
+Graph expands the union Out into two edges. Optional flow routing: `branch(block, { LoggedIn: next, LoginPage: null })`.
+
+No breaking change for atomics - document observe/resolve (+ optional `branch`) as the Branch pattern.

package/templates/quickstart/package.json

@@ -19,7 +19,7 @@
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.7.14"
+    "waygraph": "^0.7.16"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/quickstart/src/blocks/saucedemo-web/actions/submit-login.action.block.ts

@@ -1,4 +1,4 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
+import { defineActionBlock, checkpoint, Trait } from "waygraph";
 import type { LoginPage, LoginSubmitOutcome } from "../../../states/checkout.states.js";
 import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 
@@ -6,13 +6,13 @@ type LoginObserve = "success" | "failure";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/actions/  (page URL /)
  *
  * Fills credentials and submits - never page.goto (nav-login owns that).
  * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
  */
-export const SubmitLoginActionBlock = defineBlock<LoginPage, LoginSubmitOutcome>({
+export const SubmitLoginActionBlock = defineActionBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
   description: "Logs a user in when credentials are valid; stays on LoginPage when auth fails.",
   requires: [LoginCreds.key],

package/templates/quickstart/src/blocks/saucedemo-web/actions/submit-logout.action.block.ts

@@ -1,14 +1,14 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
+import { defineActionBlock, checkpoint, Trait } from "waygraph";
 import type { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/actions/  (page URL / after logout)
  *
  * Burger menu Logout - real cycle back to LoginPage (same Checkpoint nav-login lands on).
  */
-export const SubmitLogoutBlock = defineBlock<LoggedIn, LoginPage>({
+export const SubmitLogoutBlock = defineActionBlock<LoggedIn, LoginPage>({
   name: "submit-logout",
   description: "Opens the burger menu and logs out.",
   instruction: {

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

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/cart/  (= /cart.html)
  *
  * click, not url - header cart link from inventory-adjacent pages.
  */
-export const NavCartBlock = defineNavBlock<CartPage>({
+export const NavCartBlock = defineNavClickBlock<CartPage>({
   name: "nav-cart",
   description: "Clicks the cart link in the header.",
   checkpoint: "CartPage",

package/templates/quickstart/src/blocks/saucedemo-web/cart/nav-checkout-info.block.ts

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { CheckoutInfoPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/cart/  (click leaves /cart.html -> /checkout-step-one.html)
  *
  * Cart page "Checkout" button - owns the nav into step one.
  */
-export const NavCheckoutInfoBlock = defineNavBlock<CheckoutInfoPage>({
+export const NavCheckoutInfoBlock = defineNavClickBlock<CheckoutInfoPage>({
   name: "nav-checkout-info",
   description: "Clicks 'Checkout' on the cart page.",
   checkpoint: "CheckoutInfoPage",

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/actions/submit-checkout-info.action.block.ts

@@ -1,15 +1,15 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
+import { defineActionBlock, checkpoint, Trait } from "waygraph";
 import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/checkout-step-one/actions/  (= /checkout-step-one.html)
  *
  * Fills shipping form and continues - never navigates itself
  * (nav-checkout-info already got here).
  */
-export const SubmitCheckoutInfoBlock = defineBlock<CheckoutInfoPage, CheckoutOverviewPage>({
+export const SubmitCheckoutInfoBlock = defineActionBlock<CheckoutInfoPage, CheckoutOverviewPage>({
   name: "submit-checkout-info",
   description: "Fills in the shipping info form and continues to the order overview.",
   instruction: {

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/actions/finish-order.action.block.ts

@@ -1,14 +1,14 @@
-import { defineBlock, checkpoint, Trait, narrate } from "waygraph";
+import { defineActionBlock, checkpoint, Trait, narrate } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 
 /**
  * Kind: Action
- * Helper: defineBlock
+ * Helper: defineActionBlock
  * Route: saucedemo-web/checkout-step-two/actions/  (= /checkout-step-two.html)
  *
  * Places the order on the overview page - form/finish click, not a NavBlock.
  */
-export const FinishOrderBlock = defineBlock<CheckoutOverviewPage, OrderComplete>({
+export const FinishOrderBlock = defineActionBlock<CheckoutOverviewPage, OrderComplete>({
   name: "finish-order",
   description: "Places the order and confirms the 'Thank you for your order!' completion page.",
   instruction: {

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

@@ -1,15 +1,15 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/inventory-item/  (= /inventory-item.html From)
  *
  * click, not url - detail page "Back to products". Separate Block from
  * nav-back-to-products (different From Checkpoint; atomic convention).
  */
-export const NavBackToInventoryBlock = defineNavBlock<LoggedIn>({
+export const NavBackToInventoryBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-back-to-inventory",
   description: "Clicks 'Back to products' on the item detail page.",
   checkpoint: "LoggedIn",

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

@@ -1,15 +1,15 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/inventory-item/  (lands on /inventory.html)
  *
  * click, not url - order-complete "Back Home" proves the button path
  * (a url NavBlock would teleport without exercising the control).
  */
-export const NavBackToProductsBlock = defineNavBlock<LoggedIn>({
+export const NavBackToProductsBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-back-to-products",
   description: "Clicks 'Back Home' on the order confirmation page.",
   checkpoint: "LoggedIn",

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

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { LoggedIn } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/inventory-item/  (lands on /inventory.html)
  *
  * click, not url - cart page "Continue Shopping" proves the app's own path.
  */
-export const NavContinueShoppingBlock = defineNavBlock<LoggedIn>({
+export const NavContinueShoppingBlock = defineNavClickBlock<LoggedIn>({
   name: "nav-continue-shopping",
   description: "Clicks 'Continue Shopping' on the cart page.",
   checkpoint: "LoggedIn",