waygraph 0.15.50 → 0.15.52

package/dist/commands/upgrade.js

@@ -0,0 +1,107 @@
+import { basename, join, relative, resolve, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { packageRoot } from "../cli/util.js";
+import { agentSkillFiles } from "./agent-dive-scaffold.js";
+// Filled in per project at init, so they never compare equal to the template.
+const SKIP = new Set(["package.json", join("config", "waygraph.config.ts")]);
+function walk(dir, base = dir) {
+    return readdirSync(dir).flatMap((name) => {
+        const full = join(dir, name);
+        return statSync(full).isDirectory() ? walk(full, base) : [relative(base, full)];
+    });
+}
+const targetName = (rel) => (rel === "gitignore" ? ".gitignore" : rel);
+const major = (v) => v.replace(/^[^\d]*/, "").split(".").map((n) => parseInt(n, 10) || 0);
+const isOlder = (a, b) => {
+    for (let i = 0; i < 3; i++)
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) < (b[i] ?? 0);
+    return false;
+};
+/**
+ * `waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff]`
+ * 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("--"));
+    const first = positional[0];
+    const hasProject = first !== undefined && existsSync(join(resolve(first), "package.json"));
+    const proj = resolve(hasProject ? first : process.cwd());
+    const paths = hasProject ? positional.slice(1) : positional;
+    const templateDir = join(packageRoot(), "templates", "scaffold");
+    const ownVersion = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf-8")).version;
+    const pkgPath = join(proj, "package.json");
+    if (!existsSync(pkgPath)) {
+        console.error(`waygraph upgrade: no package.json in ${proj}`);
+        process.exit(1);
+    }
+    const added = [];
+    const differing = [];
+    // Every shipped file as [path in the project, content]: the scaffold tree plus the agent skills.
+    const shipped = new Map();
+    for (const rel of walk(templateDir))
+        if (!SKIP.has(rel))
+            shipped.set(rel, readFileSync(join(templateDir, rel)));
+    for (const { rel, text } of agentSkillFiles())
+        shipped.set(rel, Buffer.from(text));
+    for (const [rel, content] of shipped) {
+        const dest = join(proj, targetName(rel));
+        if (!existsSync(dest))
+            added.push(rel);
+        else if (!readFileSync(dest).equals(content))
+            differing.push(rel);
+    }
+    const selected = (rel) => paths.some((p) => rel === p || rel.startsWith(p.replace(/\/?$/, "/")));
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const current = pkg.dependencies?.waygraph;
+    const depStale = current !== undefined && !current.startsWith("file:") && isOlder(major(current), major(ownVersion));
+    console.log(`waygraph upgrade: ${proj} (waygraph ${current ?? "not a dependency"} -> ${ownVersion})`);
+    if (depStale)
+        console.log(`  dependency  waygraph ${current} -> ^${ownVersion}`);
+    for (const rel of added)
+        console.log(`  new         ${rel}`);
+    for (const rel of differing)
+        console.log(`  differs     ${rel}`);
+    if (!depStale && added.length === 0 && differing.length === 0)
+        console.log("  up to date");
+    const legacy = ["ts", "mts", "js", "mjs", "cjs"].find((e) => existsSync(join(proj, `playwright.config.${e}`)));
+    if (legacy) {
+        console.log(`  deprecated  playwright.config.${legacy} - move its settings into config/waygraph.config.ts (testDir, webServer, playwright: { ... })`);
+    }
+    if (flags.has("--diff")) {
+        for (const rel of differing.filter((r) => paths.length === 0 || selected(r))) {
+            const shippedCopy = join(tmpdir(), `waygraph-upgrade-${process.pid}-${basename(rel)}`);
+            writeFileSync(shippedCopy, shipped.get(rel));
+            spawnSync("diff", ["-u", join(proj, targetName(rel)), shippedCopy], { stdio: "inherit" });
+            rmSync(shippedCopy, { force: true });
+        }
+    }
+    if (!flags.has("--apply")) {
+        if (added.length + differing.length > 0) {
+            console.log("\nDry run. Copy files with: waygraph upgrade <paths...> --apply   (add --overwrite to replace differing files)");
+        }
+        return;
+    }
+    if (depStale) {
+        pkg.dependencies.waygraph = `^${ownVersion}`;
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+        console.log("updated package.json - run npm install");
+    }
+    if (paths.length === 0 && added.length + differing.length > 0) {
+        console.log("no paths given, so no files were copied (e.g. waygraph upgrade \"src/map/(external)/hoppscotch\" --apply)");
+        return;
+    }
+    const copy = [...added, ...(flags.has("--overwrite") ? differing : [])].filter(selected);
+    for (const rel of copy) {
+        const dest = join(proj, targetName(rel));
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, shipped.get(rel));
+        console.log(`  wrote       ${rel}`);
+    }
+    if (copy.length === 0 && paths.length > 0)
+        console.log("nothing matched those paths");
+}

package/dist/config.d.ts

@@ -1,10 +1,47 @@
+import type { PlaywrightTestConfig } from "@playwright/test";
+import type { ExtensionSpec } from "./extensions.js";
+import type { WebServerConfig } from "./webserver.js";
 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. */
