waygraph 0.7.2 → 0.7.3

package/README.md

@@ -9,6 +9,18 @@ sites/apps (saucedemo.com, zsign-app) live in the sibling `projects_waygraph/` r
 See [ROADMAP.md](./ROADMAP.md) for what's shipped, spec'd, and planned by version, and
 `openspec/changes/` for the actual planning artifacts behind each roadmap item.
 
+## Docs (GitHub Pages)
+
+Browser docs (quick start, engine handout, consumer layout, deploy path):
+
+- **Published:** https://deviate-dv8.github.io/waygraph/ (after repo Pages source is set to GitHub Actions once)
+- **Source:** [`docs/`](./docs/) — static HTML, no build step
+- **Local preview:** `npm run docs:preview` → http://127.0.0.1:4173/
+- **Deploy:** push to `main` touching `docs/**` runs [`.github/workflows/pages.yml`](./.github/workflows/pages.yml) (`workflow_dispatch` also works)
+
+This README stays the in-repo API narrative; Pages is the same material for eyeballing and cross-mesh handoff.
+
+
 ## Install
 
 ```bash
@@ -157,6 +169,19 @@ at the namespace root; no invented `landing/`/`root/`; sidebar = chrome + edges)
 
 Deliberately **not yet implemented** (tracked on the project board):
 - Interstitials/Watchers - background overlay handling (cookie banners, popups).
+- Split `requires` (externally-supplied vs producedBy) recovery hints.
+- Federated multi-package pool of waygraphs.
+
+**Available now:** `waygraph auto [project]` discovers the app's Checkpoint/Block
+state graph (JSON or `--mermaid`); `locate(page, library)` answers "where am I"
+from NavBlock verify Traits. Unattended JSON execution is `chain` + `WAYGRAPH_JSON=1`
+(not named `auto`).
+
+**Friendly demo run:** `waygraph demo <flow> [project]` defaults to STEP+headed.
+Flags beat env: `--step` / `--autoplay` / `--base-url` / `--title`. BASE_URL falls
+back to `package.json` `waygraph.baseUrl` then `playwright.config` `baseURL`. Prefer
+flags (or `npm run demo*`) over a pile of `WAYGRAPH_*` vars. NavBlock `click` shows
+demo cursor travel + pulse before the real click; `url` NavBlocks still `goto`.
 
 ## Example
 

package/dist/cli.d.ts

@@ -8,8 +8,11 @@
  *   validate [project]           Import and validate all flows
  *   run <flow> [project]         Run a named flow with a fresh browser
  *   chain <spec> [project]       Run one or more Blocks by name, ad hoc, no flow file needed
+ *   demo <flow|spec> [project]   Friendly step-mode run (flags beat env; defaults STEP+headed)
+ *   try     [project]            Bundled quickstart showcase
  *
  * "project" defaults to the current directory.
  * A project is any directory containing *.flow.ts files (typically under src/flows/).
+ * Run flags (--step/--autoplay/--base-url/--title) beat WAYGRAPH_* env when present.
  */
 export {};

package/dist/cli.js

@@ -8,15 +8,19 @@
  *   validate [project]           Import and validate all flows
  *   run <flow> [project]         Run a named flow with a fresh browser
  *   chain <spec> [project]       Run one or more Blocks by name, ad hoc, no flow file needed
+ *   demo <flow|spec> [project]   Friendly step-mode run (flags beat env; defaults STEP+headed)
+ *   try     [project]            Bundled quickstart showcase
  *
  * "project" defaults to the current directory.
  * A project is any directory containing *.flow.ts files (typically under src/flows/).
+ * Run flags (--step/--autoplay/--base-url/--title) beat WAYGRAPH_* env when present.
  */
 import { existsSync, readdirSync, readFileSync, writeFileSync, rmSync, cpSync } from "node:fs";
 import { resolve, relative, join, basename, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { MemPage } from "./mem-page.js";
+import { discoverGraph, toMermaid } from "./graph.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -197,6 +201,7 @@ function isFlowLike(val) {
 const CHAIN_RUNNER_SCRIPT = `
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
+import { tmpdir } from "node:os";
 
 function walkDir(dir, pattern) {
   const results = [];
@@ -1260,11 +1265,18 @@ async function teardownOverlay(page) {
 async function moveCursorTo(page, box, ms) {
   const x = box.x + box.width / 2;
   const y = box.y + box.height / 2;
+  const travel = Math.max(0, Number(ms) || 0);
   await page
     .evaluate(({ x, y, ms }) => {
       if (window.__wgMoveCursorTo) window.__wgMoveCursorTo(x, y, ms);
-    }, { x, y, ms })
+    }, { x, y, ms: travel })
     .catch(() => {});
+  // CSS transition is async - wait the full travel so the cursor is ON the
+  // target before ring/pulse/real click (NavBlock click nav was skipping
+  // this and looked like a teleport).
+  if (travel > 0) {
+    await new Promise((res) => setTimeout(res, travel));
+  }
   return { x, y };
 }
 
