waygraph 0.15.53 → 0.16.0

package/dist/core/flow.d.ts

@@ -1,293 +0,0 @@
-import type { Block, Checkpoint } from "../types.js";
-import type { RunGraphOptions } from "./run-graph.js";
-import type { EngineConfig } from "./config.js";
-import type { BrowserContext, Page } from "@playwright/test";
-import { MemPage } from "../mem-page.js";
-import type { Trait } from "../trait.js";
-import type { DemoPace, HighlightStyleDefaults } from "../highlights.js";
-/**
- * A composed, runnable flow. Always begins from Checkpoint<"__start__">, same as
- * runGraph's `entry`. `run(context, mem)` uses a context you already have (the
- * usual case inside a `@playwright/test` file, via its `context` fixture) -
- * there's no browser for this Flow to launch, so no config to pass. `run(mem,
- * config?)` - no context - has the Engine launch and own its own browser for
- * this one run instead, and closes it in `finally`; use this outside a
- * Playwright test file, or when a flow genuinely needs its own browser instance
- * rather than sharing the test's. `config` here overrides, per key, whatever
- * `new Engine(...)` was constructed with - so one flow (module-level, imported
- * by many specs) can still have every run choose its own `headless`/`slowMo`
- * rather than being stuck with whatever the flow's own file happened to set.
- *
- * `withBlockVerify`/`modBlockVerify` do what {@link withVerify}/{@link modVerify}
- * do for a single Block, one level up - a spec that only imports the finished
- * Flow (not necessarily the individual Blocks it was built from) can still
- * patch one Block's verify for just that call, without editing the flow's own
- * file or hand-rebuilding its Block list. Addressed the same three ways
- * `modVerify` already addresses a Trait - the Block reference itself
- * (`LoginBlock`, imported like any other Block; typo-proof, refactor-safe,
- * jump-to-definition works), a plain string name, or a numeric index into this
- * Flow's Block list (position between `start`/`end`, 0-based) for a spec that
- * genuinely doesn't have the Block imported and doesn't want to spell its
- * name. A reference or string resolves by `.name` under the hood (a Block's
- * own stable identity in this codebase, same as every error message elsewhere
- * in this file already uses) rather than object identity - it stays
- * resolvable even after an earlier patch already swapped that slot for a new
- * object, since the name survives every `withVerify`/`modVerify` in the
- * chain; an index is checked fresh against this Flow's current Block list
- * each call, so it's still correct after a patch too. Returns a new Flow -
- * the original is untouched, same as every other decorator in this module.
- */
-/**
- * One Block's identity as exposed by graph introspection - {@link Flow.blocks},
- * {@link ComposedBlock.steps} - without needing to execute anything. Does not
- * include the Block's literal Checkpoint `In`/`Out` tags: those are TypeScript
- * literal types, erased at runtime, and can only be recovered by a build-time
- * static-analysis tool reading the source's own type annotations - see the
- * `graph-visualization` openspec change for that piece.
- */
-export interface BlockInfo {
-    name: string;
-    /** `branch()`'s routing table, if this Block has one - see {@link Block.routes}. */
-    routes?: Readonly<Record<string, string | null>>;
-    /**
-     * True when {@link chainFlow} inserted a session-reset boundary
-     * immediately before this Block - i.e. this is the first Block of a
-     * sub-flow that was wrapped in {@link withSessionReset}, and it isn't
-     * the very first sub-flow in the chain. Absent (not just false) from
-     * `Flow.blocks()` on an ordinary, non-chained Flow.
-     */
-    resetSessionBefore?: boolean;
-    /**
-     * The actual Block, re-runnable on its own via
-     * `engine.defineFlow([start, info.block, end])` - e.g. step-through
-     * tooling that runs a Flow's Blocks one at a time. Introspection that only
-     * wants to read the shape (a visualizer) can ignore this and use `name`/
-     * `routes` alone.
-     */
-    block: Block<any, any>;
-}
-export interface Flow<Out extends Checkpoint<string>> {
-    /**
-     * True once this Flow has been wrapped in {@link withSessionReset} - a
-     * hint for `chainFlow`, not something `run()` itself checks: it marks
-     * this Flow as one that expects to start from a genuinely fresh,
-     * unauthenticated browser state (e.g. a login flow meant to be
-     * re-entered later in a longer chain). `chainFlow` clears cookies and
-     * storage right before this Flow's first Block runs, but only when this
-     * Flow isn't the very first thing in the chain (nothing to reset yet).
-     */
-    readonly resetSession: boolean;
-    /**
-     * Set once this Flow has been wrapped in {@link withTitle} - a display
-     * hint for a step-through overlay/showcase (e.g. "Ticket #123"), not
-     * something `run()` itself uses.
-     */
-    readonly title?: string;
-    /**
-     * Set once this Flow has been wrapped in {@link withExpectedFailure} - a
-     * display hint for a step-through overlay: this Flow is DESIGNED to throw
-     * (e.g. a blocked user's login attempt genuinely failing), not a bug in
-     * the demo itself. `run()` never reads this - the Flow still throws
-     * exactly as it would otherwise; only the overlay's error panel reads it,
-     * to show an informational "this is the point" panel instead of an
-     * alarming one indistinguishable from a real break.
-     */
-    readonly expectedFailureReason?: string;
-    /**
-     * Set once this Flow has been wrapped in {@link withHighlightFixtures} -
-     * demo narration overrides (unlimited purposes on `.flow.ts`) keyed by
-     * block.name. `run()` never reads this; step/`demo` merges onto block stubs.
-     */
-    readonly highlightFixtures?: import("../highlights.js").HighlightFixtureMap;
-    /**
-     * Demo pacing for this Flow's episode (`withDemoPace`).
-     * `run()` ignores; step/demo applies per Block in the episode.
-     */
-    readonly demoPace?: import("../highlights.js").DemoPace;
-    /**
-     * Default highlight size/weight/tone for this Flow's episode (`withHighlightStyle`).
-     * Per-slot stub/fixture values win. `run()` ignores.
-     */
-    readonly highlightStyle?: import("../highlights.js").HighlightStyleDefaults;
-    /**
-     * Set once this Flow has been wrapped in {@link withMemStub} - opts into
-     * auto-filling `requires` keys with registered fake values
-     * (`registerMemStub`, `src/mem-stub.ts`) instead of failing preflight when
-     * the caller didn't supply them. `run()` never reads this - the CLI's own
-     * `--data`/`--mem-stub` seeding, or a bare-library caller's own explicit
-     * `seedMemStub(mem, flow)` call, is what actually fills mem before `run()`.
-     */
-    readonly memStub?: boolean;
-    /**
-     * This Flow's constituent Blocks, in order between `start`/`end`, as plain
-     * data - for introspection/visualization tools, without running anything.
-     * @example loginFlow.blocks() // [{ name: "login" }, { name: "add-to-cart", routes: {...} }]
-     */
-    blocks(): readonly BlockInfo[];
-    run(context: BrowserContext, mem: MemPage): Promise<Out>;
-    /**
-     * `options.closeOnFinish: false` hands the driven page back instead of
-     * closing it - use this overload (a literal `false`, not a `boolean`) to
-     * get the `{ result, page }` shape typed correctly.
-     * @example const { result, page } = await loginFlow.run(context, mem, { closeOnFinish: false });
-     */
-    run(context: BrowserContext, mem: MemPage, options: RunGraphOptions & {
-        closeOnFinish: false;
-    }): Promise<{
-        result: Out;
-        page: Page;
-    }>;
-    /**
-     * `options.page` drives that already-open page instead of opening a new
-     * one - see {@link RunGraphOptions}.
-     * @example await loginFlow.run(context, mem, { page: existingPage });
-     */
-    run(context: BrowserContext, mem: MemPage, options?: RunGraphOptions): Promise<Out>;
-    run(mem: MemPage, config?: EngineConfig): Promise<Out>;
-    /**
-     * Replaces the given Block's whole verify list, wherever it sits in this
-     * Flow - same rules as {@link withVerify}. Throws if no Block in this Flow
-     * matches.
-     * @example checkoutFlow.withBlockVerify(LoginBlock, [])
-     * @example checkoutFlow.withBlockVerify("login", [])
-     * @example checkoutFlow.withBlockVerify(0, [])
-     */
-    withBlockVerify(block: Block<any, any> | string | number, verify: Trait[] | ((out: any) => Trait[])): Flow<Out>;
-    /**
-     * Replaces one Trait inside the given Block's verify list - same rules as
-     * {@link modVerify}. Throws if no Block in this Flow matches, or if that
-     * Block has no verify trait at the given name/index.
-     * @example checkoutFlow.modBlockVerify(LoginBlock, "url-matches", Trait.url({ pathname: "/inventory.html" }))
-     */
-    modBlockVerify(block: Block<any, any> | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): Flow<Out>;
-}
-export declare function buildFlow<Out extends Checkpoint<string>>(middle: readonly Block<any, any>[], engineConfig: EngineConfig): Flow<Out>;
-/**
- * Marks a Flow as expecting to start from a genuinely fresh, unauthenticated
- * browser state - e.g. a login flow meant to be re-entered later in a longer
- * showcase. Non-destructive, same pattern as {@link withVerify}: returns a
- * new Flow: the original is untouched, and the flag survives any further
- * `withBlockVerify`/`modBlockVerify` patch applied to the result.
- *
- * By itself this does nothing - `Flow.run()` never reads `resetSession`.
- * It's a hint {@link chainFlow} looks for: right before this Flow's first
- * Block runs (skipped if it's the very first thing in the chain - nothing
- * to reset yet), chainFlow clears cookies and storage so this Flow starts
- * exactly as if a human had opened the app fresh, not wherever the
- * previous Flow in the chain happened to leave the page.
- * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
- * @deprecated Use `map().flow(sub, { reset: true })`; the reset belongs to where flows are joined.
- */
-export declare function withSessionReset<Out extends Checkpoint<string>>(flow: Flow<Out>): Flow<Out>;
-/**
- * Names a Flow for display - a step-through overlay/showcase (waygraph's
- * `chain --step`) shows this as the running banner while this Flow's own
- * Blocks are executing, instead of one fixed title for the whole run.
- * Non-destructive, same pattern as {@link withSessionReset}.
- * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
- * @deprecated Name a flow with `ctx.title(...)` in a stub on its first step.
- */
-export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
-/**
- * Opts this Flow into memStub: `requires` keys the caller didn't supply get
- * filled from `registerMemStub`'s registry (`src/mem-stub.ts`) instead of
- * failing preflight, for any key that has a registered fake generator - a
- * required key with no registration still fails exactly as before.
- * Non-destructive, same pattern as {@link withTitle}. `run()` never reads
- * this itself - the CLI's `--data`/`--mem-stub` seeding, or a bare-library
- * caller's own explicit `seedMemStub(mem, flow)` call, does the filling.
- * @example const demoLogin = withMemStub(loginFlow);
- * @deprecated Use `engine.map({ memStub: true })`.
- */
-export declare function withMemStub<Out extends Checkpoint<string>>(flow: Flow<Out>): Flow<Out>;
-/**
- * Demo pacing for a whole Flow episode (fast review vs slow gap/wrong walkthrough).
- * Non-destructive. `fastForwardComposeBlock` is always blitz for its own step;
- * use this when an entire episode should be fast or slow.
- * @example withDemoPace(withTitle(gapFlow, "Episode 2 - gaps"), "slow")
- * @example withDemoPace(happyFlow, 0.5)  // 2x faster than normal
- * @example withDemoPace(gapFlow, 2.5)    // 2.5x slower
- * @example withDemoPace(gapFlow, 4500)   // absolute ~4.5s gates/dwells
- * @deprecated Use `engine.map({ demoPace })`, a step `{ pace }`, or `demo.pace` in the config.
- */
-export declare function withDemoPace<Out extends Checkpoint<string>>(flow: Flow<Out>, pace: DemoPace): Flow<Out>;
-/**
- * Default highlight look for a Flow episode (size / weight / optional tone).
- * Per-slot stub or {@link withHighlightFixtures} values win when set.
- * @example withHighlightStyle(withDemoPace(gapFlow, "slow"), { size: "lg", weight: "bold" })
- * @deprecated Use `engine.map({ highlightStyle })`.
- */
-export declare function withHighlightStyle<Out extends Checkpoint<string>>(flow: Flow<Out>, style: HighlightStyleDefaults): Flow<Out>;
-/**
- * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
- * @example withBlockPace(composeBlock("gap-review", [...]), "slow")
- * @deprecated Use a step option: `.method(Block, { pace })`.
- */
-export declare function withBlockPace<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, pace: DemoPace): Block<In, Out>;
-/**
- * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
- * login attempt genuinely failing, demonstrating the app's own real
- * behavior rather than a bug in the demo. Non-destructive, same pattern as
- * {@link withTitle}.
- *
- * By itself this changes nothing about how the Flow runs - it still throws
- * Marks a Flow whose last step is an intentional product failure (demo overlay).
- * Step mode shows stubOnError rings + an amber "expected outcome" panel when:
- * - the last block **throws**, or
- * - the last block **succeeds** on the fail branch (e.g. LoginPage + error banner
- *   after submit-login branched instead of throwing).
- * Headless `run()` is unchanged - branching success returns the checkpoint.
- * @example const viewerBlockedFlow = withExpectedFailure(
- *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
- *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
- * );
- * @deprecated Use `engine.map({ expectedFailure: reason })`.
- */
-export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow: Flow<Out>, reason: string): Flow<Out>;
-/**
- * Attaches demo highlight fixtures to a Flow - unlimited purposes on `.flow.ts`
- * (AC copy, BUG/GATE tags, detail) merged onto each block's stubBefore/stubAfter/
- * stubOnError slots. Non-destructive, same pattern as {@link withTitle}.
- * Demo/`chain --step` reads `flow.highlightFixtures`; `run()` ignores it.
- * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
- * @deprecated Chain ctx stubs on the Block: `Block.stubAfter((ctx) => …)`.
- */
-export declare function withHighlightFixtures<Out extends Checkpoint<string>>(flow: Flow<Out>, fixtures: import("../highlights.js").HighlightFixtureMap): Flow<Out>;
-/** Everything a `with*` wrapper can set, given up front: `engine.defineFlow([...], { title, memStub, ... })`. */
-export interface FlowOptions {
-    /** Shown as the banner while the Flow runs (`withTitle`). */
-    title?: string;
-    /** Fill missing `requires` keys from `registerMemStub` (`withMemStub`). */
-    memStub?: boolean;
-    /** Clear cookies and storage before this Flow's first Block when chained after another (`withSessionReset`). */
-    sessionReset?: boolean;
-    /** `withDemoPace`. */
-    demoPace?: DemoPace;
-    /** `withHighlightStyle`. */
-    highlightStyle?: HighlightStyleDefaults;
-    /** Marks a Flow that is supposed to throw, with the reason (`withExpectedFailure`). */
-    expectedFailure?: string;
-}
-/** Applies each set option through its `with*` wrapper, so both spellings produce the same Flow. */
-export declare function applyFlowOptions<Out extends Checkpoint<string>>(flow: Flow<Out>, options: FlowOptions | undefined): Flow<Out>;
-export declare function clearSessionState(context: BrowserContext, page: Page): Promise<void>;
-/**
- * Runs several complete, independent Flows one after another, reusing the
- * same page/context/mem in order - each remains its own validated
- * start-to-end unit (a Flow's own `[start, ...blocks, end]` contract is
- * untouched), this only sequences whole Flows. Deliberately NOT the same
- * thing as {@link composeBlock}: composeBlock nests several Blocks into
- * one Block that can drop back into another `defineFlow([...])` - a
- * chainFlow result is a Flow, but not meant to be nested inside another
- * Flow's own Block list. Recursive nesting stays composeBlock's job alone;
- * chainFlow is a flat, one-level sequencing of complete showcases (e.g.
- * "ticket #123 end to end, then ticket #456 end to end").
- *
- * A sub-flow wrapped in {@link withSessionReset} gets its cookies/storage
- * cleared right before it runs (skipped for the very first flow in the
- * chain - nothing to reset yet). The combined result is whatever the LAST
- * flow resolved to.
- * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
- * @deprecated Nest flows with `map().flow(a).flow(b, { reset: true })`.
- */
-export declare function chainFlow(...flows: readonly Flow<any>[]): Flow<any>;