waygraph 0.0.1 → 0.1.0

package/README.md

@@ -1,12 +1,58 @@
 # 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.
+flat pile of ad hoc helper functions.
 
 This repo is the `waygraph` npm package itself. Consumer projects proving it against real
 sites/apps (saucedemo.com, zsign-app) live in the sibling `projects_waygraph/` repo, not here.
 
+## Install
+
+```bash
+npm install waygraph @playwright/test
+```
+
+`@playwright/test` is a peer dependency, not bundled - you bring your own version (`^1.40.0`
+or later) since it's also what drives the rest of your test suite. Requires Node 22+ (uses
+`URL`/`URLPattern` from `@types/node` for `Trait.url`'s type checking).
+
+## Quick start
+
+A Block wraps one `act`/`resolve` step (add `observe`/`verify` once you need them); a `Flow`
+chains several into a run:
+
+```typescript
+import { Engine, start, end, MemPage, key, checkpoint, Trait } from "waygraph";
+import type { Block, Checkpoint, Start } from "waygraph";
+
+type LoggedIn = Checkpoint<"LoggedIn">;
+
+const Username = key<string>("username");
+
+const Login: Block<Start, LoggedIn> = {
+  name: "login",
+  instruction: {
+    async act(page, _input, mem) {
+      await page.goto("https://example.com/login");
+      await page.getByLabel("Username").fill(mem.get(Username));
+      await page.getByRole("button", { name: "Sign in" }).click();
+    },
+    resolve: () => checkpoint("LoggedIn"),
+    verify: [Trait.url({ pathname: "/dashboard" })],
+  },
+};
+
+const mem = new MemPage();
+mem.set(Username, "alice");
+
+const flow = new Engine().defineFlow([start, Login, end]);
+const result = await flow.run(mem); // Engine launches its own browser
+// result === { __state: "LoggedIn" }
+```
+
+Inside an existing `@playwright/test` file, reuse its `context` fixture instead of having the
+Engine launch its own browser: `await flow.run(context, mem)`.
+
 **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
@@ -34,17 +80,33 @@ components you leave out default to "match anything," so `Trait.url({ pathname:
 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):
+position in the flow - without editing the flow's own file. `composeBlock(name, steps)`
+chains several Blocks into one named unit the same way `connect()` already does - the
+multi-step-form case (a government form with several stepper pages, say), which is
+naturally "one feature" but still wants each step's own real `verify` independently
+overridable, not one giant Block with no per-step confirmation. `composedBlock.withStepVerify`/
+`modStepVerify` patch one step from outside, addressed the same three ways
+`withBlockVerify`/`modBlockVerify` already are - a `composeBlock` result is a plain Block,
+so it drops straight into `defineFlow([start, ..., composed, ..., end])` like any other.
+`spawnTab(entry, page, mem)` drives a genuinely separate second tab through its own
+Block/Flow, in the same browser context an existing `page` already belongs to - the
+pattern `observe()` could already reach for (it's the only phase allowed to touch
+`page.context()`), now a named, discoverable, tested primitive instead of something
+you'd have to already know to hand-roll. `flow.run(context, mem, options)` also accepts a
+trailing optional options object - additively, so `flow.run(context, mem)` still behaves
+byte-for-byte as before: `options.page` drives that already-open page instead of opening
+a fresh tab (the run won't close a page you handed it unless you say so), and
+`options.closeOnFinish: false` leaves the run's page open and returns `{ result, page }`
+so the caller can keep driving it - hands a run tab back instead of losing it. See
+"Recipes" for capture-on-popup, which stays a documented pattern until a second real use
+case promotes it to an engine API.
+
+[`create-waygraph`](https://github.com/deviate-dv8/create-waygraph) scaffolds a new
+project (package.json, tsconfig, playwright.config, one working example flow) in one
+command - built and proven end-to-end, not yet published to npm.
+
+Deliberately **not yet implemented** (tracked on the project board):
 - 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
 
@@ -54,9 +116,8 @@ real page:
 
 ```typescript
 import { Engine, start, end, MemPage, key, checkpoint } from "waygraph";
-import type { Block, Checkpoint } from "waygraph";
+import type { Block, Checkpoint, Start } from "waygraph";
 
-type Start = Checkpoint<"__start__">;
 type FormLoaded = Checkpoint<"FormLoaded">;
 type Submitted = Checkpoint<"Submitted">;
 
