waygraph 0.4.0 → 0.5.0

package/README.md

@@ -6,6 +6,9 @@ flat pile of ad hoc helper functions.
 This repo is the `waygraph` npm package itself. Consumer projects proving it against real
 sites/apps (saucedemo.com, zsign-app) live in the sibling `projects_waygraph/` repo, not here.
 
+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.
+
 ## Install
 
 ```bash
@@ -100,6 +103,22 @@ 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
+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
+editor shows navigation struck through the instant it's typed in a regular Block, pointing
+at `defineNavBlock` - nothing is blocked, no build ever fails, existing code that already
+navigates from a regular Block keeps compiling and running unchanged. `waygraph check
+[project]` is the complementary whole-project sweep for contexts with no editor watching
+(CI, generated code) - same warning, on demand, across every `*.block.ts` file at once.
+`new Engine({ browsers: { chromium, firefox, webkit } })` overrides which `BrowserType`
+actually launches for a `mem`-only run, per browser name - waygraph is deliberately "just
+an opinionated Playwright," so a stealth-patched or otherwise customized launcher (e.g.
+`playwright-extra` plus a stealth plugin) drops in unmodified, since those already expose
+the same `.launch()` shape as Playwright's own `chromium`/`firefox`/`webkit`.
 
 ```bash
 npx create-waygraph my-project && cd my-project && npm install && npm test

package/dist/cli.js

@@ -1687,6 +1687,64 @@ async function validateFlows(projectDir) {
     return results;
 }
 // ---------------------------------------------------------------------------
