waygraph 0.15.54 → 0.16.0

package/dist/manifest/project.js

@@ -0,0 +1,101 @@
+// Scans a project (and any injected Block libraries) into its Blocks and Flows, with each Block's route.
+import { relative } from "node:path";
+import { matchBlocksSelect } from "./select.js";
+import { exploreRoots, injectTaggedFile } from "./roots.js";
+import { blockKind, importFresh, isBlockLike, isFlowLike, walkDir } from "./scan.js";
+import { installedMapPackages, mapPackageBlockFiles } from "./maps.js";
+function kindOf(block) {
+    const kind = blockKind(block);
+    if (kind === "nav" || kind === "page" || kind === "assert" || kind === "api")
+        return kind;
+    const salt = block.__waygraphSalt;
+    if (salt === "effect" || salt === "method" || salt === "api")
+        return salt;
+    return "block";
+}
+/** A file that fails to import is left out of the scan, and said so: a silent skip reads as "nothing there". */
+export function reportImportError(relFile, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`waygraph: skip ${relFile}: ${msg.split("\n")[0]}`);
+}
+/** Imports every `*.block.ts` (and `*.flow.ts`) under the project and its injected roots. */
+export async function scanProject(projectDir, opts = {}) {
+    const select = opts.blocksSelect;
+    const onError = opts.onImportError ?? reportImportError;
+    const blocks = [];
+    const flows = [];
+    const skipped = [];
+    const scanBlockFile = async (absFile, rel, file, map) => {
+        let mod;
+        try {
+            mod = await importFresh(absFile);
+        }
+        catch (err) {
+            onError(rel, err);
+            return;
+        }
+        for (const [exportName, exported] of Object.entries(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            if (select && !matchBlocksSelect(select, { relFile: file, blockName: exported.name }))
+                continue;
+            const marked = exported;
+            const from = marked.__waygraphFrom ?? [];
+            const to = marked.__waygraphTo ?? [];
+            // Every factory records a route; only a bare defineBlock has none.
+            if (to.length === 0)
+                skipped.push({ block: exported.name, file, reason: "no route: build it with a define*Block factory and Checkpoint values" });
+            blocks.push({
+                block: exported,
+                name: exported.name,
+                exportName,
+                kind: kindOf(exported),
+                description: typeof exported.description === "string" ? exported.description : "",
+                from: [...from],
+                to: [...to],
+                requires: (exported.requires ?? []).map((k) => k.name),
+                file,
+                absFile,
+                ...(map ? { map } : {}),
+            });
+        }
+    };
+    for (const root of exploreRoots(projectDir, opts.inject)) {
+        let files = walkDir(root, /\.block\.ts$/);
+        if (select && select.kind !== "regex") {
+            files = files.filter((f) => matchBlocksSelect(select, { relFile: relative(root, f).replace(/\\/g, "/") }));
+        }
+        for (const absFile of files) {
+            const rel = relative(root, absFile).replace(/\\/g, "/");
+            await scanBlockFile(absFile, rel, injectTaggedFile(projectDir, root, rel));
+        }
+        if (opts.flows === false)
+            continue;
+        for (const absFile of walkDir(root, /\.flow\.ts$/)) {
+            const rel = relative(root, absFile).replace(/\\/g, "/");
+            let mod;
+            try {
+                mod = await importFresh(absFile);
+            }
+            catch (err) {
+                onError(rel, err);
+                continue;
+            }
+            for (const [exportName, exported] of Object.entries(mod)) {
+                if (isFlowLike(exported))
+                    flows.push({ flow: exported, exportName, file: injectTaggedFile(projectDir, root, rel), absFile });
+            }
+        }
+    }
+    if (opts.maps !== false) {
+        for (const pkg of installedMapPackages(projectDir)) {
+            for (const absFile of mapPackageBlockFiles(pkg)) {
+                const rel = relative(pkg.dir, absFile).replace(/\\/g, "/");
+                if (select && select.kind !== "regex" && !matchBlocksSelect(select, { relFile: `${pkg.name}/${rel}` }))
+                    continue;
+                await scanBlockFile(absFile, rel, `${pkg.name}/${rel}`, pkg.name);
+            }
+        }
+    }
+    return { projectDir, blocks, flows, skipped };
+}

package/dist/{session/block-inject.js → manifest/roots.js}

@@ -5,12 +5,9 @@
 import { existsSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 /**
  * This package's own installed root (contains `templates/`/`examples/`, sibling to `dist/`) -
- * this file compiles to `dist/session/block-inject.js`, two levels down, not one. Same class of
- * bug as `cli/util.ts`'s own `packageRoot()` (see its comment) - self-inflicted here by moving
- * this file into `src/session/` without updating the path math to match the new depth.
+ * this file compiles to `dist/manifest/roots.js`, two levels down.
  */
 function packageRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -32,20 +29,6 @@ export function injectTaggedFile(hostDir, root, relFile) {
 }
 const PRESETS = {
     saucedemo: () => join(packageRoot(), "examples", "saucedemo"),
-    demosauce: () => join(packageRoot(), "examples", "saucedemo"),
-    veciro: () => {
-        if (process.env.WAYGRAPH_INJECT_VECIRO) {
-            return resolve(process.env.WAYGRAPH_INJECT_VECIRO);
-        }
-        for (const c of [
-            join(homedir(), "Desktop", "Work", "veciro-waygraph"),
-            join(homedir(), "Desktop", "Projects", "veciro-waygraph"),
-        ]) {
-            if (existsSync(c))
-                return c;
-        }
-        return null;
-    },
 };
 /**
  * Resolve one `--inject` token to an absolute directory (preset name or path).

package/dist/manifest/scan.d.ts

@@ -0,0 +1,19 @@
+import type { Block } from "../engine/block/block.js";
+import type { Checkpoint } from "../engine/checkpoint/checkpoint.js";
+/** Every file under `dir` whose name matches, skipping `node_modules`, `dist` and `.git`. */
+export declare function walkDir(dir: string, pattern: RegExp): string[];
+/**
+ * Imports a project file. The file's mtime is part of the URL: Node caches an ESM import per specifier for the life of the
+ * process, so a long-running session reloading an edited Block would otherwise keep the first version.
+ */
+export declare function importFresh(filePath: string): Promise<Record<string, unknown>>;
+export type AnyBlock = Block<Checkpoint<string>, Checkpoint<string>> & {
+    description?: string;
+};
+export declare function isBlockLike(val: unknown): val is AnyBlock;
+export declare function isFlowLike(val: unknown): val is {
+    run: (...args: unknown[]) => Promise<unknown>;
+    blocks: () => unknown[];
+};
+/** The factory kind a Block was built with (`nav`, `page`, `assert`), or undefined for Methods and Effects. */
+export declare function blockKind(block: object): string | undefined;

package/dist/manifest/scan.js

@@ -0,0 +1,57 @@
+// The one place a project's files are walked and imported. Everything that needs the project's Blocks or Flows
+// (graph, check, map, auto, traverse, the runner) goes through here.
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+/** Every file under `dir` whose name matches, skipping `node_modules`, `dist` and `.git`. */
+export 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;
+}
+/**
+ * Imports a project file. The file's mtime is part of the URL: Node caches an ESM import per specifier for the life of the
+ * process, so a long-running session reloading an edited Block would otherwise keep the first version.
+ */
+export async function importFresh(filePath) {
+    const resolved = resolve(filePath);
+    const url = pathToFileURL(resolved);
+    url.searchParams.set("t", String(statSync(resolved).mtimeMs));
+    return (await import(url.href));
+}
+export function isBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    if (typeof obj.name !== "string")
+        return false;
+    const instruction = obj.instruction;
+    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
+}
+export function isFlowLike(val) {
+    return (val !== null &&
+        typeof val === "object" &&
+        typeof val.run === "function" &&
+        typeof val.blocks === "function");
+}
+/** The factory kind a Block was built with (`nav`, `page`, `assert`), or undefined for Methods and Effects. */
+export function blockKind(block) {
+    return block.__waygraphKind;
+}

