waygraph 0.4.0 → 0.6.0

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
@@ -169,6 +170,16 @@ export interface Flow<Out extends Checkpoint<string>> {
      * something `run()` itself uses.
      */
     readonly title?: string;
+    /**
+     * Set once this Flow has been wrapped in {@link withExpectedFailure} - a
+     * display hint for a step-through overlay: this Flow is DESIGNED to throw
+     * (e.g. a blocked user's login attempt genuinely failing), not a bug in
+     * the demo itself. `run()` never reads this - the Flow still throws
+     * exactly as it would otherwise; only the overlay's error panel reads it,
+     * to show an informational "this is the point" panel instead of an
+     * alarming one indistinguishable from a real break.
+     */
+    readonly expectedFailureReason?: string;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -236,6 +247,25 @@ export declare function withSessionReset<Out extends Checkpoint<string>>(flow: F
  * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
  */
 export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
+/**
+ * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
+ * login attempt genuinely failing, demonstrating the app's own real
+ * behavior rather than a bug in the demo. Non-destructive, same pattern as
+ * {@link withTitle}.
+ *
+ * By itself this changes nothing about how the Flow runs - it still throws
+ * exactly as it would otherwise. It's a hint a step-through overlay
+ * (waygraph's `chain --step`) reads when that throw happens, to show an
+ * informational "this is the point" panel instead of one indistinguishable
+ * from a genuine break - the distinction a demo author needs so a viewer
+ * (or the author, mid-build) can tell "the app just did what it's supposed
+ * to" apart from "something in this demo is actually broken."
+ * @example const viewerBlockedFlow = withExpectedFailure(
+ *   engine.defineFlow([start, NavLoginBlock, blockedLoginCheck, end]),
+ *   "locked_out_user can never reach /inventory.html - this is the block working as intended.",
+ * );
+ */
+export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow: Flow<Out>, reason: string): Flow<Out>;
 /**
  * Runs several complete, independent Flows one after another, reusing the
  * same page/context/mem in order - each remains its own validated
@@ -313,6 +343,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 +427,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
@@ -327,6 +341,32 @@ export function withTitle(flow, title) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
     };
 }
+/**
+ * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
+ * login attempt genuinely failing, demonstrating the app's own real
+ * behavior rather than a bug in the demo. Non-destructive, same pattern as
+ * {@link withTitle}.
+ *
+ * By itself this changes nothing about how the Flow runs - it still throws
+ * exactly as it would otherwise. It's a hint a step-through overlay
+ * (waygraph's `chain --step`) reads when that throw happens, to show an
+ * informational "this is the point" panel instead of one indistinguishable
+ * from a genuine break - the distinction a demo author needs so a viewer
+ * (or the author, mid-build) can tell "the app just did what it's supposed
+ * to" apart from "something in this demo is actually broken."
+ * @example const viewerBlockedFlow = withExpectedFailure(
+ *   engine.defineFlow([start, NavLoginBlock, blockedLoginCheck, end]),
+ *   "locked_out_user can never reach /inventory.html - this is the block working as intended.",
+ * );
+ */
+export function withExpectedFailure(flow, reason) {
+    return {
+        ...flow,
+        expectedFailureReason: reason,
+        withBlockVerify: (block, verify) => withExpectedFailure(flow.withBlockVerify(block, verify), reason),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withExpectedFailure(flow.modBlockVerify(block, nameOrIndex, newCheck), reason),
+    };
+}
 function locateInChain(flows, block) {
     if (typeof block === "number") {
         let remaining = block;
@@ -391,7 +431,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 +608,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, withExpectedFailure, 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, withExpectedFailure, 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.6.0",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",
@@ -16,7 +16,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "templates"
   ],
   "repository": {
     "type": "git",

package/templates/quickstart/src/blocks/actions/add-to-cart.action.block.ts

@@ -0,0 +1,18 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { LoggedIn, ItemInCart } from "../../states/quickstart.states.js";
+
+export const AddToCartBlock = defineBlock<LoggedIn, ItemInCart>({
+  name: "add-to-cart",
+  description: "Adds the Sauce Labs Backpack to the cart and confirms the cart badge shows 1 item.",
+  instruction: {
+    async act(page) {
+      await page.locator("#add-to-cart-sauce-labs-backpack").click();
+    },
+    resolve: () => checkpoint("ItemInCart"),
+    verify: [Trait.text(".shopping_cart_badge", "1")],
+    // Author-declared highlights - independent of verify's own pass/fail
+    // check. "Remember this" moments a step-through overlay can call out
+    // even when there's nothing to assert, just something worth pointing at.
+    highlights: () => [{ selector: ".shopping_cart_badge", label: "remember this: cart now has 1 item" }],
+  },
+});

package/templates/quickstart/src/blocks/actions/checkout-info.action.block.ts

@@ -0,0 +1,19 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { ItemInCart, CheckoutInfoFilled } from "../../states/quickstart.states.js";
+
+export const CheckoutInfoBlock = defineBlock<ItemInCart, CheckoutInfoFilled>({
+  name: "checkout-info",
+  description: "Goes to the cart, starts checkout, and fills in the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(".shopping_cart_link").click();
+      await page.locator("#checkout").click();
+      await page.locator("#first-name").fill("Ada");
+      await page.locator("#last-name").fill("Lovelace");
+      await page.locator("#postal-code").fill("1000");
+      await page.locator("#continue").click();
+    },
+    resolve: () => checkpoint("CheckoutInfoFilled"),
+    verify: [Trait.url({ pathname: "/checkout-step-two.html" })],
+  },
+});

package/templates/quickstart/src/blocks/actions/finish-order.action.block.ts

@@ -0,0 +1,18 @@
+import { defineBlock, checkpoint, Trait, narrate } from "waygraph";
+import type { CheckoutInfoFilled, OrderComplete } from "../../states/quickstart.states.js";
+
+export const FinishOrderBlock = defineBlock<CheckoutInfoFilled, OrderComplete>({
+  name: "finish-order",
+  description: "Places the order and confirms the 'Thank you for your order!' completion page.",
+  instruction: {
+    async act(page) {
+      // narrate() captions an explicit action for a step-through overlay,
+      // instead of it guessing a generic label from the element's own text.
+      const finishButton = page.locator("#finish");
+      await narrate(finishButton, "Placing the order", () => finishButton.click());
+    },
+    resolve: () => checkpoint("OrderComplete"),
+    verify: [Trait.text(".complete-header", "Thank you for your order!")],
+    highlights: () => [{ selector: ".complete-header", label: "remember this: order confirmed" }],
+  },
+});

package/templates/quickstart/src/blocks/actions/submit-login.action.block.ts

@@ -0,0 +1,22 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { LoginPage, LoggedIn } from "../../states/quickstart.states.js";
+
+// Credentials hardcoded on purpose, to keep this first look at waygraph
+// self-contained - no setup step, nothing to type before you can watch it
+// run. A real project reaches for a MemKey/keyGroup instead (see waygraph's
+// own README, or projects_waygraph/saucedemo in this same workspace) so
+// different scenarios (an Owner vs. a blocked Viewer, say) can hand a Flow
+// different credentials at run time without editing the Block itself.
+export const SubmitLoginActionBlock = defineBlock<LoginPage, LoggedIn>({
+  name: "submit-login",
+  description: "Logs a standard user into Swag Labs and confirms the inventory page loads.",
+  instruction: {
+    async act(page) {
+      await page.locator("#user-name").fill("standard_user");
+      await page.locator("#password").fill("secret_sauce");
+      await page.locator("#login-button").click();
+    },
+    resolve: () => checkpoint("LoggedIn"),
+    verify: [Trait.url({ pathname: "/inventory.html" })],
+  },
+});

package/templates/quickstart/src/blocks/nav-login.block.ts

@@ -0,0 +1,15 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { LoginPage } from "../states/quickstart.states.js";
+
+// Navigation lives in its own Block, built by defineNavBlock - its act() is
+// ALWAYS exactly page.goto(url), generated for you, never hand-written. A
+// regular defineBlock() Block that calls page.goto/reload/goBack/goForward
+// instead gets a struck-through @deprecated warning in your editor, pointing
+// back here - see waygraph's ActionPage type and `waygraph check`.
+export const NavLoginBlock = defineNavBlock<LoginPage>({
+  name: "nav-login",
+  description: "Goes to the Swag Labs login page.",
+  checkpoint: "LoginPage",
+  url: "/",
+  verify: [Trait.visible("#login-button")],
+});

package/templates/quickstart/src/flows/quickstart.flow.ts

@@ -0,0 +1,19 @@
+import { Engine, start, end, withTitle } from "waygraph";
+import { NavLoginBlock } from "../blocks/nav-login.block.js";
+import { SubmitLoginActionBlock } from "../blocks/actions/submit-login.action.block.js";
+import { AddToCartBlock } from "../blocks/actions/add-to-cart.action.block.js";
+import { CheckoutInfoBlock } from "../blocks/actions/checkout-info.action.block.js";
+import { FinishOrderBlock } from "../blocks/actions/finish-order.action.block.js";
+
+const engine = new Engine();
+
+// This is it - a whole real waygraph Flow, five Blocks wide, generated by
+// `waygraph try` but otherwise no different from a Flow you'd hand-write:
+// nav-* Blocks (defineNavBlock) navigate, action-* Blocks (defineBlock) do
+// everything else, connect() (here, defineFlow's own array form) chains
+// them into one typed graph, each Block's own Trait verify confirms it
+// actually landed where it says it did.
+export const quickstartFlow = withTitle(
+  engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, AddToCartBlock, CheckoutInfoBlock, FinishOrderBlock, end]),
+  "waygraph quickstart - swag labs demo",
+);

package/templates/quickstart/src/states/quickstart.states.ts

@@ -0,0 +1,11 @@
+import type { Checkpoint } from "waygraph";
+
+// One Checkpoint per real state the target app can be in - the whole shape
+// of this quickstart's Flow, readable in one place before you ever open a
+// Block file. `Start` is waygraph's own exported type, not redeclared here.
+
+export type LoginPage = Checkpoint<"LoginPage">;
+export type LoggedIn = Checkpoint<"LoggedIn">;
+export type ItemInCart = Checkpoint<"ItemInCart">;
+export type CheckoutInfoFilled = Checkpoint<"CheckoutInfoFilled">;
+export type OrderComplete = Checkpoint<"OrderComplete">;