waygraph 0.15.52 → 0.15.53

package/README.md

@@ -16,7 +16,14 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoggedIn>({
 });
 
 // A Flow = Blocks in order.
-export const loginFlow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
+export const loginFlow = engine
+  .map()
+  .start()
+  .gotoPage(NavLoginBlock)
+  .method(FillUsernameBlock)
+  .method(FillPasswordBlock)
+  .method(SubmitLoginBlock)
+  .end();
 ```
 
 ## Try it in 60 seconds

package/dist/analysis/map-check.d.ts

@@ -1,9 +1,9 @@
-export interface MapViolation {
+interface MapViolation {
     file: string;
     block: string;
     reason: string;
 }
-export interface MapNode {
+interface MapNode {
     block: string;
     checkpoint: string | undefined;
     file: string;
@@ -16,3 +16,4 @@ export interface MapCheckResult {
     violations: MapViolation[];
 }
 export declare function checkMap(projectDir: string): Promise<MapCheckResult>;
+export {};

package/dist/cli/flags.js

@@ -2,7 +2,7 @@
 import { basename, relative, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { walkDir } from "./discover.js";
-import { resolveBaseUrl } from "../config.js";
+import { loadWaygraphConfig, resolveBaseUrl } from "../config.js";
 function takeFlagValue(argv, i, a, flag) {
     if (a.startsWith(flag + "=")) {
         return { value: a.slice(flag.length + 1), nextI: i };
@@ -323,6 +323,8 @@ export { resolveBaseUrl };
  * Call after applyRunFlags so explicit flags already won.
  */
 export async function applyDemoDefaults(projectDir) {
+    // Config first: its defaults (headed, autoNext, pace...) must land before the demo defaults below fill the same variables.
+    await loadWaygraphConfig(projectDir);
     if (process.env.WAYGRAPH_STEP === undefined)
         process.env.WAYGRAPH_STEP = "1";
     if (process.env.WAYGRAPH_STEP === "1" && process.env.WAYGRAPH_HEADED === undefined) {

package/dist/cli/usage.js

@@ -186,13 +186,16 @@ Primary (less is more):
                                            has a trace - test report opens it.
 
 Also:
+  --config <name|file>   (any command) use another config instead of waygraph.config.ts, e.g.
+                 waygraph test --config staging   (config/waygraph.staging.config.ts)
   --env <mode>   (any command) load .env.<mode> / .env.<mode>.local on top of .env, e.g.
                  waygraph test --env staging   (default: NODE_ENV, else development)
-  waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff]
+  waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff] [--skills]
                                            Compare a project with the scaffold in this waygraph:
                                            lists new and differing files and a stale waygraph
                                            dependency. Dry run unless --apply; only the paths you
                                            name are copied, differing files only with --overwrite.
+                                           --skills refreshes .agents/skills to this waygraph's.
   waygraph extensions install [project] [--update]
                                            Download the browser extensions listed in
                                            waygraph.config.* (extensions: ["hoppscotch"]) into

package/dist/cli.js

@@ -16,6 +16,7 @@
  */
 import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./commands/agent-dive-scaffold.js";
 import { takeEnvFlag } from "./env-file.js";
+import { takeConfigFlag } from "./config.js";
 import { usage } from "./cli/usage.js";
 import { listCase, navCase } from "./commands/list.js";
 import { checkCase, typecheckCase, validateCase } from "./commands/check.js";
@@ -29,8 +30,10 @@ import { tryCase } from "./commands/try.js";
 import { upgradeCase } from "./commands/upgrade.js";
 import { extensionsCase } from "./commands/extensions.js";
 import { mapCase } from "./commands/map.js";
-const args = takeEnvFlag(process.argv.slice(2));
+const args = takeConfigFlag(takeEnvFlag(process.argv.slice(2)));
 const command = args[0];
+if (command)
+    process.env.WAYGRAPH_COMMAND = command;
 async function main() {
     if (!command || command === "--help" || command === "-h") {
         usage();

package/dist/commands/agent-dive-scaffold.d.ts

@@ -1,24 +1,4 @@
 export type AgentDiveLoop = "claude" | "opencode" | "cursor" | "vscode";
-export interface AgentSpec {
-    name: string;
-    description: string;
-    model?: string;
-    color?: string;
-    tools: string[];
-    instructions: string;
-}
-/** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
-export declare function parseAgentSpec(filePath: string): AgentSpec;
-export declare function loadAgentSpecs(): AgentSpec[];
-/**
- * Claude Code Skills (`.claude/skills/<name>/SKILL.md`) - a different
- * mechanism than the agent persona files above: loadable instructions
- * triggered by task shape, not a persona. Claude-Code-specific (no
- * equivalent in the opencode/cursor/vscode loops), additive to the
- * `claude` loop only. Reuses the same `name: .../description: ...` +
- * body frontmatter shape `parseAgentSpec` already parses.
- */
-export declare function loadSkillSpecs(): AgentSpec[];
 /** CLI flag -> packaged skill file stem (under templates/skills/). */
 export declare const SKILL_FLAG_MAP: {
     readonly "--skill-pilot": "waygraph-pilot";

package/dist/commands/agent-dive-scaffold.js

@@ -16,7 +16,7 @@ function skillsTemplateDir() {
     return join(packageRoot(), "templates", "skills");
 }
 /** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
-export function parseAgentSpec(filePath) {
+function parseAgentSpec(filePath) {
     const raw = readFileSync(filePath, "utf-8");
     if (!raw.startsWith("---\n")) {
         throw new Error(`agent-dive: missing frontmatter in ${filePath}`);
@@ -58,7 +58,7 @@ export function parseAgentSpec(filePath) {
         instructions: body,
     };
 }
-export function loadAgentSpecs() {
+function loadAgentSpecs() {
     const dir = agentsTemplateDir();
     if (!existsSync(dir)) {
         throw new Error(`agent-dive: templates missing at ${dir}`);
@@ -76,7 +76,7 @@ export function loadAgentSpecs() {
  * `claude` loop only. Reuses the same `name: .../description: ...` +
  * body frontmatter shape `parseAgentSpec` already parses.
  */
-export function loadSkillSpecs() {
+function loadSkillSpecs() {
     const dir = skillsTemplateDir();
     if (!existsSync(dir))
         return [];

package/dist/commands/init.js

@@ -85,7 +85,7 @@ function initCommand(projectName) {
     console.log("  waygraph typecheck   # tsc --noEmit + bad-practice warnings (use --no-practices to skip)");
     console.log("  waygraph auto        # interactive explore (headed panel)");
     console.log("  waygraph auto --cli  # same menus in the terminal");
-    console.log("  waygraph demo --blocks exampleFlow");
+    console.log("  waygraph demo --blocks homeHelloFlow");
     console.log("  waygraph graph       # static state graph JSON");
     console.log("  .agents/skills/      # waygraph skills for coding agents (waygraph agent-dive adds agent personas)");
     console.log("");

package/dist/commands/upgrade.d.ts

@@ -1,5 +1,5 @@
 /**
- * `waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff]`
+ * `waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff] [--skills]`
  * Compares the project with the scaffold shipped in this waygraph. Dry run by default.
  * Only the paths you name are copied, because a real project deliberately drops parts of the demo.
  */

package/dist/commands/upgrade.js

@@ -21,13 +21,19 @@ const isOlder = (a, b) => {
     return false;
 };
 /**
- * `waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff]`
+ * `waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff] [--skills]`
  * Compares the project with the scaffold shipped in this waygraph. Dry run by default.
  * Only the paths you name are copied, because a real project deliberately drops parts of the demo.
  */
 export async function upgradeCase(args) {
     const flags = new Set(args.filter((a) => a.startsWith("--")));
     const positional = args.slice(1).filter((a) => !a.startsWith("--"));
+    // --skills: the agent skills are waygraph's own text, never edited by a project, so refresh them in place.
+    if (flags.has("--skills")) {
+        flags.add("--apply");
+        flags.add("--overwrite");
+        positional.push(".agents/skills");
+    }
     const first = positional[0];
     const hasProject = first !== undefined && existsSync(join(resolve(first), "package.json"));
     const proj = resolve(hasProject ? first : process.cwd());

package/dist/config.d.ts

@@ -1,29 +1,60 @@
 import type { PlaywrightTestConfig } from "@playwright/test";
 import type { ExtensionSpec } from "./extensions.js";
 import type { WebServerConfig } from "./webserver.js";
+import type { DemoPace } from "./highlights.js";
+export interface VideoSettings {
+    /** Where recordings are saved: absolute, `~/…`, or relative to the project. Default `~/Downloads/waygraph-videos/<project>` (the project's `.waygraph-videos/` where there is no Downloads folder, and on CI). */
+    dir?: string;
+    /** Recording size, e.g. `"1920x1080"` (demo default) or `"1280x720"` (run default). */
+    viewport?: string;
+}
+/** Settings `waygraph run` and `waygraph demo` share. */
+export interface RunSettings {
+    /** Show the browser window. */
+    headed?: boolean;
+    /**
+     * `run`: Playwright's `slowMo`, ms before every operation. `demo`: waygraph's own pause after each action (default 350),
+     * applied once per action rather than per keystroke, and removed by a step's `pace: "blitz"`.
+     */
+    slowMo?: number;
+    video?: VideoSettings;
+}
+/** Settings for `waygraph demo`. */
+export interface DemoSettings extends RunSettings {
+    /** Default pace for flows and steps that set none: `"fast"`, `"slow"`, `"blitz"`, or a multiplier like `0.5` / `2`. Narration gates and dwell scale with it; `"blitz"` also skips typing animation. */
+    pace?: DemoPace;
+    /**
+     * What the named paces mean, as multipliers of normal dwell and gate time (1 = normal): blitz 0.05, fast 0.33, slow 2 by
+     * default. Lower is faster. `blitz` also skips the cursor, ring pops and typing animation.
+     * @example speeds: { fast: 0.5, blitz: 0.1 }
+     */
+    speeds?: {
+        blitz?: number;
+        fast?: number;
+        slow?: number;
+    };
+    /** Typing animation: ms per character (default 30). `0` types instantly. */
+    typingMs?: number;
+    /** Advance steps automatically instead of waiting for Next. */
+    autoNext?: boolean;
+    /** Shorter Next / auto-next gates; keeps the cursor and typing animation. */
+    fast?: boolean;
+}
 export interface WaygraphConfig {
     /** Same value `resolveBaseUrl` would otherwise read from package.json's `waygraph.baseUrl`. */
     baseUrl?: string;
     /** Chromium extensions to load in every run: `"hoppscotch"`, a Chrome Web Store id, or `{ path }` to an unpacked one. */
     extensions?: ExtensionSpec[];
-    /** Recording with `--video` (`waygraph run` / `demo`). */
-    video?: {
-        /** Where recordings are saved: absolute, `~/…`, or relative to the project. Default `~/Downloads/waygraph-videos/<project>` (the project's `.waygraph-videos/` where there is no Downloads folder, and on CI). */
-        dir?: string;
-        /** Recording size, e.g. `"1920x1080"` (demo default) or `"1280x720"` (run default). */
-        viewport?: string;
-    };
-    /** Milliseconds to pause before each browser action in `run` / `demo`, to make it watchable. */
+    /** Recording with `--video` (`waygraph run` / `demo`); `run` and `demo` below can override it. */
+    video?: VideoSettings;
+    /** Default for `run` and `demo`: milliseconds to pause around each browser action, so a run is watchable. */
     slowMo?: number;
-    /** Show the browser window. Default: `demo` and `auto` are headed, `run` is headless. */
+    /** Default for `run` and `demo`: show the browser window. Without it `demo` and `auto` are headed and `run` is headless. */
     headed?: boolean;
-    /** `waygraph demo` defaults. */
-    demo?: {
-        /** Advance steps automatically instead of waiting for Next. */
-        autoNext?: boolean;
-        /** Blitz through fast-forward steps. */
-        fast?: boolean;
-    };
+    /** Settings for `waygraph run` only. They override the shared ones above. */
+    run?: RunSettings;
+    /** Settings for `waygraph demo` only. They override the shared ones above. */
+    demo?: DemoSettings;
     /** Folder of test files, relative to the project. Default `"tests"`. */
     testDir?: string;
     /** App to start around `waygraph test`, `run`, `demo` and `auto` (same fields as Playwright's `webServer`). */
@@ -42,6 +73,8 @@ export interface ConfigContext {
  * @example export default defineConfig(({ env }) => ({ baseUrl: env.BASE_URL }))
  */
 export declare function defineConfig(config: WaygraphConfig | ((context: ConfigContext) => WaygraphConfig)): WaygraphConfig;
+/** Removes `--config <file>` / `--config=<file>` from argv and records it as `WAYGRAPH_CONFIG`, so every command reads that config. */
+export declare function takeConfigFlag(argv: string[]): string[];
 /**
  * Looks for the first `waygraph.config.*` in `projectDir` and imports it - `.ts` works
  * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli.js` ever runs
