waygraph 0.15.51 → 0.15.53

package/dist/commands/try.js

@@ -6,6 +6,7 @@ import { packageRoot, runInherited } from "../cli/util.js";
 import { tmpdir } from "node:os";
 import { runChain } from "../cli/run-chain.js";
 import { applyRunFlags, parseRunFlags } from "../cli/flags.js";
+import { resolveVideoDir } from "../video-dir.js";
 /**
  * Runs a throwaway probe script rooted at `projectDir` - the exact same
  * directory the real demo files get copied into, so it resolves "waygraph"
@@ -196,7 +197,7 @@ async function runTryDemo() {
     const videoTo = process.env.WAYGRAPH_VIDEO;
     console.log(videoTo
         ? "waygraph try demo: step-through + record (Sign In -> Shop & Checkout -> blocked Viewer login) - click Next; video -> " +
-            (videoTo === "1" ? ".waygraph-videos/" : videoTo)
+            (videoTo === "1" ? await resolveVideoDir(destDir) : videoTo)
         : "waygraph try demo: step-through (Sign In -> Shop & Checkout -> blocked Viewer login) - click Next for each step ...");
     await runChain(destDir, TRY_DEMO_CHAIN);
     if (process.exitCode)

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `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 declare function upgradeCase(args: string[]): Promise<void>;

package/dist/commands/upgrade.js

@@ -0,0 +1,113 @@
+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] [--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());
+    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,80 @@
+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`); `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;
+    /** Default for `run` and `demo`: show the browser window. Without it `demo` and `auto` are headed and `run` is headless. */
+    headed?: 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`). */
+    webServer?: WebServerConfig | WebServerConfig[];
+    /** Anything else for the test runner, e.g. `workers`, `timeout`, `reporter`, `use: { video: "on" }`. Merged over waygraph's defaults. */
+    playwright?: PlaywrightTestConfig;
+}
+/** 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>;
 }
-/** 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;
+/**
+ * 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;
+/** 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
@@ -32,3 +102,11 @@ 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, 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, command?: string | undefined): void;

package/dist/config.js

@@ -3,21 +3,52 @@
 // 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 { 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_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;
 }
-const CONFIG_FILENAMES = [
-    "waygraph.config.ts",
-    "waygraph.config.mts",
-    "waygraph.config.mjs",
-    "waygraph.config.js",
-    "waygraph.config.cjs",
-];
 /**
  * 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,10 +58,15 @@ const CONFIG_FILENAMES = [
  * anything" instead of "your config file has a bug."
  */
 export async function loadWaygraphConfig(projectDir) {
-    for (const name of CONFIG_FILENAMES) {
-        const p = join(projectDir, name);
-        if (!existsSync(p))
+    loadEnvFiles(projectDir);
+    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));
@@ -38,7 +74,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 +130,40 @@ 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, 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, 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;
+    };
+    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

@@ -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;
 /**
@@ -17,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
@@ -59,12 +62,26 @@ 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
+ * 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

@@ -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,18 +202,57 @@ 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);
 }
+/**
+ * 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/nav.d.ts

@@ -39,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>;
@@ -103,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/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;
 }