@@ -1386,6 +1398,14 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
       let clickPoint = null;
       try {
         await installOverlay(page);
+        // Wait until the target is visible BEFORE measuring - otherwise
+        // defineNavBlock({ click }) (and any slow-to-appear control) skips
+        // the cursor entirely: boundingBox was null, then originalClick
+        // waited and clicked with no demo animation.
+        await this.waitFor({
+          state: "visible",
+          timeout: (options && options.timeout) || 30000,
+        }).catch(() => {});
         const box = await this.boundingBox();
         const narrated = box ? await wasJustNarrated(page) : false;
         if (box && !narrated) {
@@ -1396,6 +1416,14 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
           } catch {
             // element has no simple text (an icon button, say) - generic label is fine
           }
+          // Prefer "nav: …" when this locator is a NavBlock click target
+          // (set on page by runStepMode just before act).
+          try {
+            const navLabel = await page.evaluate(() => window.__wgPendingNavClickLabel || null);
+            if (navLabel) label = String(navLabel);
+          } catch {
+            /* ignore */
+          }
           clickPoint = await moveCursorTo(page, box, cursorMs(600));
           await showRing(page, box, label);
           // "pop for a few seconds" - Dan's own phrase, matching the
@@ -1685,6 +1713,23 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       }
     }
     await markStepRunning(page);
+    // NavBlock click-nav: label the upcoming Locator.click demo cursor as
+    // "nav: <block>" so pia/demo watchers see cursor+pulse on click nav
+    // (not only on regular Block clicks).
+    const navClick = r.block.__waygraphNavClick;
+    if (r.block.__waygraphKind === "nav" && navClick !== undefined) {
+      await page
+        .evaluate((label) => {
+          window.__wgPendingNavClickLabel = label;
+        }, "nav: " + (r.block.name || "click"))
+        .catch(() => {});
+    } else {
+      await page
+        .evaluate(() => {
+          delete window.__wgPendingNavClickLabel;
+        })
+        .catch(() => {});
+    }
     const stepFlow = engine.defineFlow([start, r.block, end]);
     // { closeOnFinish: false } makes Flow.run return { result, page }, not
     // the plain checkpoint - destructure it, don't treat the wrapper as the
@@ -1694,6 +1739,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     try {
       stepOutcome = await stepFlow.run(context, mem, { page, closeOnFinish: false });
     } catch (err) {
+      await page
+        .evaluate(() => {
+          delete window.__wgPendingNavClickLabel;
+        })
+        .catch(() => {});
       // A thrown act()/observe()/a failed verify Trait used to just crash
       // the whole Node process with a raw stack trace - the browser closes
       // (main()'s own try/finally) before a human watching ever sees WHY.
@@ -1723,6 +1773,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       }
       throw err;
     }
+    await page
+      .evaluate(() => {
+        delete window.__wgPendingNavClickLabel;
+      })
+      .catch(() => {});
     result = stepOutcome.result;
     const highlights = extractVerifyHighlights(r.block, result.__state);
     await renderAfterStep(page, {
@@ -1747,11 +1802,65 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   return result;
 }
 
+/**
+ * "chain WAYGRAPH_JSON=1" - the unattended counterpart to "chain --step": no
+ * human gate, no overlay, headless by default. The same execution --step
+ * already has (session-reset boundaries, per-segment mem-seeding) but
+ * reporting built for an agent reading stdout afterward, not a human
+ * watching the browser live - a flat JSON object naming exactly which Block
+ * failed, what every EARLIER Block resolved to, and a screenshot at the
+ * exact moment of failure, since there's no live browser for a human to
+ * glance at instead. (Previously its own "waygraph auto" verb - renamed once
+ * "auto" came to mean the state-machine discovery tool instead; this is a
+ * chain reporting mode, not a distinct command.)
+ */
+async function runJsonReportMode(engine, start, end, context, page, mem, resolved, baseURL) {
+  const steps = [];
+  for (let i = 0; i < resolved.length; i++) {
+    const r = resolved[i];
+    if (r.seedMem) r.seedMem();
+    if (r.resetSession && i > 0) {
+      await resetPageState(context, page, baseURL);
+    }
+    const startedAt = Date.now();
+    const stepFlow = engine.defineFlow([start, r.block, end]);
+    try {
+      const outcome = await stepFlow.run(context, mem, { page, closeOnFinish: false });
+      steps.push({ name: r.block.name, checkpoint: outcome.result, ms: Date.now() - startedAt });
+    } catch (err) {
+      let screenshot = null;
+      try {
+        screenshot = join(tmpdir(), "waygraph-chain-failure-" + Date.now() + ".png");
+        await page.screenshot({ path: screenshot, fullPage: true });
+      } catch {
+        screenshot = null;
+      }
+      return {
+        ok: false,
+        failedAt: r.block.name,
+        stepIndex: i,
+        totalSteps: resolved.length,
+        error: err && err.message ? err.message : String(err),
+        steps,
+        screenshot,
+      };
+    }
+  }
+  return { ok: true, result: steps.length > 0 ? steps[steps.length - 1].checkpoint : null, steps };
+}
+
 async function main() {
   const projectDir = process.argv[2];
   const spec = process.argv[3];
   const { connect, MemPage, Engine, start, end, chainFlow } = await import("waygraph");
   const mem = new MemPage();
+  // Computed early - JSON-report mode's stdout is meant to be ONE parseable
+  // JSON object for whatever's reading it afterward (a script, an agent),
+  // not a human's console. Every informational console.log below is
+  // skipped for it; only the final JSON report (or a thrown Error, for a
+  // truly unexpected failure outside runJsonReportMode's own try/catch)
+  // reaches stdout.
+  const jsonReport = process.env.WAYGRAPH_JSON === "1";
   let resolved = [];
   // A bare identifier (no "(", no "then") might name an existing Flow
   // that's already wired up (e.g. loginFlow) - try that FIRST so pointing
@@ -1766,11 +1875,13 @@ async function main() {
         exportName: bi.name,
         expectedFailureReason: flow.expectedFailureReason,
       }));