+// `check` - secondary/complementary to the ActionPage @deprecated warning
+// (src/types.ts). That's the primary, always-on signal an editor shows the
+// instant a regular Block's act() calls a navigation method; this command
+// sweeps a whole project in one shot for contexts with no editor watching
+// (CI, an autonomous agent writing Block files without a language server).
+// See openspec/changes/nav-block-and-check/ for the full rationale.
+// ---------------------------------------------------------------------------
+function discoverBlocks(projectDir) {
+    return walkDir(projectDir, /\.block\.ts$/);
+}
+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";
+}
+const NAV_METHOD_CALLS = ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
+/**
+ * Walks every `*.block.ts` file under `projectDir`, imports each to find its
+ * exported Blocks, and for any Block NOT built via `defineNavBlock`, scans
+ * that file's own source text for a navigation call. Warning only - never
+ * throws, never changes the caller's exit code on its own account (a Block
+ * file that fails to import for unrelated reasons is silently skipped here;
+ * `validate` is the command that reports import failures).
+ */
+async function checkCommand(projectDir) {
+    const files = discoverBlocks(projectDir);
+    const warnings = [];
+    for (const file of files) {
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch {
+            continue;
+        }
+        let src;
+        for (const [exportName, exported] of Object.entries(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            if (isNavBlockMarked(exported))
+                continue;
+            src ??= readFileSync(file, "utf-8");
+            if (NAV_METHOD_CALLS.some((needle) => src.includes(needle))) {
+                warnings.push({ file, blockName: exported.name, exportName });
+            }
+        }
+    }
+    return warnings;
+}
+// ---------------------------------------------------------------------------
 // `run`
 // ---------------------------------------------------------------------------
 async function runFlow(projectDir, flowName) {
@@ -1725,6 +1783,13 @@ 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 check   [project]      Warn about navigation outside a NavBlock
+
+    "check" is a secondary sweep, complementary to the always-on TypeScript
+    warning every regular Block's act() already gets (a struck-through
+    page.goto/reload/goBack/goForward, pointing at defineNavBlock) - useful
+    where nothing is watching in an editor (CI, generated code). Warning
+    only, never fails - see openspec/changes/nav-block-and-check/.
 
     "chain" needs no .flow.ts file - reference Blocks (by their own
     runtime .name, or their export identifier) straight from the command
@@ -1844,6 +1909,23 @@ async function main() {
             await runChain(proj, spec);
             break;
         }
+        case "check": {
+            const proj = resolve(args[1] ?? process.cwd());
+            const warnings = await checkCommand(proj);
+            if (warnings.length === 0) {
+                console.log(`waygraph check: no navigation found outside NavBlocks under ${proj}`);
+            }
+            else {
+                for (const w of warnings) {
+                    const rel = relative(proj, w.file);
+                    console.warn(`waygraph check: ${rel} (${w.blockName}) calls page.goto/reload/goBack/goForward outside a NavBlock - consider defineNavBlock instead`);
+                }
+                console.log(`waygraph check: ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`);
+            }
+            // Warning only - never fails the command, matching the spec's
+            // "never a build failure" requirement.
+            break;
+        }
         default:
             console.error(`waygraph: unknown command "${command}"`);
             process.exit(1);

package/dist/engine.d.ts

@@ -1,6 +1,7 @@
-import type { BrowserContext, Page, Locator } from "@playwright/test";
-import type { Block, Checkpoint, Instruction, DefinedBlock } from "./types.js";
+import type { BrowserContext, BrowserType, Page, Locator } from "@playwright/test";
+import type { Block, Checkpoint, Instruction, DefinedBlock, ActionPage, WaygraphHighlight } from "./types.js";
 import { MemPage } from "./mem-page.js";
+import type { MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
@@ -313,6 +314,18 @@ export interface EngineConfig {
     browserName?: "chromium" | "firefox" | "webkit";
     /** Milliseconds Playwright pauses before each operation - for watching a non-headless run with your own eyes, not for real runs. Default `0`. */
     slowMo?: number;
+    /**
+     * Overrides which `BrowserType` actually launches, per browser name -
+     * default is the real `@playwright/test` export for whichever one
+     * `browserName` picks. Accepts anything shaped like Playwright's own
+     * `chromium`/`firefox`/`webkit` (same `.launch()` signature) - a
+     * stealth-patched or otherwise customized launcher (e.g. `playwright-extra`
+     * plus a stealth plugin) drops in here unmodified. Puppeteer is a
+     * different `Page`/`BrowserContext` shape entirely and isn't supported by
+     * this seam.
+     * @example new Engine({ browsers: { chromium: stealthChromium } })
+     */
+    browsers?: Partial<Record<"chromium" | "firefox" | "webkit", BrowserType>>;
 }
 type S = Checkpoint<"__start__">;
 /**
@@ -385,11 +398,48 @@ export declare function branch<In extends Checkpoint<string>, Out extends Checkp
 export declare function defineBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: {
     name: string;
     description?: Block<In, Out>["description"];
-    instruction: Instruction<In, Out, any>;
+    instruction: Omit<Instruction<In, Out, any>, "act"> & {
+        act(page: ActionPage, input: In, mem: MemPage): Promise<void>;
+    };
     next?: Block<In, Out>["next"];
     requires?: Block<In, Out>["requires"];
     routes?: Block<In, Out>["routes"];
 }): DefinedBlock<In, Out>;
+/**
+ * A Block whose only possible action is navigating to a URL - built via
+ * {@link defineNavBlock}, never with a hand-authored `act()`. Extends `Block`
+ * (same shape `DefinedBlock`/`ComposedBlock` already use), so it drops into
+ * `defineFlow([...])`, `connect()`, `composeBlock()` exactly like any other
+ * Block - no special-casing needed anywhere that only expects a `Block`.
+ * See `openspec/changes/nav-block-and-check/` for why this exists.
+ */
+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
+ * 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: {
+    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>;
 /**
  * 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

@@ -3,6 +3,20 @@ import { connect, checkpoint } from "./types.js";
 import { MemPage } from "./mem-page.js";
 import { runVerify } from "./trait.js";
 const LAUNCHERS = { chromium, firefox, webkit };
+/**
+ * Resolves which `BrowserType` actually launches for a `mem`-only run (no
+ * caller-supplied context) - `config.browsers[browserName]` if given,
+ * otherwise the real `@playwright/test` export. Waygraph is deliberately
+ * "just an opinionated Playwright" - it doesn't own browser automation
+ * itself, so it shouldn't force every consumer onto the vanilla launcher.
+ * A stealth-patched or otherwise customized launcher (e.g. `playwright-extra`
+ * plus a stealth plugin) is a drop-in replacement for `chromium`/`firefox`/
+ * `webkit` - same `.launch()` shape - so accepting one here costs nothing for
+ * a consumer who never sets it.
+ */
+function resolveLauncher(browserName, config) {
+    return config?.browsers?.[browserName] ?? LAUNCHERS[browserName];
+}
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
@@ -218,7 +232,7 @@ function buildFlow(middle, engineConfig) {
             // run(context, mem) already has via an existing context.
             preflight(mem, chain);
             const browserName = config.browserName ?? "chromium";
-            const launch = LAUNCHERS[browserName];
+            const launch = resolveLauncher(browserName, config);
             // If CHROME_PATH/CHROMIUM_PATH is set in the environment (e.g. a system
             // or Flatpak Chromium), launch that instead of Playwright's own bundled
             // binary - only for chromium (the env var names a Chromium build, not a
@@ -391,7 +405,7 @@ export function chainFlow(...flows) {
             // the point of sequencing them (a fresh browser is itself a full
             // session reset, silently making withSessionReset a no-op).
             const browserName = config?.browserName ?? "chromium";
-            const launch = LAUNCHERS[browserName];
+            const launch = resolveLauncher(browserName, config);
             const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
             const browser = await launch.launch({
                 headless: config?.headless ?? true,
@@ -568,6 +582,50 @@ export function defineBlock(base) {
         modVerifyAll: (patches) => modVerifyAll(plain, patches),
     };
 }
+/**
+ * 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.
+ * @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 function defineNavBlock(options) {
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(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);
+            },
+            resolve: () => checkpoint(options.checkpoint),
+            ...(options.verify ? { verify: options.verify } : {}),
+            ...(options.highlights ? { highlights: options.highlights } : {}),
+        },
+    });
+    // Non-enumerable so it never shows up in Object.keys/JSON/autocomplete -
+    // purely a runtime marker `waygraph check` (or anything else walking a
+    // project's Blocks) can test for to tell a NavBlock apart from a regular
+    // one, since the TypeScript type alone (NavBlock = DefinedBlock) doesn't
+    // survive to runtime.
+    Object.defineProperty(built, "__waygraphKind", {
+        value: "nav",
+        enumerable: false,
+        configurable: false,
+    });
+    return built;
+}
 /**
  * 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/index.d.ts

@@ -2,5 +2,6 @@ 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, composeBlock, preflight, withSessionReset, withTitle, chainFlow, } from "./engine.js";
-export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, composeBlock, preflight, withSessionReset, withTitle, chainFlow, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock } from "./engine.js";
+export type { ActionPage } from "./types.js";

package/dist/index.js

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

package/dist/types.d.ts

@@ -23,6 +23,29 @@ export declare function checkpoint<Tag extends string>(tag: Tag): Checkpoint<Tag
  * @example export const LoginBlock: Block<Start, LoggedIn> = { ... }
  */
 export type Start = Checkpoint<"__start__">;
+/**
+ * The `page` a regular Block's `act()` is typed against via `defineBlock` -
+ * structurally identical to Playwright's own `Page` (the same real object is
+ * passed at runtime; this is a type-only narrowing), except `goto`, `reload`,
+ * `goBack`, and `goForward` are re-declared under `@deprecated`. Nothing is
+ * blocked - every method is still fully present and callable, and this never
+ * causes a build to fail - but a TypeScript-aware editor shows the call
+ * struck through with a hover warning the instant it's typed, pointing at
+ * `defineNavBlock` instead. `NavBlock`'s own generated `act()` (the one place
+ * navigation actually belongs) uses the real `Page`, not this type - that
+ * distinction lives entirely inside `defineNavBlock` and never reaches a
+ * NavBlock's own author, who never writes its `act()` by hand.
+ */
+export type ActionPage = Omit<Page, "goto" | "reload" | "goBack" | "goForward"> & {
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goto: Page["goto"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    reload: Page["reload"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goBack: Page["goBack"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goForward: Page["goForward"];
+};
 /**
  * The four-phase pipeline every Block runs. Most Blocks only need `act` + a
  * one-line `resolve` - add `observe` only once a Block genuinely branches, add

package/package.json

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