+    slowMo?: number;
+    /** Show the browser window. Default: `demo` and `auto` are headed, `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;
+    };
+    /** 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`). */
+    webServer?: WebServerConfig | WebServerConfig[];
+    /** Anything else for the test runner, e.g. `workers`, `timeout`, `reporter`, `use: { video: "on" }`. Merged over waygraph's defaults. */
+    playwright?: PlaywrightTestConfig;
 }
-/** Identity helper, purely for editor type-checking/autocomplete - same role `defineConfig` plays
- * in a `playwright.config.ts` or `vite.config.ts`. `export default defineConfig({ ... })`. */
-export declare function defineConfig(config: WaygraphConfig): WaygraphConfig;
+/** What a config function receives: the env mode and the environment with `.env` files already loaded. */
+export interface ConfigContext {
+    mode: string;
+    env: Record<string, string | undefined>;
+}
+/**
+ * Typed identity helper, like `defineConfig` in `vite.config.ts`. Pass an object, or a function when values come
+ * from `.env` files (`.env`, `.env.local`, `.env.<mode>`; pick the mode with `--env <mode>`):
+ * @example export default defineConfig(({ env }) => ({ baseUrl: env.BASE_URL }))
+ */
+export declare function defineConfig(config: WaygraphConfig | ((context: ConfigContext) => WaygraphConfig)): WaygraphConfig;
 /**
  * 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,3 +69,10 @@ export declare function loadWaygraphConfig(projectDir: string): Promise<Waygraph
  *    as a side effect, which resolving a URL string has no business doing).
  */
 export declare function resolveBaseUrl(projectDir: string): Promise<string | undefined>;
+/** 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.
+ */
+export declare function applyConfigEnv(config: WaygraphConfig | undefined): void;

package/dist/config.js

@@ -5,19 +5,23 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { loadEnvFiles } from "./env-file.js";
-/** Identity helper, purely for editor type-checking/autocomplete - same role `defineConfig` plays
- * in a `playwright.config.ts` or `vite.config.ts`. `export default defineConfig({ ... })`. */
+import { extensionPathsFromEnv } from "./browser.js";
+import { envMode, loadEnvFiles } from "./env-file.js";
+import { resolveExtensions } from "./extensions.js";
+/**
+ * Typed identity helper, like `defineConfig` in `vite.config.ts`. Pass an object, or a function when values come
+ * from `.env` files (`.env`, `.env.local`, `.env.<mode>`; pick the mode with `--env <mode>`):
+ * @example export default defineConfig(({ env }) => ({ baseUrl: env.BASE_URL }))
+ */
 export function defineConfig(config) {
-    return config;
+    if (typeof config !== "function")
+        return config;
+    loadEnvFiles(process.cwd());
+    return config({ mode: envMode(), env: process.env });
 }
