waygraph 0.0.1

package/README.md

@@ -0,0 +1,143 @@
+# Waygraph
+
+A typed graph of reusable Blocks for driving a browser through E2E flows, in place of a
+flat pile of ad hoc helper functions - see
+`openspec/changes/archive/2026-08-27-core-spine/proposal.md` for the full motivation.
+
+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.
+
+**Status:** `Checkpoint`, `MemPage`, `Instruction`/`Block` (`act`/`observe`/`resolve`/`verify`),
+`connect()`, `Trait`, `Engine.defineFlow([start, ...blocks, end])`, and `branch()`/self-loops
+with a `maxSteps` safety cap. A Block's output type is the only contract the next Block can
+rely on, `resolve` is structurally incapable of touching the browser or shared memory,
+`verify` runs only after `resolve` has already decided (confirms or fails loud, never
+redirects), `branch()` attaches routing to a Block - including back to itself - without ever
+touching that Block's own phases, a Block's `requires: MemKey[]` gets checked by
+`preflight()` (built into `runGraph`) before a tab even opens - a missing credential fails
+in milliseconds, not after several real browser actions already ran - and `new Engine({ headless, browserName, slowMo })` configures a browser the Engine
+launches and owns itself: `flow.run(mem)` (no context) uses it, and `flow.run(mem, {
+...overrides })` overrides it per call - so one module-level `Flow`, imported by many
+specs, doesn't force every caller into the same settings. `flow.run(context, mem)` still
+works exactly as before and ignores all of this, since that context is already launched.
+`withVerify(block, verify)` decorates any existing Block with different confirmation - same
+`act`/`resolve`, same routing - without that Block needing to have been authored as a
+parameterized factory (`withVerify(LoginBlock, [])` is the "I only care that I navigated
+this far, no DOM check" case). Built-in Trait factories are reachable two ways - as free
+functions (`urlMatches`, `textEquals`, `visible`) or, for autocomplete discoverability,
+off `Trait.` itself (`Trait.url`, `Trait.text`, `Trait.visible` - the exact same functions,
+just findable by typing `Trait.` without needing to already know their names). `Trait.url`
+takes a structured `URLPatternInit` (`{ pathname, hostname, search, hash, ... }`, the same
+shape the standard `URLPattern` Web API takes), not a hand-written regex - whichever
+components you leave out default to "match anything," so `Trait.url({ pathname:
+"/inventory.html" })` already ignores whatever query params a hybrid SPA tacks on, with no
+separate flag needed for that. Once Blocks are composed into a `Flow`, `flow.withBlockVerify`/
+`flow.modBlockVerify` patch one Block's verify from outside - a spec that only imports the
+finished flow, addressed by the Block reference (preferred), its name, or its numeric
+position in the flow - without editing the flow's own file.
+
+Deliberately **not yet implemented** (each tracked as its own future OpenSpec change,
+building on this one):
+- Interstitials/Watchers - background overlay handling (cookie banners, popups).
+- `spawnTab` - a second browser tab.
+- A patchable way to compose several Blocks into one named unit with per-step verify
+  addressable from outside (`connect()`-composed chains don't get `withVerify`/`modVerify`
+  attached the way `defineBlock()`/`branch()`/`Flow` outputs do) - useful for a multi-step
+  form (e.g. a government form with several stepper pages) that's naturally "one feature" but
+  still wants each step's own confirmation independently overridable.
+
+## Example
+
+Two Tier-0 Blocks (only `act` + `resolve`, no branching), each confirmed with `verify`
+after the fact rather than asserting mid-`observe`, defined as a flow and run against a
+real page:
+
+```typescript
+import { Engine, start, end, MemPage, key, checkpoint } from "waygraph";
+import type { Block, Checkpoint } from "waygraph";
+
+type Start = Checkpoint<"__start__">;
+type FormLoaded = Checkpoint<"FormLoaded">;
+type Submitted = Checkpoint<"Submitted">;
+
+const EmailKey = key<string>("form.email");
+const PasswordKey = key<string>("form.password");
+
+const GotoForm: Block<Start, FormLoaded> = {
+  name: "goto-form",
+  instruction: {
+    async act(page) {
+      await page.goto("https://example.com/login");
+    },
+    resolve: () => checkpoint("FormLoaded"),
+  },
+};
+
+const FillAndSubmit: Block<FormLoaded, Submitted> = {
+  name: "fill-and-submit",
+  instruction: {
+    async act(page, _input, mem) {
+      await page.getByPlaceholder("Email").fill(mem.get(EmailKey));
+      await page.getByPlaceholder("Password").fill(mem.get(PasswordKey));
+      await page.getByRole("button", { name: "Submit" }).click();
+    },
+    resolve: () => checkpoint("Submitted"),
+    verify: [
+      {
+        name: "submitted-heading-shown",
+        check: async (page) => {
+          await page.getByRole("heading", { name: "Submitted" }).waitFor();
+          return true;
+        },
+      },
+    ],
+  },
+};
+
+const mem = new MemPage();
+mem.set(EmailKey, "alice@test.com");
+mem.set(PasswordKey, "hunter2");
+
+const engine = new Engine();
+const flow = engine.defineFlow([start, GotoForm, FillAndSubmit, end]);
+const result = await flow.run(context, mem);
+// result === { __state: "Submitted" }
+```
+
+See `tests/define-flow.spec.ts` here, and `saucedemo/tests/checkout-flow.spec.ts` in
+`projects_waygraph/` (a real 4-Block flow against the live saucedemo.com), for this running
+for real. The lower-level `connect()`/`runGraph()` still exist and are what `defineFlow`
+builds on - reach for them directly only if you need a shape `defineFlow`'s array can't
+express yet.
+
+## Commands
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm run test        # playwright test
+npm run build       # tsc -p tsconfig.build.json, emits dist/
+```
+
+## Layout
+
+```
+package.json              the "waygraph" npm package itself
+src/
+  types.ts                 Checkpoint, Instruction, Block, connect()
+  mem-page.ts               MemKey, key(), MemPage
+  trait.ts                   Trait (type + discoverable Trait.url/.text/.visible), runVerify()
+  engine.ts                   runGraph(), Engine, start, end, Flow (+ withBlockVerify/modBlockVerify)
+  index.ts                     public barrel
+typecheck/                 compile-time-only fixtures (assignability, @ts-expect-error cases)
+tests/                      runtime unit + integration tests (@playwright/test)
+tsconfig.json                base config - typecheck script includes src/ + typecheck/ + tests/
+tsconfig.build.json          extends base, src/ only, emits to dist/
+openspec/                  the OpenSpec change history for this repo (propose -> apply per change)
+```
+
+Consumer projects (saucedemo.com proof, zsign-app integration) live in the sibling
+`projects_waygraph/` repo, depending on this package via `"waygraph": "file:../../waygraph"`
+during local dev (see its own `.npmrc` - `install-links=true` is required there, or npm will
+symlink instead of copy and pull this package's own `node_modules` in through the symlink,
+causing a duplicate-Playwright-installation error).

package/dist/engine.d.ts

@@ -0,0 +1,214 @@
+import type { BrowserContext } from "@playwright/test";
+import type { Block, Checkpoint, Instruction, DefinedBlock } from "./types.js";
+import { MemPage } from "./mem-page.js";
+import type { Trait } from "./trait.js";
+/**
+ * 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
+ * composed Block, so calling this on a `defineFlow`-built Flow's entry - which
+ * `runGraph` does automatically, before opening a tab - covers every Block in
+ * that flow. It does not see Blocks only reachable through `branch()` routing,
+ * since those depend on a runtime decision that hasn't happened yet.
+ */
+export declare function preflight(mem: MemPage, block: Block<any, any>): void;
+/**
+ * Runs `entry` against a fresh tab and returns the resulting terminal Checkpoint.
+ * The engine owns the tab's lifecycle, not any individual Block: the tab is
+ * created before the first `act` runs and closed in `finally`, so it closes even
+ * if a step throws.
+ *
+ * After each Block resolves, its `next` (if any, from `branch()`) is followed to
+ * the following Block, in the same tab - a Block with no `next` runs exactly once,
+ * unchanged from before `branch()` existed. `next` returning the same Block is a
+ * self-loop; `maxSteps` bounds the loop so a routing bug fails loud instead of
+ * hanging.
+ *
+ * `terminals`, if given, is a sanity check: the Checkpoint the run stops on must be
+ * one of the tags the caller actually expects, or the run fails loud instead of
+ * silently returning an unexpected result. Omit it when there is only ever one
+ * 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>;
+/** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
+export declare const start: unique symbol;
+export declare const end: unique symbol;
+type StartMarker = typeof start;
+type EndMarker = typeof end;
+/**
+ * A composed, runnable flow. Always begins from Checkpoint<"__start__">, same as
+ * runGraph's `entry`. `run(context, mem)` uses a context you already have (the
+ * usual case inside a `@playwright/test` file, via its `context` fixture) -
+ * there's no browser for this Flow to launch, so no config to pass. `run(mem,
+ * config?)` - no context - has the Engine launch and own its own browser for
+ * this one run instead, and closes it in `finally`; use this outside a
+ * Playwright test file, or when a flow genuinely needs its own browser instance
+ * rather than sharing the test's. `config` here overrides, per key, whatever
+ * `new Engine(...)` was constructed with - so one flow (module-level, imported
+ * by many specs) can still have every run choose its own `headless`/`slowMo`
+ * rather than being stuck with whatever the flow's own file happened to set.
+ *
+ * `withBlockVerify`/`modBlockVerify` do what {@link withVerify}/{@link modVerify}
+ * do for a single Block, one level up - a spec that only imports the finished
+ * Flow (not necessarily the individual Blocks it was built from) can still
+ * patch one Block's verify for just that call, without editing the flow's own
+ * file or hand-rebuilding its Block list. Addressed the same three ways
+ * `modVerify` already addresses a Trait - the Block reference itself
+ * (`LoginBlock`, imported like any other Block; typo-proof, refactor-safe,
+ * jump-to-definition works), a plain string name, or a numeric index into this
+ * Flow's Block list (position between `start`/`end`, 0-based) for a spec that
+ * genuinely doesn't have the Block imported and doesn't want to spell its
+ * name. A reference or string resolves by `.name` under the hood (a Block's
+ * own stable identity in this codebase, same as every error message elsewhere
+ * in this file already uses) rather than object identity - it stays
+ * resolvable even after an earlier patch already swapped that slot for a new
+ * object, since the name survives every `withVerify`/`modVerify` in the
+ * chain; an index is checked fresh against this Flow's current Block list
+ * 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.
+ */
+export interface Flow<Out extends Checkpoint<string>> {
+    run(context: BrowserContext, mem: MemPage): Promise<Out>;
+    run(mem: MemPage, config?: EngineConfig): Promise<Out>;
+    /**
+     * Replaces the given Block's whole verify list, wherever it sits in this
+     * Flow - same rules as {@link withVerify}. Throws if no Block in this Flow
+     * matches.
+     * @example checkoutFlow.withBlockVerify(LoginBlock, [])
+     * @example checkoutFlow.withBlockVerify("login", [])
+     * @example checkoutFlow.withBlockVerify(0, [])
+     */
+    withBlockVerify(block: Block<any, any> | string | number, verify: Trait[] | ((out: any) => Trait[])): Flow<Out>;
+    /**
+     * Replaces one Trait inside the given Block's verify list - same rules as
+     * {@link modVerify}. Throws if no Block in this Flow matches, or if that
+     * Block has no verify trait at the given name/index.
+     * @example checkoutFlow.modBlockVerify(LoginBlock, "url-matches", Trait.url({ pathname: "/inventory.html" }))
+     */
+    modBlockVerify(block: Block<any, any> | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): Flow<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. */
+    headless?: boolean;
+    /** Default `"chromium"`. */
+    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;
+}
+type S = Checkpoint<"__start__">;
+/**
+ * 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
+ * (`headless`/`browserName`/`slowMo`); traits/interstitials/watchers land here
+ * in a later change.
+ * @example const engine = new Engine({ headless: false, slowMo: 250 });
+ */
+export declare class Engine {
+    private readonly config;
+    constructor(config?: EngineConfig);
+    /**
+     * 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`)
+     * 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])
+     */
+    defineFlow<B extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, EndMarker]): Flow<B>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, EndMarker]): Flow<C>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, Block<C, D>, EndMarker]): Flow<D>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, Block<C, D>, Block<D, E>, EndMarker]): Flow<E>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        EndMarker
+    ]): Flow<F>;
+    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>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        EndMarker
+    ]): Flow<G>;
+}
+/**
+ * Attaches routing to `block` without touching its act/observe/resolve/verify -
+ * `routes` must cover every tag of `block`'s output (a missing route is a compile
+ * error), and the returned Block runs exactly as `block` always did, just followed
+ * by whichever next Block the resolved tag routes to. `null` for a tag means that
+ * tag is terminal - the run stops there, same as a Block with no routing at all.
+ * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
+ * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
+ * a route can lead anywhere, including back through itself, so there is no fixed
+ * Out type to express; state the expected outcomes to `runGraph` via `terminals`
+ * instead.
+ */
+export declare function branch<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, routes: {
+    [K in Out["__state"]]: Block<Extract<Out, Checkpoint<K>>, any> | null;
+}): DefinedBlock<In, any>;
+/**
+ * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
+ * methods - `LoginBlock.withVerify([...])`, discoverable by typing
+ * `LoginBlock.` in an editor, not just callable as `withVerify(LoginBlock, ...)`
+ * if you already know it exists. A raw object literal is still a perfectly
+ * valid Block (every test fixture in this codebase is one) - it just won't have
+ * these attached. The methods are thin: they delegate to the identically-named
+ * free functions, which remain the one place this logic actually lives.
+ */
+export declare function defineBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: {
+    name: string;
+    instruction: Instruction<In, Out, any>;
+    next?: Block<In, Out>["next"];
+    requires?: Block<In, Out>["requires"];
+}): DefinedBlock<In, 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
+ * looser, or just different) confirmation on a Block it didn't author, without
+ * that Block needing to have been written as a parameterized factory in
+ * anticipation. Same move as `branch()`: decorate an existing Block, don't ask
+ * every Block to pre-build its own override mechanism.
+ *
+ * Wrap the one Block you want to change, in place, wherever it already sits in
+ * a `defineFlow([...])` array - every other Block stays untouched:
+ * `defineFlow([start, LoginBlock, withVerify(AddToCartBlock, [...]), end])`.
+ * There is no separate positional array to keep in sync and no `null`
+ * placeholder for "skip this one" - `defineFlow` has no per-slot verify
+ * argument at all, only whatever `verify` each Block's own `instruction` (or
+ * a `withVerify(...)` wrapping it) carries with it.
+ */
+export declare function withVerify<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, verify: Trait[] | ((out: Out) => Trait[])): DefinedBlock<In, Out>;
+/**
+ * Replaces one Trait inside `block`'s verify list, leaving every other check
+ * untouched - the v1/v2/legacy-variant case, where one check needs a different
+ * selector or URL pattern but the rest of the Block is identical. Addressed by
+ * the Trait's own `name` (recommended - inserting or reordering other checks
+ * can't silently retarget it) or, if you genuinely know the position and don't
+ * need that safety, a numeric index. Either way a bad address fails loud
+ * immediately instead of quietly doing nothing. `newCheck` can be a bare
+ * `check` function (keeps the existing name) or a full `Trait` (to rename too).
+ * Only works on a flat `verify` array - a function-form `verify` (from
+ * `verify: (out) => Trait[]`) has no fixed list to address into, so this
+ * throws rather than guess; use `withVerify` to replace it wholesale instead.
+ */
+export declare function modVerify<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
+/**
+ * `modVerify`, but for several named checks in one call - a v2 variant that
+ * differs in five ways from v1 shouldn't need five nested `modVerify(modVerify(
+ * modVerify(...)))` calls to track by eye. `patches` keys are plain strings (a
+ * Trait's `name`, not a `MemKey` instance), so an ordinary object literal is
+ * fine here - unlike `MemPage`, there's no identity-collision reason to need
+ * `[name, check]` pairs. Applies each patch in turn via `modVerify`, so the
+ * same fail-loud-on-unknown-name behavior holds for every entry.
+ */
+export declare function modVerifyAll<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
+export {};

