waygraph 0.15.53 → 0.16.0

package/dist/runner/modes/demo.js

@@ -0,0 +1,13 @@
+// `waygraph demo`: the same steps, with the waygraph UI around each one (src/demo/stepper/).
+import { createStepper } from "../../demo/stepper/stepper.js";
+export async function demoMode(session, steps, options, beat) {
+    const stepper = await createStepper(session.page, session.mem, steps, { title: options.title, fastBlocks: options.fastBlocks, beat });
+    return {
+        name: "demo",
+        afterReset: stepper.afterReset,
+        before: stepper.before,
+        after: (index, result) => stepper.after(index, result),
+        failed: (index, failure) => stepper.failed(index, failure),
+        end: () => stepper.end(),
+    };
+}

package/dist/runner/modes/report.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, PlaySession } from "../mode.js";
+export declare function reportMode(session: PlaySession): Mode;

package/dist/runner/modes/report.js

@@ -0,0 +1,54 @@
+// `waygraph run` with WAYGRAPH_JSON=1: plays like `run` and prints one JSON report (each step's Checkpoint and time,
+// a screenshot on failure). `runId` names the matching `.waygraph/runs/<runId>.jsonl`.
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { currentRunId, recordArtifact } from "../../engine/run/events.js";
+export function reportMode(session) {
+    let steps = [];
+    const done = [];
+    let screenshot = null;
+    const message = (error) => (error instanceof Error ? error.message : String(error));
+    return {
+        name: "report",
+        async begin(all) {
+            steps = all;
+        },
+        async after(index, result, ms) {
+            done.push({ name: steps[index].block.name, checkpoint: result, ms });
+        },
+        async failed(index, failure, ms) {
+            const step = steps[index];
+            if (failure.result) {
+                done.push({ name: step.block.name, checkpoint: failure.result, ms });
+            }
+            else if (step.expectedFailureReason) {
+                done.push({ name: step.block.name, expectedFailure: true, error: message(failure.error), ms });
+            }
+            else {
+                screenshot = join(tmpdir(), "waygraph-chain-failure-" + Date.now() + ".png");
+                await session.page.screenshot({ path: screenshot, fullPage: true }).then(() => recordArtifact("screenshot", screenshot), () => (screenshot = null));
+            }
+            return "stop";
+        },
+        async end(outcome) {
+            const runId = currentRunId();
+            const report = outcome.failedAt
+                ? {
+                    runId,
+                    ok: false,
+                    failedAt: outcome.failedAt.step.block.name,
+                    stepIndex: outcome.failedAt.index,
+                    totalSteps: steps.length,
+                    error: message(outcome.failedAt.error),
+                    steps: done,
+                    screenshot,
+                }
+                : outcome.expectedFailure && outcome.result === undefined
+                    ? { runId, ok: true, expectedFailure: true, failedAt: outcome.expectedFailure.step.block.name, reason: outcome.expectedFailure.reason, steps: done }
+                    : { runId, ok: true, result: done.length > 0 ? done[done.length - 1].checkpoint : null, steps: done };
+            console.log(JSON.stringify(report, null, 2));
+            if (!report.ok)
+                process.exitCode = 1;
+        },
+    };
+}

package/dist/runner/modes/run.d.ts

@@ -0,0 +1,2 @@
+import type { Mode } from "../mode.js";
+export declare function runMode(): Mode;

package/dist/runner/modes/run.js

@@ -0,0 +1,3 @@
+export function runMode() {
+    return { name: "run" };
+}

package/dist/runner/options.d.ts

