waygraph 0.0.1 → 0.2.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,37 @@ 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.
+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.
+
+```bash
+npx create-waygraph my-project && cd my-project && npm install && npm test
+```
+
+[`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, published on npm - the above runs a real green test with no manual edits.
 
-Deliberately **not yet implemented** (each tracked as its own future OpenSpec change,
-building on this one):
+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 +120,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 +175,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 +235,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 {};