package/dist/manifest/source.d.ts

@@ -0,0 +1,23 @@
+import type { SourceFile } from "ts-morph";
+/** The file as it is on disk now. */
+export declare function parseSource(file: string): SourceFile;
+/** Names the file exports: `export const|let|var|function|class X`, and `export { X }`. */
+export declare function exportedNames(sf: SourceFile): string[];
+/** Every module the file imports or re-exports from, including dynamic `import("x")`. */
+export declare function importSpecifiers(sf: SourceFile): string[];
+/** Names imported from modules whose specifier passes `from`, in source order (the imported name, not an alias). */
+export declare function namedImportsFrom(sf: SourceFile, from: (specifier: string) => boolean): string[];
+/** The string literal at `argIndex` of every call whose callee text passes `callee`, in source order. */
+export declare function stringArgs(sf: SourceFile, callee: (text: string) => boolean, argIndex?: number): string[];
+/** A string property of the object literal passed to every matching call: `Trait.url({ pathname: "/x" })` -> "/x". */
+export declare function objectArgProperty(sf: SourceFile, callee: (text: string) => boolean, property: string): string[];
+/** Every string literal in the file (comments are not strings), with the property name it initializes, if any. */
+export declare function stringLiterals(sf: SourceFile): {
+    value: string;
+    property: string | undefined;
+}[];
+/** Every call in the file (comments and strings are not calls): its callee as written and whether its first argument is a string. */
+export declare function calls(sf: SourceFile): {
+    callee: string;
+    literalFirstArg: boolean;
+}[];

