waygraph 0.15.52 → 0.15.54

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

@@ -16,6 +16,8 @@ export declare class Engine {
     private readonly config;
     constructor(config?: EngineConfig);
     /**
+     * @deprecated Build flows with `engine.map()`, which checks each step's Block kind and nests flows with `.flow()`.
+     *
      * Builds a runnable {@link Flow} from `[start, ...Blocks, end]`, typechecked
      * so each Block's `In` must match the previous Block's `Out` - the same
      * check `connect()` does, just declared as a flat array instead of hand-nested

package/dist/core/engine.js

@@ -36,7 +36,9 @@ export class Engine {
      *   .end();
      */
     map(options) {
-        return MapBuilder.begin(this.defineFlow.bind(this), options?.homeOrigin);
+        const { homeOrigin, ...flowOptions } = options ?? {};
+        const define = this.defineFlow.bind(this);
+        return MapBuilder.begin((blocks, extra) => define(blocks, { ...flowOptions, ...extra }), homeOrigin);
     }
 }
 /**

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
@@ -176,6 +177,7 @@ export declare function buildFlow<Out extends Checkpoint<string>>(middle: readon
  * 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 declare function withSessionReset<Out extends Checkpoint<string>>(flow: Flow<Out>): Flow<Out>;
 /**
@@ -184,6 +186,7 @@ export declare function withSessionReset<Out extends Checkpoint<string>>(flow: F
  * 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 declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
 /**
@@ -195,6 +198,7 @@ export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out
  * 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 declare function withMemStub<Out extends Checkpoint<string>>(flow: Flow<Out>): Flow<Out>;
 /**
@@ -205,17 +209,20 @@ export declare function withMemStub<Out extends Checkpoint<string>>(flow: Flow<O
  * @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 declare function withDemoPace<Out extends Checkpoint<string>>(flow: Flow<Out>, pace: DemoPace): Flow<Out>;
 /**
  * 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 declare function withHighlightStyle<Out extends Checkpoint<string>>(flow: Flow<Out>, style: HighlightStyleDefaults): Flow<Out>;
 /**
  * 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 declare function withBlockPace<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, pace: DemoPace): Block<In, Out>;
 /**
@@ -235,6 +242,7 @@ export declare function withBlockPace<In extends Checkpoint<string>, Out extends
  *   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 declare function withExpectedFailure<Out extends Checkpoint<string>>(flow: Flow<Out>, reason: string): Flow<Out>;
 /**
@@ -243,6 +251,7 @@ export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow
  * 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 declare function withHighlightFixtures<Out extends Checkpoint<string>>(flow: Flow<Out>, fixtures: import("../highlights.js").HighlightFixtureMap): Flow<Out>;
 /** Everything a `with*` wrapper can set, given up front: `engine.defineFlow([...], { title, memStub, ... })`. */
@@ -262,6 +271,7 @@ export interface FlowOptions {
 }
 /** Applies each set option through its `with*` wrapper, so both spellings produce the same Flow. */
 export declare function applyFlowOptions<Out extends Checkpoint<string>>(flow: Flow<Out>, options: FlowOptions | undefined): Flow<Out>;
+export declare function clearSessionState(context: BrowserContext, page: Page): Promise<void>;
 /**
  * Runs several complete, independent Flows one after another, reusing the
  * same page/context/mem in order - each remains its own validated
@@ -279,5 +289,6 @@ export declare function applyFlowOptions<Out extends Checkpoint<string>>(flow: F
  * 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 declare function chainFlow(...flows: readonly Flow<any>[]): Flow<any>;

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,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 every `MapBuilder` step method (`.gotoPage()`/`.method()`/`.assert()`) takes. */
+/** 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
@@ -22,7 +23,14 @@ 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;
 }
+/** 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
@@ -31,6 +39,24 @@ 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;
+    /**
+     * 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). */
+    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. Defaults to the sub-flow's own `sessionReset`. */
+    reset?: boolean;
 }
 /**
  * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
@@ -119,6 +145,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 +198,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 ?? sub.resetSession) ? 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/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,12 +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;
-/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
+/** 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;
@@ -34,6 +35,25 @@ 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;
+}
+/** 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)
@@ -41,13 +61,14 @@ 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;
 }
+/** 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);
 }
@@ -61,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;
@@ -73,6 +95,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/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;