waygraph 0.0.1 → 0.2.0

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserContext } from "@playwright/test";
+import type { BrowserContext, Page } from "@playwright/test";
 import type { Block, Checkpoint, Instruction, DefinedBlock } from "./types.js";
 import { MemPage } from "./mem-page.js";
 import type { Trait } from "./trait.js";
@@ -29,7 +29,45 @@ export declare function preflight(mem: MemPage, block: Block<any, any>): void;
  * reachable outcome by construction (as with a `defineFlow`-built Flow, which has
  * no routing at all) - there is nothing to validate against.
  */
-export declare function runGraph<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, terminals: ReadonlySet<string> | undefined, context: BrowserContext, mem: MemPage, maxSteps?: number): Promise<TOut>;
+export declare function runGraph<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, terminals: ReadonlySet<string> | undefined, context: BrowserContext, mem: MemPage, maxSteps?: number, options?: RunGraphOptions): Promise<TOut>;
+/** Options for `runGraph`'s trailing `options` arg and for {@link Flow.run}'s `options` overload. */
+export interface RunGraphOptions {
+    /**
+     * Drive this already-open page instead of opening a new one via
+     * `context.newPage()`. Lets a run continue on a tab the caller already
+     * has open (e.g. one that's already logged in), instead of every run
+     * being forced to start its own fresh tab and lose access to whatever was
+     * already there.
+     */
+    page?: Page;
+    /**
+     * `Flow.run` defaults this to `true` only when it opened the page itself
+     * (no `page` given) - matching every call from before this option
+     * existed. If you pass your own `page`, it defaults to `false` instead:
+     * a page you opened is yours to close, not this run's to close out from
+     * under you. Either way an explicit value here always wins. `runGraph`
+     * itself has no such page-aware default (its caller already decided
+     * `page` and `closeOnFinish` together) - it just does what you ask.
+     */
+    closeOnFinish?: boolean;
+}
+/**
+ * Drives a genuinely separate second tab through its own Block/Flow, in the
+ * same browser context an existing `page` already belongs to - the primitive
+ * `observe()` is specifically allowed to reach for (see {@link Instruction.observe}),
+ * since `act`/`resolve` can't touch `page.context()` at all. A thin, named
+ * wrapper around `runGraph` (which already opens its own page from whatever
+ * context it's given) rather than a new mechanism - the point is making the
+ * pattern discoverable and giving it a real name, not inventing new tab-lifecycle
+ * logic. The spawned tab is closed (by `runGraph`'s own `finally`) before this
+ * resolves; the original `page` is never touched.
+ * @example
+ * async observe(page, mem) {
+ *   const receipt = await spawnTab(EmailReceiptFlow, page, mem);
+ *   mem.set(ReceiptCode, receipt.__state);
+ * }
+ */
+export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, page: Page, mem: MemPage, maxSteps?: number): Promise<TOut>;
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export declare const start: unique symbol;
 export declare const end: unique symbol;
@@ -67,8 +105,53 @@ type EndMarker = typeof end;
  * each call, so it's still correct after a patch too. Returns a new Flow -
  * the original is untouched, same as every other decorator in this module.
  */