package/dist/manifest/source.js

@@ -0,0 +1,86 @@
+// Reads a TypeScript file's shape (its exports, imports, string arguments) from the AST (ts-morph), for the places that
+// need it without importing the file: `list`, `nav`, a flow file's export name, a map group's imports.
+import { readFileSync } from "node:fs";
+import { Node, Project, SyntaxKind } from "ts-morph";
+const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+/** The file as it is on disk now. */
+export function parseSource(file) {
+    return project.createSourceFile(file.replace(/\\/g, "/").replace(/^[A-Za-z]:/, ""), readFileSync(file, "utf8"), { overwrite: true });
+}
+/** Names the file exports: `export const|let|var|function|class X`, and `export { X }`. */
+export function exportedNames(sf) {
+    const names = [];
+    for (const statement of sf.getStatements()) {
+        if (Node.isVariableStatement(statement) && statement.isExported())
+            names.push(...statement.getDeclarations().map((d) => d.getName()));
+        else if ((Node.isFunctionDeclaration(statement) || Node.isClassDeclaration(statement)) && statement.isExported() && statement.getName())
+            names.push(statement.getName());
+        else if (Node.isExportDeclaration(statement) && !statement.getModuleSpecifier())
+            names.push(...statement.getNamedExports().map((e) => e.getAliasNode()?.getText() ?? e.getName()));
+    }
+    return names;
+}
+/** Every module the file imports or re-exports from, including dynamic `import("x")`. */
+export function importSpecifiers(sf) {
+    const specs = [
+        ...sf.getImportDeclarations().map((d) => d.getModuleSpecifierValue()),
+        ...sf.getExportDeclarations().flatMap((d) => d.getModuleSpecifierValue() ?? []),
+    ];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const arg = call.getArguments()[0];
+        if (call.getExpression().getKind() === SyntaxKind.ImportKeyword && Node.isStringLiteral(arg))
+            specs.push(arg.getLiteralValue());
+    }
+    return specs;
+}
+/** Names imported from modules whose specifier passes `from`, in source order (the imported name, not an alias). */
+export function namedImportsFrom(sf, from) {
+    return sf
+        .getImportDeclarations()
+        .filter((d) => from(d.getModuleSpecifierValue()))
+        .flatMap((d) => d.getNamedImports().map((n) => n.getName()));
+}
+/** The string literal at `argIndex` of every call whose callee text passes `callee`, in source order. */
+export function stringArgs(sf, callee, argIndex = 0) {
+    const out = [];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!callee(call.getExpression().getText()))
+            continue;
+        const arg = call.getArguments()[argIndex];
+        if (Node.isStringLiteral(arg) || Node.isNoSubstitutionTemplateLiteral(arg))
+            out.push(arg.getLiteralValue());
+    }
+    return out;
+}
+/** A string property of the object literal passed to every matching call: `Trait.url({ pathname: "/x" })` -> "/x". */
+export function objectArgProperty(sf, callee, property) {
+    const out = [];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!callee(call.getExpression().getText()))
+            continue;
+        const arg = call.getArguments()[0];
+        const prop = Node.isObjectLiteralExpression(arg) ? arg.getProperty(property) : undefined;
+        const value = Node.isPropertyAssignment(prop) ? prop.getInitializer() : undefined;
+        if (Node.isStringLiteral(value) || Node.isNoSubstitutionTemplateLiteral(value))
+            out.push(value.getLiteralValue());
+    }
+    return out;
+}
+/** Every string literal in the file (comments are not strings), with the property name it initializes, if any. */
+export function stringLiterals(sf) {
+    const out = [];
+    for (const node of [...sf.getDescendantsOfKind(SyntaxKind.StringLiteral), ...sf.getDescendantsOfKind(SyntaxKind.NoSubstitutionTemplateLiteral)]) {
+        const parent = node.getParent();
+        if (Node.isImportDeclaration(parent) || Node.isExportDeclaration(parent))
+            continue;
+        out.push({ value: node.getLiteralValue(), property: Node.isPropertyAssignment(parent) && parent.getInitializer() === node ? parent.getName() : undefined });
+    }
+    return out;
+}
+/** Every call in the file (comments and strings are not calls): its callee as written and whether its first argument is a string. */
+export function calls(sf) {
+    return sf.getDescendantsOfKind(SyntaxKind.CallExpression).map((call) => {
+        const arg = call.getArguments()[0];
+        return { callee: call.getExpression().getText(), literalFirstArg: Node.isStringLiteral(arg) || Node.isTemplateExpression(arg) || Node.isNoSubstitutionTemplateLiteral(arg) };
+    });
+}

