waygraph 0.3.2 → 0.4.0

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserContext, Page } from "@playwright/test";
+import type { BrowserContext, Page, Locator } from "@playwright/test";
 import type { Block, Checkpoint, Instruction, DefinedBlock } from "./types.js";
 import { MemPage } from "./mem-page.js";
 import type { Trait } from "./trait.js";
@@ -68,6 +68,24 @@ export interface RunGraphOptions {
  * }
  */
 export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, page: Page, mem: MemPage, maxSteps?: number): Promise<TOut>;
+/**
+ * Wraps one `act()` interaction with a caption and highlight, for a Block
+ * author who wants to explicitly narrate a specific step rather than rely
+ * on the generic per-fill/per-click narration `waygraph chain
+ * WAYGRAPH_STEP=1` already does automatically -
+ * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
+ * reads at the call site instead of being inferred.
+ *
+ * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
+ * for a `window.__wgPositionRing` hook the step-mode overlay installs on
+ * the page before doing anything, so a headless/CI/automated run (nobody
+ * watching, per-character delays and highlight pauses would just be wasted
+ * time) pays zero extra cost - not even the boundingBox() lookup runs. The
+ * `action` itself always runs regardless; only the narration is
+ * conditional.
+ * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
+ */
+export declare function narrate<T>(locator: Locator, caption: string, action: () => Promise<T>): Promise<T>;
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export declare const start: unique symbol;
 export declare const end: unique symbol;
