waygraph 0.15.54 → 0.16.1

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

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})`);
+    }
+}