@@ -0,0 +1,31 @@
+import type { PlayStep } from "./mode.js";
+export type ModeName = "run" | "demo" | "report" | "branches";
+export interface PlayOptions {
+    mode: ModeName;
+    headed: boolean;
+    baseURL: string | undefined;
+    title: string | undefined;
+    /** Block names that skip the demo's added dwell (WAYGRAPH_FAST_BLOCKS). */
+    fastBlocks: Set<string>;
+    /** Clear the session before every step after the first (WAYGRAPH_CLEAR_SESSION). */
+    clearSession: boolean;
+    /** Record a video: the folder, or "1" for the default one. */
+    video: string | undefined;
+    videoViewport: string | undefined;
+    /** Expand fast-forward units into their inner steps (--ff-expand / --ff-disabled). */
+    ffExpand: boolean;
+    ffDisabled: boolean;
+    /** Fill missing `requires` from registerMemStub for every flow (--mem-stub). */
+    memStub: boolean;
+    /** --all-branches without cloning the session per branch. */
+    sharedSession: boolean;
+}
+export declare function readOptions(): PlayOptions;
+/**
+ * The slowMo for the browser launch and the demo's own beat after each action. The demo launches at 0 and paces
+ * itself, so a step's pace can remove the beat; a fast-forward unit in the steps drops the beat to 0.
+ */
+export declare function slowMoFor(options: PlayOptions, steps: readonly PlayStep[]): {
+    launch: number | undefined;
+    demoBeat: number;
+};

package/dist/runner/options.js

@@ -0,0 +1,42 @@
+// How to play, read once from the environment the CLI set (flags beat the config file, which beats these defaults).
+import { envFlag, envNumber, envString, envSwitch } from "../engine/env.js";
+function readMode() {
+    if (envFlag("WAYGRAPH_ALL_BRANCHES"))
+        return "branches";
+    if (envFlag("WAYGRAPH_JSON"))
+        return "report";
+    return envFlag("WAYGRAPH_STEP") ? "demo" : "run";
+}
+export function readOptions() {
+    const mode = readMode();
+    return {
+        mode,
+        // A manual demo is watched, so it is headed by default; WAYGRAPH_HEADED=0 (e.g. --auto-play-video) still wins.
+        headed: envSwitch("WAYGRAPH_HEADED", mode === "demo"),
+        baseURL: envString("WAYGRAPH_BASE_URL"),
+        title: envString("WAYGRAPH_TITLE"),
+        fastBlocks: new Set((envString("WAYGRAPH_FAST_BLOCKS") || "").split(",").map((s) => s.trim()).filter(Boolean)),
+        clearSession: envFlag("WAYGRAPH_CLEAR_SESSION"),
+        video: envString("WAYGRAPH_VIDEO"),
+        videoViewport: envString("WAYGRAPH_VIDEO_VIEWPORT"),
+        ffExpand: envFlag("WAYGRAPH_FF_EXPAND") || envFlag("WAYGRAPH_FF_DISABLED"),
+        ffDisabled: envFlag("WAYGRAPH_FF_DISABLED"),
+        memStub: envFlag("WAYGRAPH_MEM_STUB"),
+        sharedSession: envFlag("WAYGRAPH_SHARED_SESSION"),
+    };
+}
+/**
+ * The slowMo for the browser launch and the demo's own beat after each action. The demo launches at 0 and paces
+ * itself, so a step's pace can remove the beat; a fast-forward unit in the steps drops the beat to 0.
+ */
+export function slowMoFor(options, steps) {
+    const demo = options.mode === "demo";
+    const hasFastForward = steps.some((s) => s.block.fastForward === true || s.wasFastForward === true);
+    const slowMo = envNumber("WAYGRAPH_SLOWMO") ?? (demo ? (hasFastForward ? 0 : 350) : undefined);
+    if (demo && hasFastForward && envNumber("WAYGRAPH_SLOWMO") === undefined) {
+        console.error(options.ffDisabled
+            ? "waygraph demo: --ff-disabled (expanded) -> Playwright slowMo=0 on former FF steps (blitz; same acts as opaque FF)"
+            : "waygraph demo: opaque FFCompose in flow -> Playwright slowMo=0 (blitz); set WAYGRAPH_SLOWMO to override");
+    }
+    return { launch: demo ? 0 : slowMo, demoBeat: slowMo ?? 0 };
+}

package/dist/runner/plan/find.d.ts

