waygraph 0.15.47 → 0.15.50

package/dist/errors.js

@@ -9,102 +9,102 @@
  */
 export const WAYGRAPH_ERRORS = {
     WG_PREFLIGHT_MISSING_KEY: {
-        where: "engine/run-graph.ts - preflight()",
+        where: "core/run-graph.ts - preflight()",
         means: "A Flow/chain needs a MemKey that mem.set() never received before run() started.",
         fix: "Pass --data / a mem.set() call for that key, or registerMemStub + --mem-stub for a fake value.",
     },
     WG_RUNGRAPH_MAX_STEPS: {
-        where: "engine/run-graph.ts - runGraph()",
+        where: "core/run-graph.ts - runGraph()",
         means: "A chain took more steps than maxSteps without reaching a Block with no .next() - almost always an unintended self-loop in branch()/next routing.",
         fix: "Check the Block(s) involved in the loop; raise maxSteps only if the loop is genuinely intended.",
     },
     WG_RUNGRAPH_NOT_TERMINAL: {
-        where: "engine/run-graph.ts - runGraph()",
+        where: "core/run-graph.ts - runGraph()",
         means: "A Block with no .next() resolved to a Checkpoint that wasn't in the caller's declared `terminals` set.",
         fix: "Add that Checkpoint to `terminals`, or fix the Block's resolve() - it landed somewhere the caller didn't expect.",
     },
     WG_MAP_WRONG_KIND: {
-        where: "engine/engine-class.ts - MapBuilder.gotoPage/gotoExternal/assert/method()",
+        where: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal/assert/method()",
         means: "A Block passed to a MapBuilder step method doesn't carry the __waygraphKind a real defineNavBlock/definePageBlock/defineAssertBlock/defineMethodBlock/defineEffectBlock stamps - either the wrong factory was used, or the object was hand-rolled instead of going through one.",
         fix: "Use the factory the error names, or move this Block to the matching .gotoPage()/.assert()/.method() call.",
     },
     WG_MAP_WRONG_SALT: {
-        where: "engine/engine-class.ts - MapBuilder.method()",
+        where: "core/map-builder.ts - MapBuilder.method()",
         means: "A Block passed to .method() isn't a real Method/Effect Block (missing __waygraphSalt).",
         fix: "Build it with defineMethodBlock/defineEffectBlock, or use .assert() if it's actually a defineAssertBlock.",
     },
     WG_MAP_WRONG_ORIGIN: {
-        where: "engine/engine-class.ts - MapBuilder.gotoPage/gotoExternal()",
+        where: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal()",
         means: "A Block's static `url` origin doesn't match what .gotoPage() (same-origin) or .gotoExternal() (cross-origin) expects, given this map()'s homeOrigin.",
         fix: "Use .gotoExternal() for a genuinely different origin, .gotoPage() for the app's own homeOrigin, or fix the Block's url.",
     },
     WG_MAP_FF_ALREADY_OPEN: {
-        where: "engine/engine-class.ts - MapBuilder.ffStart()",
+        where: "core/map-builder.ts - MapBuilder.ffStart()",
         means: ".ffStart() was called while a previous .ffStart() window is still open.",
         fix: "Call .ffEnd() before opening another fast-forward window.",
     },
     WG_MAP_FF_EMPTY: {
-        where: "engine/engine-class.ts - MapBuilder.ffEnd()",
+        where: "core/map-builder.ts - MapBuilder.ffEnd()",
         means: ".ffEnd() closed a window with zero steps inside it.",
         fix: "Add at least one .gotoPage()/.method()/.assert() inside the .ffStart()/.ffEnd() window.",
     },
     WG_MAP_FF_NOT_CLOSED: {
-        where: "engine/engine-class.ts - MapBuilder.end()",
+        where: "core/map-builder.ts - MapBuilder.end()",
         means: ".end() was called while a .ffStart() window was still open.",
         fix: "Call .ffEnd() before .end().",
     },
     WG_MAP_FF_NOT_OPEN: {
-        where: "engine/engine-class.ts - MapBuilder.ffEnd()",
+        where: "core/map-builder.ts - MapBuilder.ffEnd()",
         means: ".ffEnd() was called with no matching .ffStart().",
         fix: "Remove the stray .ffEnd(), or add the .ffStart() it's meant to close.",
     },
     WG_MAP_EMPTY: {
-        where: "engine/engine-class.ts - MapBuilder.end()",
+        where: "core/map-builder.ts - MapBuilder.end()",
         means: ".end() was called with zero steps added.",
         fix: "Add at least one .gotoPage()/.gotoExternal()/.assert()/.method() before .end().",
     },
     WG_MAP_BRANCH_NO_PRIOR_STEP: {
-        where: "engine/engine-class.ts - MapBuilder.branch()",
+        where: "core/map-builder.ts - MapBuilder.branch()",
         means: ".branch() was called before any step existed to branch FROM.",
         fix: "Add a .gotoPage()/.gotoExternal()/.method()/.assert() before .branch().",
     },
     WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED: {
-        where: "engine/engine-class.ts - a .branch()-built Flow's run()",
+        where: "core/map-builder.ts - a .branch()-built Flow's run()",
         means: "run(mem, config) was called on a branched Flow - that convenience form always closes its own browser/page before the branch's tag is known, so the branch can never be reached.",
         fix: "Call run(context, mem[, options]) instead, keeping the same page across the branch.",
     },
     WG_BRANCH_REGRESSION_NO_BROWSER: {
-        where: "engine/branch-regression.ts - runBranchRegression()",
+        where: "core/branch-regression.ts - runBranchRegression()",
         means: "cloneSession is on (the default) but context.browser() returned null - a persistent context has no Browser to clone a new context from.",
         fix: "Pass { cloneSession: false } to run the single live path in this context instead.",
     },
     WG_COMPOSE_EMPTY: {
-        where: "engine/compose.ts - composeBlock()",
+        where: "core/compose.ts - composeBlock()",
         means: "composeBlock() was called with zero steps.",
         fix: "Pass at least one Block.",
     },
     WG_FASTFORWARD_EMPTY: {
-        where: "engine/compose.ts - fastForwardComposeBlock()",
+        where: "core/compose.ts - fastForwardComposeBlock()",
         means: "A fast-forward window was closed with zero steps inside it.",
         fix: "Add at least one Block between ffStart()/ffEnd() (or the equivalent Map builder call).",
     },
     WG_FLOW_BLOCK_NOT_FOUND: {
-        where: "engine/core.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)",
+        where: "core/block.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)",
         means: "The Block name/index/reference given doesn't exist in this Flow (or chained Flows).",
         fix: "Check the name/index against flow.blocks() - it lists every Block this Flow actually has, tag-prefixed for branches.",
     },
     WG_CHAINFLOW_EMPTY: {
-        where: "engine/flow.ts - chainFlow()",
+        where: "core/flow.ts - chainFlow()",
         means: "chainFlow() was called with zero Flows.",
         fix: "Pass at least one Flow.",
     },
     WG_MODVERIFY_FUNCTION_FORM: {
-        where: "engine/core.ts - modVerify()",
+        where: "core/block.ts - modVerify()",
         means: "modVerify() was called on a Block whose verify is a function (tag-driven), which has no fixed list to address an item into.",
         fix: "Use withVerify() to replace the whole verify instead.",
     },
     WG_MODVERIFY_NOT_FOUND: {
-        where: "engine/core.ts - modVerify()",
+        where: "core/block.ts - modVerify()",
         means: "The Trait name/index given doesn't exist in this Block's verify list.",
         fix: "Check the Block's actual verify list for the right name/index.",
     },
@@ -114,6 +114,53 @@ export const WAYGRAPH_ERRORS = {
         fix: "Set it first, or use mem.has(key) to check before an optional read.",
     },
 };
