waygraph 0.15.42 → 0.15.44

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,15 +12,15 @@ 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 { 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 { AutoSession, stubFilePath } from "./auto-session.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 { 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 { AutoSession, stubFilePath } from "./auto-session.js";
 export { pilotStart } from "./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/practices-check.js

@@ -130,17 +130,19 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
             warnings.push({
                 kind: "overcomplex-selector",
                 file: rel,
-                detail: `uses ${via} — reach for a plain CSS selector (id/class/data-attribute, via a .sel.ts ` +
-                    "export) instead of a regex/XPath match unless the DOM genuinely has no stable selector",
+                detail: `uses ${via} — reach for a plain CSS selector (id/class/data-attribute, via a _sel.ts/` +
+                    "*.sel.ts export) instead of a regex/XPath match unless the DOM genuinely has no stable selector",
             });
         }
         if (!isIgnored("inline-selector-should-use-sel-file", ignore) && INLINE_SIMPLE_SELECTOR.test(src)) {
-            const siblingSelFile = readdirSync(dirname(file)).some((f) => f.endsWith(".sel.ts"));
+            // Two real, coexisting conventions: the Map layout's own `_sel.ts` (one per page folder, next
+            // to `_nav`/`_page`/`_methods`) and the freeform layout's per-concern `<name>.sel.ts`.
+            const siblingSelFile = readdirSync(dirname(file)).some((f) => f === "_sel.ts" || f.endsWith(".sel.ts"));
             if (siblingSelFile) {
                 warnings.push({
                     kind: "inline-selector-should-use-sel-file",
                     file: rel,
-                    detail: "a selector string is inlined here, but this directory already has a *.sel.ts file — " +
+                    detail: "a selector string is inlined here, but this directory already has a _sel.ts / *.sel.ts file — " +
                         "add/reuse the selector there instead of a new one-off literal",
                 });
             }
@@ -171,7 +173,7 @@ export function practiceKindLabel(kind) {
         case "overcomplex-selector":
             return "regex/XPath selector where a plain one would do";
         case "inline-selector-should-use-sel-file":
-            return "inline selector — a .sel.ts file already exists here";
+            return "inline selector — a _sel.ts/*.sel.ts file already exists here";
         default: {
             const _exhaustive = kind;
             return _exhaustive;

package/dist/traverse/coverage.d.ts

@@ -0,0 +1,59 @@
+export interface TraverseCoverageReport {
+    version: 1;
+    generatedAt: string;
+    projectDir: string;
+    parallel: number;
+    /** Unique edge keys in the discovered graph (block names). */
+    edgesTotal: number;
+    /** Graph edges successfully walked this suite (after instance normalize). */
+    edgesHit: number;
+    /** edgesHit / edgesTotal (0 when total is 0). */
+    ratio: number;
+    /** Optional suite gate that was applied (0-1). */
+    minEdgeCoverage?: number;
+    /** true when minEdgeCoverage was set and ratio met it. */
+    coveragePass?: boolean;
+    /** Sorted graph edge keys that were hit. */
+    hit: string[];
+    /** Sorted graph edge keys never walked. */
+    missed: string[];
+    /** Raw worker hit keys (may include block::instanceId). */
+    rawHit?: string[];
+    workers?: Array<{
+        traverseId: string;
+        exitCode: number;
+        steps: number;
+        edgesHit: number;
+        leaf?: string;
+    }>;
+}
+/** Static graph edge key = Block runtime name. */
+export declare function edgeKeyFromGraphEdge(edge: {
+    block: string;
+}): string;
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export declare function collectGraphEdgeKeys(edges: ReadonlyArray<{
+    block: string;
+}>): string[];
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export declare function normalizeHitKey(hitKey: string, graphKeys: ReadonlySet<string>): string | null;
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export declare function parseMinEdgeCoverage(raw: unknown): number | null;
+export declare function buildCoverageReport(opts: {
+    projectDir: string;
+    parallel: number;
+    allEdgeKeys: readonly string[];
+    hitKeys: ReadonlySet<string> | readonly string[];
+    minEdgeCoverage?: number | null;
+    workers?: TraverseCoverageReport["workers"];
+}): TraverseCoverageReport;
+/** Greppable one-liner for agents/CI. */
+export declare function formatCoverageLine(report: TraverseCoverageReport): string;
+export declare function defaultCoverageOutPath(projectDir: string): string;
+export declare function writeCoverageReport(path: string, report: TraverseCoverageReport): void;

package/dist/traverse/coverage.js

@@ -0,0 +1,127 @@
+/**
+ * Phase E: traverse edge coverage report + suite gate.
+ * Coverage is independent of leaf PASS - a green leaf can still fail CI
+ * when --min-edge-coverage is set and ratio is too low.
+ *
+ * Denominator = unique static graph edge block names (FF inners stay as their
+ * own graph edges when discovered; RFC open Q deferred - no covered-via-prefix yet).
+ * A hit of `block::instanceId` counts as covering `block`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Static graph edge key = Block runtime name. */
+export function edgeKeyFromGraphEdge(edge) {
+    return edge.block;
+}
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export function collectGraphEdgeKeys(edges) {
+    const set = new Set();
+    for (const e of edges)
+        set.add(edgeKeyFromGraphEdge(e));
+    return [...set].sort();
+}
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export function normalizeHitKey(hitKey, graphKeys) {
+    if (graphKeys.has(hitKey))
+        return hitKey;
+    const base = hitKey.includes("::") ? hitKey.slice(0, hitKey.indexOf("::")) : hitKey;
+    if (graphKeys.has(base))
+        return base;
+    return null;
+}
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export function parseMinEdgeCoverage(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        if (raw < 0)
+            return null;
+        if (raw <= 1)
+            return raw;
+        if (raw <= 100)
+            return raw / 100;
+        return null;
+    }
+    if (typeof raw !== "string")
+        return null;
+    const t = raw.trim().toLowerCase();
+    if (!t)
+        return null;
+    if (t.endsWith("%")) {
+        const n = Number(t.slice(0, -1));
+        if (!Number.isFinite(n) || n < 0 || n > 100)
+            return null;
+        return n / 100;
+    }
+    const n = Number(t);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    if (n <= 1)
+        return n;
+    if (n <= 100)
+        return n / 100;
+    return null;
+}
+export function buildCoverageReport(opts) {
+    const all = [...new Set(opts.allEdgeKeys)].sort();
+    const graphSet = new Set(all);
+    const rawList = Array.isArray(opts.hitKeys) ? [...opts.hitKeys] : [...opts.hitKeys];
+    const covered = new Set();
+    for (const raw of rawList) {
+        const n = normalizeHitKey(raw, graphSet);
+        if (n)
+            covered.add(n);
+    }
+    const hit = all.filter((k) => covered.has(k));
+    const missed = all.filter((k) => !covered.has(k));
+    const edgesTotal = all.length;
+    const edgesHit = hit.length;
+    const ratio = edgesTotal === 0 ? 0 : edgesHit / edgesTotal;
+    const min = opts.minEdgeCoverage != null && Number.isFinite(opts.minEdgeCoverage)
+        ? Math.min(1, Math.max(0, opts.minEdgeCoverage))
+        : undefined;
+    const coveragePass = min === undefined ? undefined : ratio + 1e-12 >= min;
+    const coverageExtra = min !== undefined && coveragePass !== undefined
+        ? { minEdgeCoverage: min, coveragePass }
+        : {};
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        projectDir: opts.projectDir,
+        parallel: opts.parallel,
+        edgesTotal,
+        edgesHit,
+        ratio: Math.round(ratio * 10000) / 10000,
+        ...coverageExtra,
+        hit,
+        missed,
+        rawHit: [...new Set(rawList)].sort(),
+        ...(opts.workers ? { workers: opts.workers } : {}),
+    };
+}
+/** Greppable one-liner for agents/CI. */
+export function formatCoverageLine(report) {
+    const pct = (report.ratio * 100).toFixed(1);
+    const minPart = report.minEdgeCoverage !== undefined
+        ? ` min=${(report.minEdgeCoverage * 100).toFixed(1)}%` +
+            (report.coveragePass === false
+                ? " FAIL"
+                : report.coveragePass === true
+                    ? " PASS"
+                    : "")
+        : "";
+    return `[Coverage edges=${report.edgesHit}/${report.edgesTotal} ratio=${pct}%${minPart}]`;
+}
+export function defaultCoverageOutPath(projectDir) {
+    return join(projectDir, ".waygraph-traverse", "coverage.json");
+}
+export function writeCoverageReport(path, report) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(report, null, 2) + "\n", "utf-8");
+}

package/dist/traverse/lease.d.ts

@@ -0,0 +1,18 @@
+export interface EdgeLeaseRecord {
+    workerId: string;
+    claimedAt: number;
+}
+export declare class EdgeLeaseCoordinator {
+    private readonly held;
+    private readonly dir;
+    constructor(opts?: {
+        projectDir?: string;
+        persist?: boolean;
+    });
+    /** True if this worker now owns `edgeKey` (or already owned it). */
+    tryClaim(edgeKey: string, workerId: string): boolean;
+    release(edgeKey: string, workerId: string): void;
+    /** Stable partition: same key always maps to the same worker index. */
+    static partitionIndex(edgeKey: string, parallel: number): number;
+    private flush;
+}