@@ -110,9 +171,52 @@ for real. The lower-level `connect()`/`runGraph()` still exist and are what `def
 builds on - reach for them directly only if you need a shape `defineFlow`'s array can't
 express yet.
 
-## Commands
+## Recipes
+
+### Detect / drive the surviving tab after a run
+
+The default run closes the page it opened, and a page you hand in via `options.page`
+survives. For a flow that must BE the surviving tab after it returns (an interactive demo,
+a hand-back to a caller), ask for the page back explicitly:
+
+```typescript
+const { result, page } = await registerFlow.run(context, mem, { closeOnFinish: false });
+// `result.__state` reached the terminal Checkpoint; `page` is still open where the
+// flow left it - the caller keeps driving it, and closes it whenever IT is done.
+```
+
+### Capture a popup (`target=_blank` click)
+
+Frameworks and email UIs routinely rewrite links to `target="_blank"`, so a click that
+"should navigate" actually opens a second, engine-invisible tab. Until a second real use
+case promotes this to an engine API, capture it in userland with a context-level page
+event armed before the click that is expected to open exactly one popup:
+
+```typescript
+let popup: Page | undefined;
+context.once("page", (p) => { popup = p; });
+await linkHandle.click();          // the block that causes the popup (e.g. the
+                                   // MailHog email's real verify link)
+if (popup) {
+  await popup.waitForLoadState();  // fully loaded before calling into the engine
+  await verifyLinkFlow.run(context, mem, { page: popup, closeOnFinish: false });
+  // popup is now the caller's page - close it when done, or leave it as the
+  // surviving tab of a demo.
+}
+```
+
+`context.once` (not `.on`) guarantees a second stray popup won't re-fire the handler and
+clobber your handle; if a page truly can open more than one popup, this recipe needs to
+collect them instead. The popup is a normal Playwright `Page` from the same context, so
+anything `Flow.run(context, mem, { page })` can drive is available to keep driving here,
+and `closeOnFinish: false` hands it back into your ownership instead of the run closing
+it out from under you.
+
+## Developing this package
 
 ```bash
+git clone git@github.com:deviate-dv8/waygraph.git
+cd waygraph
 npm install
 npm run typecheck   # tsc --noEmit
 npm run test        # playwright test
@@ -127,13 +231,12 @@ 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)
+  engine.ts                   runGraph(), spawnTab(), composeBlock(), Engine, start, end, Flow
   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