-      console.log(
-        "waygraph: running existing flow \\"" + bareRef + "\\" - " +
-          resolved.map((r) => r.block.name).join(" -> ") + " (" + resolved.length + " block" +
-          (resolved.length === 1 ? "" : "s") + ", no chain spec needed)",
-      );
+      if (!jsonReport) {
+        console.log(
+          "waygraph: running existing flow \\"" + bareRef + "\\" - " +
+            resolved.map((r) => r.block.name).join(" -> ") + " (" + resolved.length + " block" +
+            (resolved.length === 1 ? "" : "s") + ", no chain spec needed)",
+        );
+      }
     }
   }
   if (resolved.length === 0) {
@@ -1855,10 +1966,12 @@ async function main() {
       isFirstOfSegment = false;
       return entry;
     });
-    console.log(
-      "waygraph: chaining " + resolved.map((r) => r.block.name).join(" -> ") +
-        " (" + resolved.length + " block" + (resolved.length === 1 ? "" : "s") + ")",
-    );
+    if (!jsonReport) {
+      console.log(
+        "waygraph: chaining " + resolved.map((r) => r.block.name).join(" -> ") +
+          " (" + resolved.length + " block" + (resolved.length === 1 ? "" : "s") + ")",
+      );
+    }
   }
   const step = process.env.WAYGRAPH_STEP === "1";
   // Stepping through headless defeats the point - a human can't watch it.