@@ -0,0 +1,18 @@
+import type { AnyBlock } from "../../manifest/scan.js";
+import type { Flow } from "../../engine/flow/flow.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+export interface FoundBlock {
+    block: AnyBlock;
+    exportName: string;
+    file: string;
+}
+export declare function findBlock(projectDir: string, ref: string): Promise<FoundBlock>;
+/**
+ * Finds an already-defined Flow by its export name (e.g. loginFlow) among
+ * the project's *.flow.ts files - "I already have this wired up, just point
+ * the stepper at it, no chain spec to hand-write." Flows have no runtime
+ * .name of their own (unlike Blocks), so this only matches by export
+ * identifier. Returns null (not a throw) when nothing matches - the caller
+ * falls back to ordinary block-chain spec parsing.
+ */
+export declare function findFlow(projectDir: string, flowName: string): Promise<Flow<Checkpoint<string>> | null>;

package/dist/runner/plan/find.js

@@ -0,0 +1,65 @@
+// Finds a Block or Flow in the project (and its installed map packages) by export name or Block name.
+import { relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isBlockLike, walkDir } from "../../manifest/scan.js";
+/** A built Flow: what `map().end()` returns. */
+function isFlow(val) {
+    return val !== null && typeof val === "object" && typeof val.run === "function" && typeof val.blocks === "function";
+}
+import { installedMapPackages, mapPackageBlockFiles } from "../../manifest/maps.js";
+import { reportImportError } from "../../manifest/project.js";
+export async function findBlock(projectDir, ref) {
+    const files = [...walkDir(projectDir, /\.block\.ts$/), ...installedMapPackages(projectDir).flatMap(mapPackageBlockFiles)];
+    const byRuntimeName = [];
+    for (const file of files) {
+        let mod;
+        try {
+            mod = await import(pathToFileURL(file).href);
+        }
+        catch (err) {
+            reportImportError(relative(projectDir, file), err);
+            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);
+}
+/**
+ * Finds an already-defined Flow by its export name (e.g. loginFlow) among
+ * the project's *.flow.ts files - "I already have this wired up, just point
+ * the stepper at it, no chain spec to hand-write." Flows have no runtime
+ * .name of their own (unlike Blocks), so this only matches by export
+ * identifier. Returns null (not a throw) when nothing matches - the caller
+ * falls back to ordinary block-chain spec parsing.
+ */
+export async function findFlow(projectDir, flowName) {
+    const files = walkDir(projectDir, /\.flow\.ts$/);
+    for (const file of files) {
+        let mod;
+        try {
+            mod = await import(pathToFileURL(file).href);
+        }
+        catch (err) {
+            reportImportError(relative(projectDir, file), err);
+            continue;
+        }
+        const candidate = mod[flowName];
+        if (isFlow(candidate))
+            return candidate;
+    }
+    return null;
+}

package/dist/runner/plan/plan.d.ts

@@ -0,0 +1,11 @@
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { Flow } from "../../engine/flow/flow.js";
+import type { PlayStep } from "../mode.js";
+import type { PlayOptions } from "../options.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+export interface Plan {
+    steps: PlayStep[];
+    /** One Flow per segment (`--all-branches` needs exactly one). */
+    flows: Flow<Checkpoint<string>>[];
+}
+export declare function planSteps(projectDir: string, spec: string, mem: MemPage, options: PlayOptions): Promise<Plan>;

package/dist/runner/plan/plan.js

