waygraph 0.15.52 → 0.15.54

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-run.js

@@ -1,3 +1,4 @@
+import { getMemStub } from "../mem-stub.js";
 import { createInterface } from "node:readline/promises";
 import { ensureShadowRoot } from "../ui/shadow.js";
 import { stdin as input, stdout as output } from "node:process";
@@ -115,6 +116,11 @@ export function seedDefaultMem(library, mem) {
                 mem.set(k, envParsed[k.name]);
                 continue;
             }
+            const stub = getMemStub(k);
+            if (stub) {
+                mem.set(k, stub());
+                continue;
+            }
             const def = defaultMemValueForKey(k.name);
             if (def !== undefined)
                 mem.set(k, def);

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

@@ -10,11 +10,17 @@
  *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
  */
 import type { Page } from "@playwright/test";
+/** Selector matching every element waygraph's overlay draws into a page. */
 export declare const WG_UI_SEL = "[data-wg-ui=\"1\"]";
+/** Selector of the overlay element that appears when the step panel is ready. */
 export declare const WG_READY_PANEL_SEL = "[data-wg-modal=\"panel\"][data-wg-ready=\"1\"]";
+/** Selector of the overlay element that appears when the auto panel is ready. */
 export declare const WG_READY_AUTO_SEL = "[data-wg-modal=\"auto-panel\"][data-wg-ready=\"1\"]";
+/** Selector of the overlay element that appears when the banner is ready. */
 export declare const WG_READY_BANNER_SEL = "[data-wg-modal=\"banner\"][data-wg-ready=\"1\"]";
+/** The kind of modal the overlay beacon reports. */
 export type WgModalKind = "panel" | "banner" | "auto-panel";