package/dist/engine.js

@@ -0,0 +1,282 @@
+import { chromium, firefox, webkit } from "@playwright/test";
+import { connect, checkpoint } from "./types.js";
+import { MemPage } from "./mem-page.js";
+import { runVerify } from "./trait.js";
+const LAUNCHERS = { chromium, firefox, webkit };
+/**
+ * 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
+ * composed Block, so calling this on a `defineFlow`-built Flow's entry - which
+ * `runGraph` does automatically, before opening a tab - covers every Block in
+ * that flow. It does not see Blocks only reachable through `branch()` routing,
+ * since those depend on a runtime decision that hasn't happened yet.
+ */
+export function preflight(mem, block) {
+    const missing = (block.requires ?? []).filter((k) => !mem.has(k));
+    if (missing.length > 0) {
+        throw new Error(`preflight: MemPage is missing required key(s) before "${block.name}" can run: ${missing
+            .map((k) => `"${k.name}"`)
+            .join(", ")}`);
+    }
+}
+/**
+ * Runs `entry` against a fresh tab and returns the resulting terminal Checkpoint.
+ * The engine owns the tab's lifecycle, not any individual Block: the tab is
+ * created before the first `act` runs and closed in `finally`, so it closes even
+ * if a step throws.
+ *
+ * After each Block resolves, its `next` (if any, from `branch()`) is followed to
+ * the following Block, in the same tab - a Block with no `next` runs exactly once,
+ * unchanged from before `branch()` existed. `next` returning the same Block is a
+ * self-loop; `maxSteps` bounds the loop so a routing bug fails loud instead of
+ * hanging.
+ *
+ * `terminals`, if given, is a sanity check: the Checkpoint the run stops on must be
+ * one of the tags the caller actually expects, or the run fails loud instead of
+ * silently returning an unexpected result. Omit it when there is only ever one
+ * 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) {
+    preflight(mem, entry);
+    const page = await context.newPage();
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let current = entry;
+        let input = checkpoint("__start__");
+        let steps = 0;
+        for (;;) {
+            if (++steps > maxSteps) {
+                throw new Error(`runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`);
+            }
+            await current.instruction.act(page, input, mem);
+            const observed = current.instruction.observe
+                ? await current.instruction.observe(page, mem)
+                : undefined;
+            const checkpoint = await current.instruction.resolve(observed);
+            await runVerify(current.instruction.verify, checkpoint, page, mem, current.name);
+            const next = current.next?.(checkpoint);
+            if (!next) {
+                if (terminals && !terminals.has(checkpoint.__state)) {
+                    throw new Error(`runGraph: "${current.name}" resolved to "${checkpoint.__state}", which is not a registered terminal (expected one of: ${[...terminals].join(", ")})`);
+                }
+                return checkpoint;
+            }
+            current = next;
+            input = checkpoint;
+        }
+    }
+    finally {
+        await page.close();
+    }
+}
+/** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
+export const start = Symbol("waygraph.start");
+export const end = Symbol("waygraph.end");
+function findBlockIndex(middle, block) {
+    if (typeof block === "number") {
+        if (block < 0 || block >= middle.length) {
+            throw new Error(`Flow: no Block at index ${block} in this flow (has ${middle.length})`);
+        }
+        return block;
+    }
+    const blockName = typeof block === "string" ? block : block.name;
+    const index = middle.findIndex((b) => b.name === blockName);
+    if (index === -1) {
+        throw new Error(`Flow: no Block named "${blockName}" in this flow (has: ${middle.map((b) => b.name).join(", ")})`);
+    }
+    return index;
+}
+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();
+                }
+            }
+            return runGraph(chain, undefined, contextOrMem, memOrConfig);
+        },
+        withBlockVerify(block, verify) {
+            const index = findBlockIndex(middle, block);
+            const patched = [...middle];
+            patched[index] = withVerify(middle[index], verify);
+            return buildFlow(patched, engineConfig);
+        },
+        modBlockVerify(block, nameOrIndex, newCheck) {
+            const index = findBlockIndex(middle, block);
+            const patched = [...middle];
+            patched[index] = modVerify(middle[index], nameOrIndex, newCheck);
+            return buildFlow(patched, engineConfig);
+        },
+    };
+}
+/**
+ * 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
+ * (`headless`/`browserName`/`slowMo`); traits/interstitials/watchers land here
+ * in a later change.
+ * @example const engine = new Engine({ headless: false, slowMo: 250 });
+ */
+export class Engine {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    defineFlow(blocks) {
+        return buildFlow(blocks.slice(1, -1), this.config);
+    }
+}
+/**
+ * Attaches routing to `block` without touching its act/observe/resolve/verify -
+ * `routes` must cover every tag of `block`'s output (a missing route is a compile
+ * error), and the returned Block runs exactly as `block` always did, just followed
+ * by whichever next Block the resolved tag routes to. `null` for a tag means that
+ * tag is terminal - the run stops there, same as a Block with no routing at all.
+ * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
+ * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
+ * a route can lead anywhere, including back through itself, so there is no fixed
+ * Out type to express; state the expected outcomes to `runGraph` via `terminals`
+ * instead.
+ */
+export function branch(block, routes) {
+    const base = stripMethods(block);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let routed;
+    routed = defineBlock({
+        ...base,
+        next: (checkpoint) => {
+            const target = routes[checkpoint.__state];
+            if (target === undefined || target === null)
+                return undefined;
+            // A route naming `block` itself (the only self-reference in scope when
+            // `routes` was written) means "loop back with routing intact" - substitute
+            // the routed Block, not the original with no `next` of its own.
+            return target === block ? routed : target;
+        },
+    });
+    return routed;
+}
+/**
+ * Strips `withVerify`/`modVerify`/`modVerifyAll` off a Block, keeping everything
+ * else - `name`, `instruction`, `next`, `requires`. Every function below that
+ * returns a new Block calls this on its input first, then rebuilds through
+ * `defineBlock`. Without it, a Block's attached methods close over the shape it
+ * had *when they were attached* - call `.withVerify()` on a Block that
+ * `branch()` added routing to afterward, and without this step the result would
+ * silently drop that routing, since the stale closure never knew about it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function stripMethods(block) {
+    return {
+        name: block.name,
+        instruction: block.instruction,
+        ...(block.next ? { next: block.next } : {}),
+        ...(block.requires ? { requires: block.requires } : {}),
+    };
+}
+/**
+ * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
+ * methods - `LoginBlock.withVerify([...])`, discoverable by typing
+ * `LoginBlock.` in an editor, not just callable as `withVerify(LoginBlock, ...)`
+ * if you already know it exists. A raw object literal is still a perfectly
+ * valid Block (every test fixture in this codebase is one) - it just won't have
+ * these attached. The methods are thin: they delegate to the identically-named
+ * free functions, which remain the one place this logic actually lives.
+ */
+export function defineBlock(base) {
+    const plain = {
+        name: base.name,
+        instruction: base.instruction,
+        ...(base.next ? { next: base.next } : {}),
+        ...(base.requires ? { requires: base.requires } : {}),
+    };
+    return {
+        ...plain,
+        withVerify: (verify) => withVerify(plain, verify),
+        modVerify: (nameOrIndex, newCheck) => modVerify(plain, nameOrIndex, newCheck),
+        modVerifyAll: (patches) => modVerifyAll(plain, patches),
+    };
+}
+/**
+ * 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
+ * looser, or just different) confirmation on a Block it didn't author, without
+ * that Block needing to have been written as a parameterized factory in
+ * anticipation. Same move as `branch()`: decorate an existing Block, don't ask
+ * every Block to pre-build its own override mechanism.
+ *
+ * Wrap the one Block you want to change, in place, wherever it already sits in
+ * a `defineFlow([...])` array - every other Block stays untouched:
+ * `defineFlow([start, LoginBlock, withVerify(AddToCartBlock, [...]), end])`.
+ * There is no separate positional array to keep in sync and no `null`
+ * placeholder for "skip this one" - `defineFlow` has no per-slot verify
+ * argument at all, only whatever `verify` each Block's own `instruction` (or
+ * a `withVerify(...)` wrapping it) carries with it.
+ */
+export function withVerify(block, verify) {
+    const base = stripMethods(block);
+    return defineBlock({ ...base, instruction: { ...base.instruction, verify } });
+}
+/**
+ * Replaces one Trait inside `block`'s verify list, leaving every other check
+ * untouched - the v1/v2/legacy-variant case, where one check needs a different
+ * selector or URL pattern but the rest of the Block is identical. Addressed by
+ * the Trait's own `name` (recommended - inserting or reordering other checks
+ * can't silently retarget it) or, if you genuinely know the position and don't
+ * need that safety, a numeric index. Either way a bad address fails loud
+ * immediately instead of quietly doing nothing. `newCheck` can be a bare
+ * `check` function (keeps the existing name) or a full `Trait` (to rename too).
+ * Only works on a flat `verify` array - a function-form `verify` (from
+ * `verify: (out) => Trait[]`) has no fixed list to address into, so this
+ * throws rather than guess; use `withVerify` to replace it wholesale instead.
+ */
+export function modVerify(block, nameOrIndex, newCheck) {
+    const verify = block.instruction.verify;
+    if (typeof verify === "function") {
+        throw new Error(`modVerify: "${block.name}" has a function-form verify, which has no fixed list to address into - use withVerify to replace it wholesale instead`);
+    }
+    const traits = verify ?? [];
+    const index = typeof nameOrIndex === "number" ? nameOrIndex : traits.findIndex((t) => t.name === nameOrIndex);
+    const existing = traits[index];
+    if (!existing) {
+        throw new Error(typeof nameOrIndex === "number"
+            ? `modVerify: "${block.name}" has no verify trait at index ${nameOrIndex} (has ${traits.length})`
+            : `modVerify: "${block.name}" has no verify trait named "${nameOrIndex}" (has: ${traits.map((t) => t.name).join(", ") || "none"})`);
+    }
+    const replacement = typeof newCheck === "function"
+        ? { name: typeof nameOrIndex === "string" ? nameOrIndex : existing.name, check: newCheck }
+        : newCheck;
+    const updated = [...traits];
+    updated[index] = replacement;
+    return withVerify(block, updated);
+}
+/**
+ * `modVerify`, but for several named checks in one call - a v2 variant that
+ * differs in five ways from v1 shouldn't need five nested `modVerify(modVerify(
+ * modVerify(...)))` calls to track by eye. `patches` keys are plain strings (a
+ * Trait's `name`, not a `MemKey` instance), so an ordinary object literal is
+ * fine here - unlike `MemPage`, there's no identity-collision reason to need
+ * `[name, check]` pairs. Applies each patch in turn via `modVerify`, so the
+ * same fail-loud-on-unknown-name behavior holds for every entry.
+ */
+export function modVerifyAll(block, patches) {
+    return Object.entries(patches).reduce((current, [name, newCheck]) => modVerify(current, name, newCheck), defineBlock(stripMethods(block)));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { Checkpoint, Instruction, Block, DefinedBlock } 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";

package/dist/index.js

@@ -0,0 +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";

package/dist/mem-page.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A typed key into MemPage. The phantom `_phantom` field is never assigned - it
+ * exists only so TypeScript can infer `T` at each call site. The store is keyed by
+ * the MemKey *instance* (object identity), not by `name`, so two keys can share a
+ * debug name and never collide - `name` is for error messages only.
+ */
+export declare class MemKey<T> {
+    readonly name: string;
+    private readonly _phantom;
+    constructor(name: string);
+}
+/**
+ * Builds a MemKey for a single typed value - the `T` you give here is what
+ * `mem.get`/`mem.set` enforce everywhere this key is used.
+ * @example const Username = key<string>("saucedemo.username");
+ */
+export declare function key<T>(name: string): MemKey<T>;
+/**
+ * A named shorthand for a single MemKey holding a whole shaped value (a
+ * credentials object, not two separate primitive keys). `LoginCreds({ username,
+ * password })` returns a `[key, value]` pair ready for `setAll`; `LoginCreds.key`
+ * is the underlying MemKey, for `mem.get(LoginCreds.key)` or `Block.requires`.
+ * `T` is given explicitly at the `keyGroup<T>(...)` call site, not inferred from
+ * how it's later called, so this doesn't carry the same inference risk `setAll`'s
+ * first attempt did.
+ */
+export declare function keyGroup<T>(name: string): ((value: T) => readonly [MemKey<T>, T]) & {
+    key: MemKey<T>;
+};
+/**
+ * Typed, identity-keyed shared memory for one graph run. Reading a key that was
+ * never written throws immediately, naming the key, instead of returning
+ * `undefined` - a misuse fails loud at the read site, not silently downstream.
+ */
+export declare class MemPage {
+    private readonly store;
+    /** `mem.set(key, value)`, or `mem.set(LoginCreds({ ... }))` with a `keyGroup` pair directly - no "All" for just one. */
+    set<T>(k: MemKey<T>, value: T): void;
+    set<T>(pair: readonly [MemKey<T>, T]): void;
+    /**
+     * Reads `k`'s value, throwing (naming `k`) if it was never `set` - never
+     * returns `undefined` for a genuinely missing key, so a misuse fails loud at
+     * the read site instead of surfacing as a confusing error deep in `act`.
+     * @example const { username, password } = mem.get(LoginCreds.key);
+     */
+    get<T>(k: MemKey<T>): T;
+    /** True once `k` has been `set` - use before a `get` that's genuinely optional. */
+    has<T>(k: MemKey<T>): boolean;
+    /** Covers add/remove/insert/nest generically - MemPage never needs to know the shape of T. */
+    update<T>(k: MemKey<T>, fn: (current: T) => T): void;
+    /**
+     * Sets several keys in one call - `mem.setAll([UsernameKey, "standard_user"], [PasswordKey, "secret_sauce"])`
+     * instead of one `.set()` per line. Can't take a plain `{ ... }` object literal:
+     * MemKey instances are the identity the store is keyed by, and object literals
+     * can only have string/symbol property names, not object instances - a `[key,
+     * value]` pair is the shape that keeps that identity-based guarantee.
+     *
+     * Overloaded per pair count (2-6, same reasoning as `Engine.defineFlow`'s
+     * overloads) rather than one fully-generic variadic signature - each pair binds
+     * its own type parameter independently, which TS checks reliably; a single
+     * self-referential mapped-tuple-over-a-rest-parameter type was tried first and
+     * silently failed to catch a mismatched pair, so it was not trusted over this.
+     */
+    setAll<A>(p1: readonly [MemKey<A>, A]): void;
+    setAll<A, B>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B]): void;
+    setAll<A, B, C>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C]): void;
+    setAll<A, B, C, D>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D]): void;
+    setAll<A, B, C, D, E>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D], p5: readonly [MemKey<E>, E]): void;
+    setAll<A, B, C, D, E, F>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D], p5: readonly [MemKey<E>, E], p6: readonly [MemKey<F>, F]): void;
+}