@@ -0,0 +1,97 @@
+import { buildFlow, chainFlow } from "../../engine/flow/flow.js";
+import { isFastForwardBlock } from "../../engine/block/compose.js";
+import { findBlock, findFlow } from "./find.js";
+import { seedMemForBlock, seedMemForFlow } from "./seed-mem.js";
+import { parseChainSpec } from "./spec.js";
+export async function planSteps(projectDir, spec, mem, options) {
+    const bareFlow = await findBareFlow(projectDir, spec);
+    const segments = bareFlow
+        ? [flowSegment(bareFlow, spec.trim(), undefined, mem, options)]
+        : await Promise.all(parseSegments(spec).map((seg) => resolveSegment(projectDir, seg, mem, options)));
+    const steps = stepsOf(segments, options, { episodes: !bareFlow });
+    if (options.mode !== "report")
+        announce(spec, steps, !!bareFlow, options);
+    return { steps, flows: segments.map((s) => s.flow) };
+}
+/** A spec that is just a name might be an existing Flow (`cartFlow`); then no chain spec is needed. */
+async function findBareFlow(projectDir, spec) {
+    const ref = spec.trim();
+    if (!/^[A-Za-z_$][\w]*$/.test(ref))
+        return undefined;
+    const flow = await findFlow(projectDir, ref);
+    return flow && typeof flow.blocks === "function" ? flow : undefined;
+}
+function parseSegments(spec) {
+    const segments = parseChainSpec(spec);
+    if (segments.length === 0)
+        throw new Error("waygraph chain: empty spec - give at least one block name");
+    return segments;
+}
+async function resolveSegment(projectDir, seg, mem, options) {
+    const flow = await findFlow(projectDir, seg.ref);
+    if (flow && typeof flow.blocks === "function")
+        return flowSegment(flow, seg.ref, seg.json, mem, options);
+    const found = await findBlock(projectDir, seg.ref);
+    if (!found)
+        throw new Error(`waygraph: no Block or Flow named "${seg.ref}"`);
+    return {
+        flow: buildFlow([found.block], {}),
+        ref: seg.ref,
+        named: false,
+        // A bare Block has no map({ memStub }) to opt in; only --mem-stub fills its keys.
+        seedMem: () => seedMemForBlock(mem, found, seg.json, options.memStub),
+    };
+}
+function flowSegment(flow, ref, json, mem, options) {
+    // seeded when the segment starts, not now: two segments may give the same key different values
+    const seedMem = () => seedMemForFlow(mem, flow.blocks(), json, ref, flow.memStub === true || options.memStub);
+    return { flow, ref, named: true, seedMem };
+}
+/** A fast-forward unit is one step, unless --ff-expand plays its inner Blocks one by one. */
+function expand(infos, options) {
+    if (!options.ffExpand)
+        return [...infos];
+    return infos.flatMap((info) => isFastForwardBlock(info.block)
+        ? info.block.steps().map((inner) => ({
+            ...inner,
+            ...(info.resetSessionBefore ? { resetSessionBefore: true } : {}),
+            wasFastForward: true,
+            ffSource: info.block.name,
+        }))
+        : [info]);
+}
+function stepsOf(segments, options, { episodes }) {
+    // chainFlow marks each segment's first Block when that segment wants a fresh session.
+    const resets = new Set(chainFlow(...segments.map((s) => s.flow)).blocks().filter((b) => b.resetSessionBefore).map((b) => b.block));
+    let episode = 0;
+    return segments.flatMap((segment) => {
+        const episodeNumber = episodes && segment.named ? ++episode : undefined;
+        const infos = expand(segment.flow.blocks(), options);
+        return infos.map((info, i) => ({
+            block: info.block,
+            exportName: info.name,
+            config: segment.flow.config,
+            episodeNumber,
+            episodeTitle: episodeNumber === undefined ? undefined : segment.ref,
+            resetSession: i === 0 && resets.has(segment.flow.blocks()[0]?.block),
+            seedMem: i === 0 ? segment.seedMem : undefined,
+            expectedFailureReason: i === infos.length - 1 ? segment.flow.expectedFailureReason : undefined,
+            demoPace: segment.flow.demoPace,
+            highlightStyle: segment.flow.highlightStyle,
+            ...(info.wasFastForward ? { wasFastForward: true, ffSource: info.ffSource } : {}),
+        }));
+    });
+}
+function announce(spec, steps, bare, options) {
+    const names = steps.map((s) => s.block.name).join(" -> ");
+    const count = steps.length + " block" + (steps.length === 1 ? "" : "s");
+    if (bare) {
+        console.log(`waygraph: running existing flow "${spec.trim()}" - ${names} (${count}, no chain spec needed)`);
+        if (options.ffDisabled) {
+            console.error("waygraph demo: --ff-disabled - FFCompose expanded to inners (dispute / step locus); blitz pacing kept on former FF steps");
+        }
+    }
+    else {
+        console.log(`waygraph: chaining ${names} (${count})`);
+    }
+}

