waygraph 0.6.0 → 0.7.0

package/README.md

@@ -103,9 +103,16 @@ a fresh tab (the run won't close a page you handed it unless you say so), and
 so the caller can keep driving it - hands a run tab back instead of losing it. See
 "Recipes" for capture-on-popup, which stays a documented pattern until a second real use
 case promotes it to an engine API.
-`defineNavBlock({ name, checkpoint, url })` builds a Block whose only possible action is
-navigating - `url` accepts a plain string or `(mem) => string` for parameterized routes,
-and the generated `act()` is always exactly `page.goto(url)`, never author-supplied. A
+`defineNavBlock({ name, checkpoint, url })` or `defineNavBlock({ name, checkpoint, click })`
+builds a Block whose only possible action is navigating - exactly one of `url`/`click` is
+required, enforced at compile time. Both accept a plain string or `(mem) => string`/
+`(mem) => selector` for parameterized routes; the generated `act()` is always exactly
+`page.goto(url)` or `page.locator(click).click()`, never author-supplied. `click` is the
+opinionated default - navigating by clicking a real element already on the page (a nav
+link, a sidebar item) instead of teleporting straight to a URL, so a Block actually proves
+the app's own navigation path works instead of skipping past it. `url` still exists for the
+real cases with no click path to get there (a deep link from an email, a public share
+link). A
 regular `defineBlock`'s `act()` receives its `page` typed as `ActionPage` instead of raw
 `Page` - structurally identical, every method still fully present and callable, except
 `goto`/`reload`/`goBack`/`goForward` are re-declared `@deprecated`, so a TypeScript-aware

package/dist/cli.js

@@ -2003,11 +2003,9 @@ function packageRoot() {
  * directory the real demo files get copied into, so it resolves "waygraph"
  * and "@playwright/test" exactly as they will - and actually launches (then
  * immediately closes) chromium, a real check rather than a guess at whether
- * the browser's installed. Returns null when everything's ready, or a
- * friendly, actionable message naming exactly what to install when it
- * isn't. Never leaves the probe script behind.
+ * the browser's installed. Never leaves the probe script behind.
  */
-async function checkTryPrereqs(projectDir) {
+async function probeTryPrereqs(projectDir) {
     const tsxEsm = import.meta.resolve("tsx/esm");
     const probeScript = [
         "try {",
@@ -2050,27 +2048,80 @@ async function checkTryPrereqs(projectDir) {
             child.on("exit", (code) => res({ code: code ?? 1, stderr: stderrBuf }));
         });
         if (result.code === 0)
-            return null;
+            return { ok: true };
         const stderr = result.stderr;
-        if (stderr.includes("WAYGRAPH_TRY_MISSING_WAYGRAPH")) {
-            return `"waygraph" isn't resolvable as a dependency from ${projectDir}.\nRun this first, inside that directory:\n  npm install waygraph\n  npm install -D @playwright/test\n  npx playwright install chromium`;
-        }
-        if (stderr.includes("WAYGRAPH_TRY_MISSING_PLAYWRIGHT_TEST")) {
-            return `"@playwright/test" isn't resolvable as a dependency from ${projectDir}.\nRun this first, inside that directory:\n  npm install -D @playwright/test\n  npx playwright install chromium`;
-        }
-        if (stderr.includes("WAYGRAPH_TRY_MISSING_BROWSER")) {
-            return "Playwright's chromium browser isn't installed yet.\nRun this first:\n  npx playwright install chromium";
-        }
-        return `couldn't verify prerequisites:\n${stderr.trim()}`;
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_WAYGRAPH"))
+            return { ok: false, missing: "waygraph" };
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_PLAYWRIGHT_TEST"))
+            return { ok: false, missing: "playwright-test" };
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_BROWSER"))
+            return { ok: false, missing: "browser" };
+        return { ok: false, missing: "unknown", detail: stderr.trim() || `probe exited with code ${result.code}` };
     }
     finally {
         rmSync(probePath, { force: true });
     }
 }
+/** Spawns with inherited stdio (the real npm/playwright output, visible) and resolves to its exit code. */
+function runInherited(cmd, args, cwd) {
+    return new Promise((res, rej) => {
+        const child = spawn(cmd, args, { cwd, stdio: "inherit", env: process.env });
+        child.on("error", rej);
+        child.on("exit", (code) => res(code ?? 1));
+    });
+}
+/**
+ * `waygraph try` is meant to be a genuine one-shot `npx waygraph try` -
+ * no separate init/install step the human has to remember, the same shape
+ * as `npm create vite@latest`. Probes first; anything missing gets
+ * installed right here (a minimal package.json if none exists, then
+ * `npm install waygraph @playwright/test`, then Playwright's own chromium
+ * download), with the real install output visible the whole time - not
+ * silent, just not a separate step you have to run yourself first. Returns
+ * null once everything's actually ready, or a message naming whatever
+ * still isn't after really trying.
+ */
+async function ensureTryPrereqs(projectDir) {
+    let status = await probeTryPrereqs(projectDir);
+    if (status.ok)
+        return null;
+    if (status.missing === "unknown") {
+        return `couldn't verify prerequisites:\n${status.detail}`;
+    }
+    if (status.missing === "waygraph" || status.missing === "playwright-test") {
+        if (!existsSync(join(projectDir, "package.json"))) {
+            writeFileSync(join(projectDir, "package.json"), JSON.stringify({ name: basename(projectDir) || "waygraph-quickstart", private: true, type: "module" }, null, 2) + "\n");
+            console.log(`waygraph try: no package.json in ${projectDir} - created a minimal one.`);
+        }
+        console.log(`waygraph try: installing waygraph + @playwright/test in ${projectDir} ...`);
+        const installCode = await runInherited("npm", ["install", "waygraph", "@playwright/test"], projectDir);
+        if (installCode !== 0) {
+            return `npm install exited with code ${installCode} - see the output above.`;
+        }
+        status = await probeTryPrereqs(projectDir);
+        if (status.ok)
+            return null;
+        if (status.missing === "unknown")
+            return `couldn't verify prerequisites:\n${status.detail}`;
+    }
+    // Only the browser can still be missing at this point.
+    console.log("waygraph try: downloading Playwright's chromium browser ...");
+    const localPlaywrightBin = join(projectDir, "node_modules", ".bin", "playwright");
+    const browserCode = existsSync(localPlaywrightBin)
+        ? await runInherited(localPlaywrightBin, ["install", "chromium"], projectDir)
+        : await runInherited("npx", ["--yes", "playwright", "install", "chromium"], projectDir);
+    if (browserCode !== 0) {
+        return `"playwright install chromium" exited with code ${browserCode} - see the output above.`;
+    }
+    status = await probeTryPrereqs(projectDir);
+    if (status.ok)
+        return null;
+    return status.detail ?? "prerequisites still aren't ready after attempting to install them.";
+}
 async function runTry(projectDir) {
-    const problem = await checkTryPrereqs(projectDir);
+    const problem = await ensureTryPrereqs(projectDir);
     if (problem) {
-        console.error(`waygraph try: not ready yet.\n${problem}`);
+        console.error(`waygraph try: couldn't get ready.\n${problem}`);
         process.exitCode = 1;
         return;
     }
@@ -2208,16 +2259,20 @@ Usage:
   waygraph run <flow> [project]   Run a named flow
   waygraph chain <spec> [project] Run one or more Blocks by name, ad hoc
   waygraph check   [project]      Warn about navigation outside a NavBlock
-  waygraph try     [project]      Quickstart showcase - no setup beyond
-                                  "waygraph" + "@playwright/test" installed
-                                  in [project] (default: cwd) and its
-                                  chromium browser downloaded. Checks both
-                                  for real (a real launch+close, not a
-                                  guess) and tells you exactly what to run
-                                  if either's missing, instead of a raw
-                                  Playwright stack trace. If ready, copies a
-                                  small real Flow (nav/action Blocks, Trait
-                                  verify, narrate()) into
+  waygraph try     [project]      One-shot quickstart showcase - genuinely
+                                  "npx waygraph try", no separate init step.
+                                  Checks (a real launch+close, not a guess)
+                                  whether "waygraph" + "@playwright/test"
+                                  resolve from [project] (default: cwd) and
+                                  its chromium browser is downloaded; if
+                                  anything's missing, installs it right
+                                  there (writes a minimal package.json if
+                                  [project] doesn't have one yet, then
+                                  npm install, then the browser download),
+                                  real output visible the whole time. Once
+                                  ready, copies a small real Flow
+                                  (nav/action Blocks, Trait verify,
+                                  narrate()) into
                                   [project]/.waygraph-quickstart/ and runs
                                   it in step mode against a public demo
                                   site - then prints the absolute path to

package/dist/engine.d.ts

@@ -444,31 +444,59 @@ export declare function defineBlock<In extends Checkpoint<string>, Out extends C
  */
 export type NavBlock<Out extends Checkpoint<string>> = DefinedBlock<Checkpoint<string>, Out>;
 /**
- * Builds a {@link NavBlock}. `url` accepts a plain string or a function
- * `(mem) => string` for parameterized routes (e.g. `/dashboard/requests/:id`
- * with a real id read from mem). `checkpoint` is the tag this NavBlock
+ * `defineNavBlock`'s own options - exactly one of `url`/`click` required,
+ * enforced at compile time (giving both, or neither, is a type error - see
+ * `typecheck/nav-block.types.ts`). `checkpoint` is the tag this NavBlock
  * resolves to once navigation completes - a NavBlock never branches on
  * observed evidence the way a regular Block can, so there's no `resolve`
  * logic to author; it always just declares "arrived."
- *
- * The generated `act()` is always exactly `page.goto(url)` - never anything
- * else, never author-supplied. Callers get a real `Page` here internally
- * (the one legitimate place navigation belongs); `defineBlock`'s own
- * `ActionPage` narrowing is what discourages navigation everywhere else,
- * and never applies to this generated function since no author ever writes
- * it by hand.
- * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
- * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
  */
-export declare function defineNavBlock<Out extends Checkpoint<string>>(options: {
+export type NavBlockOptions<Out extends Checkpoint<string>> = {
     name: string;
     description?: string;
     checkpoint: Out["__state"];
-    url: string | ((mem: MemPage) => string);
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
-}): NavBlock<Out>;
+} & ({
+    /**
+     * Direct URL navigation. Accepts a plain string or a function
+     * `(mem) => string` for parameterized routes (e.g.
+     * `/dashboard/requests/:id` with a real id read from mem). The
+     * escape hatch for the few real cases with no click path to get
+     * there (a deep link from an email, a public share link) - not for
+     * skipping past navigation an agent didn't feel like finding. Prefer
+     * `click` whenever the target app actually has one.
+     */
+    url: string | ((mem: MemPage) => string);
+    click?: never;
+} | {
+    /**
+     * Navigates by clicking a real element already on the page (a nav
+     * link, a sidebar item) instead of teleporting straight to a URL -
+     * the opinionated default. Accepts a Playwright selector string, or
+     * a function `(mem) => selector` for a target that depends on mem
+     * (e.g. clicking the row for a specific id). Verifying arrival is
+     * `verify`'s job (typically `Trait.url(...)`), same as a `url`-based
+     * NavBlock - the click itself is only ever awaited for its own
+     * completion, not for whatever navigation it triggers.
+     */
+    click: string | ((mem: MemPage) => string);
+    url?: never;
+});
+/**
+ * Builds a {@link NavBlock}. The generated `act()` is always exactly
+ * `page.goto(url)` or `page.locator(click).click()` - never anything else,
+ * never author-supplied. Callers get a real `Page` here internally (the one
+ * legitimate place navigation belongs); `defineBlock`'s own `ActionPage`
+ * narrowing is what discourages navigation everywhere else, and never
+ * applies to this generated function since no author ever writes it by
+ * hand.
+ * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
+ * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
+ * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ */
+export declare function defineNavBlock<Out extends Checkpoint<string>>(options: NavBlockOptions<Out>): NavBlock<Out>;
 /**
  * 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

@@ -609,21 +609,16 @@ export function defineBlock(base) {
     };
 }
 /**
- * Builds a {@link NavBlock}. `url` accepts a plain string or a function
- * `(mem) => string` for parameterized routes (e.g. `/dashboard/requests/:id`
- * with a real id read from mem). `checkpoint` is the tag this NavBlock
- * resolves to once navigation completes - a NavBlock never branches on
- * observed evidence the way a regular Block can, so there's no `resolve`
- * logic to author; it always just declares "arrived."
- *
- * The generated `act()` is always exactly `page.goto(url)` - never anything
- * else, never author-supplied. Callers get a real `Page` here internally
- * (the one legitimate place navigation belongs); `defineBlock`'s own
- * `ActionPage` narrowing is what discourages navigation everywhere else,
- * and never applies to this generated function since no author ever writes
- * it by hand.
+ * Builds a {@link NavBlock}. The generated `act()` is always exactly
+ * `page.goto(url)` or `page.locator(click).click()` - never anything else,
+ * never author-supplied. Callers get a real `Page` here internally (the one
+ * legitimate place navigation belongs); `defineBlock`'s own `ActionPage`
+ * narrowing is what discourages navigation everywhere else, and never
+ * applies to this generated function since no author ever writes it by
+ * hand.
  * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
  * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
+ * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
  */
 export function defineNavBlock(options) {
     const built = defineBlock({
@@ -632,8 +627,14 @@ export function defineNavBlock(options) {
         ...(options.requires ? { requires: options.requires } : {}),
         instruction: {
             async act(page, _input, mem) {
-                const url = typeof options.url === "function" ? options.url(mem) : options.url;
-                await page.goto(url);
+                if (options.url !== undefined) {
+                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
+                    await page.goto(url);
+                }
+                else {
+                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
+                    await page.locator(selector).click();
+                }
             },
             resolve: () => checkpoint(options.checkpoint),
             ...(options.verify ? { verify: options.verify } : {}),

package/dist/index.d.ts

@@ -3,5 +3,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 type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions } from "./engine.js";
 export type { ActionPage } from "./types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",