waygraph 0.15.53 → 0.16.0

package/dist/engine/env.d.ts

@@ -0,0 +1,59 @@
+export declare const WAYGRAPH_ENV: {
+    readonly WAYGRAPH_BASE_URL: "Base URL for relative gotos (--base-url, the config's baseUrl)";
+    readonly WAYGRAPH_CONFIG: "Which config file to load (--config <name|file>)";
+    readonly WAYGRAPH_ENV: "Env mode: loads .env.<mode> on top of .env (--env)";
+    readonly WAYGRAPH_COMMAND: "The command running (run / demo / test), so the config's per-command section applies";
+    readonly WAYGRAPH_PROJECT_DIR: "The project waygraph test runs Playwright for";
+    readonly WAYGRAPH_HEADED: "1 shows the browser, 0 hides it (--non-headless; demo default 1)";
+    readonly WAYGRAPH_STEP: "1 plays steps through the demo stepper (demo, run --step)";
+    readonly WAYGRAPH_JSON: "1 prints a JSON report instead of the demo log";
+    readonly WAYGRAPH_ALL_BRANCHES: "1 explores every branch() path (--all-branches)";
+    readonly WAYGRAPH_SHARED_SESSION: "1 keeps one session across branches (--shared-session)";
+    readonly WAYGRAPH_TITLE: "Demo banner title (--title)";
+    readonly WAYGRAPH_TITLE_POS: "Demo banner position: left | center | right";
+    readonly WAYGRAPH_DATA: "Mem seed JSON (--data)";
+    readonly WAYGRAPH_AUTO_MEM: "Mem seed JSON for auto sessions (same as WAYGRAPH_DATA)";
+    readonly WAYGRAPH_MEM_STUB: "1 fills missing requires from registerMemStub (--mem-stub)";
+    readonly WAYGRAPH_AUTOPLAY: "1 advances demo steps on their own (--auto-next)";
+    readonly WAYGRAPH_AUTOPLAY_MS: "Auto-next wait per step, ms (default 1800)";
+    readonly WAYGRAPH_DEMO_FAST: "1 shortens the demo's gates (--fast)";
+    readonly WAYGRAPH_DEMO_PACE: "Default pace for every demo step (the config's demo.pace)";
+    readonly WAYGRAPH_PACE_SPEEDS: "JSON of pace multipliers, e.g. {\"fast\":0.5}";
+    readonly WAYGRAPH_FAST_BLOCKS: "Comma-separated Block names that skip the demo's added dwell";
+    readonly WAYGRAPH_SLOWMO: "Playwright slowMo / the demo's beat after each action, ms";
+    readonly WAYGRAPH_TYPING_MS: "Demo typing delay per character, ms (default 30)";
+    readonly WAYGRAPH_SWIPE_MS: "Demo swipe gesture duration, ms (default 650)";
+    readonly WAYGRAPH_DEVICE_TRANSITION_MS: "Demo device resize animation, ms (default 520)";
+    readonly WAYGRAPH_STEPPER: "full shows every step chip (--full); default carousel";
+    readonly WAYGRAPH_MINI: "1 forces the compact stepper panel (--mini)";
+    readonly WAYGRAPH_TODO_POS: "Todo dock side: left | right (--todo-left / --todo-right)";
+    readonly WAYGRAPH_TODO_UI: "full turns off the todo dock's compact / collision / behind-ring (--todo-full)";
+    readonly WAYGRAPH_TODO_COLLISION: "0 turns off the todo dock moving away from a ring";
+    readonly WAYGRAPH_TODO_BEHIND: "0 turns off dimming the todo dock behind a ring";
+    readonly WAYGRAPH_TODO_COMPACT: "0 turns off folding long todo lists";
+    readonly WAYGRAPH_TODO_CAP: "Rows a folded todo list shows (default 5)";
+    readonly WAYGRAPH_TODO_EXPAND_CAP: "Rows a hovered todo list shows (default 14)";
+    readonly WAYGRAPH_FF_EXPAND: "1 plays fast-forward units step by step (--ff-expand)";
+    readonly WAYGRAPH_FF_DISABLED: "1 expands fast-forward units and keeps their blitz pace (--ff-disabled)";
+    readonly WAYGRAPH_CLEAR_SESSION: "1 clears the session before every step after the first";
+    readonly WAYGRAPH_VIDEO: "Record a video: the folder, or 1 for the default (--video)";
+    readonly WAYGRAPH_VIDEO_DIR: "Default video folder";
+    readonly WAYGRAPH_VIDEO_VIEWPORT: "Recording size, e.g. 1920x1080 (--video-viewport)";
+    readonly WAYGRAPH_RUN_LOG: "Run log: 0 turns it off, or a folder (the config's runLog)";
+    readonly WAYGRAPH_EXTENSIONS: "Unpacked browser extension folders, path-separated (overrides the config's extensions)";
+    readonly WAYGRAPH_CACHE_DIR: "Where downloaded extensions are cached";
+    readonly WAYGRAPH_PROVE_SHOT: "Demo self-check: screenshot path for the overlay proof";
+    readonly WAYGRAPH_PROVE_EXIT: "1 exits after the first overlay proof (demo self-check)";
+    readonly WAYGRAPH_PROVE_EVERY: "1 proves the overlay on every step, not only the first";
+};
+export type WaygraphEnvName = keyof typeof WAYGRAPH_ENV;
+/** The raw value, or undefined when unset. */
+export declare function envString(name: WaygraphEnvName): string | undefined;
+/** On / off: 1 / true / yes / on, or 0 / false / no / off; `fallback` when unset or anything else. */
+export declare function envSwitch(name: WaygraphEnvName, fallback: boolean): boolean;
+/** True only when switched on. */
+export declare function envFlag(name: WaygraphEnvName): boolean;
+/** The value as a number, or undefined when unset or not a number. */
+export declare function envNumber(name: WaygraphEnvName): number | undefined;
+/** Sets a variable (for the runner child the CLI spawns); undefined unsets it. */
+export declare function setEnv(name: WaygraphEnvName, value: string | undefined): void;