package/dist/runner/plan/seed-mem.d.ts

@@ -0,0 +1,12 @@
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { BlockInfo } from "../../engine/flow/flow.js";
+import type { FoundBlock } from "./find.js";
+export declare function seedMemForBlock(mem: MemPage, resolved: FoundBlock, json: string | undefined, stubActive: boolean): void;
+/**
+ * Same idea as seedMemForBlock, but for a whole Flow segment
+ * ("loginFlow({...}) then ...") - a Flow has no single .requires of its
+ * own, so this unions every constituent Block's requires (deduped by key
+ * name) and seeds them all from one JSON payload, same keyed-by-name shape
+ * as a multi-key Block payload already uses.
+ */
+export declare function seedMemForFlow(mem: MemPage, flowBlocks: readonly BlockInfo[], json: string | undefined, label: string, stubActive: boolean): void;

package/dist/runner/plan/seed-mem.js

@@ -0,0 +1,98 @@
+import { getMemStub } from "../../engine/mem/mem-stub.js";
+import { envString } from "../../engine/env.js";
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+function seedMemFromRequires(mem, requires, json, label, stubActive) {
+    if (requires.length === 0) {
+        if (json !== undefined) {
+            throw new Error("waygraph chain: \"" + label + "\" takes no input (empty requires) but got a payload: " + json);
+        }
+        return;
+    }
+    if (json === undefined) {
+        // --data / WAYGRAPH_DATA supplies the same payload shape as blockName({...}).
+        const fromEnv = envString("WAYGRAPH_DATA");
+        if (fromEnv && fromEnv.trim())
+            json = fromEnv;
+    }
+    let parsed;
+    let haveParsed = false;
+    if (json !== undefined) {
+        try {
+            parsed = JSON.parse(json);
+            haveParsed = true;
+        }
+        catch (err) {
+            throw new Error("waygraph chain: \"" + label + "\" payload is not valid JSON - " + String(err));
+        }
+    }
+    if (!haveParsed) {
+        // No payload at all - only a hard failure when memStub isn't active for
+        // this flow; when it is, fall through with an empty object so the
+        // per-key loop below gets a chance to fill each one from the registry.
+        if (!stubActive) {
+            throw new Error("waygraph chain: \"" + label + "\" requires " + requires.map((k) => k.name).join(", ") +
+                " - give a JSON payload (inline blockName({...}) or --data '{...}'), or enable --mem-stub" +
+                " with registerMemStub for these keys");
+        }
+        parsed = {};
+    }
+    // Keyed-by-name when every require name is a top-level key (preferred for
+    // --data and for {"saucedemo.credentials":{...}} even with one require).
+    if (isRecord(parsed)) {
+        const payload = parsed;
+        if (requires.every((k) => k.name in payload)) {
+            for (const k of requires)
+                mem.set(k, payload[k.name]);
+            return;
+        }
+    }
+    // Single-key shorthand: the whole payload IS that one key's value - only
+    // when a real payload was actually given (the stub-only "{}" fallback
+    // above must fall through to per-key stub resolution instead).
+    if (haveParsed && requires.length === 1) {
+        mem.set(requires[0], parsed);
+        return;
+    }
+    if (!isRecord(parsed)) {
+        throw new Error("waygraph chain: \"" + label + "\" requires " + requires.length + " keys (" +
+            requires.map((k) => k.name).join(", ") + ") - payload must be an object keyed by each key's name");
+    }
+    const payload = parsed;
+    const stillMissing = [];
+    for (const k of requires) {
+        if (k.name in payload) {
+            mem.set(k, payload[k.name]);
+            continue;
+        }
+        const fake = stubActive ? getMemStub(k) : undefined;
+        if (fake) {
+            mem.set(k, fake());
+            continue;
+        }
+        stillMissing.push(k);
+    }
+    if (stillMissing.length > 0) {
+        throw new Error("waygraph chain: \"" + label + "\" payload is missing required key(s): " +
+            stillMissing.map((k) => "\"" + k.name + "\"").join(", "));
+    }
+}
+export function seedMemForBlock(mem, resolved, json, stubActive) {
+    seedMemFromRequires(mem, resolved.block.requires ?? [], json, resolved.exportName, stubActive);
+}
+/**
+ * Same idea as seedMemForBlock, but for a whole Flow segment
+ * ("loginFlow({...}) then ...") - a Flow has no single .requires of its
+ * own, so this unions every constituent Block's requires (deduped by key
+ * name) and seeds them all from one JSON payload, same keyed-by-name shape
+ * as a multi-key Block payload already uses.
+ */
+export function seedMemForFlow(mem, flowBlocks, json, label, stubActive) {
+    const seen = new Map();
+    for (const bi of flowBlocks) {
+        for (const k of bi.block.requires ?? []) {
+            if (!seen.has(k.name))
+                seen.set(k.name, k);
+        }
+    }
+    seedMemFromRequires(mem, Array.from(seen.values()), json, label, stubActive);
+}

