waygraph 0.15.54 → 0.16.1

package/dist/{config.js → runtime/waygraph-config.js}

@@ -2,12 +2,14 @@
 // keeps working untouched; this is a second, richer place to put the same kind of project-level
 // setting, for consumers who'd rather have a real typed file than a JSON field. Real ask: "I
 // think its time to add waygraph config now."
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { extensionPathsFromEnv } from "./browser.js";
 import { envMode, loadEnvFiles } from "./env-file.js";
 import { resolveExtensions } from "./extensions.js";
+import { envString, setEnv } from "../engine/env.js";
+import { takeGlobalFlag } from "./global-flag.js";
 /**
  * Typed identity helper, like `defineConfig` in `vite.config.ts`. Pass an object, or a function when values come
  * from `.env` files (`.env`, `.env.local`, `.env.<mode>`; pick the mode with `--env <mode>`):
@@ -27,7 +29,7 @@ const CONFIG_FILENAMES = [...CONFIG_NAMES.map((n) => join("config", n)), ...CONF
  * (`staging` -> `config/waygraph.staging.config.ts`, also tried in the project root). Without it, `waygraph.config.*`.
  */
 function configCandidates() {
-    const chosen = process.env.WAYGRAPH_CONFIG;
+    const chosen = envString("WAYGRAPH_CONFIG");
     if (!chosen)
         return CONFIG_FILENAMES;
     if (/[\\/]/.test(chosen) || /\.[cm]?[jt]s$/.test(chosen))
@@ -37,21 +39,14 @@ function configCandidates() {
 }
 /** Removes `--config <file>` / `--config=<file>` from argv and records it as `WAYGRAPH_CONFIG`, so every command reads that config. */
 export function takeConfigFlag(argv) {
-    const out = [];
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--config" && argv[i + 1] !== undefined)
-            process.env.WAYGRAPH_CONFIG = argv[++i];
-        else if (a.startsWith("--config="))
-            process.env.WAYGRAPH_CONFIG = a.slice("--config=".length);
-        else
-            out.push(a);
-    }
-    return out;
+    const { value, rest } = takeGlobalFlag(argv, "config");
+    if (value !== undefined)
+        setEnv("WAYGRAPH_CONFIG", value);
+    return rest;
 }
 /**
  * Looks for the first `waygraph.config.*` in `projectDir` and imports it - `.ts` works
- * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli.js` ever runs
+ * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli/cli.js` ever runs
  * (the same mechanism that already lets a consumer's `.block.ts`/`.flow.ts` import directly), so
  * no separate loader/transpile step is needed here. A broken config file throws loud, naming the
  * file - silently swallowing it would make a missing `baseUrl` look like "nobody configured
@@ -62,8 +57,8 @@ export async function loadWaygraphConfig(projectDir) {
     for (const name of configCandidates()) {
         const p = isAbsolute(name) ? name : join(projectDir, name);
         if (!existsSync(p)) {
-            if (process.env.WAYGRAPH_CONFIG && name === process.env.WAYGRAPH_CONFIG) {
-                throw new Error(`waygraph: config "${process.env.WAYGRAPH_CONFIG}" not found (looked for ${p})`);
+            if (envString("WAYGRAPH_CONFIG") && name === envString("WAYGRAPH_CONFIG")) {
+                throw new Error(`waygraph: config "${envString("WAYGRAPH_CONFIG")}" not found (looked for ${p})`);
             }
             continue;
         }
@@ -82,7 +77,7 @@ export async function loadWaygraphConfig(projectDir) {
 }
 /**
  * Single source of truth for a project's base URL. Was three independently drifted copies
- * (`src/cli/flags.ts`, `src/traverse/run.ts`, `src/session/auto-explore-run.ts`), each checking
+ * (`src/cli/flags.ts`, `src/live/traverse/traverse.ts`, `src/live/auto/auto.ts`), each checking
  * a slightly different subset of sources in a different order - real duplication, not just
  * stylistic, since one copy skipped `config.waygraph.*` nesting and another checked
  * `WAYGRAPH_BASE_URL` first instead of last. Checked in this order:
@@ -91,43 +86,14 @@ export async function loadWaygraphConfig(projectDir) {
  *    `loadEnvFiles`, called here so every caller gets native `.env` support for free, not just
  *    whichever command remembered to call it).
  * 2. A `waygraph.config.*` file's `baseUrl`.
- * 3. `package.json`'s `waygraph.baseUrl`/`baseURL` (`config.waygraph.*` also checked - a common
- *    nested-config convention some tooling uses).
- * 4. `playwright.config.*`'s own `baseURL` (regex-read as text, never imported - importing a
- *    consumer's real playwright.config risks pulling in `@playwright/test`'s own global setup
- *    as a side effect, which resolving a URL string has no business doing).
  */
 export async function resolveBaseUrl(projectDir) {
     loadEnvFiles(projectDir);
-    if (process.env.WAYGRAPH_BASE_URL)
-        return process.env.WAYGRAPH_BASE_URL;
+    if (envString("WAYGRAPH_BASE_URL"))
+        return envString("WAYGRAPH_BASE_URL");
     const config = await loadWaygraphConfig(projectDir);
     if (config?.baseUrl && config.baseUrl.trim())
         return config.baseUrl.trim();
-    const pkgPath = join(projectDir, "package.json");
-    if (existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-            const fromPkg = pkg.waygraph?.baseUrl ??
-                pkg.waygraph?.baseURL ??
-                pkg.config?.waygraph?.baseUrl ??
-                pkg.config?.waygraph?.baseURL;
-            if (typeof fromPkg === "string" && fromPkg.trim())
-                return fromPkg.trim();
-        }
-        catch {
-            // ignore malformed package.json - fall through to playwright.config
-        }
-    }
-    for (const name of ["playwright.config.ts", "playwright.config.mts", "playwright.config.js", "playwright.config.mjs"]) {
-        const p = join(projectDir, name);
-        if (!existsSync(p))
-            continue;
-        const src = readFileSync(p, "utf-8");
-        const m = src.match(/baseURL\s*:\s*["']([^"']+)["']/);
-        if (m?.[1])
-            return m[1];
-    }
     return undefined;
 }
 /** Unpacked extension directories for a run: `WAYGRAPH_EXTENSIONS` if set, else the config file's `extensions` (fetched on first use). */