-const CONFIG_FILENAMES = [
-    "waygraph.config.ts",
-    "waygraph.config.mts",
-    "waygraph.config.mjs",
-    "waygraph.config.js",
-    "waygraph.config.cjs",
-];
+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];
 /**
  * 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
@@ -27,6 +31,7 @@ const CONFIG_FILENAMES = [
  * anything" instead of "your config file has a bug."
  */
 export async function loadWaygraphConfig(projectDir) {
+    loadEnvFiles(projectDir);
     for (const name of CONFIG_FILENAMES) {
         const p = join(projectDir, name);
         if (!existsSync(p))
@@ -38,7 +43,9 @@ export async function loadWaygraphConfig(projectDir) {
         catch (err) {
             throw new Error(`waygraph: failed to load ${name}: ${err instanceof Error ? err.message : String(err)}`);
         }
-        return mod.default ?? mod;
+        const loaded = mod.default ?? mod;
+        applyConfigEnv(loaded);
+        return loaded;
     }
     return undefined;
 }
@@ -92,3 +99,29 @@ export async function resolveBaseUrl(projectDir) {
     }
     return undefined;
 }
+/** Unpacked extension directories for a run: `WAYGRAPH_EXTENSIONS` if set, else the config file's `extensions` (fetched on first use). */
+export async function configuredExtensions(projectDir) {
+    const fromEnv = extensionPathsFromEnv();
+    if (fromEnv.length > 0)
+        return fromEnv;
+    loadEnvFiles(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.
+ */
+export function applyConfigEnv(config) {
+    if (!config)
+        return;
+    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);
+}

package/dist/core/block.d.ts

@@ -1,5 +1,6 @@
 import type { ActionPage, Block, Checkpoint, DefinedBlock, Instruction } from "../types.js";
 import { MemPage } from "../mem-page.js";
+import type { MemKey } from "../mem-page.js";
 import type { Trait } from "../trait.js";
 export declare function findBlockIndex(middle: readonly Block<any, any>[], block: Block<any, any> | string | number): number;
 /**
@@ -65,6 +66,17 @@ export declare function withStubBefore<B extends Block<any, any>>(block: B, stub
 export declare function withStubAfter<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
 /** @see {@link withStubBefore} */
 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
+ * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
+ * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
+ * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
+ */
+export declare function withDialog<B extends Block<any, any>>(block: B, options?: {
+    accept?: boolean;
+    into?: MemKey<string>;
+    promptText?: string;
+}): B;
 /**
  * Replaces one Trait inside `block`'s verify list, leaving every other check
  * untouched - the v1/v2/legacy-variant case, where one check needs a different

package/dist/core/block.js

@@ -213,6 +213,42 @@ export function withStubAfter(block, stub) {
 export function withStubOnError(block, stub) {
     return withStubPhase(block, "stubOnError", stub);
 }
+/**
+ * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
+ * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
+ * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
+ * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
+ */
+export function withDialog(block, options = {}) {
+    const base = stripMethods(block);
+    const act = base.instruction.act.bind(base.instruction);
+    const next = defineBlock({
+        ...base,
+        instruction: {
+            ...base.instruction,
+            async act(page, input, mem) {
+                const answer = async (dialog) => {
+                    if (options.into)
+                        mem.set(options.into, dialog.message());
+                    if (options.accept === false)
+                        await dialog.dismiss();
+                    else
+                        await dialog.accept(options.promptText);
+                };
+                const raw = page;
+                raw.once("dialog", answer);
+                try {
+                    await act(page, input, mem);
+                }
+                finally {
+                    raw.off("dialog", answer);
+                }
+            },
+        },
+    });
+    copyWaygraphRuntime(block, next);
+    return next;
+}
 /**
  * Replaces one Trait inside `block`'s verify list, leaving every other check
  * untouched - the v1/v2/legacy-variant case, where one check needs a different

package/dist/core/blocks/effect.d.ts

@@ -17,13 +17,10 @@ export type EffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): EffectBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
 };
 /** @deprecated Prefer {@link EffectBlock} - same type; Mem* was an early name. */
 export type MemEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = EffectBlock<In, Out>;

package/dist/core/blocks/method.d.ts

@@ -17,13 +17,10 @@ export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): MethodBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
 };
 /** @deprecated Prefer {@link MethodBlock} - same type; Action was the 0.7 name. */
 export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = MethodBlock<In, Out>;
