waygraph 0.15.51 → 0.15.53

package/dist/core/engine.d.ts

@@ -1,7 +1,7 @@
 import type { Block, Checkpoint } from "../types.js";
 import type { EngineConfig } from "./config.js";
 import type { EndMarker, StartMarker } from "./run-graph.js";
-import type { Flow } from "./flow.js";
+import type { Flow, FlowOptions } from "./flow.js";
 import { MapBuilder } from "./map-builder.js";
 import type { MapBuilderOptions } from "./map-builder.js";
 type S = Checkpoint<"__start__">;
@@ -16,18 +16,21 @@ export declare class Engine {
     private readonly config;
     constructor(config?: EngineConfig);
     /**
+     * @deprecated Build flows with `engine.map()`, which checks each step's Block kind and nests flows with `.flow()`.
+     *
      * Builds a runnable {@link Flow} from `[start, ...Blocks, end]`, typechecked
      * so each Block's `In` must match the previous Block's `Out` - the same
      * check `connect()` does, just declared as a flat array instead of hand-nested
      * calls. Overloaded for 2-9 array slots (1-8 real Blocks between `start`/`end`)
      * rather than one fully-generic recursive tuple type, so each arity is as
      * reliably checked as `connect<A,B,C>` itself.
-     * @example engine.defineFlow([start, LoginBlock, AddToCartBlock, end])
+     * Options go in the second argument instead of wrapping the result in `withTitle(withMemStub(...))`.
+     * @example engine.defineFlow([start, LoginBlock, AddToCartBlock, end], { title: "Login", memStub: true })
      */
-    defineFlow<B extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, EndMarker]): Flow<B>;
-    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, EndMarker]): Flow<C>;
-    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, Block<C, D>, EndMarker]): Flow<D>;
-    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, Block<C, D>, Block<D, E>, EndMarker]): Flow<E>;
+    defineFlow<B extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, EndMarker], options?: FlowOptions): Flow<B>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, EndMarker], options?: FlowOptions): Flow<C>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, Block<C, D>, EndMarker], options?: FlowOptions): Flow<D>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>>(blocks: readonly [StartMarker, Block<S, B>, Block<B, C>, Block<C, D>, Block<D, E>, EndMarker], options?: FlowOptions): Flow<E>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -36,7 +39,7 @@ export declare class Engine {
         Block<D, E>,
         Block<E, F>,
         EndMarker
-    ]): Flow<F>;
+    ], options?: FlowOptions): Flow<F>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -46,7 +49,7 @@ export declare class Engine {
         Block<E, F>,
         Block<F, G>,
         EndMarker
-    ]): Flow<G>;
+    ], options?: FlowOptions): Flow<G>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -57,7 +60,7 @@ export declare class Engine {
         Block<F, G>,
         Block<G, H>,
         EndMarker
-    ]): Flow<H>;
+    ], options?: FlowOptions): Flow<H>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -69,7 +72,7 @@ export declare class Engine {
         Block<G, H>,
         Block<H, I>,
         EndMarker
-    ]): Flow<I>;
+    ], options?: FlowOptions): Flow<I>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -82,7 +85,7 @@ export declare class Engine {
         Block<H, I>,
         Block<I, J>,
         EndMarker
-    ]): Flow<J>;
+    ], options?: FlowOptions): Flow<J>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -96,7 +99,7 @@ export declare class Engine {
         Block<I, J>,
         Block<J, K>,
         EndMarker
-    ]): Flow<K>;
+    ], options?: FlowOptions): Flow<K>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -111,7 +114,7 @@ export declare class Engine {
         Block<J, K>,
         Block<K, L>,
         EndMarker
-    ]): Flow<L>;
+    ], options?: FlowOptions): Flow<L>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>, M extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -127,7 +130,7 @@ export declare class Engine {
         Block<K, L>,
         Block<L, M>,
         EndMarker
-    ]): Flow<M>;
+    ], options?: FlowOptions): Flow<M>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>, M extends Checkpoint<string>, N extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -144,7 +147,7 @@ export declare class Engine {
         Block<L, M>,
         Block<M, N>,
         EndMarker
-    ]): Flow<N>;
+    ], options?: FlowOptions): Flow<N>;
     defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>, M extends Checkpoint<string>, N extends Checkpoint<string>, O extends Checkpoint<string>>(blocks: readonly [
         StartMarker,
         Block<S, B>,
@@ -162,7 +165,7 @@ export declare class Engine {
         Block<M, N>,
         Block<N, O>,
         EndMarker
-    ]): Flow<O>;
+    ], options?: FlowOptions): Flow<O>;
     /**
      * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
      * see {@link MapBuilder}. Real, direct request this responds to: pia/zsign's

package/dist/core/engine.js

@@ -1,4 +1,4 @@
-import { buildFlow } from "./flow.js";
+import { applyFlowOptions, buildFlow } from "./flow.js";
 import { MapBuilder } from "./map-builder.js";
 /**
  * Holds engine-level configuration shared across every flow defined from it -
@@ -12,8 +12,8 @@ export class Engine {
     constructor(config = {}) {
         this.config = config;
     }
-    defineFlow(blocks) {
-        return buildFlow(blocks.slice(1, -1), this.config);
+    defineFlow(blocks, options) {
+        return applyFlowOptions(buildFlow(blocks.slice(1, -1), this.config), options);
     }
     /**
      * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
@@ -36,7 +36,9 @@ export class Engine {
      *   .end();
      */
     map(options) {
-        return MapBuilder.begin(this.defineFlow.bind(this), options?.homeOrigin);
+        const { homeOrigin, ...flowOptions } = options ?? {};
+        const define = this.defineFlow.bind(this);
+        return MapBuilder.begin((blocks, extra) => define(blocks, { ...flowOptions, ...extra }), homeOrigin);
     }
 }
 /**

package/dist/core/flow.d.ts

@@ -176,6 +176,7 @@ export declare function buildFlow<Out extends Checkpoint<string>>(middle: readon
  * 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>;
 /**
@@ -184,6 +185,7 @@ export declare function withSessionReset<Out extends Checkpoint<string>>(flow: F
  * 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>;
 /**
@@ -195,6 +197,7 @@ export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out
  * 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>;
 /**
@@ -205,17 +208,20 @@ export declare function withMemStub<Out extends Checkpoint<string>>(flow: Flow<O
  * @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>;
 /**
@@ -235,6 +241,7 @@ export declare function withBlockPace<In extends Checkpoint<string>, Out extends
  *   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>;
 /**
@@ -243,8 +250,27 @@ export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow
  * 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
@@ -262,5 +288,6 @@ export declare function withHighlightFixtures<Out extends Checkpoint<string>>(fl
  * 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>;

package/dist/core/flow.js

@@ -1,12 +1,43 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { connect } from "../types.js";
-import { chromiumExecutablePath } from "../browser-path.js";
+import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "../browser.js";
+import { resolveExtensions } from "../extensions.js";
+import { loadWaygraphConfig } from "../config.js";
 import { WaygraphError, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_CHAINFLOW_EMPTY, } from "../errors.js";
 import { preflight, runGraph } from "./run-graph.js";
 import { resolveLauncher } from "./config.js";
 import { MemPage } from "../mem-page.js";
-import { findBlockIndex, modVerify, withVerify } from "./block.js";
+import { copyWaygraphRuntime, findBlockIndex, modVerify, withVerify } from "./block.js";
 import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../highlights.js";
+/** Launches the browser and context an Engine uses when the caller gave none, from its config. */
+async function openOwnContext(engineConfig) {
+    // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with, so a flow that imports
+    // an engine from one config file still follows the config the run selected.
+    const chosen = process.env.WAYGRAPH_CONFIG ? await loadWaygraphConfig(process.cwd()) : undefined;
+    const config = chosen
+        ? {
+            ...engineConfig,
+            ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
+            ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
+        }
+        : engineConfig;
+    const browserName = config?.browserName ?? "chromium";
+    const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
+    const baseURL = config?.baseUrl ?? process.env.WAYGRAPH_BASE_URL;
+    return launchContext({
+        launcher: resolveLauncher(browserName, config),
+        launch: {
+            headless: config?.headless ?? true,
+            ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+            ...(executablePath ? { executablePath } : {}),
+        },
+        context: {
+            ...(baseURL ? { baseURL } : {}),
+            ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
+        },
+        extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
+    });
+}
 export function buildFlow(middle, engineConfig) {
     // resetSession/title start false/unset here - defineFlow itself carries
     // no such options anymore. They're set by wrapping the result in
@@ -32,16 +63,8 @@ export function buildFlow(middle, engineConfig) {
             // before a page opens - the same "fail loud, cheaply" guarantee
             // run(context, mem) already has via an existing context.
             preflight(mem, chain);
-            const browserName = config.browserName ?? "chromium";
-            const launch = resolveLauncher(browserName, config);
-            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
-            const browser = await launch.launch({
-                headless: config.headless ?? true,
-                ...(config.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-                ...(executablePath ? { executablePath } : {}),
-            });
+            const { context, close } = await openOwnContext(config);
             try {
-                const context = await browser.newContext(config.recordVideo ? { recordVideo: config.recordVideo } : {});
                 try {
                     return await runGraph(chain, undefined, context, mem, 5000, {
                         ...(config.layouts !== undefined ? { layouts: config.layouts } : {}),
@@ -56,7 +79,7 @@ export function buildFlow(middle, engineConfig) {
                 }
             }
             finally {
-                await browser.close();
+                await close();
             }
         }
         const context = contextOrMem;
@@ -97,7 +120,12 @@ export function buildFlow(middle, engineConfig) {
     };
     return {
         resetSession: false,
-        blocks: () => middle.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
+        blocks: () => middle.map((b) => ({
+            name: b.name,
+            block: b,
+            ...(b.routes ? { routes: b.routes } : {}),
+            ...(b.__waygraphResetBefore ? { resetSessionBefore: true } : {}),
+        })),
         run: run,
         withBlockVerify(block, verify) {
             const index = findBlockIndex(middle, block);
@@ -127,6 +155,7 @@ export function buildFlow(middle, engineConfig) {
  * 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 function withSessionReset(flow) {
     return {
@@ -142,6 +171,7 @@ export function withSessionReset(flow) {
  * 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 function withTitle(flow, title) {
     return {
@@ -160,6 +190,7 @@ export function withTitle(flow, title) {
  * 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 function withMemStub(flow) {
     return {
@@ -177,6 +208,7 @@ export function withMemStub(flow) {
  * @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 function withDemoPace(flow, pace) {
     const demoPace = pace;
@@ -191,6 +223,7 @@ export function withDemoPace(flow, pace) {
  * 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 function withHighlightStyle(flow, style) {
     const highlightStyle = {
@@ -208,12 +241,12 @@ export function withHighlightStyle(flow, style) {
 /**
  * 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 function withBlockPace(block, pace) {
-    return {
-        ...block,
-        demoPace: pace,
-    };
+    const next = { ...block, demoPace: pace };
+    copyWaygraphRuntime(block, next);
+    return next;
 }
 /**
  * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
@@ -232,6 +265,7 @@ export function withBlockPace(block, pace) {
  *   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 function withExpectedFailure(flow, reason) {
     return {
@@ -247,6 +281,7 @@ export function withExpectedFailure(flow, reason) {
  * 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 function withHighlightFixtures(flow, fixtures) {
     return {
@@ -256,6 +291,25 @@ export function withHighlightFixtures(flow, fixtures) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightFixtures(flow.modBlockVerify(block, nameOrIndex, newCheck), fixtures),
     };
 }
+/** Applies each set option through its `with*` wrapper, so both spellings produce the same Flow. */
+export function applyFlowOptions(flow, options) {
+    if (!options)
+        return flow;
+    let f = flow;
+    if (options.sessionReset)
+        f = withSessionReset(f);
+    if (options.title !== undefined)
+        f = withTitle(f, options.title);
+    if (options.demoPace)
+        f = withDemoPace(f, options.demoPace);
+    if (options.highlightStyle)
+        f = withHighlightStyle(f, options.highlightStyle);
+    if (options.expectedFailure !== undefined)
+        f = withExpectedFailure(f, options.expectedFailure);
+    if (options.memStub)
+        f = withMemStub(f);
+    return f;
+}
 function locateInChain(flows, block) {
     if (typeof block === "number") {
         let remaining = block;
@@ -275,7 +329,7 @@ function locateInChain(flows, block) {
     }
     throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME(blockName));
 }
-async function clearSessionState(context, page) {
+export async function clearSessionState(context, page) {
     await context.clearCookies().catch(() => { });
     await page
         .evaluate(() => {
@@ -306,6 +360,7 @@ async function clearSessionState(context, page) {
  * 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 function chainFlow(...flows) {
     if (flows.length === 0) {
@@ -319,16 +374,8 @@ export function chainFlow(...flows) {
             // config) would otherwise each launch a separate browser, defeating
             // the point of sequencing them (a fresh browser is itself a full
             // session reset, silently making withSessionReset a no-op).
-            const browserName = config?.browserName ?? "chromium";
-            const launch = resolveLauncher(browserName, config);
-            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
-            const browser = await launch.launch({
-                headless: config?.headless ?? true,
-                ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-                ...(executablePath ? { executablePath } : {}),
-            });
+            const { context, close } = await openOwnContext(config);
             try {
-                const context = await browser.newContext(config?.recordVideo ? { recordVideo: config.recordVideo } : {});
                 try {
                     return await run(context, mem, { closeOnFinish: true });
                 }
@@ -337,7 +384,7 @@ export function chainFlow(...flows) {
                 }
             }
             finally {
-                await browser.close();
+                await close();
             }
         }
         const context = contextOrMem;

package/dist/core/map-builder.d.ts

@@ -1,6 +1,7 @@
 import type { Block, Checkpoint } from "../types.js";
 import type { EndMarker, StartMarker } from "./run-graph.js";
-import type { Flow } from "./flow.js";
+import type { Flow, FlowOptions } from "./flow.js";
+import type { DemoPace, HighlightStyleDefaults } from "../highlights.js";
 import type { NavBlock } from "./blocks/nav.js";
 import type { PageBlock } from "./blocks/page.js";
 import type { AssertBlock, MethodBlock } from "./blocks/method.js";
@@ -12,8 +13,7 @@ type S = Checkpoint<"__start__">;
  * import each other (Engine.map() builds a MapBuilder; MapBuilder.end() calls back into
  * defineFlow) - a real cycle check:structure forbids. This type is how that's avoided.
  */
-export type DefineFlowFn = (blocks: readonly [StartMarker, ...Block<any, any>[], EndMarker]) => Flow<any>;
-/** Per-step options every `MapBuilder` step method (`.gotoPage()`/`.method()`/`.assert()`) takes. */
+export type DefineFlowFn = (blocks: readonly [StartMarker, ...Block<any, any>[], EndMarker], options?: FlowOptions) => Flow<any>;
 export interface MapStepOpts {
     /**
      * Fast-forward just this step, inline - no `.ffStart()/.ffEnd()` bracket needed. Consecutive
@@ -22,6 +22,12 @@ export interface MapStepOpts {
      * @example map().gotoPage(NavLoginBlock, { ff: true }).method(FillUsernameBlock, { ff: true })
      */
     ff?: boolean;
+    /**
+     * Demo pace for just this step (`"blitz"` skips the typing animation and the pause after the action; `"fast"`, `"slow"`,
+     * or a number scale the narration gates). The map equivalent of `withBlockPace`, with no wrapper.
+     * @example map().method(SetBearerTokenBlock, { pace: "blitz" })
+     */
+    pace?: DemoPace;
 }
 export interface MapBuilderOptions {
     /**
@@ -31,6 +37,19 @@ export interface MapBuilderOptions {
      * way; only the internal/external origin distinction is opt-in).
      */
     homeOrigin?: string;
+    /** Fill missing `requires` keys from `registerMemStub` when the flow runs (what `withMemStub` did). */
+    memStub?: boolean;
+    /** Marks a flow that is supposed to throw, with the reason shown in the demo (what `withExpectedFailure` did). */
+    expectedFailure?: string;
+    /** Default demo pace for the whole flow (what `withDemoPace` did). */
+    demoPace?: DemoPace;
+    /** Default ring tone, size and weight for the whole flow (what `withHighlightStyle` did). */
+    highlightStyle?: HighlightStyleDefaults;
+}
+/** What `.flow()` takes for the sub-flow it runs inline. */
+export interface MapFlowOpts {
+    /** Clear cookies and storage right before the sub-flow, e.g. to start a second user fresh (what `withSessionReset` + `chainFlow` did). */
+    reset?: boolean;
 }
 /**
  * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
@@ -119,6 +138,12 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
     method<NextOut extends Checkpoint<string>>(block: (MethodBlock<Out, NextOut> | EffectBlock<Out, NextOut>) & {
         name: string;
     }, opts?: MapStepOpts): MapBuilder<NextOut>;
+    /**
+     * Runs another flow's steps inline here, in the same page, browser and `mem`. This is how flows nest:
+     * `map().flow(loginFlow).flow(viewerFlow, { reset: true })`. With `{ reset: true }` cookies and storage are cleared
+     * right before the sub-flow's first step. Replaces `chainFlow` and `withSessionReset`.
+     */
+    flow<NextOut extends Checkpoint<string>>(sub: Flow<NextOut>, opts?: MapFlowOpts): MapBuilder<NextOut>;
     /**
      * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
      * resolved Checkpoint's tag - same page, same context, same mem. `routes` must cover every tag
@@ -166,6 +191,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      * left open at `.end()` closes silently; an EXPLICIT `.ffStart()` left open
      * still throws - the author opened that one and needs to close it themselves.
      */
-    end(): Flow<Out>;
+    /** @param options @deprecated Pass flow settings to `map({ … })` instead. */
+    end(options?: FlowOptions): Flow<Out>;
 }
 export {};

package/dist/core/map-builder.js

@@ -2,6 +2,30 @@ import { WaygraphError, MSG_MAP_WRONG_KIND, MSG_MAP_WRONG_SALT, MSG_MAP_WRONG_OR
 import { end, start } from "./run-graph.js";
 import { MemPage } from "../mem-page.js";
 import { fastForwardComposeBlock } from "./compose.js";
+import { clearSessionState, withBlockPace } from "./flow.js";
+import { copyWaygraphRuntime } from "./block.js";
+/** Per-step options every `MapBuilder` step method (`.gotoPage()`/`.method()`/`.assert()`) takes. */
+/** The same Block, but it clears cookies and storage before it acts. Keeps the runtime markers. */
+function resetBefore(block) {
+    const act = block.instruction.act.bind(block.instruction);
+    const next = {
+        ...block,
+        instruction: {
+            ...block.instruction,
+            async act(page, input, mem) {
+                await clearSessionState(page.context(), page);
+                return act(page, input, mem);
+            },
+        },
+    };
+    copyWaygraphRuntime(block, next);
+    Object.defineProperty(next, "__waygraphResetBefore", { value: true, enumerable: false, configurable: true });
+    return next;
+}
+/** Applies a step's `pace` option, keeping the Block's runtime markers. */
+function paced(block, opts) {
+    return (opts?.pace === undefined ? block : withBlockPace(block, opts.pace));
+}
 function mapKindOf(block) {
     return block?.__waygraphKind;
 }
@@ -237,7 +261,7 @@ export class MapBuilder {
     gotoPage(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoPage");
         assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
-        return this.appendStep(block, opts?.ff);
+        return this.appendStep(paced(block, opts), opts?.ff);
     }
     /**
      * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
@@ -249,7 +273,7 @@ export class MapBuilder {
     gotoExternal(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoExternal");
         assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
-        return this.appendStep(block, opts?.ff);
+        return this.appendStep(paced(block, opts), opts?.ff);
     }
     /**
      * Appends a self-loop verification step - requires a Block from
@@ -258,7 +282,7 @@ export class MapBuilder {
      */
     assert(block, opts) {
         assertMapKind(block, ["assert"], "assert");
-        return this.appendStep(block, opts?.ff);
+        return this.appendStep(paced(block, opts), opts?.ff);
     }
     /**
      * Appends a non-navigating page action (submit, upload, add/remove an
@@ -274,7 +298,20 @@ export class MapBuilder {
             throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_METHOD_GOT_ASSERT(block.name));
         }
         assertMapSalt(block, ["method", "effect"], "method");
-        return this.appendStep(block, opts?.ff);
+        return this.appendStep(paced(block, opts), opts?.ff);
+    }
+    /**
+     * Runs another flow's steps inline here, in the same page, browser and `mem`. This is how flows nest:
+     * `map().flow(loginFlow).flow(viewerFlow, { reset: true })`. With `{ reset: true }` cookies and storage are cleared
+     * right before the sub-flow's first step. Replaces `chainFlow` and `withSessionReset`.
+     */
+    flow(sub, opts) {
+        let next = this;
+        sub.blocks().forEach((info, i) => {
+            const block = i === 0 && opts?.reset ? resetBefore(info.block) : info.block;
+            next = next.appendStep(block);
+        });
+        return next;
     }
     /**
      * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
@@ -329,17 +366,18 @@ export class MapBuilder {
      * left open at `.end()` closes silently; an EXPLICIT `.ffStart()` left open
      * still throws - the author opened that one and needs to close it themselves.
      */
-    end() {
+    /** @param options @deprecated Pass flow settings to `map({ … })` instead. */
+    end(options) {
         if (this.ff && !this.ff.auto) {
             throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", MSG_MAP_FF_NOT_CLOSED(this.ff.name));
         }
         if (this.ff && this.ff.auto) {
-            return this.closeFf().end();
+            return this.closeFf().end(options);
         }
         if (this.steps.length === 0) {
             throw new WaygraphError("WG_MAP_EMPTY", MSG_MAP_EMPTY);
         }
         const chain = [start, ...this.steps, end];
-        return this.defineFlow(chain);
+        return this.defineFlow(chain, options);
     }
 }

package/dist/env-file.d.ts

@@ -1,10 +1,10 @@
+/** The env mode: `--env <mode>` / `WAYGRAPH_ENV`, else `NODE_ENV`, else "development". */
+export declare function envMode(): string;
+/** Removes `--env <mode>` / `--env=<mode>` from argv and records it as `WAYGRAPH_ENV`, so it never reaches a forwarded command. */
+export declare function takeEnvFlag(argv: string[]): string[];
 /**
- * Auto-loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root,
- * same layering Vite/Next use (`mode` defaults to `NODE_ENV`, falling back to "development"),
- * merged into `process.env` in increasing priority. A real, already-set `process.env` value -
- * whatever the shell actually exported - always wins over every file; a `.env` file only fills
- * a gap, it never silently overrides something the caller explicitly set. Safe to call more
- * than once (e.g. once eagerly at `cwd`, again once the real project dir is known) - loading
- * twice is a no-op the second time for any key already filled.
+ * Loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root, the layering
+ * Vite and Next use: each later file overrides the earlier ones (`.env.<mode>.local` wins). A value the
+ * shell already exported always beats every file, so a file only fills gaps. Calling it twice is harmless.
  */
 export declare function loadEnvFiles(projectDir: string, mode?: string): void;