+/**
+ * One Block's identity as exposed by graph introspection - {@link Flow.blocks},
+ * {@link ComposedBlock.steps} - without needing to execute anything. Does not
+ * include the Block's literal Checkpoint `In`/`Out` tags: those are TypeScript
+ * literal types, erased at runtime, and can only be recovered by a build-time
+ * static-analysis tool reading the source's own type annotations - see the
+ * `graph-visualization` openspec change for that piece.
+ */
+export interface BlockInfo {
+    name: string;
+    /** `branch()`'s routing table, if this Block has one - see {@link Block.routes}. */
+    routes?: Readonly<Record<string, string | null>>;
+    /**
+     * The actual Block, re-runnable on its own via
+     * `engine.defineFlow([start, info.block, end])` - e.g. step-through
+     * tooling that runs a Flow's Blocks one at a time. Introspection that only
+     * wants to read the shape (a visualizer) can ignore this and use `name`/
+     * `routes` alone.
+     */
+    block: Block<any, any>;
+}
 export interface Flow<Out extends Checkpoint<string>> {
+    /**
+     * This Flow's constituent Blocks, in order between `start`/`end`, as plain
+     * data - for introspection/visualization tools, without running anything.
+     * @example loginFlow.blocks() // [{ name: "login" }, { name: "add-to-cart", routes: {...} }]
+     */
+    blocks(): readonly BlockInfo[];
     run(context: BrowserContext, mem: MemPage): Promise<Out>;
+    /**
+     * `options.closeOnFinish: false` hands the driven page back instead of
+     * closing it - use this overload (a literal `false`, not a `boolean`) to
+     * get the `{ result, page }` shape typed correctly.
+     * @example const { result, page } = await loginFlow.run(context, mem, { closeOnFinish: false });
+     */
+    run(context: BrowserContext, mem: MemPage, options: RunGraphOptions & {
+        closeOnFinish: false;
+    }): Promise<{
+        result: Out;
+        page: Page;
+    }>;
+    /**
+     * `options.page` drives that already-open page instead of opening a new
+     * one - see {@link RunGraphOptions}.
+     * @example await loginFlow.run(context, mem, { page: existingPage });
+     */
+    run(context: BrowserContext, mem: MemPage, options?: RunGraphOptions): Promise<Out>;
     run(mem: MemPage, config?: EngineConfig): Promise<Out>;
     /**
      * Replaces the given Block's whole verify list, wherever it sits in this
@@ -87,6 +170,56 @@ export interface Flow<Out extends Checkpoint<string>> {
      */
     modBlockVerify(block: Block<any, any> | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): Flow<Out>;
 }
+/**
+ * A Block guaranteed to have `withStepVerify`/`modStepVerify` attached - what
+ * {@link composeBlock} returns. Extends plain `Block`, so it drops straight into
+ * `defineFlow([start, ..., composed, ..., end])` like any other Block; no special
+ * casing needed anywhere that only expects a `Block`.
+ */
+export interface ComposedBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> extends Block<In, Out> {
+    /**
+     * This composed Block's constituent steps, in order, as plain data - same
+     * shape and purpose as {@link Flow.blocks}.
+     * @example GovFormBlock.steps() // [{ name: "step-1-name" }, { name: "step-2-address" }, ...]
+     */
+    steps(): readonly BlockInfo[];
+    /**
+     * Replaces one step's whole verify list, wherever it sits in this composed
+     * Block - same rules as {@link withVerify}. Throws if no step matches.
+     * @example GovFormBlock.withStepVerify("step-2-address", [])
+     */
+    withStepVerify(step: Block<any, any> | string | number, verify: Trait[] | ((out: any) => Trait[])): ComposedBlock<In, Out>;
+    /**
+     * Replaces one Trait inside one step's verify list - same rules as
+     * {@link modVerify}. Throws if no step matches, or that step has no verify
+     * trait at the given name/index.
+     * @example GovFormBlock.modStepVerify("step-2-address", "zip-visible", Trait.visible("#zip-confirmed"))
+     */
+    modStepVerify(step: Block<any, any> | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): ComposedBlock<In, Out>;
+}
+/**
+ * Chains several Blocks into one named, exported unit - what a naturally
+ * multi-step feature (a stepper form with several pages, say) wants instead of
+ * either one giant Block with no per-step confirmation, or several separately
+ * exported Blocks the caller has to wire together by hand every time. Each
+ * step keeps its own real `act`/`resolve`/`verify`, chained the same way
+ * `connect()` already chains any two Blocks - `composeBlock` is not a new
+ * execution mechanism, just `connect()` reduced over the list plus a name and
+ * the same step-list closure `Flow` already keeps for its own Block list, so
+ * `withStepVerify`/`modStepVerify` can patch one step from outside without the
+ * caller needing to hand-rebuild the chain. Resolution is by `.name`, not
+ * object identity, so a step reference stays valid even after an earlier patch
+ * swapped that slot for a new object - see {@link Flow.withBlockVerify} for
+ * the identical guarantee one level up. Each call returns a new composed
+ * Block; the original is untouched.
+ * @example composeBlock("gov-form", [step1, step2, step3, step4])
+ */
+export declare function composeBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, F>, Block<F, Out>]): ComposedBlock<In, Out>;
 /** Configures how an Engine launches its own browser - only used by `Flow.run(mem)` (no context given); ignored by `Flow.run(context, mem)`, since that context is already launched. */
 export interface EngineConfig {
     /** Default `true`, matching Playwright's own default. */
@@ -169,6 +302,7 @@ export declare function defineBlock<In extends Checkpoint<string>, Out extends C
     instruction: Instruction<In, Out, any>;
     next?: Block<In, Out>["next"];
     requires?: Block<In, Out>["requires"];
+    routes?: Block<In, Out>["routes"];
 }): DefinedBlock<In, Out>;
 /**
  * Returns a new Block that runs exactly like `block` - same act/observe/resolve,

package/dist/engine.js

@@ -37,9 +37,10 @@ export function preflight(mem, block) {
  * reachable outcome by construction (as with a `defineFlow`-built Flow, which has
  * no routing at all) - there is nothing to validate against.
  */
