waygraph 0.15.53 → 0.16.0

package/examples/routed-demo/src/map/(app_base)/dashboard/_methods/click-widget.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint, Trait } from "waygraph";
-import type { Dashboard } from "../../../../states/routed-demo.states.js";
+import { defineMethodBlock, Trait } from "waygraph";
+import { Dashboard } from "../../../../states/routed-demo.states.js";
 import { DashboardSel } from "../_sel.js";
 
 /**
@@ -10,14 +10,15 @@ import { DashboardSel } from "../_sel.js";
  * folder's own actions live under methods/, same as today's freeform
  * convention's own methods/ subfolder.
  */
-export const ClickWidgetBlock = defineMethodBlock<Dashboard, Dashboard>({
+export const ClickWidgetBlock = defineMethodBlock({
   name: "click-widget",
   description: "Clicks the dashboard's demo widget button.",
+  from: Dashboard,
+  to: Dashboard,
   instruction: {
     async act(page) {
       await page.locator(DashboardSel.widgetBtn).click();
     },
-    resolve: () => checkpoint("Dashboard"),
     verify: [Trait.text(DashboardSel.widgetOut, "clicked")],
   },
 });

package/examples/routed-demo/src/map/(app_base)/dashboard/_nav.block.ts

@@ -1,5 +1,5 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { Dashboard } from "../../../states/routed-demo.states.js";
+import { Dashboard } from "../../../states/routed-demo.states.js";
 import { DashboardSel, DASHBOARD_URL } from "./_sel.js";
 
 /**
@@ -9,10 +9,10 @@ import { DashboardSel, DASHBOARD_URL } from "./_sel.js";
  * Fixed file name under the Waygraph Map convention - every page-slug
  * folder's own navigation Block is always nav.block.ts.
  */
-export const NavDashboardBlock = defineNavBlock<Dashboard>({
+export const NavDashboardBlock = defineNavBlock({
   name: "nav-dashboard",
   description: "Opens the dashboard page.",
-  checkpoint: "Dashboard",
+  checkpoint: Dashboard,
   url: DASHBOARD_URL,
   verify: [Trait.visible(DashboardSel.heading)],
 });

package/examples/routed-demo/src/map/(app_base)/dashboard/_page.block.ts

@@ -1,5 +1,5 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { Dashboard } from "../../../states/routed-demo.states.js";
+import { Dashboard } from "../../../states/routed-demo.states.js";
 import { DashboardSel } from "./_sel.js";
 import { ClickWidgetBlock } from "./_methods/click-widget.block.js";
 
@@ -11,10 +11,10 @@ import { ClickWidgetBlock } from "./_methods/click-widget.block.js";
  * folder's own arrival hub is always page.block.ts. Arrival-only
  * (nav.block.ts already landed on Dashboard).
  */
-export const DashboardPageBlock = definePageBlock<Dashboard>({
+export const DashboardPageBlock = definePageBlock({
   name: "page-dashboard",
   description: "Dashboard hub - the routed-demo example's (app_base) group.",
-  checkpoint: "Dashboard",
+  checkpoint: Dashboard,
   verify: [Trait.visible(DashboardSel.heading)],
   methods: {
     clickWidget: () => ClickWidgetBlock,

package/examples/routed-demo/src/map/(external)/docs/_nav.block.ts

@@ -1,5 +1,5 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { Docs } from "../../../states/routed-demo.states.js";
+import { Docs } from "../../../states/routed-demo.states.js";
 import { DocsSel, DOCS_URL } from "./_sel.js";
 
 /**
@@ -12,10 +12,10 @@ import { DocsSel, DOCS_URL } from "./_sel.js";
  * already-established `*-external/` namespacing precedent from
  * waygraph-mail-adapters.
  */
-export const NavDocsBlock = defineNavBlock<Docs>({
+export const NavDocsBlock = defineNavBlock({
   name: "nav-docs",
   description: "Opens the docs page.",
-  checkpoint: "Docs",
+  checkpoint: Docs,
   url: DOCS_URL,
   verify: [Trait.visible(DocsSel.heading)],
 });

package/examples/routed-demo/src/map/(external)/docs/_page.block.ts

@@ -1,5 +1,5 @@
 import { definePageBlock, Trait } from "waygraph";
-import type { Docs } from "../../../states/routed-demo.states.js";
+import { Docs } from "../../../states/routed-demo.states.js";
 import { DocsSel } from "./_sel.js";
 
 /**
@@ -7,9 +7,9 @@ import { DocsSel } from "./_sel.js";
  * Route: (external)/docs/
  * Arrival-only (nav.block.ts already landed on Docs).
  */
-export const DocsPageBlock = definePageBlock<Docs>({
+export const DocsPageBlock = definePageBlock({
   name: "page-docs",
   description: "Docs hub - the routed-demo example's (external) group.",
-  checkpoint: "Docs",
+  checkpoint: Docs,
   verify: [Trait.visible(DocsSel.heading)],
 });

package/examples/routed-demo/src/states/routed-demo.states.ts

@@ -1,4 +1,4 @@
-import type { Checkpoint } from "waygraph";
+import { checkpoint } from "waygraph";
 
 /**
  * Checkpoint names match their own folder's page-slug (PascalCase) under the
@@ -6,5 +6,7 @@ import type { Checkpoint } from "waygraph";
  * See openspec/changes/waygraph-map for why this is a naming convention, not
  * something any tool enforces.
  */
-export type Dashboard = Checkpoint<"Dashboard">;
-export type Docs = Checkpoint<"Docs">;
+export const Dashboard = checkpoint("Dashboard");
+export type Dashboard = typeof Dashboard;
+export const Docs = checkpoint("Docs");
+export type Docs = typeof Docs;

package/examples/routed-demo/tests/routed-demo.spec.ts

@@ -41,10 +41,10 @@ test("a real detached session navigates the convention-organized site for real,
   test.setTimeout(30_000);
   const { stdout } = await exec(node, [
     CLI,
-    "auto",
-    "--cli",
-    "--detach",
-    "--base-url",
+    "browser",
+    "start",
+    "--headless",
+    "--goto",
     process.env.WAYGRAPH_BASE_URL || "http://127.0.0.1:4277",
     root,
   ]).then((r) => r);

package/examples/routed-demo/tsconfig.json

@@ -14,5 +14,5 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts"]
+  "include": ["config/**/*.ts", "src/**/*.ts", "tests/**/*.ts"]
 }

package/examples/saucedemo/README.md

@@ -7,7 +7,6 @@ the **reference** for waygraph consumer conventions:
 - **Nav** / **Effect** / **Action** file kinds (helpers are TypeScript salt;
   runtime is still `Block`)
 - `instanceOptions` menus for `waygraph auto` (Add/Remove + Open details)
-- Detailed Kind / Helper / Route comments on every Block file
 - Per-route `NAV.md` + root `src/blocks/SITE-MAP.md`
 - Inline `{ ff: true }` fast-forward, no `.ffStart()/.ffEnd()` bracket - see
   `checkoutFlow` (`src/flows/checkout.flow.ts`)
@@ -44,30 +43,30 @@ npx playwright install chromium
 | Graph crawl (Phase B-E) | `npm run traverse` |
 | Parallel crawl + leases | `npm run traverse:parallel` |
 | Coverage JSON + min gate (10%) | `npm run traverse:coverage` |
-| Shop demo stepper | `npm run demo:step` |
+| Shop demo (login, then shop) | `npm run demo` |
 | Shop demo autoplay | `npm run demo:auto-next` |
-| **Device showcase** (mobile/tablet + portrait/landscape) | `npm run demo:device` |
-| Device showcase + `.webm` | `npm run demo:device:video` |
+| **Device showcase** (mobile/tablet + portrait/landscape; narration in `src/stubs/device-showcase.ts`) | `npm run demo:device` |
+| Device showcase + `.webm` | `npm run demo:video` |
 | **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
-| Cart bulk autoplay | `npm run demo:bulk:auto-next` |
 | **Owner checkout** (inline `{ ff: true }`, `ctx.caption()`, banner position) | `npm run demo:checkout` |
-| Owner checkout + `.webm` | `npm run demo:checkout:video` |
 | **FE + BE in one Flow** (`defineApiBlock`, live network panel) | `npm run demo:api` |
-| FE + BE demo + `.webm` | `npm run demo:api:video` |
+| Record (headless `.webm`) | `npm run record` |
 | List flows | `npm run flows` |
 
+Credentials and the selected item come from `registerMemStub` in `src/states/checkout.mem-stubs.ts` (`memStub: true` on the
+flows), so no command needs `--data`. Settings, the base URL and the shared `engine` are in `config/waygraph.config.ts`.
+Narration is chained on Blocks in the flows (`src/flows/`) or shared from `src/stubs/`; the Block files carry none.
+
 **Demo vs auto vs run for cart bulk**
 
 | | CLI | Needs `.flow.ts`? |
 |--|-----|-------------------|
-| **`run --blocks`** | `npm run run:bulk` — Block names + `--data` | No |
-| **`demo --blocks`** | `npm run demo:bulk` — named flow + `--data` | Optional (`cartBulkFlow`) |
+| **`run --blocks`** | `waygraph run --blocks "loginFlow then add-all-to-cart"` | No |
+| **`demo --blocks`** | `npm run demo:bulk` — named flow | Optional (`cartBulkFlow`) |
 | **`auto`** | `npm run auto` / `auto:cli` | No — live menu |
-| **`traverse`** | `npm run traverse` / `traverse:parallel` / `traverse:coverage` | No — graph crawl + `.waygraph-traverse/coverage.json` |
+| **`traverse`** | `npm run traverse` | No — graph crawl + `.waygraph-traverse/coverage.json` |
 | **`auto --blocks From To`** | path-find on graph | No — checkpoints only |
 
-QA watch+record: `npm run demo:bulk:video` (`--auto-play-video`).
-
 ## Layout (short)
 
 ```text

package/examples/saucedemo/config/waygraph.config.ts

@@ -0,0 +1,17 @@
+import { Engine, defineConfig } from "waygraph";
+
+const config = defineConfig({
+  baseUrl: "https://www.saucedemo.com",
+  playwright: {
+    workers: 1,
+    fullyParallel: false,
+    timeout: 30_000,
+    use: {
+      headless: true,
+      launchOptions: { args: ["--no-sandbox", "--disable-dev-shm-usage"] },
+    },
+  },
+});
+
+export default config;
+export const engine = new Engine(config);

package/examples/saucedemo/docs/CONVENTION.md

@@ -48,7 +48,6 @@ src/blocks/
   saucedemo-web/                 # THIS FOLDER IS URL "/"
     NAV.md
     nav-login.block.ts             # Page hub
-    ff-owner-auth.block.ts         # FFCompose wrapping the 4 Blocks below
     methods/
       fill-username.method.block.ts   # self-loop, fills only
       fill-password.method.block.ts   # self-loop, fills only
@@ -98,13 +97,12 @@ edges (including cycles via logout / continue-shopping / back-to-products).
 Prefer flags (or npm scripts) over a pile of `WAYGRAPH_*` env vars:
 
 ```bash
-npm run demo                 # waygraph demo shopFlow  (STEP+headed; BASE_URL from package.json / playwright)
-npm run demo:autoplay        # --autoplay --title "Shop demo"
+npm run demo                 # waygraph demo --blocks "loginFlow then shopFlow" (headed; baseUrl from config/waygraph.config.ts)
+npm run demo:auto-next       # the same, advancing on its own
 waygraph demo shopFlow --base-url https://www.saucedemo.com --title "Shop"
-waygraph chain "loginFlow" --step --no-autoplay
+waygraph demo loginFlow --no-auto-next
 ```
 
-Flags beat env: `--step` / `--no-step`, `--autoplay` / `--no-autoplay`,
+Flags beat env: `--auto-next` / `--no-auto-next`,
 `--base-url <url>`, `--title <text>`. Default BASE_URL resolution order for
-`demo`: `--base-url` > `WAYGRAPH_BASE_URL` > `package.json` `waygraph.baseUrl`
-> `playwright.config` `baseURL`.
+`demo`: `--base-url` > `WAYGRAPH_BASE_URL` > `baseUrl` in `config/waygraph.config.ts`.

package/examples/saucedemo/docs/HELPERS.md

@@ -12,19 +12,16 @@ Runtime is always a `Block`. Helpers are TypeScript salt + clear intent.
 | `defineAssertBlock` | Self-loop assertion, no state change - `verify` only | `*.method.block.ts` under `methods/` |
 | `defineEffectBlock` | Instance mutate + auto menu rows | `*.effect.block.ts` under `methods/` |
 | `defineBlock` | Escape hatch: tests, unsure, probes | any |
-| `defineActionBlock` | **Deprecated** alias of `defineMethodBlock` | - |
 
-`defineNavBlock({ click })` still works (compat) - prefer `defineNavClickBlock` in app code.
+`defineNavBlock({ click })` and `defineNavClickBlock` build the same Block; app code reads better with `defineNavClickBlock`.
 
 **One distinct action per Block.** A Method that fills fields *and* submits is wrong even if
 it "works" - split it (`fill-username` + `fill-password` + `submit-login`, not one Block).
 `defineAssertBlock({ name, checkpoint, verify, waitForHeading?, requires? })` is the
 self-loop-only shape for "assert something on the current page, no state change" - no
 hand-written `act`/`resolve` to accidentally make do two things. `waygraph check` warns when
-a `verify` array inlines a literal selector string instead of a `*Sel` reference. Give it an
-explicit type argument (`defineAssertBlock<LoggedIn>({...})`) whenever it is not the last
-Block before `end` - otherwise `Out` defaults to wildcard `Checkpoint<string>`, which breaks
-`defineFlow`'s tuple typing mid-chain.
+a `verify` array inlines a literal selector string instead of a `*Sel` reference. Its `checkpoint` is a Checkpoint
+value, which types it on both sides, so it sits anywhere in a `map()` chain.
 
 ---
 
@@ -41,7 +38,7 @@ export const InventorySel = {
 
 export const InventoryPageBlock = definePageBlock({
   name: "page-inventory",
-  checkpoint: "LoggedIn",
+  checkpoint: LoggedIn,
   verify: [Trait.url({ pathname: "/inventory.html" }), Trait.visible(InventorySel.list)],
   methods: {
     addToCart: () => AddToCartBlock,
@@ -84,8 +81,10 @@ Checkpoint = place on the map. `branch()` = which road to take from that place.
 Conditional Out (no `branch()` needed for auto/graph):
 
 ```ts
-defineMethodBlock<LoginPage, LoggedIn | LoginPage>({
+defineMethodBlock({
   name: "submit-login",
+  from: LoginPage,
+  to: [LoggedIn, LoginPage],
   instruction: {
     async act(page) { /* click only - fields were filled by earlier Blocks */ },
     async observe(page) {
@@ -110,7 +109,7 @@ branch(SubmitLoginBlock, {
 });
 ```
 
-Linear `defineFlow([start, …, end])` usually skips `branch()` (one happy path).
+A linear `map()` chain usually skips `branch()` (one happy path).
 
 ---
 
@@ -123,8 +122,9 @@ then run the Block (act reads mem as usual).
 ### Effect - spawn Method-like rows (Add / Remove)
 
 ```ts
-defineEffectBlock<Checkpoint<string>, ItemInCart>({
+defineEffectBlock({
   name: "add-to-cart",
+  to: ItemInCart, // no `from`: runs from anywhere
   requires: [SelectedItem.key],
   instruction: {
     async act(page, _in, mem) {
@@ -151,9 +151,9 @@ Auto shows: `Add "Sauce Labs Backpack" to cart`, `Add "Bike Light"…`, …
 ### MemNav - spawn Nav rows (Open details)
 
 ```ts
-defineMemNavBlock<ItemDetailPage>({
+defineMemNavBlock({
   name: "nav-item-detail",
-  checkpoint: "ItemDetailPage",
+  checkpoint: ItemDetailPage,
   requires: [SelectedItem.key],
   click: (mem) => InventorySel.title(mem.get(SelectedItem.key).id),
   verify: [Trait.url({ pathname: "/inventory-item.html" })],

package/examples/saucedemo/package-lock.json

@@ -16,10 +16,12 @@
       }
     },
     "../..": {
-      "version": "0.15.19",
+      "version": "0.15.53",
       "license": "MIT",
       "dependencies": {
-        "tsx": "^4.0.0"
+        "open-props": "^1.7.23",
+        "tsx": "^4.0.0",
+        "urlpattern-polyfill": "^10.1.0"
       },
       "bin": {
         "waygraph": "bin/waygraph"
@@ -27,7 +29,12 @@
       "devDependencies": {
         "@playwright/test": "^1.63.0",
         "@types/node": "^26.0.0",
-        "typescript": "^5.6.0"
+        "knip": "^6.42.1",
+        "typedoc": "^0.28.20",
+        "typedoc-plugin-markdown": "^4.14.1",
+        "typedoc-vitepress-theme": "^1.1.4",
+        "typescript": "^5.6.0",
+        "vitepress": "^1.6.4"
       },
       "peerDependencies": {
         "@playwright/test": "^1.40.0"

package/examples/saucedemo/package.json

@@ -9,37 +9,20 @@
     "test": "waygraph test",
     "test:ui": "waygraph test ui",
     "flows": "waygraph list",
-    "demo": "waygraph demo --blocks \"loginFlow then shopFlow\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
-    "demo:step": "waygraph demo --blocks \"loginFlow then shopFlow\" --title \"Shop demo\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
-    "demo:auto-next": "waygraph demo --blocks \"loginFlow then shopFlow\" --auto-next --title \"Product then cart\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
-    "auto": "waygraph auto",
-    "auto:cli": "waygraph auto --cli --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "prove:auto-cli": "node scripts/drive-auto-cli.mjs",
-    "traverse": "waygraph traverse --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
-    "traverse:parallel": "waygraph traverse --parallel 2 --session clone --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 30",
-    "traverse:coverage": "waygraph traverse --min-edge-coverage 10% --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
+    "check": "waygraph check",
     "graph": "waygraph graph",
     "graph:mermaid": "waygraph graph --mermaid",
-    "demo:stub-on-error": "waygraph demo --blocks stubOnErrorFlow --auto-next --fast --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --title \"stubOnError prove\"",
-    "prove:login-branch": "node scripts/prove-wrong-login-runtime.mjs",
-    "prove:graph": "node scripts/prove-auto-graph.mjs",
-    "prove:add-to-cart-menu": "node scripts/prove-add-to-cart-menu.mjs",
-    "prove": "npm run prove:login-branch && npm run prove:graph && npm run prove:add-to-cart-menu && npm test",
-    "record": "waygraph run --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --video --no-step",
-    "demo:device": "waygraph demo --blocks deviceShowcaseFlow --auto-next --title \"Device showcase\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
-    "demo:device:video": "waygraph demo --blocks deviceShowcaseFlow --auto-play-video --title \"Device showcase\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\" --video ./.tmp/device-showcase",
-    "demo:bulk": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "demo:bulk:auto-next": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-next --title \"Cart bulk demo\"",
-    "demo:bulk:video": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-play-video --title \"Cart bulk demo\"",
-    "demo:checkout": "waygraph demo --blocks checkoutFlow --auto-next --title \"Owner: Full Checkout\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
-    "demo:checkout:video": "waygraph demo --blocks checkoutFlow --auto-play-video --title \"Owner: Full Checkout\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
-    "demo:api": "waygraph demo --blocks apiDemoFlow --auto-next --title \"FE + BE in one Flow\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "demo:api:video": "waygraph demo --blocks apiDemoFlow --auto-play-video --title \"FE + BE in one Flow\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "run:bulk": "waygraph run --blocks \"loginFlow then add-all-to-cart then remove-all-from-cart\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "chain:bulk": "waygraph run --blocks \"loginFlow then add-all-to-cart then remove-all-from-cart\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --non-headless"
-  },
-  "waygraph": {
-    "baseUrl": "https://www.saucedemo.com"
+    "auto": "waygraph auto",
+    "auto:cli": "waygraph auto --cli",
+    "demo": "waygraph demo --blocks \"loginFlow then shopFlow\"",
+    "demo:auto-next": "waygraph demo --blocks \"loginFlow then shopFlow\" --auto-next",
+    "demo:checkout": "waygraph demo --blocks checkoutFlow --auto-next",
+    "demo:device": "waygraph demo --blocks deviceShowcaseFlow --auto-next",
+    "demo:bulk": "waygraph demo --blocks cartBulkFlow --auto-next",
+    "demo:api": "waygraph demo --blocks apiDemoFlow --auto-next",
+    "demo:video": "waygraph demo --blocks deviceShowcaseFlow --auto-play-video",
+    "record": "waygraph run --blocks \"loginFlow then shopFlow\" --video --no-step",
+    "traverse": "waygraph traverse --max-steps 40"
   },
   "dependencies": {
     "waygraph": "file:../.."

package/examples/saucedemo/src/blocks/SITE-MAP.md

@@ -9,7 +9,6 @@ src/blocks/
   saucedemo-web/                      # URL /
     NAV.md
     nav-login.block.ts                # Page  definePageBlock url:/
-    ff-owner-auth.block.ts            # FFCompose (nav-login + fill-username + fill-password + submit-login)
     methods/
       fill-username.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)
       fill-password.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)

package/examples/saucedemo/src/blocks/saucedemo-web/NAV.md

@@ -27,11 +27,7 @@ Fill and submit are three separate Blocks (not one that fills both fields and
 clicks Login) so the graph/demo show each as its own step - no Block does
 more than one distinct action.
 
-## Other
-
-| File | Kind | Notes |
-|------|------|-------|
-| `ff-owner-auth.block.ts` | FFCompose | Collapses nav-login + fill-username + fill-password + submit-login into one opaque demo/run step (`--ff-expand` shows all 4 again) |
+A flow that wants to skip watching auth marks those steps `{ ff: true }` (see `src/flows/checkout.flow.ts`).
 
 ## Related mem keys / checkpoints
 

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

@@ -1,7 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
-import type { StubCtx } from "waygraph";
-import type { CartPage } from "../../../states/checkout.states.js";
-import { InventorySel } from "../inventory/methods/inventory-items.js";
+import { CartPage } from "../../../states/checkout.states.js";
 import { CartSel } from "./cart.sel.js";
 
 /**
@@ -11,57 +9,10 @@ import { CartSel } from "./cart.sel.js";
  *
  * click, not url - header cart link from inventory-adjacent pages.
  */
-export const NavCartBlock = defineNavClickBlock<CartPage>({
+export const NavCartBlock = defineNavClickBlock({
   name: "nav-cart",
   description: "Clicks the cart link in the header.",
-  checkpoint: "CartPage",
+  checkpoint: CartPage,
   click: CartSel.cartLink,
   verify: [Trait.url({ pathname: "/cart.html" })],
-  stubBefore: (ctx: StubCtx) => {
-    ctx.title("Open cart · landscape");
-    ctx.landscape();
-    ctx.todos(
-      "saucedemo",
-      [
-        { id: "login-user", text: "Enter username", done: true },
-        { id: "login-pass", text: "Enter password", done: true },
-        { id: "login-submit", text: "Tap Login", done: true },
-        { id: "cart-find", text: "Find the product", done: true },
-        { id: "cart-add", text: "Add to cart", done: true },
-        { id: "cart-open", text: "Open cart" },
-      ],
-      { title: "Device showcase", index: 5 },
-    );
-    ctx.zoom(1.4);
-    ctx.zoomOut(false);
-    ctx.highlights({
-      cart: {
-        selector: CartSel.cartLink,
-        label: "Cart",
-        detail: "tone: planned (purple) - open cart",
-        tone: "planned",
-        focus: true,
-        zoomOut: false,
-        followMouse: false,
-        weight: "bold",
-        gesture: "tap",
-      },
-    });
-  },
-  stubAfter: (ctx: StubCtx) => {
-    ctx.banner("Your cart · desktop");
-    ctx.clearDevice();
-    ctx.hideTodos();
-    ctx.zoomOut(true);
-    ctx.ring("items", {
-      selector: InventorySel.cartItem,
-      label: "Cart items",
-      detail: "tone: success (green) - product in cart",
-      tone: "success",
-      focus: true,
-      zoomOut: true,
-      followMouse: false,
-      duration: true,
-    });
-  },
 });

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

@@ -1,5 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
-import type { CheckoutInfoPage } from "../../../states/checkout.states.js";
+import { CheckoutInfoPage } from "../../../states/checkout.states.js";
 import { CartSel } from "./cart.sel.js";
 
 /**
@@ -9,10 +9,10 @@ import { CartSel } from "./cart.sel.js";
  *
  * Cart page "Checkout" button - owns the nav into step one.
  */
-export const NavCheckoutInfoBlock = defineNavClickBlock<CheckoutInfoPage>({
+export const NavCheckoutInfoBlock = defineNavClickBlock({
   name: "nav-checkout-info",
   description: "Clicks 'Checkout' on the cart page.",
-  checkpoint: "CheckoutInfoPage",
+  checkpoint: CheckoutInfoPage,
   click: CartSel.checkoutBtn,
   verify: [Trait.url({ pathname: "/checkout-step-one.html" })],
 });

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { defineMethodBlock } from "waygraph";
+import { CheckoutInfoPage } from "../../../../states/checkout.states.js";
 import { CheckoutInfoSel } from "./checkout-info.sel.js";
 
 /**
@@ -10,13 +10,14 @@ import { CheckoutInfoSel } from "./checkout-info.sel.js";
  * Fills the first name field only - self-loop on CheckoutInfoPage. Continue
  * is its own Block (submit-checkout-info.method.block.ts).
  */
-export const FillFirstNameBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+export const FillFirstNameBlock = defineMethodBlock({
   name: "fill-first-name",
   description: "Fills the first name field on the shipping info form.",
+  from: CheckoutInfoPage,
+  to: CheckoutInfoPage,
   instruction: {
     async act(page) {
       await page.locator(CheckoutInfoSel.firstName).fill("Ada");
     },
-    resolve: () => checkpoint("CheckoutInfoPage"),
   },
 });

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { defineMethodBlock } from "waygraph";
+import { CheckoutInfoPage } from "../../../../states/checkout.states.js";
 import { CheckoutInfoSel } from "./checkout-info.sel.js";
 
 /**
@@ -9,13 +9,14 @@ import { CheckoutInfoSel } from "./checkout-info.sel.js";
  *
  * Fills the last name field only - self-loop on CheckoutInfoPage.
  */
-export const FillLastNameBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+export const FillLastNameBlock = defineMethodBlock({
   name: "fill-last-name",
   description: "Fills the last name field on the shipping info form.",
+  from: CheckoutInfoPage,
+  to: CheckoutInfoPage,
   instruction: {
     async act(page) {
       await page.locator(CheckoutInfoSel.lastName).fill("Lovelace");
     },
-    resolve: () => checkpoint("CheckoutInfoPage"),
   },
 });

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.ts

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint } from "waygraph";
-import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { defineMethodBlock } from "waygraph";
+import { CheckoutInfoPage } from "../../../../states/checkout.states.js";
 import { CheckoutInfoSel } from "./checkout-info.sel.js";
 
 /**
@@ -9,13 +9,14 @@ import { CheckoutInfoSel } from "./checkout-info.sel.js";
  *
  * Fills the postal code field only - self-loop on CheckoutInfoPage.
  */
-export const FillPostalCodeBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+export const FillPostalCodeBlock = defineMethodBlock({
   name: "fill-postal-code",
   description: "Fills the postal code field on the shipping info form.",
+  from: CheckoutInfoPage,
+  to: CheckoutInfoPage,
   instruction: {
     async act(page) {
       await page.locator(CheckoutInfoSel.postalCode).fill("1000");
     },
-    resolve: () => checkpoint("CheckoutInfoPage"),
   },
 });

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

@@ -1,5 +1,5 @@
-import { defineMethodBlock, checkpoint, Trait } from "waygraph";
-import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
+import { defineMethodBlock, Trait } from "waygraph";
+import { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
 import { CheckoutInfoSel } from "./checkout-info.sel.js";
 
 /**
@@ -11,14 +11,15 @@ import { CheckoutInfoSel } from "./checkout-info.sel.js";
  * fill-last-name / fill-postal-code (each its own Block). One Block, one
  * action: submit.
  */
-export const SubmitCheckoutInfoBlock = defineMethodBlock<CheckoutInfoPage, CheckoutOverviewPage>({
+export const SubmitCheckoutInfoBlock = defineMethodBlock({
   name: "submit-checkout-info",
   description: "Continues from the shipping info form to the order overview.",
+  from: CheckoutInfoPage,
+  to: CheckoutOverviewPage,
   instruction: {
     async act(page) {
       await page.locator(CheckoutInfoSel.continueBtn).click();
     },
-    resolve: () => checkpoint("CheckoutOverviewPage"),
     verify: [Trait.url({ pathname: "/checkout-step-two.html" })],
   },
 });