package/dist/engine/env.js

@@ -0,0 +1,83 @@
+// Every WAYGRAPH_* variable waygraph reads, in one place: what it means and how it is read. The CLI writes most of them
+// from flags (cli/flags.ts) and the config file (runtime/waygraph-config.ts) so the runner child it spawns inherits them; the
+// rest are environment-only knobs. Nothing else touches process.env.WAYGRAPH_* (check:structure enforces it).
+export const WAYGRAPH_ENV = {
+    WAYGRAPH_BASE_URL: "Base URL for relative gotos (--base-url, the config's baseUrl)",
+    WAYGRAPH_CONFIG: "Which config file to load (--config <name|file>)",
+    WAYGRAPH_ENV: "Env mode: loads .env.<mode> on top of .env (--env)",
+    WAYGRAPH_COMMAND: "The command running (run / demo / test), so the config's per-command section applies",
+    WAYGRAPH_PROJECT_DIR: "The project waygraph test runs Playwright for",
+    WAYGRAPH_HEADED: "1 shows the browser, 0 hides it (--non-headless; demo default 1)",
+    WAYGRAPH_STEP: "1 plays steps through the demo stepper (demo, run --step)",
+    WAYGRAPH_JSON: "1 prints a JSON report instead of the demo log",
+    WAYGRAPH_ALL_BRANCHES: "1 explores every branch() path (--all-branches)",
+    WAYGRAPH_SHARED_SESSION: "1 keeps one session across branches (--shared-session)",
+    WAYGRAPH_TITLE: "Demo banner title (--title)",
+    WAYGRAPH_TITLE_POS: "Demo banner position: left | center | right",
+    WAYGRAPH_DATA: "Mem seed JSON (--data)",
+    WAYGRAPH_AUTO_MEM: "Mem seed JSON for auto sessions (same as WAYGRAPH_DATA)",
+    WAYGRAPH_MEM_STUB: "1 fills missing requires from registerMemStub (--mem-stub)",
+    WAYGRAPH_AUTOPLAY: "1 advances demo steps on their own (--auto-next)",
+    WAYGRAPH_AUTOPLAY_MS: "Auto-next wait per step, ms (default 1800)",
+    WAYGRAPH_DEMO_FAST: "1 shortens the demo's gates (--fast)",
+    WAYGRAPH_DEMO_PACE: "Default pace for every demo step (the config's demo.pace)",
+    WAYGRAPH_PACE_SPEEDS: "JSON of pace multipliers, e.g. {\"fast\":0.5}",
+    WAYGRAPH_FAST_BLOCKS: "Comma-separated Block names that skip the demo's added dwell",
+    WAYGRAPH_SLOWMO: "Playwright slowMo / the demo's beat after each action, ms",
+    WAYGRAPH_TYPING_MS: "Demo typing delay per character, ms (default 30)",
+    WAYGRAPH_SWIPE_MS: "Demo swipe gesture duration, ms (default 650)",
+    WAYGRAPH_DEVICE_TRANSITION_MS: "Demo device resize animation, ms (default 520)",
+    WAYGRAPH_STEPPER: "full shows every step chip (--full); default carousel",
+    WAYGRAPH_MINI: "1 forces the compact stepper panel (--mini)",
+    WAYGRAPH_TODO_POS: "Todo dock side: left | right (--todo-left / --todo-right)",
+    WAYGRAPH_TODO_UI: "full turns off the todo dock's compact / collision / behind-ring (--todo-full)",
+    WAYGRAPH_TODO_COLLISION: "0 turns off the todo dock moving away from a ring",
+    WAYGRAPH_TODO_BEHIND: "0 turns off dimming the todo dock behind a ring",
+    WAYGRAPH_TODO_COMPACT: "0 turns off folding long todo lists",
+    WAYGRAPH_TODO_CAP: "Rows a folded todo list shows (default 5)",
+    WAYGRAPH_TODO_EXPAND_CAP: "Rows a hovered todo list shows (default 14)",
+    WAYGRAPH_FF_EXPAND: "1 plays fast-forward units step by step (--ff-expand)",
+    WAYGRAPH_FF_DISABLED: "1 expands fast-forward units and keeps their blitz pace (--ff-disabled)",
+    WAYGRAPH_CLEAR_SESSION: "1 clears the session before every step after the first",
+    WAYGRAPH_VIDEO: "Record a video: the folder, or 1 for the default (--video)",
+    WAYGRAPH_VIDEO_DIR: "Default video folder",
+    WAYGRAPH_VIDEO_VIEWPORT: "Recording size, e.g. 1920x1080 (--video-viewport)",
+    WAYGRAPH_RUN_LOG: "Run log: 0 turns it off, or a folder (the config's runLog)",
+    WAYGRAPH_EXTENSIONS: "Unpacked browser extension folders, path-separated (overrides the config's extensions)",
+    WAYGRAPH_CACHE_DIR: "Where downloaded extensions are cached",
+    WAYGRAPH_PROVE_SHOT: "Demo self-check: screenshot path for the overlay proof",
+    WAYGRAPH_PROVE_EXIT: "1 exits after the first overlay proof (demo self-check)",
+    WAYGRAPH_PROVE_EVERY: "1 proves the overlay on every step, not only the first",
+};
+/** The raw value, or undefined when unset. */
+export function envString(name) {
+    return process.env[name];
+}
+/** On / off: 1 / true / yes / on, or 0 / false / no / off; `fallback` when unset or anything else. */
+export function envSwitch(name, fallback) {
+    const v = (process.env[name] ?? "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(v))
+        return true;
+    if (["0", "false", "no", "off"].includes(v))
+        return false;
+    return fallback;
+}
+/** True only when switched on. */
+export function envFlag(name) {
+    return envSwitch(name, false);
+}
+/** The value as a number, or undefined when unset or not a number. */
+export function envNumber(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** Sets a variable (for the runner child the CLI spawns); undefined unsets it. */
+export function setEnv(name, value) {
+    if (value === undefined)
+        delete process.env[name];
+    else
+        process.env[name] = value;
+}

package/dist/{errors.d.ts → engine/errors.d.ts}

@@ -9,107 +9,107 @@
  */
 export declare const WAYGRAPH_ERRORS: {
     readonly WG_PREFLIGHT_MISSING_KEY: {
-        readonly where: "core/run-graph.ts - preflight()";
+        readonly where: "engine/run/run.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: "core/run-graph.ts - runGraph()";
+        readonly where: "engine/run/run.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: "core/run-graph.ts - runGraph()";
+        readonly where: "engine/run/run.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: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal/assert/method()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.method()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.ffStart()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.ffEnd()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.end()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.ffEnd()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.end()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - MapBuilder.branch()";
+        readonly where: "engine/flow/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: "core/map-builder.ts - a .branch()-built Flow's run()";
+        readonly where: "engine/flow/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: "core/branch-regression.ts - runBranchRegression()";
+        readonly where: "engine/flow/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: "core/compose.ts - composeBlock()";
+        readonly where: "engine/block/compose.ts - composeBlock()";
         readonly means: "composeBlock() was called with zero steps.";
         readonly fix: "Pass at least one Block.";
     };
     readonly WG_FASTFORWARD_EMPTY: {
-        readonly where: "core/compose.ts - fastForwardComposeBlock()";
+        readonly where: "engine/block/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: "core/block.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)";
+        readonly where: "engine/block/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: "core/flow.ts - chainFlow()";
+        readonly where: "engine/flow/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: "core/block.ts - modVerify()";
+        readonly where: "engine/block/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: "core/block.ts - modVerify()";
+        readonly where: "engine/block/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.";
     };
     readonly WG_MEM_READ_BEFORE_SET: {
-        readonly where: "mem-page.ts - MemPage.get()";
+        readonly where: "engine/mem/mem.ts - MemPage.get()";
         readonly means: "mem.get(key) was called for a key that was never mem.set() on this MemPage.";
         readonly fix: "Set it first, or use mem.has(key) to check before an optional read.";
     };
@@ -119,7 +119,7 @@ export declare const WAYGRAPH_ERRORS: {
  * 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.
+ * `grep MSG_ src/engine/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;
@@ -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/{errors.js → engine/errors.js}

@@ -9,107 +9,107 @@
  */
 export const WAYGRAPH_ERRORS = {
     WG_PREFLIGHT_MISSING_KEY: {
-        where: "core/run-graph.ts - preflight()",
+        where: "engine/run/run.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: "core/run-graph.ts - runGraph()",
+        where: "engine/run/run.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: "core/run-graph.ts - runGraph()",
+        where: "engine/run/run.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: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal/assert/method()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.method()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.ffStart()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.ffEnd()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.end()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.ffEnd()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.end()",
+        where: "engine/flow/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: "core/map-builder.ts - MapBuilder.branch()",
+        where: "engine/flow/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: "core/map-builder.ts - a .branch()-built Flow's run()",
+        where: "engine/flow/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: "core/branch-regression.ts - runBranchRegression()",
+        where: "engine/flow/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: "core/compose.ts - composeBlock()",
+        where: "engine/block/compose.ts - composeBlock()",
         means: "composeBlock() was called with zero steps.",
         fix: "Pass at least one Block.",
     },
     WG_FASTFORWARD_EMPTY: {
-        where: "core/compose.ts - fastForwardComposeBlock()",
+        where: "engine/block/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: "core/block.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)",
+        where: "engine/block/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: "core/flow.ts - chainFlow()",
+        where: "engine/flow/flow.ts - chainFlow()",
         means: "chainFlow() was called with zero Flows.",
         fix: "Pass at least one Flow.",
     },
     WG_MODVERIFY_FUNCTION_FORM: {
-        where: "core/block.ts - modVerify()",
+        where: "engine/block/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: "core/block.ts - modVerify()",
+        where: "engine/block/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.",
     },
     WG_MEM_READ_BEFORE_SET: {
-        where: "mem-page.ts - MemPage.get()",
+        where: "engine/mem/mem.ts - MemPage.get()",
         means: "mem.get(key) was called for a key that was never mem.set() on this MemPage.",
         fix: "Set it first, or use mem.has(key) to check before an optional read.",
     },
@@ -119,7 +119,7 @@ export const WAYGRAPH_ERRORS = {
  * 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.
+ * `grep MSG_ src/engine/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`;

package/dist/{core → engine/flow}/branch-regression.d.ts

@@ -1,22 +1,23 @@
-import type { Checkpoint } from "../types.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
 import type { Flow } from "./flow.js";
-import type { RunGraphOptions } from "./run-graph.js";
-import { MemPage } from "../mem-page.js";
+import type { RunGraphOptions } from "../run/run.js";
+import { MemPage } from "../mem/mem.js";
 import type { BrowserContext } from "@playwright/test";
 /** One branch reachable from `flow`, possibly several `.branch()` levels deep. */
 export interface BranchEntry {
     /** `"Away"`, or `"Away > Far"` for a nested branch - the route tags that lead here, in order. */
     path: string;
-    flow: Flow<any>;
+    flow: Flow<Checkpoint<string>>;
 }
 /** This Flow's own immediate `.branch()` routes, or `undefined` if it wasn't built by `.branch()`. */
-export declare function branchRoutes(flow: Flow<any>): ReadonlyMap<string, Flow<any> | null> | undefined;
+export declare function branchRoutes(flow: Flow<Checkpoint<string>>): ReadonlyMap<string, Flow<Checkpoint<string>> | null> | undefined;
 /**
  * Every branch Flow reachable from `flow`, at any depth, deduped by object identity (the same
  * route Flow reused under two tags is only listed once). Doesn't include `flow` itself - only its
  * `.branch()` continuations. Static - doesn't run anything.
  */
-export declare function collectBranchFlows(flow: Flow<any>): BranchEntry[];
+export declare function collectBranchFlows(flow: Flow<Checkpoint<string>>): BranchEntry[];
+/** The outcome of one branch path in a branch regression run. */
 export interface BranchRunResult {
     path: string;
     status: "ok" | "failed";
@@ -43,4 +44,4 @@ export interface RunBranchRegressionOptions extends RunGraphOptions {
  *   console.log(r.path, r.status, r.error ?? "");
  * }
  */
-export declare function runBranchRegression(flow: Flow<any>, context: BrowserContext, mem?: MemPage, options?: RunBranchRegressionOptions): Promise<BranchRunResult[]>;
+export declare function runBranchRegression(flow: Flow<Checkpoint<string>>, context: BrowserContext, mem?: MemPage, options?: RunBranchRegressionOptions): Promise<BranchRunResult[]>;

package/dist/{core → engine/flow}/branch-regression.js

@@ -1,6 +1,7 @@
 import { WaygraphError, MSG_BRANCH_REGRESSION_NO_BROWSER } from "../errors.js";
-import { MemPage } from "../mem-page.js";
-import { seedMemStub } from "../mem-stub.js";
+import { MemPage } from "../mem/mem.js";
+import { seedMemStub } from "../mem/mem-stub.js";
+import { ignorePageGone } from "../page-gone.js";
 function branchInfo(flow) {
     return flow.__wgBranch;
 }
@@ -104,7 +105,7 @@ export async function runBranchRegression(flow, context, mem = new MemPage(), op
                 const branchPage = await branchContext.newPage();
                 // Best-effort: land back on the same page the prefix ended on before this route's own
                 // Blocks run - restores cookies/localStorage AND which page was loaded, not just auth state.
-                await branchPage.goto(url).catch(() => { });
+                await branchPage.goto(url).catch(ignorePageGone);
                 await walk(route, branchContext, m.clone(), branchPath, branchPage);
             }
             finally {