-export async function runGraph(entry, terminals, context, mem, maxSteps = 5000) {
+export async function runGraph(entry, terminals, context, mem, maxSteps = 5000, options) {
     preflight(mem, entry);
-    const page = await context.newPage();
+    const page = options?.page ?? (await context.newPage());
+    const closeOnFinish = options?.closeOnFinish ?? true;
     try {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let current = entry;
@@ -67,9 +68,30 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000)
         }
     }
     finally {
-        await page.close();
+        if (closeOnFinish) {
+            await page.close();
+        }
     }
 }
+/**
+ * Drives a genuinely separate second tab through its own Block/Flow, in the
+ * same browser context an existing `page` already belongs to - the primitive
+ * `observe()` is specifically allowed to reach for (see {@link Instruction.observe}),
+ * since `act`/`resolve` can't touch `page.context()` at all. A thin, named
+ * wrapper around `runGraph` (which already opens its own page from whatever
+ * context it's given) rather than a new mechanism - the point is making the
+ * pattern discoverable and giving it a real name, not inventing new tab-lifecycle
+ * logic. The spawned tab is closed (by `runGraph`'s own `finally`) before this
+ * resolves; the original `page` is never touched.
+ * @example
+ * async observe(page, mem) {
+ *   const receipt = await spawnTab(EmailReceiptFlow, page, mem);
+ *   mem.set(ReceiptCode, receipt.__state);
+ * }
+ */
+export async function spawnTab(entry, page, mem, maxSteps = 5000) {
+    return runGraph(entry, undefined, page.context(), mem, maxSteps);
+}
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export const start = Symbol("waygraph.start");
 export const end = Symbol("waygraph.end");
