waygraph 0.15.46 → 0.15.49

package/dist/errors.d.ts

@@ -9,102 +9,102 @@
  */
 export declare const WAYGRAPH_ERRORS: {
     readonly WG_PREFLIGHT_MISSING_KEY: {
-        readonly where: "engine/run-graph.ts - preflight()";
+        readonly where: "core/run-graph.ts - preflight()";
         readonly means: "A Flow/chain needs a MemKey that mem.set() never received before run() started.";
         readonly fix: "Pass --data / a mem.set() call for that key, or registerMemStub + --mem-stub for a fake value.";
     };
     readonly WG_RUNGRAPH_MAX_STEPS: {
-        readonly where: "engine/run-graph.ts - runGraph()";
+        readonly where: "core/run-graph.ts - runGraph()";
         readonly 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.";
         readonly fix: "Check the Block(s) involved in the loop; raise maxSteps only if the loop is genuinely intended.";
     };
     readonly WG_RUNGRAPH_NOT_TERMINAL: {
-        readonly where: "engine/run-graph.ts - runGraph()";
+        readonly where: "core/run-graph.ts - runGraph()";
         readonly means: "A Block with no .next() resolved to a Checkpoint that wasn't in the caller's declared `terminals` set.";
         readonly fix: "Add that Checkpoint to `terminals`, or fix the Block's resolve() - it landed somewhere the caller didn't expect.";
     };
     readonly WG_MAP_WRONG_KIND: {
-        readonly where: "engine/engine-class.ts - MapBuilder.gotoPage/gotoExternal/assert/method()";
+        readonly where: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal/assert/method()";
         readonly 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.";
         readonly fix: "Use the factory the error names, or move this Block to the matching .gotoPage()/.assert()/.method() call.";
     };
     readonly WG_MAP_WRONG_SALT: {
-        readonly where: "engine/engine-class.ts - MapBuilder.method()";
+        readonly where: "core/map-builder.ts - MapBuilder.method()";
         readonly means: "A Block passed to .method() isn't a real Method/Effect Block (missing __waygraphSalt).";
         readonly fix: "Build it with defineMethodBlock/defineEffectBlock, or use .assert() if it's actually a defineAssertBlock.";
     };
     readonly WG_MAP_WRONG_ORIGIN: {
-        readonly where: "engine/engine-class.ts - MapBuilder.gotoPage/gotoExternal()";
+        readonly where: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal()";
         readonly means: "A Block's static `url` origin doesn't match what .gotoPage() (same-origin) or .gotoExternal() (cross-origin) expects, given this map()'s homeOrigin.";
         readonly fix: "Use .gotoExternal() for a genuinely different origin, .gotoPage() for the app's own homeOrigin, or fix the Block's url.";
     };
     readonly WG_MAP_FF_ALREADY_OPEN: {
-        readonly where: "engine/engine-class.ts - MapBuilder.ffStart()";
+        readonly where: "core/map-builder.ts - MapBuilder.ffStart()";
         readonly means: ".ffStart() was called while a previous .ffStart() window is still open.";
         readonly fix: "Call .ffEnd() before opening another fast-forward window.";
     };
     readonly WG_MAP_FF_EMPTY: {
-        readonly where: "engine/engine-class.ts - MapBuilder.ffEnd()";
+        readonly where: "core/map-builder.ts - MapBuilder.ffEnd()";
         readonly means: ".ffEnd() closed a window with zero steps inside it.";
         readonly fix: "Add at least one .gotoPage()/.method()/.assert() inside the .ffStart()/.ffEnd() window.";
     };
     readonly WG_MAP_FF_NOT_CLOSED: {
-        readonly where: "engine/engine-class.ts - MapBuilder.end()";
+        readonly where: "core/map-builder.ts - MapBuilder.end()";
         readonly means: ".end() was called while a .ffStart() window was still open.";
         readonly fix: "Call .ffEnd() before .end().";
     };
     readonly WG_MAP_FF_NOT_OPEN: {
-        readonly where: "engine/engine-class.ts - MapBuilder.ffEnd()";
+        readonly where: "core/map-builder.ts - MapBuilder.ffEnd()";
         readonly means: ".ffEnd() was called with no matching .ffStart().";
         readonly fix: "Remove the stray .ffEnd(), or add the .ffStart() it's meant to close.";
     };
     readonly WG_MAP_EMPTY: {
-        readonly where: "engine/engine-class.ts - MapBuilder.end()";
+        readonly where: "core/map-builder.ts - MapBuilder.end()";
         readonly means: ".end() was called with zero steps added.";
         readonly fix: "Add at least one .gotoPage()/.gotoExternal()/.assert()/.method() before .end().";
     };
     readonly WG_MAP_BRANCH_NO_PRIOR_STEP: {
-        readonly where: "engine/engine-class.ts - MapBuilder.branch()";
+        readonly where: "core/map-builder.ts - MapBuilder.branch()";
         readonly means: ".branch() was called before any step existed to branch FROM.";
         readonly fix: "Add a .gotoPage()/.gotoExternal()/.method()/.assert() before .branch().";
     };
     readonly WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED: {
-        readonly where: "engine/engine-class.ts - a .branch()-built Flow's run()";
+        readonly where: "core/map-builder.ts - a .branch()-built Flow's run()";
         readonly 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.";
         readonly fix: "Call run(context, mem[, options]) instead, keeping the same page across the branch.";
     };
     readonly WG_BRANCH_REGRESSION_NO_BROWSER: {
-        readonly where: "engine/branch-regression.ts - runBranchRegression()";
+        readonly where: "core/branch-regression.ts - runBranchRegression()";
         readonly means: "cloneSession is on (the default) but context.browser() returned null - a persistent context has no Browser to clone a new context from.";
         readonly fix: "Pass { cloneSession: false } to run the single live path in this context instead.";
     };
     readonly WG_COMPOSE_EMPTY: {
-        readonly where: "engine/compose.ts - composeBlock()";
+        readonly where: "core/compose.ts - composeBlock()";
         readonly means: "composeBlock() was called with zero steps.";
         readonly fix: "Pass at least one Block.";
     };
     readonly WG_FASTFORWARD_EMPTY: {
-        readonly where: "engine/compose.ts - fastForwardComposeBlock()";
+        readonly where: "core/compose.ts - fastForwardComposeBlock()";
         readonly means: "A fast-forward window was closed with zero steps inside it.";
         readonly fix: "Add at least one Block between ffStart()/ffEnd() (or the equivalent Map builder call).";
     };
     readonly WG_FLOW_BLOCK_NOT_FOUND: {
-        readonly where: "engine/core.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)";
+        readonly where: "core/block.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)";
         readonly means: "The Block name/index/reference given doesn't exist in this Flow (or chained Flows).";
         readonly fix: "Check the name/index against flow.blocks() - it lists every Block this Flow actually has, tag-prefixed for branches.";
     };
     readonly WG_CHAINFLOW_EMPTY: {
-        readonly where: "engine/flow.ts - chainFlow()";
+        readonly where: "core/flow.ts - chainFlow()";
         readonly means: "chainFlow() was called with zero Flows.";
         readonly fix: "Pass at least one Flow.";
     };
     readonly WG_MODVERIFY_FUNCTION_FORM: {
-        readonly where: "engine/core.ts - modVerify()";
+        readonly where: "core/block.ts - modVerify()";
         readonly means: "modVerify() was called on a Block whose verify is a function (tag-driven), which has no fixed list to address an item into.";
         readonly fix: "Use withVerify() to replace the whole verify instead.";
     };
     readonly WG_MODVERIFY_NOT_FOUND: {
-        readonly where: "engine/core.ts - modVerify()";
+        readonly where: "core/block.ts - modVerify()";
         readonly means: "The Trait name/index given doesn't exist in this Block's verify list.";
         readonly fix: "Check the Block's actual verify list for the right name/index.";
     };
@@ -114,6 +114,40 @@ export declare const WAYGRAPH_ERRORS: {
         readonly 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 declare const MSG_PREFLIGHT_MISSING_KEY: (blockName: string, missingKeys: string) => string;
+export declare const MSG_RUNGRAPH_MAX_STEPS: (maxSteps: number) => string;
+export declare const MSG_RUNGRAPH_NOT_TERMINAL: (blockName: string, state: string, terminals: string) => string;
+export declare const MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX: (index: number, length: number) => string;
+export declare const MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME: (blockName: string, names: string) => string;
+export declare const MSG_MODVERIFY_FUNCTION_FORM: (blockName: string) => string;
+export declare const MSG_MODVERIFY_NOT_FOUND_BY_INDEX: (blockName: string, index: number, length: number) => string;
+export declare const MSG_MODVERIFY_NOT_FOUND_BY_NAME: (blockName: string, name: string, names: string) => string;
+export declare const MSG_MAP_WRONG_KIND: (method: string, blockName: string, wanted: string, found: string) => string;
+export declare const MSG_MAP_WRONG_SALT: (method: string, blockName: string, wanted: string, found: string) => string;
+export declare const MSG_MAP_WRONG_ORIGIN_INTERNAL: (blockName: string, targetOrigin: string, wantOrigin: string) => string;
+export declare const MSG_MAP_WRONG_ORIGIN_EXTERNAL: (blockName: string, targetOrigin: string, wantOrigin: string) => string;
+export declare const MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED: string;
+export declare const MSG_MAP_FF_ALREADY_OPEN: (ffName: string) => string;
+export declare const MSG_MAP_FF_NOT_OPEN = "Waygraph map: .ffEnd() with no open .ffStart()";
+export declare const MSG_MAP_FF_EMPTY: (ffName: string) => string;
+export declare const MSG_MAP_METHOD_GOT_ASSERT: (blockName: string) => string;
+export declare const MSG_MAP_BRANCH_NO_PRIOR_STEP: string;
+export declare const MSG_MAP_FF_NOT_CLOSED: (ffName: string) => string;
+export declare const MSG_MAP_EMPTY: string;
+export declare const MSG_BRANCH_REGRESSION_NO_BROWSER: string;
+export declare const MSG_MEM_READ_BEFORE_SET: (keyName: string) => string;
+export declare const MSG_COMPOSE_EMPTY: (name: string) => string;
+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";
 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/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 subtitle-bar caption (ported from zsign's help-center-clip-engine) - a full-width,
+     * bottom-anchored gradient scrim with centered text, 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 subtitle-bar caption (ported from zsign's help-center-clip-engine) - a full-width,
+     * bottom-anchored gradient scrim with centered text; distinct from {@link StubCtx.title}, which
+     * is the top 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";

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";

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, () => ({