package/dist/runner/plan/spec.d.ts

@@ -0,0 +1,5 @@
+/** Splits a spec into segments, each a Block or Flow name with optional inline JSON for its mem. */
+export declare function parseChainSpec(spec: string): {
+    ref: string;
+    json?: string;
+}[];

package/dist/runner/plan/spec.js

@@ -0,0 +1,17 @@
+// The CLI chain spec: "login then addToCart({...json...}) then checkoutFlow".
+/** Splits a spec into segments, each a Block or Flow name with optional inline JSON for its mem. */
+export 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 };
+    });
+}

package/dist/runner/play-steps.d.ts

@@ -0,0 +1,2 @@
+import type { Mode, PlayOutcome, PlaySession, PlayStep } from "./mode.js";
+export declare function playSteps(steps: readonly PlayStep[], session: PlaySession, mode: Mode, clearSession: boolean): Promise<PlayOutcome>;

package/dist/runner/play-steps.js

@@ -0,0 +1,59 @@
+import { buildFlow } from "../engine/flow/flow.js";
+import { resetPage } from "./session.js";
+/** Where a "retry" goes back to: the first step of this step's episode, or the start of an ad hoc chain. */
+function episodeStart(steps, index) {
+    const episode = steps[index].episodeNumber;
+    return episode === undefined ? 0 : steps.findIndex((s) => s.episodeNumber === episode);
+}
+/** Runs one Block through the engine, on the session's page, with its own flow's config. */
+async function runStep(step, session) {
+    const flow = buildFlow([step.block], step.config);
+    const { result } = await flow.run(session.context, session.mem, { page: session.page, closeOnFinish: false });
+    return result;
+}
+export async function playSteps(steps, session, mode, clearSession) {
+    await mode.begin?.(steps);
+    let outcome = { ok: true };
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        // A segment's --data is seeded when it starts, so two segments can give the same key different values.
+        step.seedMem?.();
+        if ((clearSession || step.resetSession) && i > 0) {
+            await resetPage(session);
+            await mode.afterReset?.();
+        }
+        await mode.before?.(i);
+        const startedAt = Date.now();
+        let result;
+        try {
+            result = await runStep(step, session);
+        }
+        catch (error) {
+            if ((await mode.failed?.(i, { error }, Date.now() - startedAt)) === "retry") {
+                await resetPage(session);
+                await mode.afterReset?.();
+                i = episodeStart(steps, i) - 1;
+                continue;
+            }
+            outcome = step.expectedFailureReason
+                ? { ok: true, expectedFailure: { step, reason: step.expectedFailureReason } }
+                : { ok: false, failedAt: { index: i, step, error } };
+            break;
+        }
+        outcome = { ok: true, result };
+        // A flow meant to fail can also end on its failure branch without throwing (a login that stays on the login page).
+        if (step.expectedFailureReason) {
+            if ((await mode.failed?.(i, { result }, Date.now() - startedAt)) === "retry") {
+                await resetPage(session);
+                await mode.afterReset?.();
+                i = episodeStart(steps, i) - 1;
+                continue;
+            }
+            outcome = { ok: true, result, expectedFailure: { step, reason: step.expectedFailureReason } };
+            break;
+        }
+        await mode.after?.(i, result, Date.now() - startedAt);
+    }
+    await mode.end?.(outcome);
+    return outcome;
+}

