waygraph 0.15.52 → 0.15.54

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/graph.d.ts

@@ -8,6 +8,7 @@ import { type BlocksSelect } from "../blocks-select.js";
 export interface WaygraphNode {
     checkpoint: string;
 }
+/** A move in the graph: a Block from one Checkpoint tag to another. */
 export interface WaygraphEdge {
     /** The Block's own runtime `.name`. */
     block: string;
@@ -18,11 +19,13 @@ export interface WaygraphEdge {
     to: string;
     kind: "nav" | "action";
 }
+/** A Block `waygraph graph` found but could not place in the graph, with the reason. */
 export interface SkippedBlock {
     block: string;
     file: string;
     reason: string;
 }
+/** The static graph of a project: Checkpoint nodes, Block edges, skipped and orphan Blocks. */
 export interface WaygraphGraph {
     nodes: WaygraphNode[];
     edges: WaygraphEdge[];

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/auto-session/helpers.d.ts

@@ -3,6 +3,7 @@ import type { BlockEntry, ExploreMenu } from "../session/auto-explore.js";
 import type { PickResult } from "../session/auto-explore-run.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 export declare function stubPhaseHasContent(r: StubPhaseResult): boolean;
+/** One available move in a session snapshot: a Block and the Checkpoint it leads to. */
 export interface SessionSnapshotEdge {
     /** 1-based, matching the numbers a human/agent picks by (same as printCliMenu). */
     index: number;
@@ -12,10 +13,12 @@ export interface SessionSnapshotEdge {
     label?: string;
     description?: string;
 }
+/** A group of moves in a session snapshot, by page. */
 export interface SessionSnapshotSection {
     title: string;
     edges: SessionSnapshotEdge[];
 }
+/** The state of a live session: where it is, the moves available from there, and the trace so far. */
 export interface SessionSnapshot {
     here: string | null;
     sections: SessionSnapshotSection[];
@@ -82,6 +85,7 @@ export declare function walkFullDom(root: Element, caps: FullDomCaps): {
     tree: FullDomNode;
     truncated: boolean;
 };
+/** What `AutoSession.start` needs: project, selection, headless mode and the session id. */
 export interface AutoSessionInit {
     projectDir: string;
     baseURL?: string;
@@ -102,6 +106,7 @@ export interface AutoSessionInit {
      */
     sessionId?: string;
 }
+/** The result of running one menu pick in a live session. */
 export type ApplyPickResult = {
     ok: true;
     snapshot: SessionSnapshot;
@@ -110,6 +115,7 @@ export type ApplyPickResult = {
     ok: false;
     error: string;
 };
+/** The result of running a multi-step route in a live session. */
 export type ApplyPathResult = {
     ok: true;
     path: string[];
@@ -141,6 +147,7 @@ export interface TraceStep {
     stubOnError?: StubPhaseResult;
 }
 export declare const TRACE_MAX_STEPS = 500;
+/** Which stub file a live session wrote: before, after or on-error. */
 export type StubFileKind = "image" | "pdf" | "video";
 /**
  * Real, minimal, valid fixture files bundled at `assets/stubs/` - not
@@ -180,11 +187,13 @@ export interface ConsoleLogEntry {
     timestamp: string;
 }
 export declare const CONSOLE_LOG_MAX_ENTRIES = 200;
+/** One service worker registration as reported by a live session. */
 export interface ServiceWorkerRegistrationInfo {
     scope: string;
     activeUrl?: string;
     state?: string;
 }
+/** One cookie as reported by a live session's `auto cookies`. */
 export interface CookieInfo {
     name: string;
     value: string;
@@ -193,6 +202,7 @@ export interface CookieInfo {
     httpOnly: boolean;
     secure: boolean;
 }
+/** Local and session storage of a live session's page. */
 export interface StorageSnapshot {
     localStorage: Record<string, string>;
     sessionStorage: Record<string, string>;

package/dist/blocks-select.d.ts

@@ -6,6 +6,7 @@
  * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
  */
 export type BlocksSelectKind = "regex" | "glob" | "bare";
+/** A parsed `--blocks` selector: which Blocks, by name, glob or file, a command should use. */
 export interface BlocksSelect {
     kind: BlocksSelectKind;
     /** Original token. */
@@ -16,9 +17,11 @@ export interface BlocksSelect {
 }
 /** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
 export declare function isFileSelectToken(token: string): boolean;
+/** Parses a `--blocks` argument into a selector. */
 export declare function parseBlocksSelect(token: string): BlocksSelect;
 /** Glob → RegExp (simple: ** / * / ? only; no brace expansion). */
 export declare function globToRegExp(glob: string): RegExp;
+/** True when a Block name and file match a parsed `--blocks` selector. */
 export declare function matchBlocksSelect(select: BlocksSelect, opts: {
     relFile: string;
     blockName?: string;

package/dist/blocks-select.js

@@ -14,6 +14,7 @@ export function isFileSelectToken(token) {
     }
     return token.includes("*");
 }
+/** Parses a `--blocks` argument into a selector. */
 export function parseBlocksSelect(token) {
     const raw = token.trim();
     if (raw.length >= 2 && raw.startsWith("/") && raw.endsWith("/")) {
@@ -52,6 +53,7 @@ export function globToRegExp(glob) {
     }
     return new RegExp("^" + out + "$");
 }
+/** True when a Block name and file match a parsed `--blocks` selector. */
 export function matchBlocksSelect(select, opts) {
     const file = opts.relFile.replace(/\\/g, "/");
     const name = opts.blockName ?? "";

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,62 @@
 import type { PlaywrightTestConfig } from "@playwright/test";
 import type { ExtensionSpec } from "./extensions.js";
 import type { WebServerConfig } from "./webserver.js";
+import type { DemoPace } from "./highlights.js";
+/** Where `--video` recordings are saved and at what size. */
+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;
+}
+/** The project config in `config/waygraph.config.ts`: base URL, extensions, run and demo settings, web server and the Playwright block. */
 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 +75,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 +107,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/blocks/api.d.ts

@@ -10,6 +10,7 @@ export interface ApiCallResult {
     /** `response.json()` if the body parses as JSON, else the raw text (or `undefined` if neither). */
     body: unknown;
 }
+/** Options for `defineApiBlock`: the HTTP call, how its result maps to a Checkpoint, and the demo network panel. */
 export interface ApiBlockOptions<In extends Checkpoint<string>, Out extends Checkpoint<string>> {
     name: string;
     description?: string;

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

@@ -24,9 +24,11 @@ export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
 };
 /** @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>;
+/** Builds a Block for one page action (fill, submit, click) that does not navigate. */
 export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): MethodBlock<In, Out>;
 /** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
 export declare const defineActionBlock: typeof defineMethodBlock;
+/** Options for `defineAssertBlock`: a Checkpoint to stay on and the Traits that must hold. */
 export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<string>> {
     name: string;
     description?: string;

package/dist/core/blocks/method.js

@@ -1,6 +1,7 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { checkpoint } from "../../types.js";
 import { defineBlock } from "../block.js";
+/** Builds a Block for one page action (fill, submit, click) that does not navigate. */
 export function defineMethodBlock(base) {
     const built = defineBlock(base);
     Object.defineProperty(built, "__waygraphSalt", {

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

@@ -123,6 +123,7 @@ export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
 };
+/** A Block whose only action is clicking a link; built with `defineNavClickBlock`. */
 export type NavClickBlock<Out extends Checkpoint<string>> = NavBlock<Out>;
 /** @see {@link NavClickBlockOptions} */
 export declare function defineNavClickBlock<Out extends Checkpoint<string>>(options: NavClickBlockOptions<Out>): NavClickBlock<Out>;

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

@@ -4,6 +4,7 @@ import { MemPage } from "../../mem-page.js";
 import type { MemKey } from "../../mem-page.js";
 /** One Block (or lazy factory) registered on a {@link PageBlock}. */
 export type PageMethodEntry = DefinedBlock<any, any> | (() => DefinedBlock<any, any>);
+/** Options for `definePageBlock`: the Checkpoint a page hub confirms and the Methods that hang off it. */
 export type PageBlockOptions<Out extends Checkpoint<string>> = {
     name: string;
     description?: string;