@@ -80,11 +77,8 @@ export type AssertBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Out,
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): AssertBlock<Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
 };

package/dist/core/blocks/nav.d.ts

@@ -22,13 +22,10 @@ export type NavBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpo
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): NavBlock<Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
 };
 /**
  * `defineNavBlock`'s own options - exactly one of `url`/`click` required,
@@ -42,6 +39,15 @@ export type NavBlockOptions<Out extends Checkpoint<string>> = {
     name: string;
     description?: string;
     checkpoint: Out["__state"];
+    /**
+     * Checkpoint tags this Nav can run from. Omit (the default) = reachable from anywhere. Set it for
+     * a page that only exists after something else - e.g. every in-app page after sign-in - so route
+     * finding (`auto --blocks`, `pilot reach`, `traverse`) goes through the sign-in steps instead of
+     * jumping straight there from the login page.
+     * @example const SIGNED_IN = ["Dashboard", "CommandCenter"] as const; // src/states/
+     * defineNavBlock({ ..., from: SIGNED_IN })
+     */
+    from?: readonly string[];
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
     stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
@@ -106,6 +112,8 @@ export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
     description?: string;
     checkpoint: Out["__state"];
     click: string | ((mem: MemPage) => string);
+    /** See {@link NavBlockOptions.from}. */
+    from?: readonly string[];
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
     stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;

package/dist/core/blocks/nav.js

@@ -54,6 +54,13 @@ export function defineNavBlock(options) {
     });
     // Demo/step tooling: remember the click selector (or factory) so
     // overlays can label "nav click" without re-parsing source.
+    if (options.from && options.from.length > 0) {
+        Object.defineProperty(built, "__waygraphNavFrom", {
+            value: [...options.from],
+            enumerable: false,
+            configurable: false,
+        });
+    }
     if (options.click !== undefined) {
         Object.defineProperty(built, "__waygraphNavClick", {
             value: options.click,
@@ -83,6 +90,7 @@ export function defineNavClickBlock(options) {
         name: options.name,
         checkpoint: options.checkpoint,
         click: options.click,
+        ...(options.from ? { from: options.from } : {}),
         ...(options.description ? { description: options.description } : {}),
         ...(options.requires ? { requires: options.requires } : {}),
         ...(options.verify ? { verify: options.verify } : {}),

package/dist/core/blocks/page.d.ts

@@ -47,13 +47,10 @@ export type PageBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkp
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): PageBlock<Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
 };
 /** @see {@link PageBlockOptions} */
 export declare function definePageBlock<Out extends Checkpoint<string>>(options: PageBlockOptions<Out>): PageBlock<Out>;

package/dist/core/config.d.ts

@@ -1,5 +1,6 @@
 import type { BrowserType } from "@playwright/test";
 import type { Layout } from "./run-graph.js";
+import type { ExtensionSpec } from "../extensions.js";
 /**
  * Resolves which `BrowserType` actually launches for a `mem`-only run (no
  * caller-supplied context) - `config.browsers[browserName]` if given,
@@ -52,4 +53,8 @@ export interface EngineConfig {
      * @example new Engine({ layouts: [AppShellLayout] })
      */
     layouts?: readonly Layout[];
+    /** Chromium extensions to load: names, store ids or paths (see `extensions` in `waygraph.config.ts`). Default `WAYGRAPH_EXTENSIONS`. */
+    extensions?: readonly ExtensionSpec[];
+    /** Resolves relative `url`s in Nav Blocks when the Engine launches its own browser. Default `WAYGRAPH_BASE_URL`. */
+    baseUrl?: string;
 }

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__">;
@@ -22,12 +22,13 @@ export declare class Engine {
      * 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 +37,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 +47,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 +58,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 +70,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 +83,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 +97,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 +112,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 +128,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 +145,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 +163,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])` -

package/dist/core/flow.d.ts

@@ -245,6 +245,23 @@ export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow
  * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
  */
 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>;
 /**
  * Runs several complete, independent Flows one after another, reusing the
  * same page/context/mem in order - each remains its own validated