@@ -89,31 +111,77 @@ function findBlockIndex(middle, block) {
 }
 function buildFlow(middle, engineConfig) {
     const chain = middle.reduce((a, b) => connect(a, b));
-    return {
-        async run(contextOrMem, memOrConfig) {
-            if (contextOrMem instanceof MemPage) {
-                const mem = contextOrMem;
-                const config = { ...engineConfig, ...memOrConfig };
-                // Checked again inside runGraph too, but doing it here first means a
-                // missing key fails before a browser process even launches, not just
-                // before a page opens - the same "fail loud, cheaply" guarantee
-                // run(context, mem) already has via an existing context.
-                preflight(mem, chain);
-                const launch = LAUNCHERS[config.browserName ?? "chromium"];
-                const browser = await launch.launch({
-                    headless: config.headless ?? true,
-                    ...(config.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-                });
-                try {
-                    const context = await browser.newContext();
-                    return await runGraph(chain, undefined, context, mem);
-                }
-                finally {
-                    await browser.close();
-                }
+    // Declared separately (not as the object-literal method below) so the
+    // three-overload `Flow.run` signature can be checked against the actual
+    // per-call-shape behavior, then attached with a cast - object-literal
+    // methods can't satisfy TS's per-overload implementation check the way a
+    // standalone function assigned to the property can.
+    const run = async function run(contextOrMem, memOrConfig, options) {
+        if (contextOrMem instanceof MemPage) {
+            const mem = contextOrMem;
+            const config = { ...engineConfig, ...memOrConfig };
+            // Checked again inside runGraph too, but doing it here first means a
+            // missing key fails before a browser process even launches, not just
+            // before a page opens - the same "fail loud, cheaply" guarantee
+            // run(context, mem) already has via an existing context.
+            preflight(mem, chain);
+            const browserName = config.browserName ?? "chromium";
+            const launch = LAUNCHERS[browserName];
+            // 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
+            // Firefox/WebKit one), and a no-op default anywhere that env var isn't set.
+            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
+            const browser = await launch.launch({
+                headless: config.headless ?? true,
+                ...(config.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+                ...(executablePath ? { executablePath } : {}),
+            });
+            try {
+                const context = await browser.newContext();
+                return await runGraph(chain, undefined, context, mem);
             }
-            return runGraph(chain, undefined, contextOrMem, memOrConfig);
-        },
+            finally {
+                await browser.close();
+            }
+        }
+        const context = contextOrMem;
+        const mem = memOrConfig;
+        // Open (or reuse) the page here, not inside runGraph, so this method -
+        // not runGraph - decides whether to close it once the run is over; the
+        // page reference has to survive past runGraph's own return either way.
+        const gotOwnPage = options?.page === undefined;
+        const page = options?.page ?? (await context.newPage());
+        // Defaulting close-on-finish to `true` unconditionally would close a
+        // page the *caller* opened and handed in via `options.page` - the exact
+        // thing this option exists to let a caller keep driving. Only default to
+        // closing when this call opened the page itself (no `options.page`
+        // given), which is the one case that matches every `run(context, mem)`
+        // call from before this option existed. An explicit `closeOnFinish`
+        // always wins either way.
+        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
+        const result = await runGraph(chain, undefined, context, mem, 5000, {
+            page,
+            closeOnFinish: false,
+        });
+        if (closeOnFinish) {
+            await page.close();
+        }
+        // The return *shape* only changes on an explicit `closeOnFinish: false`
+        // (the literal the `{ result, page }` overload is typed against) - not
+        // on the computed `closeOnFinish` default above. A caller who passed
+        // their own `page` and left `closeOnFinish` unset already holds that
+        // page reference; handing it back again in a different return shape
+        // would silently break the plain-`Out` overload their call actually
+        // matched at the type level.
+        if (options?.closeOnFinish === false) {
+            return { result, page };
+        }
+        return result;
+    };
+    return {
+        blocks: () => middle.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
+        run: run,
         withBlockVerify(block, verify) {
             const index = findBlockIndex(middle, block);
             const patched = [...middle];
@@ -128,6 +196,29 @@ function buildFlow(middle, engineConfig) {
         },
     };
 }
+export function composeBlock(name, steps) {
+    if (steps.length === 0) {
+        throw new Error(`composeBlock: "${name}" needs at least one step`);
+    }
+    const chain = steps.reduce((a, b) => connect(a, b));
+    return {
+        ...chain,
+        name,
+        steps: () => steps.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
+        withStepVerify(step, verify) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = withVerify(steps[index], verify);
+            return composeBlock(name, patched);
+        },
+        modStepVerify(step, nameOrIndex, newCheck) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = modVerify(steps[index], nameOrIndex, newCheck);
+            return composeBlock(name, patched);
+        },
+    };
+}
 /**
  * Holds engine-level configuration shared across every flow defined from it -
  * for now, just how to launch a browser when a Flow owns its own
@@ -160,6 +251,10 @@ export function branch(block, routes) {
     const base = stripMethods(block);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let routed;
+    const routesAsData = {};
+    for (const [tag, target] of Object.entries(routes)) {
+        routesAsData[tag] = target === null ? null : target === block ? base.name : target.name;
+    }
     routed = defineBlock({
         ...base,
         next: (checkpoint) => {
@@ -171,6 +266,7 @@ export function branch(block, routes) {
             // the routed Block, not the original with no `next` of its own.
             return target === block ? routed : target;
         },
+        routes: routesAsData,
     });
     return routed;
 }
@@ -190,6 +286,7 @@ function stripMethods(block) {
         instruction: block.instruction,
         ...(block.next ? { next: block.next } : {}),
         ...(block.requires ? { requires: block.requires } : {}),
+        ...(block.routes ? { routes: block.routes } : {}),
     };
 }
 /**
@@ -207,6 +304,7 @@ export function defineBlock(base) {
         instruction: base.instruction,
         ...(base.next ? { next: base.next } : {}),
         ...(base.requires ? { requires: base.requires } : {}),
+        ...(base.routes ? { routes: base.routes } : {}),
     };
     return {
         ...plain,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export type { Checkpoint, Instruction, Block, DefinedBlock } from "./types.js";
+export type { Checkpoint, Instruction, Block, DefinedBlock, Start } from "./types.js";
 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, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, preflight, } from "./engine.js";
-export type { Flow, EngineConfig } from "./engine.js";
+export { runGraph, spawnTab, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, composeBlock, preflight, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo } from "./engine.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, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, preflight, } from "./engine.js";
+export { runGraph, spawnTab, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, composeBlock, preflight, } from "./engine.js";

package/dist/types.d.ts

@@ -13,6 +13,16 @@ export type Checkpoint<Tag extends string> = {
  * @example resolve: () => checkpoint("LoggedIn")
  */
 export declare function checkpoint<Tag extends string>(tag: Tag): Checkpoint<Tag>;
+/**
+ * The type every entry Block's `In` must be - `runGraph` always seeds a fresh
+ * run with `checkpoint("__start__")` as the fake initial input, so a Block
+ * meant to lead off a Flow needs exactly this type. Exported so no project
+ * has to know or hand-type the `"__start__"` literal itself - the same reason
+ * `checkpoint()` exists instead of every call site spelling `{ __state: tag }`
+ * by hand.
+ * @example export const LoginBlock: Block<Start, LoggedIn> = { ... }
+ */
+export type Start = Checkpoint<"__start__">;
 /**
  * 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
@@ -69,6 +79,18 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * self-loop - see `runGraph`'s `maxSteps` for the safety net that needs.
      */
     next?(checkpoint: Out): Block<any, any> | null | undefined;
+    /**
+     * `branch()`'s routing table as plain, readable data - Checkpoint tag ->
+     * target Block's `.name` (`null` for a terminal tag) - alongside {@link next}
+     * itself, which stays the actual runtime dispatch. `next` is an opaque
+     * closure a graph-introspection tool can't read; this is `next`'s own
+     * routing decisions exposed as data instead, purely additive and never
+     * consulted by `runGraph`/`connect` - it exists only for tools like
+     * `Flow`'s inspection method (and, eventually, `toMermaid`) to walk without
+     * executing anything. A route back to the Block itself (a self-loop) maps
+     * to that same Block's own name, not `null`.
+     */
+    routes?: Readonly<Record<string, string | null>>;
     /**
      * MemKeys this Block's `act` reads from `mem` and needs already set.
      * Declaring it lets {@link preflight} (built into `runGraph`) catch a missing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",
@@ -11,8 +11,12 @@
       "default": "./dist/index.js"
     }
   },
+  "bin": {
+    "waygraph": "bin/waygraph"
+  },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "repository": {
     "type": "git",
@@ -26,6 +30,9 @@
   "peerDependencies": {
     "@playwright/test": "^1.40.0"
   },
+  "dependencies": {
+    "tsx": "^4.0.0"
+  },
   "devDependencies": {
     "@playwright/test": "^1.55.0",
     "@types/node": "^26.0.0",