@@ -72,7 +105,8 @@ export declare function resolveBaseUrl(projectDir: string): Promise<string | und
 /** Unpacked extension directories for a run: `WAYGRAPH_EXTENSIONS` if set, else the config file's `extensions` (fetched on first use). */
 export declare function configuredExtensions(projectDir: string): Promise<string[]>;
 /**
- * Applies the config's run settings as the `WAYGRAPH_*` variables the runner reads. A flag, a shell variable or a `.env`
- * value that is already set always wins, so the config only supplies defaults.
+ * Applies the config's run settings as the `WAYGRAPH_*` variables the runner reads, for the command being run
+ * (`WAYGRAPH_COMMAND`, set by the CLI). The `run` / `demo` section overrides the shared top-level values. A flag, a shell
+ * variable or a `.env` value that is already set always wins, so the config only supplies defaults.
  */
-export declare function applyConfigEnv(config: WaygraphConfig | undefined): void;
+export declare function applyConfigEnv(config: WaygraphConfig | undefined, command?: string | undefined): void;

package/dist/config.js

@@ -3,7 +3,7 @@
 // setting, for consumers who'd rather have a real typed file than a JSON field. Real ask: "I
 // think its time to add waygraph config now."
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { extensionPathsFromEnv } from "./browser.js";
 import { envMode, loadEnvFiles } from "./env-file.js";
