waygraph 0.15.43 → 0.15.45

package/dist/errors.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Every error the engine throws, in one file, each with a stable code. When something breaks,
+ * `grep WG_ the-error-you-saw` (or open this file and Ctrl-F the code) tells you exactly what
+ * threw, why, and where to look - without re-explaining the engine to an AI every time.
+ *
+ * Convention: `WG_<AREA>_<WHAT>`. A code, once shipped, never changes meaning or gets reused for
+ * something else - add a new one instead. Every thrown `WaygraphError` message starts with
+ * `[CODE]`, so the code survives being copy-pasted out of a terminal/CI log on its own.
+ */
+export declare const WAYGRAPH_ERRORS: {
+    readonly WG_PREFLIGHT_MISSING_KEY: {
+        readonly where: "engine/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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.";
+    };
+};
+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 {
+    readonly code: WaygraphErrorCode;
+    constructor(code: WaygraphErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,125 @@
+/**
+ * Every error the engine throws, in one file, each with a stable code. When something breaks,
+ * `grep WG_ the-error-you-saw` (or open this file and Ctrl-F the code) tells you exactly what
+ * threw, why, and where to look - without re-explaining the engine to an AI every time.
+ *
+ * Convention: `WG_<AREA>_<WHAT>`. A code, once shipped, never changes meaning or gets reused for
+ * something else - add a new one instead. Every thrown `WaygraphError` message starts with
+ * `[CODE]`, so the code survives being copy-pasted out of a terminal/CI log on its own.
+ */
+export const WAYGRAPH_ERRORS = {
+    WG_PREFLIGHT_MISSING_KEY: {
+        where: "engine/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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        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()",
+        means: "composeBlock() was called with zero steps.",
+        fix: "Pass at least one Block.",
+    },
+    WG_FASTFORWARD_EMPTY: {
+        where: "engine/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)",
+        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()",
+        means: "chainFlow() was called with zero Flows.",
+        fix: "Pass at least one Flow.",
+    },
+    WG_MODVERIFY_FUNCTION_FORM: {
+        where: "engine/core.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()",
+        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()",
+        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.",
+    },
+};
+/** A thrown engine error with a stable, greppable `.code` - see WAYGRAPH_ERRORS for the full list. */
+export class WaygraphError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.code = code;
+        this.name = "WaygraphError";
+    }
+}

package/dist/highlights/shorthand.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Compact alternative to full-JSON `browser highlight` payloads, for the
+ * common case (a couple of rings, each just selector + label + maybe tone).
+ * Full JSON stays fully supported for anything needing size/weight/zoom/
+ * focus/detail/tag/todos - this only ever covers a subset.
+ *
+ * Grammar: `<selector>|<label>[|<tone>]` rings joined by `;`.
+ *   "#submit|Login button|warning; .error|Error banner|danger"
+ *
+ * `;` and `|` were picked because neither is valid inside a CSS/Playwright
+ * selector or an ordinary label - unlike `,`/`:`, which real selectors use
+ * constantly (`:nth-child(2)`, `:not(.x)`, `[href*="mailto:"]`, compound
+ * `a, b` lists). A selector/label containing a literal `;` or `|` needs the
+ * full-JSON form instead - documented, not silently mishandled.
+ */
+import type { PilotHighlightFixtures } from "../pilot-overlay.js";
+export type ParsedHighlightShorthand = {
+    type: "ok";
+    fixtures: PilotHighlightFixtures;
+} | {
+    type: "error";
+    reason: string;
+};
+export declare function parseHighlightShorthand(raw: string): ParsedHighlightShorthand;

package/dist/highlights/shorthand.js

@@ -0,0 +1,30 @@
+export function parseHighlightShorthand(raw) {
+    const tokens = raw
+        .split(";")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0) {
+        return { type: "error", reason: "empty highlight shorthand - give at least one <selector>|<label> ring" };
+    }
+    const rings = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        const parts = token.split("|").map((p) => p.trim());
+        if (parts.length < 2 || parts.length > 3) {
+            return {
+                type: "error",
+                reason: `ring ${i + 1} ("${token}") must be <selector>|<label> or <selector>|<label>|<tone> ` +
+                    `- got ${parts.length} part(s) separated by "|"`,
+            };
+        }
+        const [selector, label, tone] = parts;
+        if (!selector) {
+            return { type: "error", reason: `ring ${i + 1} ("${token}") has an empty selector` };
+        }
+        if (!label) {
+            return { type: "error", reason: `ring ${i + 1} ("${token}") has an empty label` };
+        }
+        rings.push(tone ? { selector, label, tone } : { selector, label });
+    }
+    return { type: "ok", fixtures: { rings } };
+}

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
 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";
@@ -10,18 +12,18 @@ export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwell
 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 { ActionPage } from "./types.js";