+/** One overlay element a session reports through its beacon. */
 export type WgBeaconRow = {
     id: string | null;
     modal: string | null;
@@ -31,6 +37,7 @@ export type WgBeaconRow = {
 };
 /** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
 export declare function readWgOverlayBeaconInPage(): WgBeaconRow[];
+/** Reads the overlay beacon from a page: what waygraph's own UI is showing. */
 export declare function readWgOverlayBeacon(page: Page): Promise<WgBeaconRow[]>;
 /**
  * Hard gate: a blank / missing / opacity-0 modal fails.

package/dist/session/overlay-beacon.js

@@ -9,9 +9,13 @@
  * Agents: do not claim the stepper works unless
  *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
  */
+/** Selector matching every element waygraph's overlay draws into a page. */
 export const WG_UI_SEL = '[data-wg-ui="1"]';
+/** Selector of the overlay element that appears when the step panel is ready. */
 export const WG_READY_PANEL_SEL = '[data-wg-modal="panel"][data-wg-ready="1"]';
+/** Selector of the overlay element that appears when the auto panel is ready. */
 export const WG_READY_AUTO_SEL = '[data-wg-modal="auto-panel"][data-wg-ready="1"]';
+/** Selector of the overlay element that appears when the banner is ready. */
 export const WG_READY_BANNER_SEL = '[data-wg-modal="banner"][data-wg-ready="1"]';
 /** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
 export function readWgOverlayBeaconInPage() {
@@ -37,6 +41,7 @@ export function readWgOverlayBeaconInPage() {
         };
     });
 }
+/** Reads the overlay beacon from a page: what waygraph's own UI is showing. */
 export async function readWgOverlayBeacon(page) {
     return page.evaluate(() => {
         const w = window;

package/dist/session/pilot.d.ts

@@ -29,9 +29,9 @@
  * 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";
+/** What `pilotStart` returns: the session id, socket path and first snapshot. */
 export interface PilotStartResult {
     sessionId: string;
     socketPath: string;
@@ -51,4 +51,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 };

package/dist/session/pilot.js

@@ -29,7 +29,7 @@
  * new execution primitive.
  */
 import { discoverGraph } from "../analysis/graph.js";
-import { requestSession, listBrowserSessions, resolveSessionMeta, } from "./auto-session-ipc.js";
+import { requestSession, resolveSessionMeta, } from "./auto-session-ipc.js";
 import { browserStart } from "./browser.js";
 /**
  * Starts a detached session and reads back its own graph + starting
@@ -77,4 +77,3 @@ export async function pilotAttach(projectDir, sessionId, inject) {
         snapshot: status.snapshot,
     };
 }
-export { listBrowserSessions };

package/dist/traverse/coverage.d.ts

@@ -1,3 +1,4 @@
+/** The edge-coverage report `traverse` writes: which graph edges were walked. */
 export interface TraverseCoverageReport {
     version: 1;
     generatedAt: string;
@@ -27,10 +28,6 @@ export interface TraverseCoverageReport {
         leaf?: string;
     }>;
 }
-/** Static graph edge key = Block runtime name. */
-export declare function edgeKeyFromGraphEdge(edge: {
-    block: string;
-}): string;
 /** Collect unique edge keys from a WaygraphGraph-like edges list. */
 export declare function collectGraphEdgeKeys(edges: ReadonlyArray<{
     block: string;
@@ -45,6 +42,7 @@ export declare function normalizeHitKey(hitKey: string, graphKeys: ReadonlySet<s
  * Returns 0-1 fraction, or null when unset/invalid.
  */
 export declare function parseMinEdgeCoverage(raw: unknown): number | null;
+/** Builds the `traverse` coverage report from the edges walked and the graph's edges. */
 export declare function buildCoverageReport(opts: {
     projectDir: string;
     parallel: number;
@@ -55,5 +53,7 @@ export declare function buildCoverageReport(opts: {
 }): TraverseCoverageReport;
 /** Greppable one-liner for agents/CI. */
 export declare function formatCoverageLine(report: TraverseCoverageReport): string;
+/** Where `traverse` writes its coverage report by default. */
 export declare function defaultCoverageOutPath(projectDir: string): string;
+/** Writes the `traverse` coverage report to disk. */
 export declare function writeCoverageReport(path: string, report: TraverseCoverageReport): void;

package/dist/traverse/coverage.js

@@ -10,7 +10,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 /** Static graph edge key = Block runtime name. */
-export function edgeKeyFromGraphEdge(edge) {
+function edgeKeyFromGraphEdge(edge) {
     return edge.block;
 }
 /** Collect unique edge keys from a WaygraphGraph-like edges list. */
@@ -68,6 +68,7 @@ export function parseMinEdgeCoverage(raw) {
         return n / 100;
     return null;
 }
+/** Builds the `traverse` coverage report from the edges walked and the graph's edges. */
 export function buildCoverageReport(opts) {
     const all = [...new Set(opts.allEdgeKeys)].sort();
     const graphSet = new Set(all);
@@ -118,9 +119,11 @@ export function formatCoverageLine(report) {
         : "";
     return `[Coverage edges=${report.edgesHit}/${report.edgesTotal} ratio=${pct}%${minPart}]`;
 }
+/** Where `traverse` writes its coverage report by default. */
 export function defaultCoverageOutPath(projectDir) {
     return join(projectDir, ".waygraph-traverse", "coverage.json");
 }
+/** Writes the `traverse` coverage report to disk. */
 export function writeCoverageReport(path, report) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, JSON.stringify(report, null, 2) + "\n", "utf-8");

package/dist/traverse/lease.d.ts

@@ -2,6 +2,7 @@ export interface EdgeLeaseRecord {
     workerId: string;
     claimedAt: number;
 }
+/** Hands out graph edges to parallel `traverse` workers so no two workers walk the same edge. */
 export declare class EdgeLeaseCoordinator {
     private readonly held;
     private readonly dir;

package/dist/traverse/lease.js

@@ -5,6 +5,7 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+/** Hands out graph edges to parallel `traverse` workers so no two workers walk the same edge. */
 export class EdgeLeaseCoordinator {
     held = new Map();
     dir;

package/dist/traverse/run.d.ts

@@ -1,10 +1,13 @@
+/** How `traverse` workers share a browser: one session, or a clone per worker. */
 export type TraverseSessionMode = "clone" | "inherit";
+/** What one `traverse` worker did: edges walked and failures. */
 export interface TraverseWorkerResult {
     exitCode: number;
     steps: number;
     edgesHit: string[];
     leaf?: string;
 }
+/** Options for `runTraverse`: workers, session mode, step limit, coverage gate. */
 export interface TraverseOptions {
     baseURL?: string;
     startUrl?: string;

package/dist/types.d.ts

@@ -2,7 +2,7 @@ import type { Page } from "@playwright/test";
 import type { MemPage, MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
 import type { HighlightStubPhaseOrFn, WaygraphHighlight, WaygraphSlidesOrFn } from "./highlights.js";
-export type { WaygraphHighlight, WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, HighlightStubPhase, HighlightStubPhaseOrFn, HighlightFixtureMap, ResolvedHighlight, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, WaygraphTodoItem, WaygraphTodoInput, } from "./highlights.js";
+export type { WaygraphHighlight } from "./highlights.js";
 /**
  * A Checkpoint is identified solely by its string tag - a phantom marker with no
  * embedded data. Two Checkpoints with the same tag are the same state everywhere.

package/examples/routed-demo/src/flows/routed-demo-map.flow.ts

@@ -13,7 +13,7 @@ const homeOrigin = process.env.WAYGRAPH_BASE_URL || "http://127.0.0.1:4277";
 /**
  * Same real Blocks, same real Checkpoints, same real fixture server as
  * routed-demo.flow.ts - built with `engine.map()` instead of
- * `engine.defineFlow([start, ..., end])` to prove the fluent builder
+ * the deprecated `engine.defineFlow([start, ..., end])` to prove the fluent builder
  * against a real browser/DOM, not just the in-memory fakes
  * tests/nav/map-builder.spec.ts already covers in the main package.
  *

package/examples/routed-demo/src/flows/routed-demo.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end } from "waygraph";
+import { Engine } from "waygraph";
 import { NavDashboardBlock } from "../map/(app_base)/dashboard/_nav.block.js";
 import { ClickWidgetBlock } from "../map/(app_base)/dashboard/_methods/click-widget.block.js";
 import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
@@ -9,4 +9,4 @@ import "../map/(external)/docs/_page.block.js";
 const engine = new Engine();
 
 /** Smoke: dashboard -> click widget -> docs, all Blocks under the Waygraph Map folder convention. */
-export const routedDemoFlow = engine.defineFlow([start, NavDashboardBlock, ClickWidgetBlock, NavDocsBlock, end]);
+export const routedDemoFlow = engine.map().start().gotoPage(NavDashboardBlock).method(ClickWidgetBlock).gotoPage(NavDocsBlock).end();

package/examples/saucedemo/README.md

@@ -7,7 +7,6 @@ the **reference** for waygraph consumer conventions:
 - **Nav** / **Effect** / **Action** file kinds (helpers are TypeScript salt;
   runtime is still `Block`)
 - `instanceOptions` menus for `waygraph auto` (Add/Remove + Open details)
-- Detailed Kind / Helper / Route comments on every Block file
 - Per-route `NAV.md` + root `src/blocks/SITE-MAP.md`
 - Inline `{ ff: true }` fast-forward, no `.ffStart()/.ffEnd()` bracket - see
   `checkoutFlow` (`src/flows/checkout.flow.ts`)
@@ -44,30 +43,30 @@ npx playwright install chromium
 | Graph crawl (Phase B-E) | `npm run traverse` |
 | Parallel crawl + leases | `npm run traverse:parallel` |
 | Coverage JSON + min gate (10%) | `npm run traverse:coverage` |
-| Shop demo stepper | `npm run demo:step` |
+| Shop demo (login, then shop) | `npm run demo` |
 | Shop demo autoplay | `npm run demo:auto-next` |
-| **Device showcase** (mobile/tablet + portrait/landscape) | `npm run demo:device` |
-| Device showcase + `.webm` | `npm run demo:device:video` |
+| **Device showcase** (mobile/tablet + portrait/landscape; narration in `src/stubs/device-showcase.ts`) | `npm run demo:device` |
+| Device showcase + `.webm` | `npm run demo:video` |
 | **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
-| Cart bulk autoplay | `npm run demo:bulk:auto-next` |
 | **Owner checkout** (inline `{ ff: true }`, `ctx.caption()`, banner position) | `npm run demo:checkout` |
-| Owner checkout + `.webm` | `npm run demo:checkout:video` |
 | **FE + BE in one Flow** (`defineApiBlock`, live network panel) | `npm run demo:api` |
-| FE + BE demo + `.webm` | `npm run demo:api:video` |
+| Record (headless `.webm`) | `npm run record` |
 | List flows | `npm run flows` |
 
+Credentials and the selected item come from `registerMemStub` in `src/states/checkout.mem-stubs.ts` (`memStub: true` on the
+flows), so no command needs `--data`. Settings, the base URL and the shared `engine` are in `config/waygraph.config.ts`.
+Narration is chained on Blocks in the flows (`src/flows/`) or shared from `src/stubs/`; the Block files carry none.
+
 **Demo vs auto vs run for cart bulk**
 
 | | CLI | Needs `.flow.ts`? |
 |--|-----|-------------------|
-| **`run --blocks`** | `npm run run:bulk` — Block names + `--data` | No |
-| **`demo --blocks`** | `npm run demo:bulk` — named flow + `--data` | Optional (`cartBulkFlow`) |
+| **`run --blocks`** | `waygraph run --blocks "loginFlow then add-all-to-cart"` | No |
+| **`demo --blocks`** | `npm run demo:bulk` — named flow | Optional (`cartBulkFlow`) |
 | **`auto`** | `npm run auto` / `auto:cli` | No — live menu |
-| **`traverse`** | `npm run traverse` / `traverse:parallel` / `traverse:coverage` | No — graph crawl + `.waygraph-traverse/coverage.json` |
+| **`traverse`** | `npm run traverse` | No — graph crawl + `.waygraph-traverse/coverage.json` |
 | **`auto --blocks From To`** | path-find on graph | No — checkpoints only |
 
-QA watch+record: `npm run demo:bulk:video` (`--auto-play-video`).
-
 ## Layout (short)
 
 ```text

package/examples/saucedemo/config/waygraph.config.ts

@@ -0,0 +1,17 @@
+import { Engine, defineConfig } from "waygraph";
+
+const config = defineConfig({
+  baseUrl: "https://www.saucedemo.com",
+  playwright: {
+    workers: 1,
+    fullyParallel: false,
+    timeout: 30_000,
+    use: {
+      headless: true,
+      launchOptions: { args: ["--no-sandbox", "--disable-dev-shm-usage"] },
+    },
+  },
+});
+
+export default config;
+export const engine = new Engine(config);

package/examples/saucedemo/docs/CONVENTION.md

@@ -106,5 +106,4 @@ waygraph chain "loginFlow" --step --no-autoplay
 
 Flags beat env: `--step` / `--no-step`, `--autoplay` / `--no-autoplay`,
 `--base-url <url>`, `--title <text>`. Default BASE_URL resolution order for
-`demo`: `--base-url` > `WAYGRAPH_BASE_URL` > `package.json` `waygraph.baseUrl`
-> `playwright.config` `baseURL`.
+`demo`: `--base-url` > `WAYGRAPH_BASE_URL` > `baseUrl` in `config/waygraph.config.ts`.

package/examples/saucedemo/docs/HELPERS.md

@@ -110,7 +110,7 @@ branch(SubmitLoginBlock, {
 });
 ```
 
-Linear `defineFlow([start, …, end])` usually skips `branch()` (one happy path).
+A linear `map()` chain usually skips `branch()` (one happy path).
 
 ---
 

package/examples/saucedemo/package-lock.json

@@ -16,10 +16,12 @@
       }
     },
     "../..": {
-      "version": "0.15.19",
+      "version": "0.15.53",
       "license": "MIT",
       "dependencies": {
-        "tsx": "^4.0.0"
+        "open-props": "^1.7.23",
+        "tsx": "^4.0.0",
+        "urlpattern-polyfill": "^10.1.0"
       },
       "bin": {
         "waygraph": "bin/waygraph"
@@ -27,7 +29,12 @@
       "devDependencies": {
         "@playwright/test": "^1.63.0",
         "@types/node": "^26.0.0",
-        "typescript": "^5.6.0"
+        "knip": "^6.42.1",
+        "typedoc": "^0.28.20",
+        "typedoc-plugin-markdown": "^4.14.1",
+        "typedoc-vitepress-theme": "^1.1.4",
+        "typescript": "^5.6.0",
+        "vitepress": "^1.6.4"
       },
       "peerDependencies": {
         "@playwright/test": "^1.40.0"