package/dist/runner/mode.d.ts

@@ -0,0 +1,71 @@
+import type { BrowserContext } from "@playwright/test";
+import type { Checkpoint } from "../engine/checkpoint/checkpoint.js";
+import type { EngineConfig } from "../engine/config.js";
+import type { MemPage } from "../engine/mem/mem.js";
+import type { DemoPace } from "../engine/stub/pace.js";
+import type { HighlightStyleDefaults } from "../engine/stub/ring.js";
+import type { WgPage } from "../demo/types.js";
+import type { SomeBlock } from "../engine/block/block.js";
+/** One Block to play, with what its flow says about it. */
+export interface PlayStep {
+    block: SomeBlock;
+    exportName: string;
+    /** The engine config of the flow it came from (its layouts apply when it runs). */
+    config: EngineConfig;
+    /** Set on a named flow's steps; ad hoc Block chains have no episodes. */
+    episodeNumber?: number | undefined;
+    episodeTitle?: string | undefined;
+    /** Clear cookies and storage before this step (a flow with `sessionReset`, chained after another). */
+    resetSession: boolean;
+    /** Seeds this segment's `--data` into mem; set on a segment's first step. */
+    seedMem?: (() => void) | undefined;
+    /** Set on a flow's last step when the flow is meant to fail (`map({ expectedFailure })`). */
+    expectedFailureReason?: string | undefined;
+    demoPace?: DemoPace | undefined;
+    highlightStyle?: HighlightStyleDefaults | undefined;
+    /** An inner step of an expanded fast-forward unit (`--ff-expand`). */
+    wasFastForward?: boolean | undefined;
+    ffSource?: string | undefined;
+}
+/** The browser everything plays in. */
+export interface PlaySession {
+    context: BrowserContext;
+    page: WgPage;
+    mem: MemPage;
+    baseURL: string | undefined;
+}
+/** How a step ended, for a mode's `failed` hook: it threw, or it landed on the branch its flow expects to fail on. */
+export type StepFailure = {
+    error: unknown;
+    result?: undefined;
+} | {
+    error?: undefined;
+    result: Checkpoint<string>;
+};
+export interface PlayOutcome {
+    ok: boolean;
+    result?: Checkpoint<string> | undefined;
+    /** The step that failed, when one did. */
+    failedAt?: {
+        index: number;
+        step: PlayStep;
+        error: unknown;
+    } | undefined;
+    /** Set when the run stopped where its flow expects to fail. */
+    expectedFailure?: {
+        step: PlayStep;
+        reason: string;
+    } | undefined;
+}
+/** A way of playing steps. Every hook is optional; with none, it is a plain Playwright run. */
+export interface Mode {
+    name: string;
+    begin?(steps: readonly PlayStep[]): Promise<void>;
+    /** After the page was reset between episodes. */
+    afterReset?(): Promise<void>;
+    before?(index: number): Promise<void>;
+    after?(index: number, result: Checkpoint<string>, ms: number): Promise<void>;
+    /** A step failed (or reached its expected failure): retry its episode, or stop. Without the hook: stop. */
+    failed?(index: number, failure: StepFailure, ms: number): Promise<"retry" | "stop">;
+    end?(outcome: PlayOutcome): Promise<void>;
+}