-export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
-export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";
+export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
+export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./analysis/graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export type { BlocksSelect, BlocksSelectKind } from "./blocks-select.js";
-export { EdgeLeaseCoordinator } from "./traverse-lease.js";
-export { runTraverse } from "./traverse-run.js";
-export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse-run.js";
-export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
-export type { TraverseCoverageReport } from "./traverse-coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
-export type { WgModalKind, WgBeaconRow } from "./overlay-beacon.js";
+export { EdgeLeaseCoordinator } from "./traverse/lease.js";
+export { runTraverse } from "./traverse/run.js";
+export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse/run.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse/coverage.js";
+export type { TraverseCoverageReport } from "./traverse/coverage.js";
+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 type { WgModalKind, WgBeaconRow } from "./session/overlay-beacon.js";
 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 "./pilot.js";
-export type { PilotStartResult } from "./pilot.js";
+export { pilotStart } from "./session/pilot.js";
+export type { PilotStartResult } from "./session/pilot.js";

package/dist/index.js

@@ -2,14 +2,15 @@ export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 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 { 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 "./graph.js";
+export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
-export { EdgeLeaseCoordinator } from "./traverse-lease.js";
-export { runTraverse } from "./traverse-run.js";
-export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
+export { EdgeLeaseCoordinator } from "./traverse/lease.js";
+export { runTraverse } from "./traverse/run.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse/coverage.js";
+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 "./pilot.js";
+export { pilotStart } from "./session/pilot.js";

package/dist/mem-page.js

@@ -1,3 +1,4 @@
+import { WaygraphError } 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
@@ -51,7 +52,7 @@ export class MemPage {
      */
     get(k) {
         if (!this.store.has(k)) {
-            throw new Error(`MemPage: "${k.name}" read before it was set`);
+            throw new WaygraphError("WG_MEM_READ_BEFORE_SET", `MemPage: "${k.name}" read before it was set`);
         }
         return this.store.get(k);
     }

package/dist/pilot.d.ts

@@ -28,7 +28,7 @@
  * hand-picking indices from each status response) that proved this needs no
  * new execution primitive.
  */
-import { type WaygraphGraph } from "./graph.js";
+import { type WaygraphGraph } from "./analysis/graph.js";
 import { listBrowserSessions, type SessionMeta } from "./auto-session-ipc.js";
 import { type BrowserStartInit } from "./browser.js";
 import type { SessionSnapshot } from "./auto-session.js";

package/dist/pilot.js

@@ -28,7 +28,7 @@
  * hand-picking indices from each status response) that proved this needs no
  * new execution primitive.
  */
-import { discoverGraph } from "./graph.js";
+import { discoverGraph } from "./analysis/graph.js";
 import { requestSession, listBrowserSessions, resolveSessionMeta, } from "./auto-session-ipc.js";
 import { browserStart } from "./browser.js";
 /**

package/dist/session/auto-explore-run.d.ts

@@ -0,0 +1,37 @@
+import type { Page, BrowserContext } from "@playwright/test";
+import { Engine } from "../engine.js";
+import { MemPage } from "../mem-page.js";
+import { type BlockEntry } from "./auto-explore.js";
+import type { Checkpoint } from "../types.js";
+export interface AutoExploreOptions {
+    /** Terminal menu (browser still runs for act()). Default false = headful picker panel. */
+    cli?: boolean;
+    baseURL?: string;
+    /** Initial URL when the page is blank (defaults to baseURL). */
+    startUrl?: string;
+    /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
+    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+}
+export declare function resolveBaseUrl(projectDir: string): string | undefined;
+export declare function detectHere(page: Page, navBlocks: BlockEntry[]): Promise<string | null>;
+export declare function ensureLivePage(context: BrowserContext, page: Page, startUrl: string | undefined): Promise<Page>;
+/**
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`.
+ * A consumer's own `key<string>("login-email")` must stay unset here, or it
+ * silently gets a saucedemo credentials object instead of its own default.
+ */
+export declare function defaultMemValueForKey(keyName: string): unknown | undefined;
+/** Pre-seed known demo keys (saucedemo creds) so headful/cli do not stop for mem forms. */
+export declare function seedDefaultMem(library: Map<string, BlockEntry>, mem: MemPage): void;
+export declare function ensureMem(entry: BlockEntry, mem: MemPage, cli: boolean): Promise<void>;
+export declare function runOneBlock(engine: Engine, entry: BlockEntry, context: BrowserContext, page: Page, mem: MemPage, headful: boolean): Promise<Checkpoint<string>>;
+export type PickResult = {
+    type: "pick";
+    index: number;
+} | {
+    type: "quit";
+};
+/**
+ * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
+ */
+export declare function runAutoExplore(projectDir: string, options?: AutoExploreOptions): Promise<void>;