package/dist/runner/runner.d.ts

@@ -0,0 +1,4 @@
+import "../runtime/run-log.js";
+export declare function play(projectDir: string, spec: string): Promise<void>;
+/** The process entry the CLI's bootstrap calls: one run (and one run log) per invocation. */
+export declare function startRunner(): void;

package/dist/runner/runner.js

@@ -0,0 +1,64 @@
+// How `waygraph run` and `waygraph demo` play a flow. The CLI spawns this inside the project (so the project's own
+// Playwright is used) with the project dir and the spec ("cartFlow", "loginFlow then add-item"). Every mode plays the
+// same steps through the same engine; the mode decides what happens around each step.
+import { MemPage } from "../engine/mem/mem.js";
+import { beginRun, endRun } from "../engine/run/events.js";
+import { withWebServer } from "../runtime/webserver.js";
+import "../runtime/run-log.js";
+import { planSteps } from "./plan/plan.js";
+import { readOptions, slowMoFor } from "./options.js";
+import { openSession } from "./session.js";
+import { playSteps } from "./play-steps.js";
+import { playBranches } from "./modes/branches.js";
+import { runMode } from "./modes/run.js";
+import { demoMode } from "./modes/demo.js";
+import { reportMode } from "./modes/report.js";
+export async function play(projectDir, spec) {
+    const options = readOptions();
+    const mem = new MemPage();
+    const { steps, flows } = await planSteps(projectDir, spec, mem, options);
+    if (options.mode === "branches")
+        return playBranches(flows, mem, options);
+    const slowMo = slowMoFor(options, steps);
+    const { session, close } = await openSession(projectDir, options, mem, slowMo.launch);
+    let outcome;
+    try {
+        const mode = await pickMode(options, session, steps, slowMo.demoBeat);
+        outcome = await playSteps(steps, session, mode, options.clearSession);
+    }
+    finally {
+        await close();
+    }
+    if (options.mode !== "report")
+        finish(outcome);
+}
+function pickMode(options, session, steps, demoBeat) {
+    if (options.mode === "demo")
+        return demoMode(session, steps, options, demoBeat);
+    if (options.mode === "report")
+        return reportMode(session);
+    return runMode();
+}
+function finish(outcome) {
+    if (outcome.failedAt)
+        throw outcome.failedAt.error;
+    if (outcome.expectedFailure) {
+        const { step, reason } = outcome.expectedFailure;
+        console.log(`waygraph: chain finished (expected failure on ${step.block.name}) -- ${reason}`);
+    }
+    else {
+        console.log("waygraph: chain finished -- " + JSON.stringify(outcome.result));
+    }
+}
+/** The process entry the CLI's bootstrap calls: one run (and one run log) per invocation. */
+export function startRunner() {
+    const projectDir = process.argv[2] ?? process.cwd();
+    const spec = process.argv[3] ?? "";
+    const opened = beginRun(spec);
+    withWebServer(projectDir, () => play(projectDir, spec))
+        .then(() => endRun(opened, {}), (err) => {
+        endRun(opened, { error: err });
+        console.error(err && err.stack ? err.stack : String(err));
+        process.exitCode = 1;
+    });
+}

package/dist/runner/session.d.ts

@@ -0,0 +1,9 @@
+import type { MemPage } from "../engine/mem/mem.js";
+import type { PlaySession } from "./mode.js";
+import type { PlayOptions } from "./options.js";
+export declare function openSession(projectDir: string, options: PlayOptions, mem: MemPage, launchSlowMo: number | undefined): Promise<{
+    session: PlaySession;
+    close: () => Promise<void>;
+}>;
+/** A fresh session between episodes: no cookies, no storage, back on the base URL (so the page itself looks fresh too). */
+export declare function resetPage(session: PlaySession): Promise<void>;