@@ -143,18 +109,22 @@ export async function configuredExtensions(projectDir) {
  * (`WAYGRAPH_COMMAND`, set by the CLI). The `run` / `demo` section overrides the shared top-level values. A flag, a shell
  * variable or a `.env` value that is already set always wins, so the config only supplies defaults.
  */
-export function applyConfigEnv(config, command = process.env.WAYGRAPH_COMMAND) {
+export function applyConfigEnv(config, command = envString("WAYGRAPH_COMMAND")) {
     if (!config)
         return;
     const isDemo = command === "demo" || command === "try";
     const section = isDemo ? config.demo : command === "run" ? config.run : undefined;
     const set = (name, value) => {
-        if (value !== undefined && process.env[name] === undefined)
-            process.env[name] = value;
+        if (value !== undefined && envString(name) === undefined)
+            setEnv(name, value);
     };
     const flag = (b) => (b === undefined ? undefined : b ? "1" : "0");
     const video = { ...config.video, ...section?.video };
     const slowMo = section?.slowMo ?? config.slowMo;
+    if (config.runLog === false)
+        set("WAYGRAPH_RUN_LOG", "0");
+    else if (typeof config.runLog === "string")
+        set("WAYGRAPH_RUN_LOG", config.runLog);
     set("WAYGRAPH_VIDEO_DIR", video.dir);
     set("WAYGRAPH_VIDEO_VIEWPORT", video.viewport);
     set("WAYGRAPH_SLOWMO", slowMo === undefined ? undefined : String(slowMo));

package/dist/{webserver.js → runtime/webserver.js}

@@ -1,38 +1,13 @@
-// Starts/stops a project's `webServer` (waygraph.config, or a legacy playwright.config) around `waygraph run`/`demo`/`auto`,
+// Starts/stops a project's `webServer` (from config/waygraph.config.ts) around `waygraph run`/`demo`/`auto`,
 // the same block `waygraph test` already honors.
-import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
-import { loadWaygraphConfig } from "./config.js";
-const CONFIG_FILES = [
-    "playwright.config.ts",
-    "playwright.config.mts",
-    "playwright.config.mjs",
-    "playwright.config.js",
-    "playwright.config.cjs",
-];
+import { loadWaygraphConfig } from "./waygraph-config.js";
 async function loadWebServerConfigs(projectDir) {
     const fromWaygraph = (await loadWaygraphConfig(projectDir))?.webServer;
-    if (fromWaygraph)
-        return Array.isArray(fromWaygraph) ? fromWaygraph : [fromWaygraph];
-    for (const name of CONFIG_FILES) {
-        const p = join(projectDir, name);
-        if (!existsSync(p))
-            continue;
-        let mod;
-        try {
-            mod = (await import(pathToFileURL(p).href));
-        }
-        catch (err) {
-            throw new Error(`waygraph: failed to load ${name}: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        const webServer = mod.default?.webServer;
-        if (!webServer)
-            return [];
-        return Array.isArray(webServer) ? webServer : [webServer];
-    }
-    return [];
+    if (!fromWaygraph)
+        return [];
+    return Array.isArray(fromWaygraph) ? fromWaygraph : [fromWaygraph];
 }
 async function isUp(target) {
     try {

package/examples/routed-demo/config/waygraph.config.ts

@@ -0,0 +1,20 @@
+import { Engine, defineConfig } from "waygraph";
+
+const config = defineConfig({
+  baseUrl: "http://127.0.0.1:4277",
+  testDir: "./tests",
+  webServer: {
+    command: "node scripts/fixture-server.mjs",
+    url: "http://127.0.0.1:4277/dashboard",
+    reuseExistingServer: !process.env.CI,
+  },
+  playwright: {
+    workers: 1,
+    fullyParallel: false,
+    timeout: 30_000,
+    use: { headless: true, trace: "retain-on-failure" },
+  },
+});
+
+export default config;
+export const engine = new Engine(config);

package/examples/routed-demo/package.json

@@ -6,15 +6,12 @@
   "description": "Waygraph Map folder convention proof - (group)/<page>/page.block.ts + nav.block.ts + methods/*.block.ts, offline fixture, zero new engine code.",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "playwright test",
+    "test": "waygraph test",
     "fixture": "node scripts/fixture-server.mjs",
     "graph": "waygraph graph",
     "map": "waygraph map",
     "auto:cli": "waygraph auto --cli"
   },
-  "waygraph": {
-    "baseUrl": "http://127.0.0.1:4277"
-  },
   "dependencies": {
     "waygraph": "file:../.."
   },

package/examples/routed-demo/scripts/fixture-server.mjs

@@ -1,5 +1,5 @@
 // Stands in for this example's real app: serves src/pages/<name>.html at clean URLs (/dashboard, /docs).
-// Started and stopped by playwright.config.ts's webServer - waygraph run/demo/auto/test all honor it.
+// Started and stopped by config/waygraph.config.ts's webServer - waygraph run/demo/auto/test all honor it.
 import { createServer } from "node:http";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";

package/examples/routed-demo/src/flows/routed-demo-map.flow.ts

@@ -1,4 +1,4 @@
-import { Engine } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
 import { NavDashboardBlock } from "../map/(app_base)/dashboard/_nav.block.js";
 import { ClickWidgetBlock } from "../map/(app_base)/dashboard/_methods/click-widget.block.js";
 import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
@@ -6,14 +6,12 @@ import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
 import "../map/(app_base)/dashboard/_page.block.js";
 import "../map/(external)/docs/_page.block.js";
 
-const engine = new Engine();
 
 const homeOrigin = process.env.WAYGRAPH_BASE_URL || "http://127.0.0.1:4277";
 
 /**
  * Same real Blocks, same real Checkpoints, same real fixture server as
- * routed-demo.flow.ts - built with `engine.map()` instead of
- * the deprecated `engine.defineFlow([start, ..., end])` to prove the fluent builder
+ * routed-demo.flow.ts - built with `engine.map()` to prove the fluent builder
  * against a real browser/DOM, not just the in-memory fakes
  * tests/nav/map-builder.spec.ts already covers in the main package.
  *

package/examples/routed-demo/src/flows/routed-demo.flow.ts

@@ -1,4 +1,4 @@
-import { Engine } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
 import { NavDashboardBlock } from "../map/(app_base)/dashboard/_nav.block.js";
 import { ClickWidgetBlock } from "../map/(app_base)/dashboard/_methods/click-widget.block.js";
 import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
@@ -6,7 +6,6 @@ import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
 import "../map/(app_base)/dashboard/_page.block.js";
 import "../map/(external)/docs/_page.block.js";
 
-const engine = new Engine();
 
 /** Smoke: dashboard -> click widget -> docs, all Blocks under the Waygraph Map folder convention. */
 export const routedDemoFlow = engine.map().start().gotoPage(NavDashboardBlock).method(ClickWidgetBlock).gotoPage(NavDocsBlock).end();

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/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,12 +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` > `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) {
@@ -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/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,5 +1,5 @@
 import { defineNavClickBlock, Trait } from "waygraph";
-import type { CartPage } from "../../../states/checkout.states.js";
+import { CartPage } from "../../../states/checkout.states.js";
 import { CartSel } from "./cart.sel.js";
 
 /**
@@ -9,10 +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" })],
 });

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"),
   },
 });