+/**
+ * The actual text every `throw new WaygraphError(...)` site uses - one named export per throw
+ * site (several throw sites can share a `WAYGRAPH_ERRORS` code but always have their own distinct
+ * message here, since the same code can legitimately fire from more than one spot with different
+ * detail). Plain strings for a message with no runtime values; a function for one that needs them.
+ * `grep MSG_ src/errors.ts` finds every fixed string the engine can throw, in one place.
+ */
+export const MSG_PREFLIGHT_MISSING_KEY = (blockName, missingKeys) => `preflight: MemPage is missing required key(s) before "${blockName}" can run: ${missingKeys}`;
+export const MSG_RUNGRAPH_MAX_STEPS = (maxSteps) => `runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`;
+export const MSG_RUNGRAPH_NOT_TERMINAL = (blockName, state, terminals) => `runGraph: "${blockName}" resolved to "${state}", which is not a registered terminal (expected one of: ${terminals})`;
+export const MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX = (index, length) => `Flow: no Block at index ${index} in this flow (has ${length})`;
+export const MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME = (blockName, names) => `Flow: no Block named "${blockName}" in this flow (has: ${names})`;
+export const MSG_MODVERIFY_FUNCTION_FORM = (blockName) => `modVerify: "${blockName}" has a function-form verify, which has no fixed list to address into - ` +
+    "use withVerify to replace it wholesale instead";
+export const MSG_MODVERIFY_NOT_FOUND_BY_INDEX = (blockName, index, length) => `modVerify: "${blockName}" has no verify trait at index ${index} (has ${length})`;
+export const MSG_MODVERIFY_NOT_FOUND_BY_NAME = (blockName, name, names) => `modVerify: "${blockName}" has no verify trait named "${name}" (has: ${names || "none"})`;
+export const MSG_MAP_WRONG_KIND = (method, blockName, wanted, found) => `Waygraph map: .${method}("${blockName}") requires a Block built with ${wanted} ` +
+    `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
+    "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.";
+export const MSG_MAP_WRONG_SALT = (method, blockName, wanted, found) => `Waygraph map: .${method}("${blockName}") requires a Block built with ${wanted} ` +
+    `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
+    "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.";
+export const MSG_MAP_WRONG_ORIGIN_INTERNAL = (blockName, targetOrigin, wantOrigin) => `Waygraph map: .gotoPage("${blockName}") targets ${targetOrigin}, which is NOT this map's ` +
+    `home origin (${wantOrigin}) - use .gotoExternal() for a genuinely cross-origin destination.`;
+export const MSG_MAP_WRONG_ORIGIN_EXTERNAL = (blockName, targetOrigin, wantOrigin) => `Waygraph map: .gotoExternal("${blockName}") targets ${targetOrigin}, which IS this map's ` +
+    `home origin (${wantOrigin}) - use .gotoPage() for an internal destination.`;
+export const MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED = "Waygraph map: a .branch()-ed Flow can't run via run(mem, config) - that convenience form " +
+    "always closes its own browser/page before a branch's tag is even known. Call " +
+    "run(context, mem[, options]) instead, keeping the same page across the branch.";
+export const MSG_MAP_FF_ALREADY_OPEN = (ffName) => `Waygraph map: .ffStart() while already inside "${ffName}" - call .ffEnd() first`;
+export const MSG_MAP_FF_NOT_OPEN = "Waygraph map: .ffEnd() with no open .ffStart()";
+export const MSG_MAP_FF_EMPTY = (ffName) => `Waygraph map: .ffEnd() for "${ffName}" has no steps - add .gotoPage/.method/… inside the window`;
+export const MSG_MAP_METHOD_GOT_ASSERT = (blockName) => `Waygraph map: .method("${blockName}") got a defineAssertBlock - use .assert() for ` +
+    "self-loop verify steps (Assert Blocks share method salt internally but are not methods).";
+export const MSG_MAP_BRANCH_NO_PRIOR_STEP = "Waygraph map: .branch() needs at least one prior step - nothing to branch from. " +
+    "Add .gotoPage()/.gotoExternal()/.method()/.assert() first.";
+export const MSG_MAP_FF_NOT_CLOSED = (ffName) => `Waygraph map: .end() while .ffStart("${ffName}") is still open - call .ffEnd() first`;
+export const MSG_MAP_EMPTY = "Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
+    ".assert()/.method() before .end()";
+export const MSG_BRANCH_REGRESSION_NO_BROWSER = "Waygraph runBranchRegression: cloneSession needs context.browser() (a persistent context " +
+    "has none) - pass { cloneSession: false } to run the single live path in this context instead.";
+export const MSG_MEM_READ_BEFORE_SET = (keyName) => `MemPage: "${keyName}" read before it was set`;
+export const MSG_COMPOSE_EMPTY = (name) => `composeBlock: "${name}" needs at least one step`;
+export const MSG_FASTFORWARD_EMPTY = (name) => `fastForwardComposeBlock: "${name}" needs at least one step`;
+export const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX = (index, count) => `chainFlow: no Block at index ${index} across ${count} chained flows`;
+export const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME = (blockName) => `chainFlow: no Block named "${blockName}" in any chained flow`;
+export const MSG_CHAINFLOW_EMPTY = "chainFlow: give at least one Flow";
 /** A thrown engine error with a stable, greppable `.code` - see WAYGRAPH_ERRORS for the full list. */
 export class WaygraphError extends Error {
     code;

package/dist/highlights/run-phase.js

@@ -28,8 +28,14 @@ export async function runStubPhase(block, phase, opts) {
         catch {
             /* best-effort */
         }
-        // Compat: legacy `(out) => map` that expected Checkpoint (__state on arg)
-        if (Object.keys(bag.highlights).length === 0 && !bag.todos) {
+        // Compat: legacy `(out) => map` that expected Checkpoint (__state on arg). Only worth trying
+        // when the real ctx call genuinely did nothing - checked against the WHOLE bag, not just
+        // highlights/todos, so a stubBefore that only calls e.g. ctx.caption()/ctx.title()/ctx.zoom()
+        // (no highlights, no todos) isn't mistaken for "didn't run" and re-invoked with a bare
+        // Checkpoint that has none of StubCtx's methods - a real, previously-triggered bug (caught via
+        // examples/saucedemo/src/flows/checkout.flow.ts's own stubBefore(ctx) { ctx.caption(...) }).
+        const bagUntouched = Object.keys(bag).length === 1 && Object.keys(bag.highlights).length === 0;
+        if (bagUntouched) {
             try {
                 const legacyOut = (opts?.out ?? { __state: "" });
                 const ret2 = raw(legacyOut);
@@ -109,6 +115,13 @@ export async function runStubPhase(block, phase, opts) {
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
         ...(bag.titlePos !== undefined ? { titlePos: bag.titlePos } : {}),
         ...(bag.bannerUi !== undefined ? { bannerUi: bag.bannerUi } : {}),
+        // Unlike title, "" is meaningful here (ctx.hideCaption()/caption("")) - forwarded so it can
+        // actually hide the bar, not filtered out the way an empty title is (title's own "" means
+        // "author didn't touch it this step", handled by simply omitting the field).
+        ...(bag.caption !== undefined ? { caption: bag.caption } : {}),
+        // Boolean, not string - "" isn't a state here, so a plain undefined-check (like zoom/title)
+        // is enough; false is real ("author called hideNetworkTab()") and must still be forwarded.
+        ...(bag.networkTabVisible !== undefined ? { networkTabVisible: bag.networkTabVisible } : {}),
         ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
         ...(bag.todoDockUi !== undefined ? { todoDockUi: bag.todoDockUi } : {}),
         ...(bag.todoParallel === true ? { todoParallel: true } : {}),

package/dist/highlights/stub-ctx.js

@@ -179,6 +179,18 @@ export function createStubCtx(bag, opts) {
             if (p)
                 bag.titlePos = p;
         },
+        caption(text) {
+            bag.caption = String(text ?? "");
+        },
+        hideCaption() {
+            bag.caption = "";
+        },
+        showNetworkTab() {
+            bag.networkTabVisible = true;
+        },
+        hideNetworkTab() {
+            bag.networkTabVisible = false;
+        },
         bannerPos(side) {
             const p = normalizeBannerPos(side);
             if (p)
@@ -280,6 +292,10 @@ export function createStubCtx(bag, opts) {
                 bag.zoomOut = !!partial.zoomOut;
             if (partial.title !== undefined)
                 bag.title = String(partial.title ?? "");
+            if (partial.caption !== undefined)
+                bag.caption = String(partial.caption ?? "");
+            if (partial.networkTabVisible !== undefined)
+                bag.networkTabVisible = !!partial.networkTabVisible;
             const bp = normalizeBannerPos(partial.titlePos);
             if (bp)
                 bag.titlePos = bp;

package/dist/highlights/types.d.ts

@@ -49,6 +49,11 @@ export interface BannerUiOpts {
     collision?: boolean;
     /** Hide the banner entirely for this phase. */
     hidden?: boolean;
+    /**
+     * Fade duration (ms) when the banner's title text changes, so a change reads as a deliberate
+     * beat instead of an instant flicker. Default 220; 0 disables the fade (instant swap).
+     */
+    captionFadeMs?: number;
 }
 /** One titled group in the floating todo dock (FR / Scenarios / ACs, etc.). */
 export type WaygraphTodoGroupInput = {
@@ -159,6 +164,18 @@ export type StubPhaseFixtures = {
     titlePos?: BannerPos;
     /** Banner UX: collision (move away from a ring it overlaps), hidden. See {@link BannerUiOpts}. */
     bannerUi?: BannerUiOpts;
+    /**
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill, distinct from the banner (top, card-shaped). Omit/clear to hide it; set again
+     * to change the text, fading out/in.
+     */
+    caption?: string;
+    /**
+     * Network-tab overlay visibility - capture always happens in the background regardless; this
+     * only controls whether the panel itself is shown. Intentionally hidden by default (`undefined`
+     * on the very first phase); omit to leave whatever the previous step set alone.
+     */
+    networkTabVisible?: boolean;
     /**
      * Floating checklist dock side. `left` | `right`.
      * Authored control (also click / WAYGRAPH_TODO_POS / --todo-left|right).
@@ -403,8 +420,25 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
      * @example ctx.bannerUi({ collision: false });
      */
     bannerUi(opts: BannerUiOpts): void;
+    /**
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill; distinct from {@link StubCtx.title}, which is the top banner card. Fades in/out
+     * on change. Pass `""` (or call {@link StubCtx.hideCaption}) to clear.
+     * @example ctx.caption("Click Add to cart to continue");
+     */
+    caption(text: string): void;
+    /** Clears the caption (fades it out). */
+    hideCaption(): void;
     /** Shorthand for `bannerUi({ hidden: true })`. */
     hideBanner(): void;
+    /**
+     * Shows the network-tab overlay (Postman-style inspector of real page traffic + defineApiBlock
+     * calls) - capture always runs in the background; this just reveals the panel. Hidden by default.
+     * @example ctx.showNetworkTab();
+     */
+    showNetworkTab(): void;
+    /** Hides the network-tab overlay (capture keeps running - only the panel disappears). */
+    hideNetworkTab(): void;
     /**
      * Floating checklist dock side (`left` | `right`). Authors control this in
      * code; click / env / --todo-left|right are fallbacks.
@@ -463,6 +497,8 @@ export type StubPhaseResult = {
     title?: string;
     titlePos?: BannerPos;
     bannerUi?: BannerUiOpts;
+    caption?: string;
+    networkTabVisible?: boolean;
     todoPos?: "left" | "right";
     /** When true, keep other docks (multi-todo). Default false = replace. */
     todoParallel?: boolean;
@@ -560,6 +596,8 @@ export type StubBagState = {
     title?: string | undefined;
     titlePos?: BannerPos | undefined;
     bannerUi?: BannerUiOpts | undefined;
+    caption?: string | undefined;
+    networkTabVisible?: boolean | undefined;
     todoPos?: "left" | "right" | undefined;
     /** Author patched todo-dock UX this phase. */
     todoDockUi?: TodoDockUiOpts | undefined;

package/dist/index.d.ts

@@ -6,11 +6,13 @@ export { css, byText, byRole } from "./selector.js";
 export { WaygraphError, WAYGRAPH_ERRORS } from "./errors.js";
 export type { WaygraphErrorCode } from "./errors.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./engine.js";
-export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./engine/branch-regression.js";
+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, 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 { 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, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";
+export type { Flow, 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";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./analysis/graph.js";
@@ -27,3 +29,5 @@ export { AutoSession, stubFilePath } from "./auto-session.js";
 export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnapshotSection, ApplyPickResult, ApplyPathResult, TraceStep, ConsoleLogEntry, StorageSnapshot, ServiceWorkerRegistrationInfo, CookieInfo, StubFileKind, } from "./auto-session.js";
 export { pilotStart } from "./session/pilot.js";
 export type { PilotStartResult } from "./session/pilot.js";
+export { defineConfig, resolveBaseUrl } from "./config.js";
+export type { WaygraphConfig } from "./config.js";

package/dist/index.js

@@ -4,7 +4,7 @@ export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
 export { css, byText, byRole } from "./selector.js";
 export { WaygraphError, WAYGRAPH_ERRORS } from "./errors.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./engine.js";
+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, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.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 { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
@@ -14,3 +14,4 @@ export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, form
 export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./session/overlay-beacon.js";
 export { AutoSession, stubFilePath } from "./auto-session.js";
 export { pilotStart } from "./session/pilot.js";
+export { defineConfig, resolveBaseUrl } from "./config.js";

package/dist/mem-page.js

@@ -1,4 +1,4 @@
-import { WaygraphError } from "./errors.js";
+import { WaygraphError, MSG_MEM_READ_BEFORE_SET } from "./errors.js";
 /**
  * A typed key into MemPage. The phantom `_phantom` field is never assigned - it
  * exists only so TypeScript can infer `T` at each call site. The store is keyed by
@@ -52,7 +52,7 @@ export class MemPage {
      */
     get(k) {
         if (!this.store.has(k)) {
-            throw new WaygraphError("WG_MEM_READ_BEFORE_SET", `MemPage: "${k.name}" read before it was set`);
+            throw new WaygraphError("WG_MEM_READ_BEFORE_SET", MSG_MEM_READ_BEFORE_SET(k.name));
         }
         return this.store.get(k);
     }

package/dist/mem-stub.d.ts

@@ -17,7 +17,7 @@
  */
 import type { MemKey } from "./mem-page.js";
 import type { MemPage } from "./mem-page.js";
-import type { Flow } from "./engine.js";
+import type { Flow } from "./core.js";
 /**
  * Registers a fake-value generator for one required MemKey.
  * @example registerMemStub(LoginCreds.key, () => ({

package/dist/pilot-overlay/fixtures.js

@@ -1,6 +1,7 @@
 // Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { buildTodoDock, formatHighlightCaption, normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight, resolveDeviceState, resolveTodoDockUi } from "../highlights.js";
 import { ensureInstalled } from "./shell.js";
+import { verboseLog } from "../auto-session/verbose-log.js";
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.
  * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
@@ -117,8 +118,34 @@ export async function showPilotFixtures(page, fixtures) {
         })
             .catch(() => { });
     }
+    // Resolve every ring's box (and the zoom target, if any) through Playwright's own locator, not a
+    // selector string handed to the page for a raw DOM querySelector to fail silently on - >>
+    // piercing / :has-text() / :visible are Playwright-only selector syntax. "Prefer live in-page
+    // rect (honors device-shell scale)" still holds: .evaluate() runs the callback bound to the
+    // resolved element, in the page's own real JS context, same as before - only the RESOLUTION
+    // step moved from an in-page querySelector to Playwright's full selector engine. count() gate:
+    // Locator.evaluate() has no timeout option and auto-waits ~30s for a match to appear - count()
+    // never waits, so a genuinely-missing selector (a real, expected case - see `missing` below)
+    // still resolves immediately instead of hanging.
+    const ringBoxes = await Promise.all(rings.map(async (r) => {
+        const loc = page.locator(r.selector).first();
+        if ((await loc.count().catch(() => 0)) === 0)
+            return null;
+        return loc
+            .evaluate((el) => {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0)
+                return null;
+            return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+        })
+            .catch(() => null);
+    }));
+    const resolvedZoomSelector = zoomSelector ?? "";
+    const zoomHandle = zoom > 1.001 && resolvedZoomSelector
+        ? await page.locator(resolvedZoomSelector).first().elementHandle({ timeout: 100 }).catch(() => null)
+        : null;
     return page
-        .evaluate(({ rings, todoGroups, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, todoUi, }) => {
+        .evaluate(({ rings, ringBoxes, todoGroups, todoPos, holdMs, zoom, zoomSelector, zoomEl, zoomOut, clearAll, todoUi, }) => {
         const w = window;
         if (w.__wgPilotFxHideTimer)
             clearTimeout(w.__wgPilotFxHideTimer);
@@ -193,17 +220,11 @@ export async function showPilotFixtures(page, fixtures) {
         // (window.__wgPaintRingAt, installed by runner/inpage/core.js's installCore - see
         // ensureInstalled) - one ring implementation, not a separate DOM-building copy here.
         rings.forEach((ring, i) => {
-            const el = document.querySelector(ring.selector);
-            if (!el) {
-                missing.push(ring.selector);
-                return;
-            }
-            const rect = el.getBoundingClientRect();
-            if (rect.width === 0 && rect.height === 0) {
+            const box = ringBoxes[i];
+            if (!box) {
                 missing.push(ring.selector);
                 return;
             }
-            const box = { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
             const ringId = `wg-fx-ring-${i}`;
             const labelId = `wg-fx-ring-${i}-label`;
             if (window.__wgPaintRingAt) {
@@ -294,7 +315,7 @@ export async function showPilotFixtures(page, fixtures) {
             }
         }
         if (zoom > 1.001 && zoomSelector) {
-            const target = document.querySelector(zoomSelector);
+            const target = zoomEl;
             if (target) {
                 target.scrollIntoView({
                     block: "center",
@@ -322,14 +343,25 @@ export async function showPilotFixtures(page, fixtures) {
         return { painted, missing };
     }, {
         rings,
+        ringBoxes,
         todoGroups,
         todoPos,
         holdMs,
         zoom,
         zoomSelector: zoomSelector ?? "",
+        zoomEl: zoomHandle,
         zoomOut,
         clearAll: fixtures.clear === true,
         todoUi,
+    })
+        .then((result) => {
+        // Debuggability: a demo/pilot run is a sequential list of steps - when a ring silently
+        // doesn't render, "where in the flow" and "which selector" are exactly what's needed to fix
+        // it, not a quiet no-op. See rings.js/slides.js/teardown.js for the same fix, same reason.
+        for (const sel of result.missing) {
+            verboseLog("pilot", `ring not painted - selector matched nothing (or a zero-size element): ${sel}`);
+        }
+        return result;
     })
         .catch(() => ({ painted: 0, missing: rings.map((r) => r.selector) }));
 }

package/dist/pilot-overlay/shell.js

@@ -1,6 +1,7 @@
 // Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { SURFACE } from "../ui/tokens.js";
 import { ensureShadowRoot, installShadowRoot } from "../ui/shadow.js";
+import { verboseLog } from "../auto-session/verbose-log.js";
 // Real, direct user request: this overlay's own colors were an improvised
 // purple/white scheme (#a78bfa / #1a1033) that didn't match anything else -
 // "our design here seems like barely shares with the ui on the stepper
@@ -216,8 +217,26 @@ export async function showPilotActivity(page, text) {
  */
 export async function showPilotVision(page, selector, label, tone = "auto") {
     await ensureInstalled(page);
+    // Resolved through Playwright's own locator (>> piercing / :has-text() / :visible support), not
+    // a raw querySelector string - see rings.js's showRing for the same fix, same reason. count()
+    // gate: Locator.evaluate() has no timeout option and auto-waits ~30s for a match to appear -
+    // count() never waits, keeping this an immediate "does it exist right now" check.
+    const visionLoc = page.locator(selector).first();
+    const box = (await visionLoc.count().catch(() => 0)) > 0
+        ? await visionLoc
+            .evaluate((el) => {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0)
+                return null;
+            return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+        })
+            .catch(() => null)
+        : null;
+    if (!box) {
+        verboseLog("pilot", `vision ring not painted - selector matched nothing (or a zero-size element): ${selector}`);
+    }
     await page
-        .evaluate(({ selector, label, tone }) => {
+        .evaluate(({ box, label, tone }) => {
         const ring = __wgById("wg-ring");
         const tag = __wgById("wg-ring-label");
         if (!ring || !tag)
@@ -225,18 +244,12 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
         const w = window;
         if (w.__wgVisionHideTimer)
             clearTimeout(w.__wgVisionHideTimer);
-        const el = document.querySelector(selector);
-        if (!el) {
-            ring.style.opacity = "0";
-            tag.style.opacity = "0";
-            return;
-        }
-        const rect = el.getBoundingClientRect();
-        if (rect.width === 0 && rect.height === 0) {
+        if (!box) {
             ring.style.opacity = "0";
             tag.style.opacity = "0";
             return;
         }
+        const rect = box;
         ring.dataset.tone = tone;
         ring.dataset.size = "md";
         tag.dataset.tone = tone;
@@ -262,6 +275,6 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
             ring.style.opacity = "0";
             tag.style.opacity = "0";
         }, 4_000);
-    }, { selector, label, tone })
+    }, { box, label, tone })
         .catch(() => { });
 }

package/dist/runner/banner-log.js

@@ -9,6 +9,7 @@ export function bannerUiFromPhase(phase) {
   if (phase && phase.bannerUi) {
     if (phase.bannerUi.collision !== undefined) ui.collision = !!phase.bannerUi.collision;
     if (phase.bannerUi.hidden !== undefined) ui.hidden = !!phase.bannerUi.hidden;
+    if (phase.bannerUi.captionFadeMs !== undefined) ui.captionFadeMs = Number(phase.bannerUi.captionFadeMs);
   }
   return ui;
 }