waygraph 0.15.53 → 0.15.54

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

@@ -2,6 +2,7 @@ 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;
@@ -40,6 +41,7 @@ export interface DemoSettings extends RunSettings {
     /** 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;

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;

package/dist/core/branch-regression.d.ts

@@ -17,6 +17,7 @@ export declare function branchRoutes(flow: Flow<any>): ReadonlyMap<string, Flow<
  * `.branch()` continuations. Static - doesn't run anything.
  */
 export declare function collectBranchFlows(flow: Flow<any>): BranchEntry[];
+/** The outcome of one branch path in a branch regression run. */
 export interface BranchRunResult {
     path: string;
     status: "ok" | "failed";

package/dist/core/compose.d.ts

@@ -67,6 +67,7 @@ export interface FastForwardComposedBlock<In extends Checkpoint<string>, Out ext
 }
 /** True when `block` came from {@link fastForwardComposeBlock}. */
 export declare function isFastForwardBlock(block: Block<any, any>): block is FastForwardComposedBlock<any, any>;
+/** Like `composeBlock`, but the steps run as one blitz-paced unit in a demo. */
 export declare function fastForwardComposeBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, Out>]): FastForwardComposedBlock<In, Out>;
 export declare function fastForwardComposeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, Out>]): FastForwardComposedBlock<In, Out>;
 export declare function fastForwardComposeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, Out>]): FastForwardComposedBlock<In, Out>;

package/dist/core/flow.d.ts

@@ -66,6 +66,7 @@ export interface BlockInfo {
      */
     block: Block<any, any>;
 }
+/** A runnable chain of Blocks built by `engine.map()`. `run(mem)` launches its own browser; `run(context, mem)` reuses one. */
 export interface Flow<Out extends Checkpoint<string>> {
     /**
      * True once this Flow has been wrapped in {@link withSessionReset} - a

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

@@ -14,6 +14,7 @@ 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 for the map builder: `ff` fast-forwards the step, `pace` sets its demo pace. */
 export interface MapStepOpts {
     /**
      * Fast-forward just this step, inline - no `.ffStart()/.ffEnd()` bracket needed. Consecutive
@@ -29,6 +30,7 @@ export interface MapStepOpts {
      */
     pace?: DemoPace;
 }
+/** Flow-level settings for `engine.map({ … })`: `memStub`, `sessionReset`, `expectedFailure`, `demoPace`, `highlightStyle`, `homeOrigin`. */
 export interface MapBuilderOptions {
     /**
      * This project's own origin (e.g. `"https://app.example.com"`) - enables
@@ -39,6 +41,11 @@ export interface MapBuilderOptions {
     homeOrigin?: string;
     /** Fill missing `requires` keys from `registerMemStub` when the flow runs (what `withMemStub` did). */
     memStub?: boolean;
+    /**
+     * This flow wants a fresh browser session (cookies and storage cleared) when it runs after another one, in a CLI chain
+     * (`waygraph run "a then b"`) or nested with `.flow(sub)`: a second user signing in, a logged-out check.
+     */
+    sessionReset?: 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). */
@@ -48,7 +55,7 @@ export interface MapBuilderOptions {
 }
 /** 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). */
+    /** Clear cookies and storage right before the sub-flow, e.g. to start a second user fresh. Defaults to the sub-flow's own `sessionReset`. */
     reset?: boolean;
 }
 /**

package/dist/core/map-builder.js

@@ -308,7 +308,7 @@ export class MapBuilder {
     flow(sub, opts) {
         let next = this;
         sub.blocks().forEach((info, i) => {
-            const block = i === 0 && opts?.reset ? resetBefore(info.block) : info.block;
+            const block = i === 0 && (opts?.reset ?? sub.resetSession) ? resetBefore(info.block) : info.block;
             next = next.appendStep(block);
         });
         return next;

package/dist/core/run-graph.d.ts

@@ -36,6 +36,7 @@ export interface Layout {
     /** Function form gets the full resolved Checkpoint, same shape `runVerify`/a Block's own `verify` already use - not just the tag. */
     verify: Trait[] | ((out: Checkpoint<string>) => Trait[]);
 }