package/dist/mem-page.js

@@ -0,0 +1,71 @@
+/**
+ * A typed key into MemPage. The phantom `_phantom` field is never assigned - it
+ * exists only so TypeScript can infer `T` at each call site. The store is keyed by
+ * the MemKey *instance* (object identity), not by `name`, so two keys can share a
+ * debug name and never collide - `name` is for error messages only.
+ */
+export class MemKey {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+/**
+ * Builds a MemKey for a single typed value - the `T` you give here is what
+ * `mem.get`/`mem.set` enforce everywhere this key is used.
+ * @example const Username = key<string>("saucedemo.username");
+ */
+export function key(name) {
+    return new MemKey(name);
+}
+/**
+ * A named shorthand for a single MemKey holding a whole shaped value (a
+ * credentials object, not two separate primitive keys). `LoginCreds({ username,
+ * password })` returns a `[key, value]` pair ready for `setAll`; `LoginCreds.key`
+ * is the underlying MemKey, for `mem.get(LoginCreds.key)` or `Block.requires`.
+ * `T` is given explicitly at the `keyGroup<T>(...)` call site, not inferred from
+ * how it's later called, so this doesn't carry the same inference risk `setAll`'s
+ * first attempt did.
+ */
+export function keyGroup(name) {
+    const k = key(name);
+    const factory = (value) => [k, value];
+    return Object.assign(factory, { key: k });
+}
+/**
+ * Typed, identity-keyed shared memory for one graph run. Reading a key that was
+ * never written throws immediately, naming the key, instead of returning
+ * `undefined` - a misuse fails loud at the read site, not silently downstream.
+ */
+export class MemPage {
+    store = new Map();
+    set(kOrPair, value) {
+        const [k, v] = kOrPair instanceof MemKey ? [kOrPair, value] : kOrPair;
+        this.store.set(k, v);
+    }
+    /**
+     * Reads `k`'s value, throwing (naming `k`) if it was never `set` - never
+     * returns `undefined` for a genuinely missing key, so a misuse fails loud at
+     * the read site instead of surfacing as a confusing error deep in `act`.
+     * @example const { username, password } = mem.get(LoginCreds.key);
+     */
+    get(k) {
+        if (!this.store.has(k)) {
+            throw new Error(`MemPage: "${k.name}" read before it was set`);
+        }
+        return this.store.get(k);
+    }
+    /** True once `k` has been `set` - use before a `get` that's genuinely optional. */
+    has(k) {
+        return this.store.has(k);
+    }
+    /** Covers add/remove/insert/nest generically - MemPage never needs to know the shape of T. */
+    update(k, fn) {
+        this.set(k, fn(this.get(k)));
+    }
+    setAll(...pairs) {
+        for (const [k, v] of pairs) {
+            this.set(k, v);
+        }
+    }
+}

package/dist/trait.d.ts

@@ -0,0 +1,62 @@
+import type { Page } from "@playwright/test";
+import type { MemPage } from "./mem-page.js";
+/**
+ * A named, independently-reportable check. `check` never runs before `resolve` has
+ * already decided the Checkpoint, and it can only confirm or fail loud - it has no
+ * way to redirect the run.
+ */
+export interface Trait {
+    /** Shows up in the error a failed check throws: `trait "${name}" failed after "${blockName}"`. */
+    name: string;
+    /** Returns `true` if the check passes. May wait (e.g. `page.waitForURL`) - just don't redirect the run. */
+    check(page: Page, mem: MemPage): Promise<boolean>;
+}
+/**
+ * Common, generic Trait factories - reusable across any Block, not one-off
+ * `{ name, check }` objects written inline per Block. Reach for one of these
+ * first; write a bespoke Trait only for a check that's genuinely app-specific.
+ */
+/**
+ * Passes once the page's URL matches `pattern`, waiting for real navigation.
+ * `pattern` is a structured `URLPatternInit` (the same shape the standard
+ * `URLPattern` Web API takes) - `{ pathname, hostname, search, hash, ... }` -
+ * not a hand-written regex. Whichever components you don't specify default to
+ * "match anything" there, so a hybrid SPA tacking its own `?tab=cart&session=xyz`
+ * onto the URL never breaks a `pathname`-only check - there's no separate flag
+ * for that, omission already means "don't care." Reach for a bespoke Trait with
+ * a raw regex only if a route genuinely needs pattern power `URLPatternInit`'s
+ * fields can't express.
+ * @example Trait.url({ pathname: "/inventory.html" })
+ * @example Trait.url({ hostname: "checkout.example.com", pathname: "/pay" })
+ * @example Trait.url({ pathname: "/users/:id" })   // named path params, matched structurally
+ */
+export declare function urlMatches(pattern: URLPatternInit): Trait;
+/** Passes when `selector`'s text content is exactly `expected`. */
+export declare function textEquals(selector: string, expected: string): Trait;
+/** Passes once `selector` is visible on the page, waiting for it to appear. */
+export declare function visible(selector: string): Trait;
+/**
+ * Discoverable entry point for the built-in Trait factories - type `Trait.` in
+ * an editor to see `url`/`text`/`visible` offered, instead of needing to
+ * already know `urlMatches`/`textEquals`/`visible` exist as free functions to
+ * import by name. Same functions, just reachable off the type's own name -
+ * `urlMatches`/`textEquals`/`visible` stay exported too, so nothing that
+ * already imports them by name breaks.
+ * @example verify: [Trait.url({ pathname: "/inventory.html" })]
+ * @example verify: [Trait.text(".shopping_cart_badge", "1")]
+ */
+export declare const Trait: {
+    url: typeof urlMatches;
+    text: typeof textEquals;
+    visible: typeof visible;
+};
+/**
+ * Runs every Trait for a Block that just resolved, throwing on the first failure
+ * with the failing Trait's own name and the Block's name - never called before
+ * resolve, never able to change what resolve already decided. `verify` may be a
+ * flat list or a function of the resolved Checkpoint (for a branching Block whose
+ * different outcomes need different checks). Called automatically by `runGraph`
+ * and `connect()` after every `resolve` - not something a Block normally calls
+ * directly.
+ */
+export declare function runVerify<Out>(verify: Trait[] | ((out: Out) => Trait[]) | undefined, out: Out, page: Page, mem: MemPage, blockName: string): Promise<void>;

package/dist/trait.js

@@ -0,0 +1,80 @@
+/**
+ * Common, generic Trait factories - reusable across any Block, not one-off
+ * `{ name, check }` objects written inline per Block. Reach for one of these
+ * first; write a bespoke Trait only for a check that's genuinely app-specific.
+ */
+/**
+ * Passes once the page's URL matches `pattern`, waiting for real navigation.
+ * `pattern` is a structured `URLPatternInit` (the same shape the standard
+ * `URLPattern` Web API takes) - `{ pathname, hostname, search, hash, ... }` -
+ * not a hand-written regex. Whichever components you don't specify default to
+ * "match anything" there, so a hybrid SPA tacking its own `?tab=cart&session=xyz`
+ * onto the URL never breaks a `pathname`-only check - there's no separate flag
+ * for that, omission already means "don't care." Reach for a bespoke Trait with
+ * a raw regex only if a route genuinely needs pattern power `URLPatternInit`'s
+ * fields can't express.
+ * @example Trait.url({ pathname: "/inventory.html" })
+ * @example Trait.url({ hostname: "checkout.example.com", pathname: "/pay" })
+ * @example Trait.url({ pathname: "/users/:id" })   // named path params, matched structurally
+ */
+export function urlMatches(pattern) {
+    const urlPattern = new URLPattern(pattern);
+    return {
+        name: `url-matches(${JSON.stringify(pattern)})`,
+        async check(page) {
+            await page.waitForURL(urlPattern);
+            return true;
+        },
+    };
+}
+/** Passes when `selector`'s text content is exactly `expected`. */
+export function textEquals(selector, expected) {
+    return {
+        name: `text-equals(${selector}, ${JSON.stringify(expected)})`,
+        async check(page) {
+            return (await page.locator(selector).textContent()) === expected;
+        },
+    };
+}
+/** Passes once `selector` is visible on the page, waiting for it to appear. */
+export function visible(selector) {
+    return {
+        name: `visible(${selector})`,
+        async check(page) {
+            await page.locator(selector).waitFor({ state: "visible" });
+            return true;
+        },
+    };
+}
+/**
+ * Discoverable entry point for the built-in Trait factories - type `Trait.` in
+ * an editor to see `url`/`text`/`visible` offered, instead of needing to
+ * already know `urlMatches`/`textEquals`/`visible` exist as free functions to
+ * import by name. Same functions, just reachable off the type's own name -
+ * `urlMatches`/`textEquals`/`visible` stay exported too, so nothing that
+ * already imports them by name breaks.
+ * @example verify: [Trait.url({ pathname: "/inventory.html" })]
+ * @example verify: [Trait.text(".shopping_cart_badge", "1")]
+ */
+export const Trait = {
+    url: urlMatches,
+    text: textEquals,
+    visible,
+};
+/**
+ * Runs every Trait for a Block that just resolved, throwing on the first failure
+ * with the failing Trait's own name and the Block's name - never called before
+ * resolve, never able to change what resolve already decided. `verify` may be a
+ * flat list or a function of the resolved Checkpoint (for a branching Block whose
+ * different outcomes need different checks). Called automatically by `runGraph`
+ * and `connect()` after every `resolve` - not something a Block normally calls
+ * directly.
+ */
+export async function runVerify(verify, out, page, mem, blockName) {
+    const traits = typeof verify === "function" ? verify(out) : (verify ?? []);
+    for (const trait of traits) {
+        if (!(await trait.check(page, mem))) {
+            throw new Error(`trait "${trait.name}" failed after "${blockName}"`);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+import type { Page } from "@playwright/test";
+import type { MemPage, MemKey } from "./mem-page.js";
+import type { Trait } from "./trait.js";
+/**
+ * A Checkpoint is identified solely by its string tag - a phantom marker with no
+ * embedded data. Two Checkpoints with the same tag are the same state everywhere.
+ */
+export type Checkpoint<Tag extends string> = {
+    readonly __state: Tag;
+};
+/**
+ * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
+ * @example resolve: () => checkpoint("LoggedIn")
+ */
+export declare function checkpoint<Tag extends string>(tag: Tag): Checkpoint<Tag>;
+/**
+ * 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
+ * `verify` only once you want to confirm the reached state, not just classify it.
+ */
+export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoint<string>, Observed = void> {
+    /** Drives the browser only, this tab only. Never touches `context` - see `observe` for that. */
+    act(page: Page, input: In, mem: MemPage): Promise<void>;
+    /**
+     * Optional. Gathers evidence for `resolve` to classify, runs assertions,
+     * writes memory - the only phase allowed to look at the DOM before a
+     * decision is made, or open a second tab via `page.context()`.
+     */
+    observe?(page: Page, mem: MemPage): Promise<Observed>;
+    /**
+     * Mandatory, pure. Its only parameter is the evidence `observe` handed it -
+     * no `page`, no `mem` in scope, not by convention but because they're
+     * missing from the signature. Reproducible from `observed` alone.
+     */
+    resolve(observed: Observed): Out | Promise<Out>;
+    /**
+     * Optional. Runs once, only after `resolve` has already decided `Out` -
+     * confirms or fails loud, can never redirect what was decided. A function
+     * form picks different checks per branch (a failed login shouldn't be
+     * checked against "reached the dashboard"); see {@link Block.withVerify} and
+     * {@link Block.modVerify} for changing this from outside the Block's own file.
+     */
+    verify?: Trait[] | ((out: Out) => Trait[]);
+}
+/**
+ * A Block wraps one instruction. Its Observed type is an internal detail, erased here.
+ * `next` is optional routing attached by `branch()` - unset on a plain or
+ * `connect()`-composed Block, meaning "terminal after one step" (today's behavior,
+ * unchanged). Returning the Block itself from `next` is a self-loop. `requires` is
+ * MemKeys this Block's `act` reads from `mem` and needs already set - declaring it
+ * lets `preflight()` catch a missing value before any browser action runs, instead
+ * of failing loud deep inside `act` after several real steps already happened.
+ *
+ * `withVerify`/`modVerify`/`modVerifyAll` are optional - present (and discoverable
+ * by typing `someBlock.`) on any Block built via `defineBlock()`, absent on a raw
+ * object literal (which is still a perfectly valid Block, e.g. every test fixture
+ * in this codebase). They delegate to the identically-named free functions - same
+ * logic, chainable as methods for the common case, still callable as
+ * `withVerify(block, ...)` for a block that doesn't have them attached.
+ */
+export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<string>> {
+    /** A short, stable label - shows up in every error this Block can produce ("trait X failed after Y"). */
+    name: string;
+    /** The act/observe/resolve/verify pipeline itself. See {@link Instruction}. */
+    instruction: Instruction<In, Out, any>;
+    /**
+     * Routing attached by {@link branch}. Unset on a plain or `connect()`-composed
+     * Block, meaning "terminal after one step". Returning the Block itself is a
+     * self-loop - see `runGraph`'s `maxSteps` for the safety net that needs.
+     */
+    next?(checkpoint: Out): Block<any, any> | null | undefined;
+    /**
+     * MemKeys this Block's `act` reads from `mem` and needs already set.
+     * Declaring it lets {@link preflight} (built into `runGraph`) catch a missing
+     * value before any browser action runs, instead of failing loud deep inside
+     * `act`.
+     * @example requires: [LoginCreds.key]
+     */
+    requires?: readonly MemKey<any>[];
+    /**
+     * Replaces this Block's whole `verify` list - the only way to clear it to
+     * empty (the "I only care that I navigated this far" case) or go from no
+     * verify to some. For tweaking one existing check without restating the
+     * rest, use {@link Block.modVerify} instead.
+     * @example LoginBlock.withVerify([])              // navigation-only, no DOM confirmation
+     * @example LoginBlock.withVerify([urlMatches(/dashboard/)])
+     */
+    withVerify?(verify: Trait[] | ((out: Out) => Trait[])): Block<In, Out>;
+    /**
+     * Replaces one existing Trait in this Block's `verify` list, by its `name`
+     * (recommended) or numeric index, leaving every other check untouched - the
+     * v1/v2/legacy-app case, where one check needs a different selector but the
+     * rest of the Block is identical. Throws loud if the name/index doesn't
+     * exist - use {@link Block.withVerify} if there's nothing there yet to replace.
+     * @example LoginBlock.modVerify("url-matches", urlMatches(/dashboard\.html/))
+     */
+    modVerify?(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): Block<In, Out>;
+    /**
+     * {@link Block.modVerify}, but for several named checks in one call - a v2
+     * variant that differs in five ways from v1 shouldn't need five nested calls.
+     * @example LoginBlock.modVerifyAll({ "url-matches": urlMatches(/v2/), "cart-badge": textEquals(".badge-v2", "1") })
+     */
+    modVerifyAll?(patches: Record<string, Trait["check"] | Trait>): Block<In, Out>;
+}
+/**
+ * A Block guaranteed to have `withVerify`/`modVerify`/`modVerifyAll` attached -
+ * what `defineBlock()` and, since they're built on it, `withVerify()`/`modVerify()`/
+ * `modVerifyAll()`/`branch()` all return. Lets `LoginBlock.withVerify(...)` be
+ * called directly, no `!`/`?.` needed - the type says the method is there, not
+ * "maybe". A plain `Block<In, Out>` (a raw object literal) doesn't get this;
+ * `DefinedBlock` is still assignable anywhere a `Block` is expected.
+ */
+export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<Block<In, Out>, "withVerify" | "modVerify" | "modVerifyAll"> & {
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): DefinedBlock<In, Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
+};
+/**
+ * Composes two Blocks into one, typechecked so this only compiles when A's output
+ * tag equals B's input tag. The composed Block's act runs A's full instruction
+ * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
+ * its own observe/resolve are simply B's, since B is what decides the final Out.
+ */
+export declare function connect<A extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>>(a: Block<A, B>, b: Block<B, C>): Block<A, C>;

package/dist/types.js

@@ -0,0 +1,39 @@
+import { runVerify } from "./trait.js";
+/**
+ * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
+ * @example resolve: () => checkpoint("LoggedIn")
+ */
+export function checkpoint(tag) {
+    return { __state: tag };
+}
+/**
+ * Composes two Blocks into one, typechecked so this only compiles when A's output
+ * tag equals B's input tag. The composed Block's act runs A's full instruction
+ * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
+ * its own observe/resolve are simply B's, since B is what decides the final Out.
+ */
+export function connect(a, b) {
+    const bObserve = b.instruction.observe;
+    const bVerify = b.instruction.verify;
+    const requires = [...(a.requires ?? []), ...(b.requires ?? [])];
+    return {
+        name: `${a.name} -> ${b.name}`,
+        ...(requires.length > 0 ? { requires } : {}),
+        instruction: {
+            async act(page, input, mem) {
+                await a.instruction.act(page, input, mem);
+                const aObserved = a.instruction.observe
+                    ? await a.instruction.observe(page, mem)
+                    : undefined;
+                const mid = await a.instruction.resolve(aObserved);
+                await runVerify(a.instruction.verify, mid, page, mem, a.name);
+                await b.instruction.act(page, mid, mem);
+            },
+            resolve: (observed) => b.instruction.resolve(observed),
+            // Only attach optional fields when B actually has them - exactOptionalPropertyTypes
+            // forbids assigning `undefined` to an optional property directly.
+            ...(bObserve ? { observe: (page, mem) => bObserve(page, mem) } : {}),
+            ...(bVerify ? { verify: bVerify } : {}),
+        },
+    };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "waygraph",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deviate-dv8/waygraph.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.40.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.55.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^5.6.0"
+  }
+}