waygraph 0.15.52 → 0.15.53

package/dist/core/flow.js

@@ -2,14 +2,25 @@
 import { connect } from "../types.js";
 import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "../browser.js";
 import { resolveExtensions } from "../extensions.js";
+import { loadWaygraphConfig } from "../config.js";
 import { WaygraphError, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_CHAINFLOW_EMPTY, } from "../errors.js";
 import { preflight, runGraph } from "./run-graph.js";
 import { resolveLauncher } from "./config.js";
 import { MemPage } from "../mem-page.js";
-import { findBlockIndex, modVerify, withVerify } from "./block.js";
+import { copyWaygraphRuntime, findBlockIndex, modVerify, withVerify } from "./block.js";
 import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../highlights.js";
 /** Launches the browser and context an Engine uses when the caller gave none, from its config. */
-async function openOwnContext(config) {
+async function openOwnContext(engineConfig) {
+    // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with, so a flow that imports
+    // an engine from one config file still follows the config the run selected.
+    const chosen = process.env.WAYGRAPH_CONFIG ? await loadWaygraphConfig(process.cwd()) : undefined;
+    const config = chosen
+        ? {
+            ...engineConfig,
+            ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
+            ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
+        }
+        : engineConfig;
     const browserName = config?.browserName ?? "chromium";
     const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
     const baseURL = config?.baseUrl ?? process.env.WAYGRAPH_BASE_URL;
@@ -109,7 +120,12 @@ export function buildFlow(middle, engineConfig) {
     };
     return {
         resetSession: false,
-        blocks: () => middle.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
+        blocks: () => middle.map((b) => ({
+            name: b.name,
+            block: b,
+            ...(b.routes ? { routes: b.routes } : {}),
+            ...(b.__waygraphResetBefore ? { resetSessionBefore: true } : {}),
+        })),
         run: run,
         withBlockVerify(block, verify) {
             const index = findBlockIndex(middle, block);
@@ -139,6 +155,7 @@ export function buildFlow(middle, engineConfig) {
  * exactly as if a human had opened the app fresh, not wherever the
  * previous Flow in the chain happened to leave the page.
  * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
+ * @deprecated Use `map().flow(sub, { reset: true })`; the reset belongs to where flows are joined.
  */
 export function withSessionReset(flow) {
     return {
@@ -154,6 +171,7 @@ export function withSessionReset(flow) {
  * Blocks are executing, instead of one fixed title for the whole run.
  * Non-destructive, same pattern as {@link withSessionReset}.
  * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
+ * @deprecated Name a flow with `ctx.title(...)` in a stub on its first step.
  */
 export function withTitle(flow, title) {
     return {
@@ -172,6 +190,7 @@ export function withTitle(flow, title) {
  * this itself - the CLI's `--data`/`--mem-stub` seeding, or a bare-library
  * caller's own explicit `seedMemStub(mem, flow)` call, does the filling.
  * @example const demoLogin = withMemStub(loginFlow);
+ * @deprecated Use `engine.map({ memStub: true })`.
  */
 export function withMemStub(flow) {
     return {
@@ -189,6 +208,7 @@ export function withMemStub(flow) {
  * @example withDemoPace(happyFlow, 0.5)  // 2x faster than normal
  * @example withDemoPace(gapFlow, 2.5)    // 2.5x slower
  * @example withDemoPace(gapFlow, 4500)   // absolute ~4.5s gates/dwells
+ * @deprecated Use `engine.map({ demoPace })`, a step `{ pace }`, or `demo.pace` in the config.
  */
 export function withDemoPace(flow, pace) {
     const demoPace = pace;
@@ -203,6 +223,7 @@ export function withDemoPace(flow, pace) {
  * Default highlight look for a Flow episode (size / weight / optional tone).
  * Per-slot stub or {@link withHighlightFixtures} values win when set.
  * @example withHighlightStyle(withDemoPace(gapFlow, "slow"), { size: "lg", weight: "bold" })
+ * @deprecated Use `engine.map({ highlightStyle })`.
  */
 export function withHighlightStyle(flow, style) {
     const highlightStyle = {
@@ -220,12 +241,12 @@ export function withHighlightStyle(flow, style) {
 /**
  * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
  * @example withBlockPace(composeBlock("gap-review", [...]), "slow")
+ * @deprecated Use a step option: `.method(Block, { pace })`.
  */
 export function withBlockPace(block, pace) {
-    return {
-        ...block,
-        demoPace: pace,
-    };
+    const next = { ...block, demoPace: pace };
+    copyWaygraphRuntime(block, next);
+    return next;
 }
 /**
  * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
@@ -244,6 +265,7 @@ export function withBlockPace(block, pace) {
  *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
  *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
  * );
+ * @deprecated Use `engine.map({ expectedFailure: reason })`.
  */
 export function withExpectedFailure(flow, reason) {
     return {
@@ -259,6 +281,7 @@ export function withExpectedFailure(flow, reason) {
  * stubOnError slots. Non-destructive, same pattern as {@link withTitle}.
  * Demo/`chain --step` reads `flow.highlightFixtures`; `run()` ignores it.
  * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
+ * @deprecated Chain ctx stubs on the Block: `Block.stubAfter((ctx) => …)`.
  */
 export function withHighlightFixtures(flow, fixtures) {
     return {
@@ -306,7 +329,7 @@ function locateInChain(flows, block) {
     }
     throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME(blockName));
 }
-async function clearSessionState(context, page) {
+export async function clearSessionState(context, page) {
     await context.clearCookies().catch(() => { });
     await page
         .evaluate(() => {
@@ -337,6 +360,7 @@ async function clearSessionState(context, page) {
  * chain - nothing to reset yet). The combined result is whatever the LAST
  * flow resolved to.
  * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
+ * @deprecated Nest flows with `map().flow(a).flow(b, { reset: true })`.
  */
 export function chainFlow(...flows) {
     if (flows.length === 0) {

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

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

package/dist/core/map-builder.js

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

package/dist/highlights/demo-pace.d.ts

@@ -10,7 +10,6 @@ export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
 export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
 export declare function normalizeDemoPace(raw: unknown): DemoPace;
-/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
 export declare function demoPaceScale(pace: DemoPace): number;
 export declare function demoPaceIsBlitz(pace: DemoPace): boolean;
 /** True when pace should use the short-gate / fast fixture path (not slow authored). */

package/dist/highlights/demo-pace.js

@@ -34,6 +34,24 @@ export function normalizeDemoPace(raw) {
     return "normal";
 }
 /** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
+/**
+ * What each named pace means, as a multiplier of normal dwell (1 = normal). `demo.speeds` in the config (or
+ * `WAYGRAPH_PACE_SPEEDS`, a JSON object) overrides any of them; the defaults are blitz 0.05, fast 0.33, slow 2.
+ */
+function paceSpeeds() {
+    const out = { blitz: 0.05, fast: 0.33, slow: 2 };
+    try {
+        const raw = process.env.WAYGRAPH_PACE_SPEEDS ? JSON.parse(process.env.WAYGRAPH_PACE_SPEEDS) : {};
+        for (const k of ["blitz", "fast", "slow"]) {
+            if (typeof raw[k] === "number" && raw[k] > 0)
+                out[k] = Math.min(10, raw[k]);
+        }
+    }
+    catch {
+        /* ignore a malformed value: defaults apply */
+    }
+    return out;
+}
 export function demoPaceScale(pace) {
     if (typeof pace === "number") {
         if (pace > 20)
@@ -41,11 +59,11 @@ export function demoPaceScale(pace) {
         return Math.min(10, Math.max(0.05, pace));
     }
     if (pace === "blitz")
-        return 0.05;
+        return paceSpeeds().blitz;
     if (pace === "fast")
-        return 0.33;
+        return paceSpeeds().fast;
     if (pace === "slow")
-        return 2;
+        return paceSpeeds().slow;
     return 1;
 }
 export function demoPaceIsBlitz(pace) {
@@ -73,6 +91,9 @@ export function demoPaceIsSlow(pace) {
 }
 /** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
 export function demoPaceGateMs(pace, baseAutoplayMs) {
+    if (pace === "blitz" && process.env.WAYGRAPH_PACE_SPEEDS) {
+        return Math.min(30000, Math.max(20, Math.round(baseAutoplayMs * paceSpeeds().blitz)));
+    }
     if (demoPaceIsBlitz(pace))
         return Math.min(80, baseAutoplayMs);
     if (typeof pace === "number" && pace > 20) {

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, withDialog, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
 export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./core/branch-regression.js";
 export type { ApiBlockOptions, ApiCallResult } from "./core/blocks/api.js";
-export type { MapStepOpts } from "./core/map-builder.js";
+export type { MapStepOpts, MapFlowOpts } from "./core/map-builder.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, BannerPos, BannerUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
 export type { Flow, FlowOptions, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./core.js";
@@ -30,7 +30,7 @@ export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnap
 export { pilotStart } from "./session/pilot.js";
 export type { PilotStartResult } from "./session/pilot.js";
 export { defineConfig, resolveBaseUrl } from "./config.js";
-export type { WaygraphConfig, ConfigContext } from "./config.js";
+export type { WaygraphConfig, ConfigContext, VideoSettings, RunSettings, DemoSettings } from "./config.js";
 export { withWebServer } from "./webserver.js";
 export { chromiumExecutablePath } from "./browser.js";
 export { resolveExtension, KNOWN_EXTENSIONS } from "./extensions.js";

package/dist/pilot-overlay/action-ring.d.ts

@@ -1,16 +1,7 @@
 import type { Page } from "@playwright/test";
-type Box = {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-/** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
-export declare function showPilotRect(page: Page, box: Box, label: string, tone?: string): Promise<void>;
 /**
  * Every Playwright instruction a Block runs against this session's page gets a gray (auto) ring + robot
  * label first, so a human watching a pilot window sees WHAT is being driven. `dwellMs` holds the ring
  * long enough to read before the action fires (0 for headless).
  */
 export declare function instrumentPilotActions(page: Page, dwellMs: number): void;
-export {};

package/dist/pilot-overlay/action-ring.js

@@ -1,6 +1,6 @@
 import { ensureInstalled } from "./shell.js";
 /** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
-export async function showPilotRect(page, box, label, tone = "auto") {
+async function showPilotRect(page, box, label, tone = "auto") {
     await ensureInstalled(page);
     await page
         .evaluate(({ box, label, tone }) => {

package/dist/pilot-overlay/panel.d.ts

@@ -1,7 +1,7 @@
 import type { SessionSnapshot } from "../auto-session.js";
 import type { Page } from "@playwright/test";
 /** Minimal shape needed to render the graph tree - matches WaygraphGraph. */
-export interface PilotOverlayGraph {
+interface PilotOverlayGraph {
     nodes: readonly {
         checkpoint: string;
     }[];
@@ -32,3 +32,4 @@ export interface PilotOverlayInfo {
  * operation over.
  */
 export declare function updatePilotOverlay(page: Page, info: PilotOverlayInfo): Promise<void>;
+export {};

package/dist/runner/interaction-patch.js

@@ -21,7 +21,36 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
   // (shorter Next/autoplay gates) and must NOT skip theater, or the whole demo
   // looks like plain waygraph run.
   const skipTheater = () => !!pacing.skipTheater;
-  const typeDelay = () => (skipTheater() ? 0 : slowMo ? 0 : 30);
+  // `slowMo` here is the demo's own beat: ms to rest after each action (once per call, never per keystroke). The browser
+  // itself is launched with slowMo 0 in step mode, so a step whose pace is blitz really does run at full speed.
+  const beat = () => (skipTheater() ? 0 : slowMo || 0);
+  const pause = (ms) => (ms > 0 ? new Promise((res) => setTimeout(res, ms)) : undefined);
+  // Per-character typing delay (WAYGRAPH_TYPING_MS, default 30). 0 for blitz steps.
+  const typingMs = () => {
+    if (skipTheater()) return 0;
+    const n = Number(process.env.WAYGRAPH_TYPING_MS);
+    return process.env.WAYGRAPH_TYPING_MS !== undefined && Number.isFinite(n) && n >= 0 ? n : 30;
+  };
+  const typeDelay = typingMs;
+  const keyboard = page.keyboard;
+  if (!keyboard.__wgBeatPatched) {
+    keyboard.__wgBeatPatched = true;
+    const originalType = keyboard.type.bind(keyboard);
+    keyboard.type = async (text, options) => {
+      await originalType(text, { delay: typingMs(), ...(options || {}) });
+      await pause(beat());
+    };
+    const originalPress = keyboard.press.bind(keyboard);
+    keyboard.press = async (key, options) => {
+      await originalPress(key, options);
+      await pause(beat());
+    };
+    const originalInsertText = keyboard.insertText.bind(keyboard);
+    keyboard.insertText = async (text) => {
+      await originalInsertText(text);
+      await pause(beat());
+    };
+  }
   // Click is a single action, not per-character, so it doesn't compound
   // the same way - but slowMo still adds its own pause around the actual
   // click, so trim our own explicit "pop" pauses when it's already active
@@ -155,6 +184,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
       // it - it was sticking around through the whole rest of the step.
       await hideRing(page);
       await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
+      await pause(beat());
       return result;
     };
   }
@@ -285,6 +315,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
       await hideRing(page);
       // Full document navigation drops #wg-todo-dock + rings; restore carry.
       await restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef);
+      await pause(beat());
       return result;
     };
   }

package/dist/runner/main.js

@@ -231,6 +231,9 @@ async function runMain() {
         : "waygraph demo: opaque FFCompose in flow -> Playwright slowMo=0 (blitz); set WAYGRAPH_SLOWMO to override",
     );
   }
+  // Step (demo) mode: slowMo is waygraph's own beat after each action, not Playwright's per-operation slowMo, so a
+  // step's pace can remove it and typing is not taxed per keystroke. The browser launches at 0.
+  const launchSlowMo = step ? 0 : slowMo;
   const baseURL = process.env.WAYGRAPH_BASE_URL;
   const title = process.env.WAYGRAPH_TITLE;
   // Comma-separated Block names (their real .name, e.g. "login") that
@@ -263,7 +266,7 @@ async function runMain() {
   const fixedVideoViewport = videoDir
     ? (videoViewportParsed ?? (step ? DEFAULT_VIDEO_VIEWPORT : DEFAULT_RUN_VIDEO_VIEWPORT))
     : null;
-  const engine = new Engine({ headless: !headed, slowMo });
+  const engine = new Engine({ headless: !headed, slowMo: launchSlowMo });
   let result;
   // Non-interactive execution (no --step) runs the whole chain as one
   // composed flow with no per-block loop of its own to defer seeding
@@ -312,7 +315,7 @@ async function runMain() {
       launcher: chromium,
       launch: {
         headless: !headed,
-        slowMo,
+        slowMo: launchSlowMo,
         args: step || fixedVideoViewport ? ["--start-maximized"] : [],
         ...(executablePath ? { executablePath } : {}),
       },

package/dist/runner/step-mode.js

@@ -1,7 +1,7 @@
 // Moved verbatim from the former CHAIN_RUNNER_SCRIPT template string in cli.ts (see src/ARCHITECTURE.md).
 // Runs inside the target project's own waygraph copy - keep it dependency-light and self-contained.
 import { instrumentInteractionHighlighting } from "./interaction-patch.js";
-import { applyHighlightStyleDefaults, demoPaceGateMs, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, formatHighlightCaption, hasAuthoredStubAfter, resolveSlides, resolveStepDemoPace, resolveTodoDockUi, runStubPhase } from "../highlights.js";
+import { applyHighlightStyleDefaults, normalizeDemoPace, demoPaceGateMs, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, formatHighlightCaption, hasAuthoredStubAfter, resolveSlides, resolveStepDemoPace, resolveTodoDockUi, runStubPhase } from "../highlights.js";
 import { markStepRunning, resetPageState, teardownOverlay } from "./teardown.js";
 import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
 import { extractVerifyHighlights, presentFailPanel, renderAfterStep, renderBeforeStep } from "./step-panels.js";
@@ -26,6 +26,8 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
   const demoFast = process.env.WAYGRAPH_DEMO_FAST === "1";
   const stepperMode = process.env.WAYGRAPH_STEPPER === "full" ? "full" : "carousel";
   const pacing = { gatesFast: demoFast, gatesSlow: false, skipTheater: false, demoPace: "normal" };
+  // A title set by a stub (`ctx.title`) names the flow from that step on, until another stub sets a new one.
+  let stickyTitle;
   const stubBeforeRef = { current: [] };
   /** Live todo dock for Method fill/click advance (same carry as stage.state.lastTodoDock). */
   const todoDockRef = { current: undefined };
@@ -213,15 +215,18 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
     }
     // Episode pace: block > flow > CLI --fast (only when no authored pace).
     // Authoring wins: withDemoPace("slow"|2|4500) keeps slow dwell even under --fast.
+    // `demo.pace` in the config (WAYGRAPH_DEMO_PACE) is the default for flows and steps that set none.
+    const defaultPace = process.env.WAYGRAPH_DEMO_PACE ? normalizeDemoPace(process.env.WAYGRAPH_DEMO_PACE) : undefined;
     const stepPace = resolveStepDemoPace({
       blockPace: r.block.demoPace,
-      flowPace: r.demoPace,
+      flowPace: r.demoPace ?? defaultPace,
       fastForward: !!r.block.fastForward,
       wasFastForward: !!r.wasFastForward,
     });
     const authoredPace =
       (r.block.demoPace != null && r.block.demoPace !== "") ||
-      (r.demoPace != null && r.demoPace !== "");
+      (r.demoPace != null && r.demoPace !== "") ||
+      defaultPace != null;
     const cliFast = demoFast || fastBlockNames.has(r.block.name);
     pacing.demoPace =
       stepPace === "normal" && cliFast && !authoredPace
@@ -266,8 +271,9 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       (stage.state.lastTodoDock && stage.state.lastTodoDock.groups[0] && stage.state.lastTodoDock.groups[0].items) ||
       stubBeforePhase.todos ||
       [];
+    if (stubBeforePhase.title && String(stubBeforePhase.title).trim()) stickyTitle = String(stubBeforePhase.title).trim();
     const overlayTitle =
-      (stubBeforePhase.title && String(stubBeforePhase.title).trim()) ||
+      stickyTitle ||
       (r.episodeTitle && String(r.episodeTitle).trim()) ||
       title ||
       "waygraph demo";

package/dist/session/auto-explore.d.ts

@@ -24,7 +24,7 @@ export interface ExploreEdge extends WaygraphEdge {
     label?: string;
     instanceOption?: WaygraphInstanceOption;
 }
-export interface ExploreSection {
+interface ExploreSection {
     title: string;
     edges: ExploreEdge[];
 }
@@ -55,3 +55,4 @@ export declare function buildExploreContext(projectDir: string, opts?: ExploreCo
     graph: WaygraphGraph;
     library: Awaited<ReturnType<typeof loadBlockLibrary>>;
 }>;
+export {};

package/dist/session/auto-session-ipc.d.ts

@@ -1,6 +1,6 @@
 import { AutoSession, type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "../auto-session.js";
 import type { PilotHighlightFixtures } from "../pilot-overlay.js";
-export type { PilotHighlightFixtures, PilotFixtureRing } from "../pilot-overlay.js";
+export type { PilotHighlightFixtures } from "../pilot-overlay.js";
 export interface SessionMeta {
     sessionId: string;
     socketPath: string;
@@ -54,7 +54,6 @@ export type HighlightResponse = {
     ok: false;
     error: string;
 };
-export declare function readSessionMeta(projectDir: string, sessionId: string): SessionMeta | null;
 /**
  * Resolve session metadata from a project hint (cwd) or the global registry.
  * Fixes "session unreachable" when the agent calls status/send from a different

package/dist/session/auto-session-ipc.js

@@ -58,7 +58,7 @@ function logPathFor(projectDir, sessionId) {
 function generateSessionId() {
     return randomBytes(4).toString("hex");
 }
-export function readSessionMeta(projectDir, sessionId) {
+function readSessionMeta(projectDir, sessionId) {
     const p = metaPath(projectDir, sessionId);
     if (!existsSync(p))
         return null;

package/dist/session/block-inject.d.ts

@@ -1,21 +1,8 @@
-/**
- * This package's own installed root (contains `templates/`/`examples/`, sibling to `dist/`) -
- * this file compiles to `dist/session/block-inject.js`, two levels down, not one. Same class of
- * bug as `cli/util.ts`'s own `packageRoot()` (see its comment) - self-inflicted here by moving
- * this file into `src/session/` without updating the path math to match the new depth.
- */
-export declare function packageRoot(): string;
-/** Human label for an injected root (used in merged `file` paths). */
-export declare function injectLabel(root: string): string;
 /**
  * Display path for a Block discovered under an inject root (not the host cwd).
  * Primary project files stay relative as-is; injected ones are tagged `@label/...`.
  */
 export declare function injectTaggedFile(hostDir: string, root: string, relFile: string): string;
-/**
- * Resolve one `--inject` token to an absolute directory (preset name or path).
- */
-export declare function resolveInjectRoot(token: string, cwd?: string): string;
 export declare function resolveInjectRoots(tokens: string[], cwd?: string): string[];
 /** Roots to scan: host project first, then each inject path (deduped). */
 export declare function exploreRoots(projectDir: string, inject?: string[]): string[];

package/dist/session/block-inject.js

@@ -12,11 +12,11 @@ import { homedir } from "node:os";
  * bug as `cli/util.ts`'s own `packageRoot()` (see its comment) - self-inflicted here by moving
  * this file into `src/session/` without updating the path math to match the new depth.
  */
-export function packageRoot() {
+function packageRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 }
 /** Human label for an injected root (used in merged `file` paths). */
-export function injectLabel(root) {
+function injectLabel(root) {
     return basename(root.replace(/\/$/, ""));
 }
 /**
@@ -50,7 +50,7 @@ const PRESETS = {
 /**
  * Resolve one `--inject` token to an absolute directory (preset name or path).
  */
-export function resolveInjectRoot(token, cwd = process.cwd()) {
+function resolveInjectRoot(token, cwd = process.cwd()) {
     const raw = token.trim();
     if (!raw)
         throw new Error("waygraph inject: empty --inject value");

package/dist/session/pilot.d.ts

@@ -29,7 +29,6 @@
  * new execution primitive.
  */
 import { type WaygraphGraph } from "../analysis/graph.js";
-import { listBrowserSessions, type SessionMeta } from "./auto-session-ipc.js";
 import { type BrowserStartInit } from "./browser.js";
 import type { SessionSnapshot } from "../auto-session.js";
 export interface PilotStartResult {
@@ -51,4 +50,3 @@ export interface PilotStartResult {
 export declare function pilotStart(init: BrowserStartInit): Promise<PilotStartResult>;
 /** Reattach to an existing browser session — does not spawn a new browser. */
 export declare function pilotAttach(projectDir: string, sessionId: string, inject?: string[]): Promise<PilotStartResult>;
-export { listBrowserSessions, type SessionMeta };