@@ -1900,12 +2013,12 @@ async function main() {
   // the same limitation "chain" always had; only --step's own runStepMode
   // loop actually needs (and correctly supports, via resolved[i].seedMem)
   // per-segment differentiated values.
-  if (!step) {
+  if (!step && !jsonReport) {
     for (const r of resolved) {
       if (r.seedMem) r.seedMem();
     }
   }
-  if (step || baseURL) {
+  if (step || jsonReport || baseURL) {
     const { chromium } = await import("playwright");
     // --start-maximized (step mode only): viewport: null alone only made
     // the PAGE content track the window - the actual browser WINDOW still
@@ -1935,6 +2048,15 @@ async function main() {
           await page.goto(baseURL).catch(() => {});
         }
         result = await runStepMode(engine, start, end, context, page, mem, resolved, slowMo, title, fastBlockNames, clearSession, baseURL);
+      } else if (jsonReport) {
+        const page = await context.newPage();
+        if (baseURL) {
+          await page.goto(baseURL).catch(() => {});
+        }
+        const report = await runJsonReportMode(engine, start, end, context, page, mem, resolved, baseURL);
+        console.log(JSON.stringify(report, null, 2));
+        if (!report.ok) process.exitCode = 1;
+        return;
       } else {
         const blocks = resolved.map((r) => r.block);
         const chained = blocks.reduce((a, b) => connect(a, b));
@@ -2244,9 +2366,119 @@ async function runFlow(projectDir, flowName) {
     console.error(`waygraph: no flow named "${flowName}" found under ${projectDir}`);
     process.exitCode = 1;
 }
-// ---------------------------------------------------------------------------
-// CLI plumbing
-// ---------------------------------------------------------------------------
+/**
+ * Pulls `--step` / `--no-step` / `--autoplay` / `--no-autoplay` /
+ * `--base-url <url>` / `--title <text>` out of argv. Unknown `--*` stay as
+ * positionals so callers like `auto --mermaid` keep working when they parse
+ * their own flags.
+ */
+function parseRunFlags(argv) {
+    const out = { positionals: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--step") {
+            out.step = true;
+        }
+        else if (a === "--no-step") {
+            out.step = false;
+        }
+        else if (a === "--autoplay") {
+            out.autoplay = true;
+        }
+        else if (a === "--no-autoplay") {
+            out.autoplay = false;
+        }
+        else if (a === "--base-url" || a.startsWith("--base-url=")) {
+            const v = a.includes("=") ? a.slice("--base-url=".length) : argv[++i];
+            if (!v || v.startsWith("-")) {
+                console.error("waygraph: --base-url needs a URL value");
+                process.exit(1);
+            }
+            out.baseUrl = v;
+        }
+        else if (a === "--title" || a.startsWith("--title=")) {
+            const v = a.includes("=") ? a.slice("--title=".length) : argv[++i];
+            if (v === undefined || (v.startsWith("-") && !a.includes("="))) {
+                console.error('waygraph: --title needs a string value');
+                process.exit(1);
+            }
+            out.title = v;
+        }
+        else {
+            out.positionals.push(a);
+        }
+    }
+    return out;
+}
+/** Writes flag values into process.env so the chain child inherits them. Flags beat prior env. */
+function applyRunFlags(flags) {
+    if (flags.step === true) {
+        process.env.WAYGRAPH_STEP = "1";
+        process.env.WAYGRAPH_HEADED = "1";
+    }
+    else if (flags.step === false) {
+        process.env.WAYGRAPH_STEP = "0";
+    }
+    if (flags.autoplay === true) {
+        process.env.WAYGRAPH_AUTOPLAY = "1";
+    }
+    else if (flags.autoplay === false) {
+        process.env.WAYGRAPH_AUTOPLAY = "0";
+    }
+    if (flags.baseUrl !== undefined) {
+        process.env.WAYGRAPH_BASE_URL = flags.baseUrl;
+    }
+    if (flags.title !== undefined) {
+        process.env.WAYGRAPH_TITLE = flags.title;
+    }
+}
+/**
+ * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set:
+ * package.json `waygraph.baseUrl` (or `baseURL`), then playwright.config `baseURL`.
+ */
+function resolveBaseUrl(projectDir) {
+    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
+        }
+    }
+    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;
+}
+/**
+ * Friendly demo defaults: STEP+headed on, BASE_URL from package/env/playwright.
+ * Call after applyRunFlags so explicit flags already won.
+ */
+function applyDemoDefaults(projectDir) {
+    if (process.env.WAYGRAPH_STEP === undefined)
+        process.env.WAYGRAPH_STEP = "1";
+    if (process.env.WAYGRAPH_STEP === "1" && process.env.WAYGRAPH_HEADED === undefined) {
+        process.env.WAYGRAPH_HEADED = "1";
+    }
+    if (!process.env.WAYGRAPH_BASE_URL) {
+        const resolved = resolveBaseUrl(projectDir);
+        if (resolved)
+            process.env.WAYGRAPH_BASE_URL = resolved;
+    }
+}
 const args = process.argv.slice(2);
 const command = args[0];
 function usage() {
@@ -2258,7 +2490,51 @@ Usage:
   waygraph validate [project]     Import and validate all flows
   waygraph run <flow> [project]   Run a named flow
   waygraph chain <spec> [project] Run one or more Blocks by name, ad hoc
+  waygraph demo <flow|spec> [project]
+                                  Friendly human-watched run. Defaults:
+                                  --step (headed overlay). BASE_URL from
+                                  --base-url, else WAYGRAPH_BASE_URL, else
+                                  package.json waygraph.baseUrl, else
+                                  playwright.config baseURL.
+  waygraph auto    [project]      Discover state graph (JSON or --mermaid)
   waygraph check   [project]      Warn about navigation outside a NavBlock
+  waygraph try     [project]      One-shot bundled quickstart showcase
+
+Run flags (chain / demo / try) - flags beat WAYGRAPH_* env:
+  --step / --no-step              human-verification overlay (implies headed)
+  --autoplay / --no-autoplay      panel Auto-advance starting state
+  --base-url <url>                base URL for relative page.goto()
+  --title <text>                  persistent overlay banner title
+
+Prefer flags (or npm scripts that pass them) over an ENV soup of WAYGRAPH_*.
+
+    WAYGRAPH_JSON=1 reports for a script/agent instead of a human: no
+    --step overlay, no informational console.log, headless by default -
+    ONE JSON object on stdout, nothing else. Success: { ok: true, result,
+    steps: [{name, checkpoint, ms}, ...] }. Failure: { ok: false, failedAt,
+    stepIndex, totalSteps, error, steps (every EARLIER Block that
+    succeeded), screenshot (a PNG path captured at the exact moment of
+    failure - there's no live browser for anyone to glance at instead) }.
+    Exit code matches ok. Same session-reset boundaries and per-segment
+    mem-seeding --step already has.
+
+  waygraph auto    [project]      Walks every *.block.ts in [project]
+                                  (default: cwd) and builds the app's own
+                                  state graph: Checkpoints are nodes, Blocks
+                                  are edges. A NavBlock's own runtime
+                                  "checkpoint" gives its Out tag for free
+                                  (In is always "*" - reachable from
+                                  anywhere); a regular defineBlock<In, Out>
+                                  gets its tags via the same lightweight
+                                  regex source-reading list/nav/check
+                                  already do, resolving each type identifier
+                                  back to its literal Checkpoint tag (a
+                                  union Out - a branching action Block -
+                                  becomes one edge per member). Prints the
+                                  graph as JSON by default, or --mermaid for
+                                  a stateDiagram-v2 text export. Reports how
+                                  many Blocks' Out couldn't be resolved
+                                  (skipped, not crashed).
   waygraph try     [project]      One-shot quickstart showcase - genuinely
                                   "npx waygraph try", no separate init step.
                                   Checks (a real launch+close, not a guess)
@@ -2298,7 +2574,7 @@ Usage:
 
     Runs in a child process rooted at "project" (its own waygraph/playwright,
     never this CLI's) so a project's real Blocks resolve against its own
-    node_modules. Env vars, all optional:
+    node_modules. Env vars still work (flags override them when both set):
       WAYGRAPH_BASE_URL   base URL for Blocks using relative page.goto()
       WAYGRAPH_HEADED=1   show the browser instead of headless
       WAYGRAPH_SLOWMO=ms  slow down each Playwright action, for watching a run
@@ -2342,6 +2618,13 @@ Usage:
                           still cycles and remembers via localStorage
 
   "project" defaults to the current directory.
+
+Examples:
+  waygraph demo shopFlow .
+  waygraph demo shopFlow . --autoplay --title "Shop demo"
+  waygraph demo loginFlow . --base-url https://www.saucedemo.com
+  waygraph chain "login then nav-cart" . --step --no-autoplay
+  npm run demo                  # scaffold: waygraph demo exampleFlow .
 `);
     process.exit(0);
 }
@@ -2394,17 +2677,70 @@ async function main() {
             break;
         }
         case "chain": {
-            const spec = args[1];
+            const flags = parseRunFlags(args.slice(1));
+            applyRunFlags(flags);
+            const spec = flags.positionals[0];
             if (!spec) {
                 console.error('waygraph chain: missing <spec>, e.g. waygraph chain "login({...}) then overview-metrics"');
                 process.exit(1);
             }
-            const proj = resolve(args[2] ?? process.cwd());
+            const proj = resolve(flags.positionals[1] ?? process.cwd());
+            if (!process.env.WAYGRAPH_BASE_URL) {
+                const resolved = resolveBaseUrl(proj);
+                if (resolved)
+                    process.env.WAYGRAPH_BASE_URL = resolved;
+            }
             await runChain(proj, spec);
             break;
         }
+        case "demo": {
+            const flags = parseRunFlags(args.slice(1));
+            applyRunFlags(flags);
+            const spec = flags.positionals[0];
+            if (!spec) {
+                console.error('waygraph demo: missing <flow|spec>, e.g. waygraph demo shopFlow .\n' +
+                    "  Flags: --step/--no-step --autoplay/--no-autoplay --base-url <url> --title <text>");
+                process.exit(1);
+            }
+            const proj = resolve(flags.positionals[1] ?? process.cwd());
+            if (!existsSync(proj)) {
+                console.error(`waygraph: no such directory: ${proj}`);
+                process.exit(1);
+            }
+            // Friendly defaults after flags: STEP+headed on; BASE_URL from package/playwright.
+            if (flags.step === undefined && process.env.WAYGRAPH_STEP === undefined) {
+                process.env.WAYGRAPH_STEP = "1";
+            }
+            applyDemoDefaults(proj);
+            console.error(`waygraph demo: STEP=${process.env.WAYGRAPH_STEP === "1" ? "on" : "off"}` +
+                ` AUTOPLAY=${process.env.WAYGRAPH_AUTOPLAY === "1" ? "on" : "off"}` +
+                ` BASE_URL=${process.env.WAYGRAPH_BASE_URL ?? "(unset)"}` +
+                (process.env.WAYGRAPH_TITLE ? ` TITLE=${JSON.stringify(process.env.WAYGRAPH_TITLE)}` : ""));
+            await runChain(proj, spec);
+            break;
+        }
+        case "auto": {
+            const mermaid = args.includes("--mermaid");
+            const proj = resolve(args.find((a, i) => i >= 1 && !a.startsWith("--")) ?? process.cwd());
+            if (!existsSync(proj)) {
+                console.error(`waygraph: no such directory: ${proj}`);
+                process.exit(1);
+            }
+            const graph = await discoverGraph(proj);
+            if (mermaid) {
+                console.log(toMermaid(graph));
+            }
+            else {
+                console.log(JSON.stringify(graph, null, 2));
+            }
+            console.error(`waygraph auto: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s), ` +
+                `${graph.skipped.length} Block(s) skipped (Out not resolvable)`);
+            break;
+        }
         case "try": {
-            const proj = resolve(args[1] ?? process.cwd());
+            const flags = parseRunFlags(args.slice(1));
+            applyRunFlags(flags);
+            const proj = resolve(flags.positionals[0] ?? process.cwd());
             if (!existsSync(proj)) {
                 console.error(`waygraph: no such directory: ${proj}`);
                 process.exit(1);

package/dist/engine.d.ts

@@ -371,7 +371,7 @@ export declare class Engine {
      * Builds a runnable {@link Flow} from `[start, ...Blocks, end]`, typechecked
      * so each Block's `In` must match the previous Block's `Out` - the same
      * check `connect()` does, just declared as a flat array instead of hand-nested
-     * calls. Overloaded for 2-7 array slots (1-6 real Blocks between `start`/`end`)
+     * calls. Overloaded for 2-9 array slots (1-8 real Blocks between `start`/`end`)
      * rather than one fully-generic recursive tuple type, so each arity is as
      * reliably checked as `connect<A,B,C>` itself.
      * @example engine.defineFlow([start, LoginBlock, AddToCartBlock, end])
@@ -399,6 +399,29 @@ export declare class Engine {
         Block<F, G>,
         EndMarker
     ]): Flow<G>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        EndMarker
+    ]): Flow<H>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        Block<H, I>,
+        EndMarker
+    ]): Flow<I>;
 }
 /**
  * Attaches routing to `block` without touching its act/observe/resolve/verify -
@@ -497,6 +520,28 @@ export type NavBlockOptions<Out extends Checkpoint<string>> = {
  * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
  */
 export declare function defineNavBlock<Out extends Checkpoint<string>>(options: NavBlockOptions<Out>): NavBlock<Out>;
+/**
+ * "Where am I" - reverse-matches a live `page` against every NavBlock in
+ * `library`, in order, returning the first one whose own `verify` Traits all
+ * pass (its `checkpoint`), or `null` if none match. Deliberately NavBlocks
+ * only: a NavBlock has exactly one fixed `checkpoint` and a `verify` list
+ * whose whole job is already "confirm arrival here," so it's a reliable
+ * fingerprint - a regular `defineBlock` can branch to different `Out` tags
+ * depending on runtime evidence, so its `verify` alone doesn't identify a
+ * single state the way a NavBlock's does.
+ *
+ * The primitive `waygraph auto`'s discovered graph is *for* - the graph says
+ * what pages exist and how to reach them; `locate()` is how an autonomous
+ * run figures out which one it's actually looking at right now, without a
+ * human telling it.
+ *
+ * More than one NavBlock matching is a real possibility (two Checkpoints
+ * whose `verify` Traits are both satisfied by the same page) - `locate()`
+ * returns the first match rather than treating that as an error; resolving
+ * genuine ambiguity is a follow-up, not solved here.
+ * @example const here = await locate(page, [NavLoginBlock, NavDashboardBlock]);
+ */
+export declare function locate(page: Page, library: readonly NavBlock<any>[]): Promise<string | null>;
 /**
  * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
  * same routing - but with `verify` replaced. For giving one flow stricter (or

package/dist/engine.js

@@ -633,6 +633,9 @@ export function defineNavBlock(options) {
                     await page.goto(url);
                 }
                 else {
+                    // Always Locator.click() so step-mode's demo cursor/pulse patch
+                    // (instrumentInteractionHighlighting) sees NavBlock click-nav -
+                    // never page.click() / goto teleport.
                     const selector = typeof options.click === "function" ? options.click(mem) : options.click;
                     await page.locator(selector).click();
                 }
@@ -652,8 +655,67 @@ export function defineNavBlock(options) {
         enumerable: false,
         configurable: false,
     });
+    // Demo/step tooling: remember the click selector (or factory) so
+    // overlays can label "nav click" without re-parsing source.
+    if (options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphNavClick", {
+            value: options.click,
+            enumerable: false,
+            configurable: false,
+        });
+    }
     return built;
 }
+/**
+ * "Where am I" - reverse-matches a live `page` against every NavBlock in
+ * `library`, in order, returning the first one whose own `verify` Traits all
+ * pass (its `checkpoint`), or `null` if none match. Deliberately NavBlocks
+ * only: a NavBlock has exactly one fixed `checkpoint` and a `verify` list
+ * whose whole job is already "confirm arrival here," so it's a reliable
+ * fingerprint - a regular `defineBlock` can branch to different `Out` tags
+ * depending on runtime evidence, so its `verify` alone doesn't identify a
+ * single state the way a NavBlock's does.
+ *
+ * The primitive `waygraph auto`'s discovered graph is *for* - the graph says
+ * what pages exist and how to reach them; `locate()` is how an autonomous
+ * run figures out which one it's actually looking at right now, without a
+ * human telling it.
+ *
+ * More than one NavBlock matching is a real possibility (two Checkpoints
+ * whose `verify` Traits are both satisfied by the same page) - `locate()`
+ * returns the first match rather than treating that as an error; resolving
+ * genuine ambiguity is a follow-up, not solved here.
+ * @example const here = await locate(page, [NavLoginBlock, NavDashboardBlock]);
+ */
+export async function locate(page, library) {
+    const mem = new MemPage();
+    for (const block of library) {
+        try {
+            // NavBlock's own resolve() ignores whatever it's called with - always
+            // exactly `checkpoint(options.checkpoint)` - so this is safe to call
+            // before verify, unlike a regular Block where resolve depends on
+            // observed evidence.
+            const resolved = await block.instruction.resolve(undefined);
+            const verify = block.instruction.verify;
+            const traits = typeof verify === "function" ? verify(resolved) : (verify ?? []);
+            let allPass = true;
+            for (const trait of traits) {
+                // eslint-disable-next-line no-await-in-loop
+                if (!(await trait.check(page, mem))) {
+                    allPass = false;
+                    break;
+                }
+            }
+            if (allPass)
+                return resolved.__state;
+        }
+        catch {
+            // This NavBlock's own verify threw (e.g. a waitFor timing out) -
+            // treat that the same as "didn't match," try the next candidate.
+        }
+    }
+    return null;
+}
 /**
  * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
  * same routing - but with `verify` replaced. For giving one flow stricter (or

package/dist/graph.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The state-machine shape `waygraph auto` discovers from a project's own
+ * Blocks - Checkpoints are nodes, Blocks are edges. Kept as plain data (not
+ * classes/functions) so it's trivially JSON-serializable for a script/agent
+ * reading `waygraph auto`'s stdout.
+ */
+export interface WaygraphNode {
+    checkpoint: string;
+}
+export interface WaygraphEdge {
+    /** The Block's own runtime `.name`. */
+    block: string;
+    /** Path the Block was discovered in, relative to the project root. */
+    file: string;
+    /** `"*"` for a NavBlock - reachable from anywhere, by design. */
+    from: string;
+    to: string;
+    kind: "nav" | "action";
+}
+export interface SkippedBlock {
+    block: string;
+    file: string;
+    reason: string;
+}
+export interface WaygraphGraph {
+    nodes: WaygraphNode[];
+    edges: WaygraphEdge[];
+    /** Blocks whose Out tag couldn't be statically resolved - not a crash, just excluded. */
+    skipped: SkippedBlock[];
+}
+/**
+ * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
+ * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`
+ * renders as Mermaid's own `[*]` start marker, matching how a NavBlock's
+ * `from` already means "reachable from anywhere."
+ * @example console.log(toMermaid(graph))
+ */
+export declare function toMermaid(graph: WaygraphGraph): string;
+/**
+ * Walks every `*.block.ts` file under `projectDir` and builds the app's own
+ * state graph. Shares the same in-process-import limitation `waygraph
+ * check` already has: a target project whose own `waygraph`/`playwright`
+ * are genuinely separate installs (not symlinked into this same
+ * node_modules resolution) can crash Playwright's own "second copy" guard
+ * on import - acceptable for an introspection command the same way it
+ * already is for `check`, unlike `chain`, which spawns a child process
+ * specifically because it also EXECUTES Blocks, not just imports them.
+ */
+export declare function discoverGraph(projectDir: string): Promise<WaygraphGraph>;

package/dist/graph.js

@@ -0,0 +1,237 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname, relative, resolve } from "node:path";
+/**
+ * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
+ * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`
+ * renders as Mermaid's own `[*]` start marker, matching how a NavBlock's
+ * `from` already means "reachable from anywhere."
+ * @example console.log(toMermaid(graph))
+ */
+export function toMermaid(graph) {
+    const lines = ["stateDiagram-v2"];
+    for (const edge of graph.edges) {
+        const from = edge.from === "*" ? "[*]" : edge.from;
+        lines.push(`  ${from} --> ${edge.to} : ${edge.block}`);
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Discovery - deliberately self-contained (no import from cli.ts): cli.ts
+// runs its own main() unconditionally at module load, so it can't safely be
+// imported from a test (or from here) without also running the whole CLI.
+// These are small, stable duplicates of cli.ts's own discoverBlocks/
+// isBlockLike/isNavBlockMarked/importModule, not a shared abstraction -
+// simpler and lower-risk than a circular import between the two modules.
+// ---------------------------------------------------------------------------
+function walkDir(dir, pattern) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
+                continue;
+            results.push(...walkDir(full, pattern));
+        }
+        else if (pattern.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function discoverBlocks(projectDir) {
+    return walkDir(projectDir, /\.block\.ts$/);
+}
+async function importModule(filePath) {
+    const url = new URL(`file://${resolve(filePath)}`);
+    return (await import(url.href));
+}
+function isBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    if (typeof obj.name !== "string")
+        return false;
+    const instruction = obj.instruction;
+    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
+}
+/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+function isNavBlockMarked(val) {
+    return val.__waygraphKind === "nav";
+}
+/**
+ * Resolves `typeName` to every literal Checkpoint tag it can mean, within
+ * one `*.states.ts` file's own source text - `type X = Checkpoint<"Tag">`
+ * directly, or `type X = A | B | Checkpoint<"C">` (a union of other type
+ * names and/or inline Checkpoint literals) recursively. A cycle or unknown
+ * identifier just contributes no tags, rather than throwing - callers treat
+ * an empty result as "couldn't resolve," not a crash.
+ */
+function resolveCheckpointTags(statesSrc, typeName, seen = new Set()) {
+    if (seen.has(typeName))
+        return [];
+    seen.add(typeName);
+    const direct = new RegExp(`type\\s+${typeName}\\s*=\\s*Checkpoint<"([^"]+)">`).exec(statesSrc);
+    if (direct)
+        return [direct[1]];
+    const aliased = new RegExp(`type\\s+${typeName}\\s*=\\s*([^;]+);`).exec(statesSrc);
+    if (!aliased)
+        return [];
+    const tags = [];
+    for (const member of aliased[1].split("|").map((s) => s.trim()).filter(Boolean)) {
+        const inline = /^Checkpoint<"([^"]+)">$/.exec(member);
+        if (inline) {
+            tags.push(inline[1]);
+        }
+        else if (/^[A-Za-z_$][\w]*$/.test(member)) {
+            tags.push(...resolveCheckpointTags(statesSrc, member, seen));
+        }
+    }
+    return tags;
+}
+/**
+ * Finds which file `blockFilePath`'s own `import type { ... }` statements
+ * say `typeName` comes from, resolved to a real path on disk (`.js` ->
+ * `.ts`, matching this project's own NodeNext import convention). Only
+ * follows relative imports - `typeName` imported from a package (e.g.
+ * `waygraph` itself, for `Checkpoint`) has no project file to read.
+ */
+function findTypeSourceFile(blockFilePath, typeName) {
+    const src = readFileSync(blockFilePath, "utf-8");
+    const importRe = /import\s+type\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
+    let m;
+    while ((m = importRe.exec(src)) !== null) {
+        const names = m[1].split(",").map((s) => s.trim());
+        if (!names.includes(typeName))
+            continue;
+        const importPath = m[2];
+        if (!importPath.startsWith("."))
+            continue;
+        const resolved = join(dirname(blockFilePath), importPath.replace(/\.js$/, ".ts"));
+        if (existsSync(resolved))
+            return resolved;
+    }
+    return null;
+}
+/** `findTypeSourceFile` + `resolveCheckpointTags`, chained - `[]` on any failure along the way. */
+function resolveTypeToTags(blockFilePath, typeName) {
+    const statesFile = findTypeSourceFile(blockFilePath, typeName);
+    if (!statesFile)
+        return [];
+    return resolveCheckpointTags(readFileSync(statesFile, "utf-8"), typeName);
+}
+/**
+ * Resolves one `defineBlock<In, Out>` generic argument, as captured by
+ * `extractDefineBlockGenerics` - either a plain type identifier (goes
+ * through `resolveTypeToTags`), an inline `Checkpoint<"Tag">` literal, or
+ * the documented wildcard forms `Checkpoint<string>`/`Checkpoint<any>` (a
+ * Block reused across several entry points, e.g. this project's own
+ * `AddToCartBlock` - reachable from anywhere, same as a NavBlock's own `"*"`).
+ */
+function resolveGenericArg(blockFilePath, arg) {
+    if (arg === "Checkpoint<string>" || arg === "Checkpoint<any>")
+        return ["*"];
+    const inline = /^Checkpoint<"([^"]+)">$/.exec(arg);
+    if (inline)
+        return [inline[1]];
+    return resolveTypeToTags(blockFilePath, arg);
+}
+/** Every `defineBlock<In, Out>(` call site in a file's own source, in order. */
+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
+    // balance correctly against a naive greedy match) - captured as a single
+    // alternation so both shapes come out of the same two capture groups.
+    const arg = String.raw `(Checkpoint<[^>]*>|[A-Za-z_$][\w]*)`;
+    const re = new RegExp(String.raw `defineBlock<\s*${arg}\s*,\s*${arg}\s*>`, "g");
+    const calls = [];
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        calls.push({ in: m[1], out: m[2] });
+    }
+    return calls;
+}
+/**
+ * Walks every `*.block.ts` file under `projectDir` and builds the app's own
+ * state graph. Shares the same in-process-import limitation `waygraph
+ * check` already has: a target project whose own `waygraph`/`playwright`
+ * are genuinely separate installs (not symlinked into this same
+ * node_modules resolution) can crash Playwright's own "second copy" guard
+ * on import - acceptable for an introspection command the same way it
+ * already is for `check`, unlike `chain`, which spawns a child process
+ * specifically because it also EXECUTES Blocks, not just imports them.
+ */
+export async function discoverGraph(projectDir) {
+    const files = discoverBlocks(projectDir);
+    const nodeTags = new Set();
+    const edges = [];
+    const skipped = [];
+    for (const file of files) {
+        const relFile = relative(projectDir, file);
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch {
+            continue;
+        }
+        const src = readFileSync(file, "utf-8");
+        // Assumes source order matches export-object iteration order - true for
+        // this codebase's own convention of one Block per file; a file with
+        // several regular Blocks in an unusual order is a known edge case, not
+        // handled specially here.
+        const calls = extractDefineBlockGenerics(src);
+        let callIndex = 0;
+        for (const exported of Object.values(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            const blockName = exported.name;
+            if (isNavBlockMarked(exported)) {
+                try {
+                    // NavBlock's own resolve() ignores whatever it's called with -
+                    // always exactly `checkpoint(options.checkpoint)`.
+                    const resolveFn = exported.instruction.resolve;
+                    const resolved = await resolveFn(undefined);
+                    const to = resolved.__state;
+                    nodeTags.add(to);
+                    edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                }
+                catch {
+                    skipped.push({ block: blockName, file: relFile, reason: "NavBlock's own resolve() threw" });
+                }
+                continue;
+            }
+            const call = calls[callIndex++];
+            if (!call) {
+                skipped.push({ block: blockName, file: relFile, reason: "no defineBlock<In, Out> generic call found" });
+                continue;
+            }
+            const fromTags = resolveGenericArg(file, call.in);
+            const toTags = resolveGenericArg(file, call.out);
+            if (fromTags.length === 0 || toTags.length === 0) {
+                const badName = fromTags.length === 0 ? call.in : call.out;
+                skipped.push({ block: blockName, file: relFile, reason: `couldn't resolve "${badName}" to a Checkpoint tag` });
+                continue;
+            }
+            for (const from of fromTags) {
+                for (const to of toTags) {
+                    if (from !== "*")
+                        nodeTags.add(from);
+                    nodeTags.add(to);
+                    edges.push({ block: blockName, file: relFile, from, to, kind: "action" });
+                }
+            }
+        }
+    }
+    return {
+        nodes: [...nodeTags].sort().map((checkpoint) => ({ checkpoint })),
+        edges,
+        skipped,
+    };
+}

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start } from "./type
 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, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
 export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions } from "./engine.js";
 export type { ActionPage } from "./types.js";
+export { discoverGraph, toMermaid } from "./graph.js";
+export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock } from "./graph.js";

package/dist/index.js

@@ -1,4 +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, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export { discoverGraph, toMermaid } from "./graph.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",
@@ -26,7 +26,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "playwright test"
+    "test": "playwright test",
+    "docs:preview": "python3 -m http.server 4173 --directory docs"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"