package/dist/runner/mode.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { Flow } from "../../engine/flow/flow.js";
+import type { PlayOptions } from "../options.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+export declare function playBranches(flows: readonly Flow<Checkpoint<string>>[], mem: MemPage, options: PlayOptions): Promise<void>;

package/dist/runner/modes/branches.js

@@ -0,0 +1,37 @@
+import { branchRoutes, runBranchRegression } from "../../engine/flow/branch-regression.js";
+import { extensionPathsFromEnv } from "../../runtime/browser.js";
+export async function playBranches(flows, mem, options) {
+    const flow = flows.length === 1 ? flows[0] : undefined;
+    if (!flow) {
+        console.error("waygraph run --all-branches: needs a single Flow reference (e.g. --blocks loginFlow), not a multi-segment chain spec - nothing else has one branch tree to explore.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!branchRoutes(flow)) {
+        console.error("waygraph run --all-branches: this Flow was not built with MapBuilder.branch() - there is no branch tree to explore. Run it normally instead.");
+        process.exitCode = 1;
+        return;
+    }
+    if (extensionPathsFromEnv().length > 0) {
+        console.warn("waygraph run --all-branches: extensions are not loaded (branches run in cloned contexts)");
+    }
+    const { chromium } = await import("@playwright/test");
+    const browser = await chromium.launch({ headless: !options.headed });
+    try {
+        const context = await browser.newContext(options.baseURL ? { baseURL: options.baseURL } : undefined);
+        const results = await runBranchRegression(flow, context, mem, { cloneSession: !options.sharedSession });
+        for (const r of results) {
+            console.log(`waygraph run --all-branches: ${r.path || "(root)"} -> ${r.status}` +
+                (r.result ? ` (${JSON.stringify(r.result)})` : "") +
+                (r.error ? ` - ${r.error}` : ""));
+        }
+        const failed = results.filter((r) => r.status === "failed");
+        if (failed.length) {
+            console.error(`waygraph run --all-branches: ${failed.length}/${results.length} path(s) failed`);
+            process.exitCode = 1;
+        }
+    }
+    finally {
+        await browser.close();
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { Mode, PlaySession, PlayStep } from "../mode.js";
+import type { PlayOptions } from "../options.js";
+export declare function demoMode(session: PlaySession, steps: readonly PlayStep[], options: PlayOptions, beat: number): Promise<Mode>;

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