+/** Options for `defineLayout`: which Checkpoints it applies to and the Traits it enforces. */
 export interface LayoutOptions {
     name: string;
     description?: string;
@@ -142,6 +143,7 @@ export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<C
 export declare function narrate<T>(locator: Locator, caption: string, action: () => Promise<T>): Promise<T>;
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export declare const start: unique symbol;
+/** Marks the end of a hand-built chain. Only the deprecated `defineFlow` needs it; `map()` does not. */
 export declare const end: unique symbol;
 export type StartMarker = typeof start;
 export type EndMarker = typeof end;

package/dist/core/run-graph.js

@@ -219,4 +219,5 @@ export async function narrate(locator, caption, action) {
 }
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export const start = Symbol("waygraph.start");
+/** Marks the end of a hand-built chain. Only the deprecated `defineFlow` needs it; `map()` does not. */
 export const end = Symbol("waygraph.end");

package/dist/errors.d.ts

@@ -148,6 +148,7 @@ export declare const MSG_FASTFORWARD_EMPTY: (name: string) => string;
 export declare const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX: (index: number, count: number) => string;
 export declare const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME: (blockName: string) => string;
 export declare const MSG_CHAINFLOW_EMPTY = "chainFlow: give at least one Flow";
+/** The code of a `WaygraphError`, e.g. `WG_PREFLIGHT_MISSING_KEY`. */
 export type WaygraphErrorCode = keyof typeof WAYGRAPH_ERRORS;
 /** A thrown engine error with a stable, greppable `.code` - see WAYGRAPH_ERRORS for the full list. */
 export declare class WaygraphError extends Error {

package/dist/extensions.d.ts

@@ -4,6 +4,7 @@ export type ExtensionSpec = string | {
     path?: string;
     sha256?: string;
 };
+/** Names accepted in `extensions: [...]` mapped to their Chrome Web Store ids. */
 export declare const KNOWN_EXTENSIONS: Readonly<Record<string, string>>;
 /** Unpacks a .crx and pins the manifest `key`, so the extension keeps its store id (its origin is then stable, e.g. for an API allowlist). */
 export declare function unpackCrx(crx: Buffer, dest: string): void;

package/dist/extensions.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { homedir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { inflateRawSync } from "node:zlib";
+/** Names accepted in `extensions: [...]` mapped to their Chrome Web Store ids. */
 export const KNOWN_EXTENSIONS = {
     hoppscotch: "amknoiejhlmhancpahfcfcfhllgkpbld",
 };

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

@@ -9,11 +9,15 @@ export declare const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
 export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
 export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
+/** Turns any accepted pace spelling into a `DemoPace`; unknown values mean normal. */
 export declare function normalizeDemoPace(raw: unknown): DemoPace;
+/** The multiplier a pace applies to dwell and gate time (1 = normal); `demo.speeds` redefines the named ones. */
 export declare function demoPaceScale(pace: DemoPace): number;
+/** True when a pace is blitz: no cursor, ring pop or typing animation. */
 export declare function demoPaceIsBlitz(pace: DemoPace): boolean;
 /** True when pace should use the short-gate / fast fixture path (not slow authored). */
 export declare function demoPaceIsFast(pace: DemoPace): boolean;
+/** True when a pace lengthens dwell and gates. */
 export declare function demoPaceIsSlow(pace: DemoPace): boolean;
 /** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
 export declare function demoPaceGateMs(pace: DemoPace, baseAutoplayMs: number): number;

package/dist/highlights/demo-pace.js

@@ -8,6 +8,7 @@ export const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
 export const SLIDE_DURATION_MS_DEFAULT = FIXTURE_DURATION_MS_DEFAULT;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
 export const SLIDE_DURATION_FAST_MS_DEFAULT = FIXTURE_DURATION_FAST_MS_DEFAULT;
+/** Turns any accepted pace spelling into a `DemoPace`; unknown values mean normal. */
 export function normalizeDemoPace(raw) {
     if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
         return raw;
@@ -52,6 +53,7 @@ function paceSpeeds() {
     }
     return out;
 }
+/** The multiplier a pace applies to dwell and gate time (1 = normal); `demo.speeds` redefines the named ones. */
 export function demoPaceScale(pace) {
     if (typeof pace === "number") {
         if (pace > 20)
@@ -66,6 +68,7 @@ export function demoPaceScale(pace) {
         return paceSpeeds().slow;
     return 1;
 }
+/** True when a pace is blitz: no cursor, ring pop or typing animation. */
 export function demoPaceIsBlitz(pace) {
     return pace === "blitz" || (typeof pace === "number" && pace > 0 && pace <= 0.1);
 }
@@ -79,6 +82,7 @@ export function demoPaceIsFast(pace) {
         return pace < 0.75;
     return false;
 }
+/** True when a pace lengthens dwell and gates. */
 export function demoPaceIsSlow(pace) {
     if (pace === "slow")
         return true;

package/dist/highlights/device.d.ts

@@ -3,7 +3,9 @@ import type { DeviceOrientation, DevicePreset, DeviceState, DeviceViewport } fro
 export declare const DEVICE_PRESETS: Record<DevicePreset, Omit<DeviceState, "touchMode"> & {
     touchMode?: boolean;
 }>;
+/** Turns a device name (`mobile`, `tablet`, ...) into a known preset. */
 export declare function normalizeDevicePreset(raw: unknown): DevicePreset | undefined;
+/** Turns `portrait` / `landscape` spellings into a device orientation. */
 export declare function normalizeDeviceOrientation(raw: unknown): DeviceOrientation | undefined;
 /** Infer orientation from box (square counts as landscape). */
 export declare function orientationFromViewport(vp: DeviceViewport): DeviceOrientation;

package/dist/highlights/device.js

@@ -25,6 +25,7 @@ export const DEVICE_PRESETS = {
         orientation: "landscape",
     },
 };
+/** Turns a device name (`mobile`, `tablet`, ...) into a known preset. */
 export function normalizeDevicePreset(raw) {
     const s = String(raw ?? "")
         .trim()
@@ -37,6 +38,7 @@ export function normalizeDevicePreset(raw) {
         return "desktop";
     return undefined;
 }
+/** Turns `portrait` / `landscape` spellings into a device orientation. */
 export function normalizeDeviceOrientation(raw) {
     const s = String(raw ?? "")
         .trim()

package/dist/highlights/types.d.ts

@@ -33,6 +33,7 @@ export type WaygraphTodoItem = {
     /** Explicit current. If omitted, derived from todoIndex (index === todoIndex). */
     current?: boolean;
 };
+/** One todo item as authored: a string or `{ id, text, done }`. */
 export type WaygraphTodoInput = string | WaygraphTodoItem;
 /**
  * Dock list presentation:
@@ -69,6 +70,7 @@ export type WaygraphTodoGroupInput = {
     /** Sequential only: which item is current (0-based). */
     todoIndex?: number;
 };
+/** A titled checklist in the demo todo dock. */
 export type WaygraphTodoGroup = {
     id?: string;
     title?: string;
@@ -300,6 +302,7 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
 export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "zoomOut" | "focus" | "followMouse" | "follow" | "color" | "cursor" | "todo" | "gesture"> & FixtureDurationFields;
+/** A static stub phase: named ring slots to paint before or after a step. */
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 /**
  * Open stub lifecycle context. Authors set rings + episode fixtures freely —
@@ -459,6 +462,7 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
         highlights?: HighlightStubPhase;
     } & StubPhaseFixtures): void;
 };
+/** A stub callback: receives the stub `ctx` and paints rings, titles and todos. */
 export type StubLifecycleFn<Out extends Checkpoint<string>> = (ctx: StubCtx<Out>) => void | HighlightStubPhase | Promise<void | HighlightStubPhase>;
 /**
  * Block stub authoring:
@@ -551,6 +555,7 @@ export type HighlightStyleDefaults = {
  *   absolute gate/dwell ms when `> 20` (e.g. `4500`)
  */
 export type DemoPaceName = "blitz" | "fast" | "normal" | "slow";
+/** How fast a demo step runs: `"fast"`, `"slow"`, `"blitz"`, `"normal"`, or a multiplier (`0.5`, `2`). */
 export type DemoPace = DemoPaceName | number;
 export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
 /** Demo stub phase names (block instruction + flow fixtures). */
@@ -570,6 +575,7 @@ export interface WaygraphHighlight {
     label: string;
     tone?: HighlightTone;
 }
+/** A ring or caption after its defaults and overrides are merged, ready to paint. */
 export type ResolvedHighlight = WaygraphHighlightStub;
 export type StubBagState = {
     highlights: HighlightStubPhase;

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/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

@@ -31,6 +31,7 @@
 import { type WaygraphGraph } from "../analysis/graph.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;

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;
@@ -41,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;
@@ -51,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

@@ -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/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();