@@ -22,6 +22,33 @@ export function defineConfig(config) {
 const CONFIG_NAMES = ["waygraph.config.ts", "waygraph.config.mts", "waygraph.config.mjs", "waygraph.config.js", "waygraph.config.cjs"];
 /** `config/` first, then the project root. */
 const CONFIG_FILENAMES = [...CONFIG_NAMES.map((n) => join("config", n)), ...CONFIG_NAMES];
+/**
+ * Which config file(s) to try. `--config <file>` / `WAYGRAPH_CONFIG` picks one: a path (`config/staging.ts`), or a short name
+ * (`staging` -> `config/waygraph.staging.config.ts`, also tried in the project root). Without it, `waygraph.config.*`.
+ */
+function configCandidates() {
+    const chosen = process.env.WAYGRAPH_CONFIG;
+    if (!chosen)
+        return CONFIG_FILENAMES;
+    if (/[\\/]/.test(chosen) || /\.[cm]?[jt]s$/.test(chosen))
+        return [chosen];
+    const names = ["ts", "mts", "mjs", "js", "cjs"].map((e) => `waygraph.${chosen}.config.${e}`);
+    return [...names.map((n) => join("config", n)), ...names, chosen];
+}
+/** Removes `--config <file>` / `--config=<file>` from argv and records it as `WAYGRAPH_CONFIG`, so every command reads that config. */
+export function takeConfigFlag(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--config" && argv[i + 1] !== undefined)
+            process.env.WAYGRAPH_CONFIG = argv[++i];
+        else if (a.startsWith("--config="))
+            process.env.WAYGRAPH_CONFIG = a.slice("--config=".length);
+        else
+            out.push(a);
+    }
+    return out;
+}
 /**
  * Looks for the first `waygraph.config.*` in `projectDir` and imports it - `.ts` works
  * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli.js` ever runs
@@ -32,10 +59,14 @@ const CONFIG_FILENAMES = [...CONFIG_NAMES.map((n) => join("config", n)), ...CONF
  */
 export async function loadWaygraphConfig(projectDir) {
     loadEnvFiles(projectDir);
-    for (const name of CONFIG_FILENAMES) {
-        const p = join(projectDir, name);
-        if (!existsSync(p))
+    for (const name of configCandidates()) {
+        const p = isAbsolute(name) ? name : join(projectDir, name);
+        if (!existsSync(p)) {
+            if (process.env.WAYGRAPH_CONFIG && name === process.env.WAYGRAPH_CONFIG) {
+                throw new Error(`waygraph: config "${process.env.WAYGRAPH_CONFIG}" not found (looked for ${p})`);
+            }
             continue;
+        }
         let mod;
         try {
             mod = (await import(pathToFileURL(p).href));
@@ -108,20 +139,31 @@ export async function configuredExtensions(projectDir) {
     return resolveExtensions((await loadWaygraphConfig(projectDir))?.extensions, projectDir);
 }
 /**
- * Applies the config's run settings as the `WAYGRAPH_*` variables the runner reads. A flag, a shell variable or a `.env`
- * value that is already set always wins, so the config only supplies defaults.
+ * Applies the config's run settings as the `WAYGRAPH_*` variables the runner reads, for the command being run
+ * (`WAYGRAPH_COMMAND`, set by the CLI). The `run` / `demo` section overrides the shared top-level values. A flag, a shell
+ * variable or a `.env` value that is already set always wins, so the config only supplies defaults.
  */
-export function applyConfigEnv(config) {
+export function applyConfigEnv(config, command = process.env.WAYGRAPH_COMMAND) {
     if (!config)
         return;
+    const isDemo = command === "demo" || command === "try";
+    const section = isDemo ? config.demo : command === "run" ? config.run : undefined;
     const set = (name, value) => {
         if (value !== undefined && process.env[name] === undefined)
             process.env[name] = value;
     };
-    set("WAYGRAPH_VIDEO_DIR", config.video?.dir);
-    set("WAYGRAPH_VIDEO_VIEWPORT", config.video?.viewport);
-    set("WAYGRAPH_SLOWMO", config.slowMo === undefined ? undefined : String(config.slowMo));
-    set("WAYGRAPH_HEADED", config.headed === undefined ? undefined : config.headed ? "1" : "0");
-    set("WAYGRAPH_AUTOPLAY", config.demo?.autoNext === undefined ? undefined : config.demo.autoNext ? "1" : "0");
-    set("WAYGRAPH_DEMO_FAST", config.demo?.fast ? "1" : undefined);
+    const flag = (b) => (b === undefined ? undefined : b ? "1" : "0");
+    const video = { ...config.video, ...section?.video };
+    const slowMo = section?.slowMo ?? config.slowMo;
+    set("WAYGRAPH_VIDEO_DIR", video.dir);
+    set("WAYGRAPH_VIDEO_VIEWPORT", video.viewport);
+    set("WAYGRAPH_SLOWMO", slowMo === undefined ? undefined : String(slowMo));
+    set("WAYGRAPH_HEADED", flag(section?.headed ?? config.headed));
+    if (isDemo) {
+        set("WAYGRAPH_AUTOPLAY", flag(config.demo?.autoNext));
+        set("WAYGRAPH_DEMO_FAST", config.demo?.fast ? "1" : undefined);
+        set("WAYGRAPH_DEMO_PACE", config.demo?.pace === undefined ? undefined : String(config.demo.pace));
+        set("WAYGRAPH_PACE_SPEEDS", config.demo?.speeds ? JSON.stringify(config.demo.speeds) : undefined);
+        set("WAYGRAPH_TYPING_MS", config.demo?.typingMs === undefined ? undefined : String(config.demo.typingMs));
+    }
 }

package/dist/core/block.d.ts

@@ -18,6 +18,8 @@ export declare function findBlockIndex(middle: readonly Block<any, any>[], block
 export declare function branch<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, routes: {
     [K in Out["__state"]]: Block<Extract<Out, Checkpoint<K>>, any> | null;
 }): DefinedBlock<In, any>;
+/** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
+export declare function copyWaygraphRuntime(from: object, to: object): void;
 /**
  * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
  * methods - `LoginBlock.withVerify([...])`, discoverable by typing
@@ -60,11 +62,14 @@ type StubPhaseFn<Out extends Checkpoint<string>> = import("../highlights.js").Hi
  * Attach / chain a stubBefore lifecycle on a Block. Prefer
  * `(ctx) => { ctx.ring(...); const x = ctx.mem?.get(Key); }`.
  * @example FillUsernameBlock.stubBefore((ctx) => { ctx.ring("username", { ... }) })
+ * @deprecated Use the chained method: `Block.stubBefore((ctx) => …)`.
  */
 export declare function withStubBefore<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
-/** @see {@link withStubBefore} */
+/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubAfter((ctx) => …)`.
+ */
 export declare function withStubAfter<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
-/** @see {@link withStubBefore} */
+/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubOnError((ctx) => …)`.
+ */
 export declare function withStubOnError<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
 /**
  * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action

package/dist/core/block.js

@@ -75,12 +75,13 @@ function stripMethods(block) {
     };
 }
 /** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
-function copyWaygraphRuntime(from, to) {
+export function copyWaygraphRuntime(from, to) {
     for (const key of [
         "__waygraphKind",
         "__waygraphSalt",
         "__waygraphNavUrl",
         "__waygraphNavClick",
+        "__waygraphNavFrom",
     ]) {
         const desc = Object.getOwnPropertyDescriptor(from, key);
         if (!desc)
@@ -201,15 +202,18 @@ function withStubPhase(block, phase, stub) {
  * Attach / chain a stubBefore lifecycle on a Block. Prefer
  * `(ctx) => { ctx.ring(...); const x = ctx.mem?.get(Key); }`.
  * @example FillUsernameBlock.stubBefore((ctx) => { ctx.ring("username", { ... }) })
+ * @deprecated Use the chained method: `Block.stubBefore((ctx) => …)`.
  */
 export function withStubBefore(block, stub) {
     return withStubPhase(block, "stubBefore", stub);
 }
-/** @see {@link withStubBefore} */
+/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubAfter((ctx) => …)`.
+ */
 export function withStubAfter(block, stub) {
     return withStubPhase(block, "stubAfter", stub);
 }
-/** @see {@link withStubBefore} */
+/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubOnError((ctx) => …)`.
+ */
 export function withStubOnError(block, stub) {
     return withStubPhase(block, "stubOnError", stub);
 }

package/dist/core/engine.d.ts

@@ -16,6 +16,8 @@ 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

package/dist/core/engine.js

@@ -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,6 +250,7 @@ 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, ... })`. */
@@ -262,6 +270,7 @@ export interface FlowOptions {
 }
 /** 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
@@ -279,5 +288,6 @@ export declare function applyFlowOptions<Out extends Checkpoint<string>>(flow: F
  * 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>;