@@ -117,6 +135,14 @@ export interface BlockInfo {
     name: string;
     /** `branch()`'s routing table, if this Block has one - see {@link Block.routes}. */
     routes?: Readonly<Record<string, string | null>>;
+    /**
+     * True when {@link chainFlow} inserted a session-reset boundary
+     * immediately before this Block - i.e. this is the first Block of a
+     * sub-flow that was wrapped in {@link withSessionReset}, and it isn't
+     * the very first sub-flow in the chain. Absent (not just false) from
+     * `Flow.blocks()` on an ordinary, non-chained Flow.
+     */
+    resetSessionBefore?: boolean;
     /**
      * The actual Block, re-runnable on its own via
      * `engine.defineFlow([start, info.block, end])` - e.g. step-through
@@ -127,6 +153,22 @@ export interface BlockInfo {
     block: Block<any, any>;
 }
 export interface Flow<Out extends Checkpoint<string>> {
+    /**
+     * True once this Flow has been wrapped in {@link withSessionReset} - a
+     * hint for `chainFlow`, not something `run()` itself checks: it marks
+     * this Flow as one that expects to start from a genuinely fresh,
+     * unauthenticated browser state (e.g. a login flow meant to be
+     * re-entered later in a longer chain). `chainFlow` clears cookies and
+     * storage right before this Flow's first Block runs, but only when this
+     * Flow isn't the very first thing in the chain (nothing to reset yet).
+     */
+    readonly resetSession: boolean;
+    /**
+     * Set once this Flow has been wrapped in {@link withTitle} - a display
+     * hint for a step-through overlay/showcase (e.g. "Ticket #123"), not
+     * something `run()` itself uses.
+     */
+    readonly title?: string;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -170,6 +212,49 @@ export interface Flow<Out extends Checkpoint<string>> {
      */
     modBlockVerify(block: Block<any, any> | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): Flow<Out>;
 }
+/**
+ * Marks a Flow as expecting to start from a genuinely fresh, unauthenticated
+ * browser state - e.g. a login flow meant to be re-entered later in a longer
+ * showcase. Non-destructive, same pattern as {@link withVerify}: returns a
+ * new Flow: the original is untouched, and the flag survives any further
+ * `withBlockVerify`/`modBlockVerify` patch applied to the result.
+ *
+ * By itself this does nothing - `Flow.run()` never reads `resetSession`.
+ * It's a hint {@link chainFlow} looks for: right before this Flow's first
+ * Block runs (skipped if it's the very first thing in the chain - nothing
+ * to reset yet), chainFlow clears cookies and storage so this Flow starts
+ * exactly as if a human had opened the app fresh, not wherever the
+ * previous Flow in the chain happened to leave the page.
+ * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
+ */
+export declare function withSessionReset<Out extends Checkpoint<string>>(flow: Flow<Out>): Flow<Out>;
+/**
+ * Names a Flow for display - a step-through overlay/showcase (waygraph's
+ * `chain --step`) shows this as the running banner while this Flow's own
+ * Blocks are executing, instead of one fixed title for the whole run.
+ * Non-destructive, same pattern as {@link withSessionReset}.
+ * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
+ */
+export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
+/**
+ * Runs several complete, independent Flows one after another, reusing the
+ * same page/context/mem in order - each remains its own validated
+ * start-to-end unit (a Flow's own `[start, ...blocks, end]` contract is
+ * untouched), this only sequences whole Flows. Deliberately NOT the same
+ * thing as {@link composeBlock}: composeBlock nests several Blocks into
+ * one Block that can drop back into another `defineFlow([...])` - a
+ * chainFlow result is a Flow, but not meant to be nested inside another
+ * Flow's own Block list. Recursive nesting stays composeBlock's job alone;
+ * chainFlow is a flat, one-level sequencing of complete showcases (e.g.
+ * "ticket #123 end to end, then ticket #456 end to end").
+ *
+ * A sub-flow wrapped in {@link withSessionReset} gets its cookies/storage
+ * cleared right before it runs (skipped for the very first flow in the
+ * chain - nothing to reset yet). The combined result is whatever the LAST
+ * flow resolved to.
+ * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
+ */
+export declare function chainFlow(...flows: readonly Flow<any>[]): Flow<any>;
 /**
  * A Block guaranteed to have `withStepVerify`/`modStepVerify` attached - what
  * {@link composeBlock} returns. Extends plain `Block`, so it drops straight into

package/dist/engine.js

@@ -92,6 +92,93 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
 export async function spawnTab(entry, page, mem, maxSteps = 5000) {
     return runGraph(entry, undefined, page.context(), mem, maxSteps);
 }
+/**
+ * Wraps one `act()` interaction with a caption and highlight, for a Block
+ * author who wants to explicitly narrate a specific step rather than rely
+ * on the generic per-fill/per-click narration `waygraph chain
+ * WAYGRAPH_STEP=1` already does automatically -
+ * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
+ * reads at the call site instead of being inferred.
+ *
+ * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
+ * for a `window.__wgPositionRing` hook the step-mode overlay installs on
+ * the page before doing anything, so a headless/CI/automated run (nobody
+ * watching, per-character delays and highlight pauses would just be wasted
+ * time) pays zero extra cost - not even the boundingBox() lookup runs. The
+ * `action` itself always runs regardless; only the narration is
+ * conditional.
+ * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
+ */
+export async function narrate(locator, caption, action) {
+    const page = locator.page();
+    const active = await page
+        .evaluate(() => typeof globalThis.__wgPositionRing === "function")
+        .catch(() => false);
+    if (!active)
+        return action();
+    let owning = false;
+    try {
+        const box = await locator.boundingBox();
+        if (box) {
+            await page
+                .evaluate(({ box, caption }) => {
+                const w = globalThis;
+                if (w.__wgPositionRing)
+                    w.__wgPositionRing(box, caption);
+                // The CLI's own automatic per-fill/per-click narration checks
+                // this before showing (and overwriting) its own guess - an
+                // explicitly authored caption should win, not get immediately
+                // replaced a moment later by the generic one.
+                w.__wgLastNarrate = Date.now();
+                // Also claim the ring itself: the auto-highlight click/fill
+                // patches each hide the ring right after THEIR own step
+                // finishes, which - if action() below does more than one thing
+                // (e.g. a click then a wait for a toast) - would wipe this
+                // caption after just the first sub-step instead of the whole
+                // narrated action. Their hideRing() calls no-op while this is
+                // true; narrate() below is the one that actually clears it.
+                w.__wgNarrateOwnsRing = true;
+            }, { box, caption })
+                .catch(() => { });
+            owning = true;
+            // The ring alone is pointless if action() fires on the very next
+            // tick - a click that navigates (e.g. a form submit) wipes the ring
+            // before a human can read the caption at all. Give it the same
+            // "pop for a few seconds" dwell as the CLI's own auto-highlight
+            // clicks before the real action runs.
+            await new Promise((resolve) => setTimeout(resolve, 650));
+            // Re-stamp __wgLastNarrate right before handing off to action() - the
+            // CLI's auto-highlight patches only treat a narrate() as "just
+            // handled" within a short window (500ms), which the dwell above
+            // already burned through. Without this, action()'s own click/fill
+            // (same patched Locator prototype) would stomp this caption with its
+            // own generic one a moment after it finally became visible.
+            await page
+                .evaluate(() => {
+                globalThis.__wgLastNarrate = Date.now();
+            })
+                .catch(() => { });
+        }
+    }
+    catch {
+        // best-effort - the real action below still runs either way
+    }
+    try {
+        return await action();
+    }
+    finally {
+        if (owning) {
+            await page
+                .evaluate(() => {
+                const w = globalThis;
+                w.__wgNarrateOwnsRing = false;
+                if (w.__wgHideRing)
+                    w.__wgHideRing();
+            })
+                .catch(() => { });
+        }
+    }
+}
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export const start = Symbol("waygraph.start");
 export const end = Symbol("waygraph.end");
@@ -110,6 +197,11 @@ function findBlockIndex(middle, block) {
     return index;
 }
 function buildFlow(middle, engineConfig) {
+    // resetSession/title start false/unset here - defineFlow itself carries
+    // no such options anymore. They're set by wrapping the result in
+    // withSessionReset()/withTitle() instead (non-destructive decorators,
+    // same pattern as withVerify), which also re-apply themselves after any
+    // further withBlockVerify/modBlockVerify patch so the flag survives.
     const chain = middle.reduce((a, b) => connect(a, b));
     // Declared separately (not as the object-literal method below) so the
     // three-overload `Flow.run` signature can be checked against the actual
@@ -180,6 +272,7 @@ function buildFlow(middle, engineConfig) {
         return result;
     };
     return {
+        resetSession: false,
         blocks: () => middle.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
         run: run,
         withBlockVerify(block, verify) {
@@ -196,6 +289,166 @@ function buildFlow(middle, engineConfig) {
         },
     };
 }
+/**
+ * Marks a Flow as expecting to start from a genuinely fresh, unauthenticated
+ * browser state - e.g. a login flow meant to be re-entered later in a longer
+ * showcase. Non-destructive, same pattern as {@link withVerify}: returns a
+ * new Flow: the original is untouched, and the flag survives any further
+ * `withBlockVerify`/`modBlockVerify` patch applied to the result.
+ *
+ * By itself this does nothing - `Flow.run()` never reads `resetSession`.
+ * It's a hint {@link chainFlow} looks for: right before this Flow's first
+ * Block runs (skipped if it's the very first thing in the chain - nothing
+ * to reset yet), chainFlow clears cookies and storage so this Flow starts
+ * exactly as if a human had opened the app fresh, not wherever the
+ * previous Flow in the chain happened to leave the page.
+ * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
+ */
+export function withSessionReset(flow) {
+    return {
+        ...flow,
+        resetSession: true,
+        withBlockVerify: (block, verify) => withSessionReset(flow.withBlockVerify(block, verify)),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withSessionReset(flow.modBlockVerify(block, nameOrIndex, newCheck)),
+    };
+}
+/**
+ * Names a Flow for display - a step-through overlay/showcase (waygraph's
+ * `chain --step`) shows this as the running banner while this Flow's own
+ * Blocks are executing, instead of one fixed title for the whole run.
+ * Non-destructive, same pattern as {@link withSessionReset}.
+ * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
+ */
+export function withTitle(flow, title) {
+    return {
+        ...flow,
+        title,
+        withBlockVerify: (block, verify) => withTitle(flow.withBlockVerify(block, verify), title),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
+    };
+}
+function locateInChain(flows, block) {
+    if (typeof block === "number") {
+        let remaining = block;
+        for (let fi = 0; fi < flows.length; fi++) {
+            const len = flows[fi].blocks().length;
+            if (remaining < len)
+                return { flowIndex: fi, localIndex: remaining };
+            remaining -= len;
+        }
+        throw new Error(`chainFlow: no Block at index ${block} across ${flows.length} chained flows`);
+    }
+    const blockName = typeof block === "string" ? block : block.name;
+    for (let fi = 0; fi < flows.length; fi++) {
+        const localIndex = flows[fi].blocks().findIndex((bi) => bi.name === blockName);
+        if (localIndex !== -1)
+            return { flowIndex: fi, localIndex };
+    }
+    throw new Error(`chainFlow: no Block named "${blockName}" in any chained flow`);
+}
+async function clearSessionState(context, page) {
+    await context.clearCookies().catch(() => { });
+    await page
+        .evaluate(() => {
+        try {
+            localStorage.clear();
+            sessionStorage.clear();
+        }
+        catch {
+            /* storage blocked (e.g. about:blank) - nothing to clear anyway */
+        }
+    })
+        .catch(() => { });
+}
+/**
+ * Runs several complete, independent Flows one after another, reusing the
+ * same page/context/mem in order - each remains its own validated
+ * start-to-end unit (a Flow's own `[start, ...blocks, end]` contract is
+ * untouched), this only sequences whole Flows. Deliberately NOT the same
+ * thing as {@link composeBlock}: composeBlock nests several Blocks into
+ * one Block that can drop back into another `defineFlow([...])` - a
+ * chainFlow result is a Flow, but not meant to be nested inside another
+ * Flow's own Block list. Recursive nesting stays composeBlock's job alone;
+ * chainFlow is a flat, one-level sequencing of complete showcases (e.g.
+ * "ticket #123 end to end, then ticket #456 end to end").
+ *
+ * A sub-flow wrapped in {@link withSessionReset} gets its cookies/storage
+ * cleared right before it runs (skipped for the very first flow in the
+ * chain - nothing to reset yet). The combined result is whatever the LAST
+ * flow resolved to.
+ * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
+ */
+export function chainFlow(...flows) {
+    if (flows.length === 0) {
+        throw new Error("chainFlow: give at least one Flow");
+    }
+    const run = async function run(contextOrMem, memOrConfig, options) {
+        if (contextOrMem instanceof MemPage) {
+            const mem = contextOrMem;
+            const config = memOrConfig;
+            // One browser for the WHOLE chain - each sub-flow's own run(mem,
+            // config) would otherwise each launch a separate browser, defeating
+            // the point of sequencing them (a fresh browser is itself a full
+            // session reset, silently making withSessionReset a no-op).
+            const browserName = config?.browserName ?? "chromium";
+            const launch = LAUNCHERS[browserName];
+            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 run(context, mem, { closeOnFinish: true });
+            }
+            finally {
+                await browser.close();
+            }
+        }
+        const context = contextOrMem;
+        const mem = memOrConfig;
+        const gotOwnPage = options?.page === undefined;
+        const page = options?.page ?? (await context.newPage());
+        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
+        let result;
+        for (let i = 0; i < flows.length; i++) {
+            const flow = flows[i];
+            if (i > 0 && flow.resetSession) {
+                await clearSessionState(context, page);
+            }
+            const outcome = (await flow.run(context, mem, { page, closeOnFinish: false }));
+            result = outcome.result;
+        }
+        if (closeOnFinish) {
+            await page.close();
+        }
+        if (options?.closeOnFinish === false) {
+            return { result, page };
+        }
+        return result;
+    };
+    return {
+        resetSession: false,
+        blocks: () => flows.flatMap((flow, idx) => flow.blocks().map((bi, i) => ({
+            ...bi,
+            ...(i === 0 && idx > 0 && flow.resetSession ? { resetSessionBefore: true } : {}),
+        }))),
+        run: run,
+        withBlockVerify(block, verify) {
+            const { flowIndex, localIndex } = locateInChain(flows, block);
+            const patched = [...flows];
+            patched[flowIndex] = patched[flowIndex].withBlockVerify(localIndex, verify);
+            return chainFlow(...patched);
+        },
+        modBlockVerify(block, nameOrIndex, newCheck) {
+            const { flowIndex, localIndex } = locateInChain(flows, block);
+            const patched = [...flows];
+            patched[flowIndex] = patched[flowIndex].modBlockVerify(localIndex, nameOrIndex, newCheck);
+            return chainFlow(...patched);
+        },
+    };
+}
 export function composeBlock(name, steps) {
     if (steps.length === 0) {
         throw new Error(`composeBlock: "${name}" needs at least one step`);

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, composeBlock, preflight, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, composeBlock, preflight, withSessionReset, withTitle, chainFlow, } from "./engine.js";

package/package.json

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