package/bin/waygraph

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Two cwd/symlink pitfalls this resolves, both real, both hit in practice:
+#  - `--import tsx/esm` is a bare specifier - Node resolves it as if from an
+#    unnamed module at the CALLER's cwd, not this script's install
+#    directory, so it broke when invoked from anywhere else.
+#  - `npm link` makes this script reachable via a SYMLINK (e.g.
+#    ~/.nvm/.../bin/waygraph) - `dirname "$0"` alone follows argv[0], not the
+#    symlink target, so it resolved to the nvm bin dir instead of this
+#    package. `readlink -f` follows the symlink to the real file first.
+SOURCE="$(readlink -f "$0")"
+DIR="$(cd "$(dirname "$SOURCE")/.." && pwd)"
+TSX_ESM="$(cd "$DIR" && node -e "console.log(require.resolve('tsx/esm'))")"
+exec node --import "$TSX_ESM" "$DIR/dist/cli.js" "$@"

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * waygraph CLI -- tooling around this same package's engine.
+ *
+ * Commands:
+ *   list    [project]            List discovered flows in a project
+ *   nav     [flow] [project]     Print flow chain + navigation-only steps (goto / Trait.url)
+ *   validate [project]           Import and validate all flows
+ *   run <flow> [project]         Run a named flow with a fresh browser
+ *   chain <spec> [project]       Run one or more Blocks by name, ad hoc, no flow file needed
+ *
+ * "project" defaults to the current directory.
+ * A project is any directory containing *.flow.ts files (typically under src/flows/).
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,534 @@
+#!/usr/bin/env node
+/**
+ * waygraph CLI -- tooling around this same package's engine.
+ *
+ * Commands:
+ *   list    [project]            List discovered flows in a project
+ *   nav     [flow] [project]     Print flow chain + navigation-only steps (goto / Trait.url)
+ *   validate [project]           Import and validate all flows
+ *   run <flow> [project]         Run a named flow with a fresh browser
+ *   chain <spec> [project]       Run one or more Blocks by name, ad hoc, no flow file needed
+ *
+ * "project" defaults to the current directory.
+ * A project is any directory containing *.flow.ts files (typically under src/flows/).
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { resolve, relative, join, basename } from "node:path";
+import { spawn } from "node:child_process";
+import { MemPage } from "./mem-page.js";
+// ---------------------------------------------------------------------------
+// Filesystem
+// ---------------------------------------------------------------------------
+function walkDir(dir, pattern) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
+                continue;
+            results.push(...walkDir(full, pattern));
+        }
+        else if (pattern.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function discoverFlows(projectDir) {
+    return walkDir(projectDir, /\.flow\.ts$/);
+}
+// ---------------------------------------------------------------------------
+// Static analysis for `list`/`nav` (no import, regex only)
+// ---------------------------------------------------------------------------
+function extractFlowNames(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const names = [];
+    const re = /export\s+const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*[=:]/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const name = m[1];
+        if (name !== undefined)
+            names.push(name);
+    }
+    return names;
+}
+/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
+function blockExportToLabel(exportId) {
+    const base = exportId.replace(/Block$/, "");
+    return base
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+}
+/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
+function parseBlockImports(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const names = [];
+    const re = /import\s*\{([^}]*)\}\s*from\s*["'][^"']*\.block(?:\.js)?["']/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        for (const part of m[1].split(",")) {
+            const name = part.trim().split(/\s+as\s+/)[0]?.trim();
+            if (name)
+                names.push(name);
+        }
+    }
+    return names;
+}
+/** Every `page.goto("...")` string literal in a file, in source order. */
+function extractGotos(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const results = [];
+    const re = /\.goto\(\s*["'`]([^"'`]*)["'`]/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const url = m[1];
+        if (url !== undefined)
+            results.push(url);
+    }
+    return results;
+}
+/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
+function extractUrlTraits(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const results = [];
+    const re = /Trait\.url\(\s*\{[^}]*pathname:\s*["'`]([^"'`]*)["'`]/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const url = m[1];
+        if (url !== undefined)
+            results.push(url);
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// `list`
+// ---------------------------------------------------------------------------
+function listCommand(projectDir) {
+    const files = discoverFlows(projectDir);
+    if (files.length === 0) {
+        console.log(`waygraph: no flows found under ${projectDir}`);
+        return;
+    }
+    for (const file of files) {
+        const rel = relative(projectDir, file);
+        for (const name of extractFlowNames(file)) {
+            console.log(`${rel}  ${name}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// `nav`
+// ---------------------------------------------------------------------------
+function navCommand(projectDir, flowName) {
+    const files = discoverFlows(projectDir);
+    const targets = flowName
+        ? files.filter((f) => extractFlowNames(f).includes(flowName))
+        : files;
+    if (targets.length === 0) {
+        console.error(flowName
+            ? `waygraph nav: no flow named "${flowName}" found under ${projectDir}`
+            : `waygraph: no flows found under ${projectDir}`);
+        process.exitCode = 1;
+        return;
+    }
+    for (const file of targets) {
+        for (const name of extractFlowNames(file)) {
+            console.log(`${name}  (${relative(projectDir, file)})`);
+            const blockDir = projectDir;
+            for (const blockExport of parseBlockImports(file)) {
+                console.log(`  -> ${blockExportToLabel(blockExport)}`);
+                const blockFile = walkDir(blockDir, /\.block\.ts$/).find((f) => readFileSync(f, "utf-8").includes(`export const ${blockExport}`));
+                if (!blockFile)
+                    continue;
+                for (const url of extractGotos(blockFile))
+                    console.log(`       goto ${url}`);
+                for (const url of extractUrlTraits(blockFile))
+                    console.log(`       verify url ~ ${url}`);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Dynamic import + validation
+// ---------------------------------------------------------------------------
+async function importModule(filePath) {
+    const url = new URL(`file://${resolve(filePath)}`);
+    return (await import(url.href));
+}
+/** Kept as a named alias - `run`/`validate` below were written against this name first. */
+const importFlowFile = importModule;
+function isFlowLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    return typeof obj.run === "function";
+}
+// ---------------------------------------------------------------------------
+// `chain`
+// ---------------------------------------------------------------------------
+/**
+ * `chain` cannot resolve Blocks by importing them straight into THIS
+ * process: this CLI's own `waygraph` (this same package) already loaded -
+ * and its engine does a top-level `import { chromium } from "playwright"`.
+ * A target project like zsign-all installs its OWN real, separate copy of
+ * both `waygraph` and `playwright` (never a symlink - see
+ * `install-links=true`), so importing one of its `.block.ts` files pulls in
+ * a second, physically different `playwright` package - which Playwright's
+ * own runtime refuses outright ("Requiring @playwright/test second time"),
+ * crashing every single import. Confirmed empirically against all 117 real
+ * zsign-all Blocks - 100% failure rate, not a corner case.
+ *
+ * The fix: never let the two copies share a process. This script is
+ * written into the TARGET project directory and run as its own child
+ * process, so every bare `import("waygraph")` / `import("playwright")` it
+ * does resolves relative to ITS OWN location on disk - the target
+ * project's own `node_modules`, exclusively. This CLI's own copy never
+ * loads in that process at all.
+ */
+const CHAIN_RUNNER_SCRIPT = `
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+function walkDir(dir, pattern) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git") continue;
+      results.push(...walkDir(full, pattern));
+    } else if (pattern.test(entry.name)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function isBlockLike(val) {
+  if (val === null || typeof val !== "object") return false;
+  if (typeof val.name !== "string") return false;
+  if (val.instruction === null || typeof val.instruction !== "object") return false;
+  return typeof val.instruction.act === "function";
+}
+
+async function findBlock(projectDir, ref) {
+  const files = walkDir(projectDir, /\\.block\\.ts$/);
+  const byRuntimeName = [];
+  for (const file of files) {
+    let mod;
+    try {
+      mod = await import("file://" + file);
+    } catch {
+      continue;
+    }
+    for (const [exportName, exported] of Object.entries(mod)) {
+      if (!isBlockLike(exported)) continue;
+      if (exportName === ref) return { block: exported, exportName, file };
+      if (exported.name === ref) byRuntimeName.push({ block: exported, exportName, file });
+    }
+  }
+  if (byRuntimeName.length === 1) return byRuntimeName[0];
+  if (byRuntimeName.length > 1) {
+    throw new Error(
+      "waygraph chain: \\"" + ref + "\\" matches " + byRuntimeName.length + " Blocks by name - " +
+        byRuntimeName.map((b) => b.exportName + " (" + b.file + ")").join(", ") +
+        ". Use the export name to disambiguate.",
+    );
+  }
+  throw new Error("waygraph chain: no Block named \\"" + ref + "\\" found under " + projectDir);
+}
+
+function parseChainSpec(spec) {
+  return spec
+    .split(/\\bthen\\b/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => {
+      const m = /^([A-Za-z_$][\\w-]*)\\s*(?:\\(([\\s\\S]*)\\))?$/.exec(s);
+      if (!m) {
+        throw new Error(
+          "waygraph chain: could not parse segment \\"" + s + "\\" - expected \\"blockName\\" or \\"blockName({...json...})\\"",
+        );
+      }
+      const ref = m[1];
+      const json = m[2] ? m[2].trim() : undefined;
+      return json ? { ref, json } : { ref };
+    });
+}
+
+function seedMemForBlock(mem, resolved, json) {
+  const requires = resolved.block.requires ?? [];
+  if (requires.length === 0) {
+    if (json !== undefined) {
+      throw new Error(
+        "waygraph chain: \\"" + resolved.exportName + "\\" takes no input (empty requires) but got a payload: " + json,
+      );
+    }
+    return;
+  }
+  if (json === undefined) {
+    throw new Error(
+      "waygraph chain: \\"" + resolved.exportName + "\\" requires " + requires.map((k) => k.name).join(", ") +
+        " - give a JSON payload, e.g. " + resolved.exportName + "({...})",
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    throw new Error("waygraph chain: \\"" + resolved.exportName + "\\" payload is not valid JSON - " + String(err));
+  }
+  if (requires.length === 1) {
+    mem.set(requires[0], parsed);
+    return;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      "waygraph chain: \\"" + resolved.exportName + "\\" requires " + requires.length + " keys (" +
+        requires.map((k) => k.name).join(", ") + ") - payload must be an object keyed by each key's name",
+    );
+  }
+  for (const k of requires) {
+    if (!(k.name in parsed)) {
+      throw new Error("waygraph chain: \\"" + resolved.exportName + "\\" payload is missing required key \\"" + k.name + "\\"");
+    }
+    mem.set(k, parsed[k.name]);
+  }
+}
+
+async function main() {
+  const projectDir = process.argv[2];
+  const spec = process.argv[3];
+  const segments = parseChainSpec(spec);
+  if (segments.length === 0) {
+    throw new Error("waygraph chain: empty spec - give at least one block name");
+  }
+  const { connect, MemPage, Engine, start, end } = await import("waygraph");
+  const mem = new MemPage();
+  const resolved = [];
+  for (const seg of segments) {
+    const r = await findBlock(projectDir, seg.ref);
+    seedMemForBlock(mem, r, seg.json);
+    resolved.push(r);
+  }
+  console.log(
+    "waygraph: chaining " + resolved.map((r) => r.block.name).join(" -> ") +
+      " (" + resolved.length + " block" + (resolved.length === 1 ? "" : "s") + ")",
+  );
+  const blocks = resolved.map((r) => r.block);
+  const chained = blocks.reduce((a, b) => connect(a, b));
+  const headed = process.env.WAYGRAPH_HEADED === "1";
+  const slowMo = process.env.WAYGRAPH_SLOWMO ? Number(process.env.WAYGRAPH_SLOWMO) : undefined;
+  const baseURL = process.env.WAYGRAPH_BASE_URL;
+  const engine = new Engine({ headless: !headed, slowMo });
+  const flow = engine.defineFlow([start, chained, end]);
+  let result;
+  if (baseURL) {
+    const { chromium } = await import("playwright");
+    const browser = await chromium.launch({ headless: !headed, slowMo });
+    const context = await browser.newContext({ baseURL, viewport: { width: 1280, height: 720 } });
+    try {
+      result = await flow.run(context, mem);
+    } finally {
+      await browser.close();
+    }
+  } else {
+    result = await flow.run(mem);
+  }
+  console.log("waygraph: chain finished -- " + JSON.stringify(result));
+}
+
+main().catch((err) => {
+  console.error(err && err.stack ? err.stack : String(err));
+  process.exitCode = 1;
+});
+`;
+/**
+ * Runs the chain runner script as a child process rooted at `projectDir` -
+ * see {@link CHAIN_RUNNER_SCRIPT} for why this can't just be imported
+ * in-process. `WAYGRAPH_BASE_URL` (relative `page.goto()` targets, like
+ * every real zsign-all Block uses), `WAYGRAPH_HEADED=1`, and
+ * `WAYGRAPH_SLOWMO=<ms>` pass straight through from this process's own env.
+ */
+async function runChain(projectDir, spec) {
+    const tsxEsm = import.meta.resolve("tsx/esm");
+    const scriptPath = join(projectDir, `.waygraph-chain-${process.pid}.mjs`);
+    writeFileSync(scriptPath, CHAIN_RUNNER_SCRIPT);
+    try {
+        const code = await new Promise((res, rej) => {
+            const child = spawn(process.execPath, ["--import", tsxEsm, scriptPath, projectDir, spec], {
+                stdio: "inherit",
+                env: process.env,
+            });
+            child.on("error", rej);
+            child.on("exit", (code) => res(code ?? 1));
+        });
+        if (code !== 0) {
+            process.exitCode = code;
+        }
+    }
+    finally {
+        rmSync(scriptPath, { force: true });
+    }
+}
+async function validateFlows(projectDir) {
+    const files = discoverFlows(projectDir);
+    const results = [];
+    for (const file of files) {
+        try {
+            const mod = await importFlowFile(file);
+            for (const [exportName, exported] of Object.entries(mod)) {
+                if (isFlowLike(exported)) {
+                    results.push({ file, name: exportName, valid: true });
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            results.push({ file, name: basename(file, ".ts"), valid: false, error: msg });
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// `run`
+// ---------------------------------------------------------------------------
+async function runFlow(projectDir, flowName) {
+    const files = discoverFlows(projectDir);
+    for (const file of files) {
+        let mod;
+        try {
+            mod = await importFlowFile(file);
+        }
+        catch {
+            continue;
+        }
+        for (const [exportName, exported] of Object.entries(mod)) {
+            if (!isFlowLike(exported) || exportName !== flowName)
+                continue;
+            console.log(`waygraph: running flow "${flowName}" from ${relative(projectDir, file)}`);
+            const result = await exported.run(new MemPage());
+            console.log(`waygraph: flow finished -- ${JSON.stringify(result)}`);
+            return;
+        }
+    }
+    console.error(`waygraph: no flow named "${flowName}" found under ${projectDir}`);
+    process.exitCode = 1;
+}
+// ---------------------------------------------------------------------------
+// CLI plumbing
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+const command = args[0];
+function usage() {
+    console.log(`waygraph -- graph project tool + engine CLI
+
+Usage:
+  waygraph list    [project]      List discovered flows
+  waygraph nav     [flow] [project]  Print flow chain + navigation steps
+  waygraph validate [project]     Import and validate all flows
+  waygraph run <flow> [project]   Run a named flow
+  waygraph chain <spec> [project] Run one or more Blocks by name, ad hoc
+
+    "chain" needs no .flow.ts file - reference Blocks (by their own
+    runtime .name, or their export identifier) straight from the command
+    line, chained with "then", each optionally given a JSON payload for
+    whatever it requires:
+
+      waygraph chain "login({\\"email\\":\\"a@b.com\\",\\"password\\":\\"x\\"}) then overview-metrics"
+
+    A Block with no requires needs no payload. One with several required
+    keys takes one JSON object keyed by each key's own name instead of a
+    flat payload.
+
+    Runs in a child process rooted at "project" (its own waygraph/playwright,
+    never this CLI's) so a project's real Blocks resolve against its own
+    node_modules. Env vars, all optional:
+      WAYGRAPH_BASE_URL   base URL for Blocks using relative page.goto()
+      WAYGRAPH_HEADED=1   show the browser instead of headless
+      WAYGRAPH_SLOWMO=ms  slow down each Playwright action, for watching a run
+
+"project" defaults to the current directory.
+`);
+    process.exit(0);
+}
+async function main() {
+    if (!command || command === "--help" || command === "-h") {
+        usage();
+    }
+    switch (command) {
+        case "list": {
+            const proj = resolve(args[1] ?? process.cwd());
+            if (!existsSync(proj)) {
+                console.error(`waygraph: no such directory: ${proj}`);
+                process.exit(1);
+            }
+            listCommand(proj);
+            break;
+        }
+        case "nav": {
+            const flowName = args[1] && args[1] !== "." ? args[1] : undefined;
+            const proj = resolve(args[2] ?? process.cwd());
+            navCommand(proj, flowName);
+            break;
+        }
+        case "validate": {
+            const proj = resolve(args[1] ?? process.cwd());
+            const results = await validateFlows(proj);
+            let failed = 0;
+            for (const r of results) {
+                const rel = relative(proj, r.file);
+                if (r.valid) {
+                    console.log(`OK    ${rel}  ${r.name}`);
+                }
+                else {
+                    failed++;
+                    console.log(`FAIL  ${rel}  ${r.name} -- ${r.error}`);
+                }
+            }
+            if (failed > 0)
+                process.exitCode = 1;
+            break;
+        }
+        case "run": {
+            const flowName = args[1];
+            if (!flowName) {
+                console.error("waygraph run: missing <flow>, e.g. waygraph run LoginFlow");
+                process.exit(1);
+            }
+            const proj = resolve(args[2] ?? process.cwd());
+            await runFlow(proj, flowName);
+            break;
+        }
+        case "chain": {
+            const spec = args[1];
+            if (!spec) {
+                console.error('waygraph chain: missing <spec>, e.g. waygraph chain "login({...}) then overview-metrics"');
+                process.exit(1);
+            }
+            const proj = resolve(args[2] ?? process.cwd());
+            await runChain(proj, spec);
+            break;
+        }
+        default:
+            console.error(`waygraph: unknown command "${command}"`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

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;
@@ -69,6 +107,24 @@ type EndMarker = typeof end;
  */
 export interface Flow<Out extends Checkpoint<string>> {
     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 +143,50 @@ 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> {
+    /**
+     * 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. */

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,76 @@ 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 {
+        run: run,
         withBlockVerify(block, verify) {
             const index = findBlockIndex(middle, block);
             const patched = [...middle];
@@ -128,6 +195,28 @@ 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,
+        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

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 } 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.0.1",
+  "version": "0.1.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",