waygraph 0.7.1 → 0.7.2

package/README.md

@@ -80,7 +80,22 @@ takes a structured `URLPatternInit` (`{ pathname, hostname, search, hash, ... }`
 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`/
+separate flag needed for that. A hand-written `Trait` isn't limited to the page, either - its
+`check(page, mem)` receives `mem` too, for the same-Checkpoint case: an action that doesn't
+navigate anywhere at all (clicking "+" to bump a cart item's quantity, say) has `In === Out`,
+which `defineBlock`/`defineFlow` already accept with no special-casing - `act()` updates `mem`
+alongside the real click (`mem.set(Quantity, mem.get(Quantity) + 1)`), and a bespoke `verify`
+Trait confirms the page's own displayed value actually matches what `mem` now expects
+(`shown === String(mem.get(Quantity))`), not just that *some* number is showing. `resolve()`
+itself stays exactly as pure as ever - it never sees `mem`, only `verify` does. `verify` only
+ever confirms what a Block itself just did, though - nothing previously checked whether the
+page was STILL there by the time the NEXT Block's `act()` starts. A `precondition` (same
+`Trait[]`/`(input) => Trait[]` shape as `verify`, checked automatically by `connect()`/
+`runGraph` right before `act()` runs, never called directly) closes that gap: a session
+timeout, a redirect, an interstitial popup - anything that changes the page in the moment
+between one Block finishing and the next one starting - fails loud with a clear "trait X
+failed before Y," instead of a confusing error deep inside `act()` trying to click something
+that's no longer there. 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. `composeBlock(name, steps)`
@@ -135,6 +150,11 @@ npx create-waygraph my-project && cd my-project && npm install && npm test
 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.
 
+**Consumer layout (Next.js App Router):** block folders mirror `app/` page routes (`/`
+at the namespace root; no invented `landing/`/`root/`; sidebar = chrome + edges). See
+`create-waygraph/README.md` "Consumer layout" and mesh handout
+`WAYGRAPH-CONSUMER-CONVENTION.md` - separate from this package API doc.
+
 Deliberately **not yet implemented** (tracked on the project board):
 - Interstitials/Watchers - background overlay handling (cookie banners, popups).
 

package/dist/engine.js

@@ -1,7 +1,7 @@
 import { chromium, firefox, webkit } from "@playwright/test";
 import { connect, checkpoint } from "./types.js";
 import { MemPage } from "./mem-page.js";
-import { runVerify } from "./trait.js";
+import { runVerify, runPrecondition } from "./trait.js";
 const LAUNCHERS = { chromium, firefox, webkit };
 /**
  * Resolves which `BrowserType` actually launches for a `mem`-only run (no
@@ -64,6 +64,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             if (++steps > maxSteps) {
                 throw new Error(`runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`);
             }
+            await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
             await current.instruction.act(page, input, mem);
             const observed = current.instruction.observe
                 ? await current.instruction.observe(page, mem)

package/dist/trait.d.ts

@@ -60,3 +60,13 @@ export declare const Trait: {
  * directly.
  */
 export declare function runVerify<Out>(verify: Trait[] | ((out: Out) => Trait[]) | undefined, out: Out, page: Page, mem: MemPage, blockName: string): Promise<void>;
+/**
+ * Runs every Trait for a Block that's ABOUT to run, throwing on the first
+ * failure with the failing Trait's own name and the Block's name - before
+ * `act` ever touches the page, not after. `precondition` may be a flat list
+ * or a function of the incoming Checkpoint (same shape `verify` already
+ * takes of the resolved one). Called automatically by `connect()`/`runGraph`
+ * right before a Block's own `act` - not something a Block normally calls
+ * directly.
+ */
+export declare function runPrecondition<In>(precondition: Trait[] | ((input: In) => Trait[]) | undefined, input: In, page: Page, mem: MemPage, blockName: string): Promise<void>;

package/dist/trait.js

@@ -78,3 +78,20 @@ export async function runVerify(verify, out, page, mem, blockName) {
         }
     }
 }
+/**
+ * Runs every Trait for a Block that's ABOUT to run, throwing on the first
+ * failure with the failing Trait's own name and the Block's name - before
+ * `act` ever touches the page, not after. `precondition` may be a flat list
+ * or a function of the incoming Checkpoint (same shape `verify` already
+ * takes of the resolved one). Called automatically by `connect()`/`runGraph`
+ * right before a Block's own `act` - not something a Block normally calls
+ * directly.
+ */
+export async function runPrecondition(precondition, input, page, mem, blockName) {
+    const traits = typeof precondition === "function" ? precondition(input) : (precondition ?? []);
+    for (const trait of traits) {
+        if (!(await trait.check(page, mem))) {
+            throw new Error(`trait "${trait.name}" failed before "${blockName}"`);
+        }
+    }
+}

package/dist/types.d.ts

@@ -54,6 +54,19 @@ export type ActionPage = Omit<Page, "goto" | "reload" | "goBack" | "goForward">
 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. Runs once, right before `act` starts - confirms the page is
+     * still in the state this Block is about to assume, before touching it.
+     * `verify` only ever confirms what a Block ITSELF just did; nothing
+     * previously checked whether the page is STILL there by the time the
+     * NEXT Block starts (a redirect, a popup, a session timeout between two
+     * Blocks - the gap `verify` alone can't see, since it only ever runs
+     * right after the PREVIOUS Block's own resolve, not right before THIS
+     * one's act). A function form picks different checks per incoming `In`,
+     * same as `verify` does per resolved `Out`.
+     * @example precondition: [Trait.visible("#checkout-form")]
+     */
+    precondition?: Trait[] | ((input: In) => Trait[]);
     /**
      * Optional. Gathers evidence for `resolve` to classify, runs assertions,
      * writes memory - the only phase allowed to look at the DOM before a

package/dist/types.js

@@ -1,4 +1,4 @@
-import { runVerify } from "./trait.js";
+import { runVerify, runPrecondition } from "./trait.js";
 /**
  * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
  * @example resolve: () => checkpoint("LoggedIn")
@@ -21,12 +21,14 @@ export function connect(a, b) {
         ...(requires.length > 0 ? { requires } : {}),
         instruction: {
             async act(page, input, mem) {
+                await runPrecondition(a.instruction.precondition, input, page, mem, a.name);
                 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 runPrecondition(b.instruction.precondition, mid, page, mem, b.name);
                 await b.instruction.act(page, mid, mem);
             },
             resolve: (observed) => b.instruction.resolve(observed),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",