waygraph 0.15.43 → 0.15.44

package/dist/analysis/practices-check.js

@@ -0,0 +1,195 @@
+/**
+ * `waygraph check` / `waygraph typecheck` practice warnings — style/typing issues
+ * that compile but erode the typed graph. Warnings only (never fail exit code)
+ * unless paired with `tsc` errors in `waygraph typecheck`.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, relative } from "node:path";
+/** define*Block<…Checkpoint<string>…> — prefer project Checkpoint types. */
+const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
+/** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
+const ASSERT_NO_TYPE_ARG = /\bdefineAssertBlock\s*\(\s*\{/;
+/** defineAssertBlock, any form - used to scope the empty-verify check below. */
+const IS_ASSERT_BLOCK = /\bdefineAssertBlock\s*[<(]/;
+/**
+ * define(Method|Effect)Block<In, Out> with two BARE identifier type args
+ * (never a nested generic like Checkpoint<string> - that's WILDCARD_CHECKPOINT's
+ * own warning) - lets a real transition (In !== Out) be told apart from a
+ * self-loop (In === Out, e.g. fill-username) using only source text.
+ */
+const METHOD_EFFECT_GENERIC = /\bdefine(?:Method|Effect)Block\s*<\s*([A-Za-z_$][\w$]*)\s*,\s*([A-Za-z_$][\w$]*)\s*>/;
+/** `verify: []` - a literal empty array, the codegen-stub shape this check exists for. */
+const EMPTY_VERIFY_ARRAY = /\bverify\s*:\s*\[\s*\]/;
+/** Any `verify:` key at all, empty or not. */
+const HAS_VERIFY_KEY = /\bverify\s*:/;
+const SCAN_GLOB = /\.(block|flow)\.ts$/;
+/**
+ * A selector string reaching for a regex-based Playwright text pseudo-class (`:has-text(/…/)`,
+ * `:text-matches(…)`) or a plain XPath - real, recurring pattern: an LLM asked to target a simple
+ * element (one class, one id, one data-attribute) instead writes a regex/XPath from scratch. Not a
+ * type error (Playwright's own selector syntax accepts all of this), so nothing else catches it.
+ */
+const TEXT_MATCHES_PSEUDO = /:text-matches\(/;
+const HAS_TEXT_REGEX_PSEUDO = /:has-text\(\s*\//;
+const XPATH_LOCATOR = /\.locator\(\s*["'`](?:xpath=)?\/\//;
+/** A selector string literal inline in a Block file (`.locator("…")`, `click: "…"`, `url: "…"`) -
+ *  scoped to simple, single-token selectors (id/class/attr/tag) so this doesn't fire on the
+ *  legitimate multi-part selectors `.sel.ts` files themselves are made of. */
+const INLINE_SIMPLE_SELECTOR = /(?:\.locator|\bclick|\burl)\s*[:(]\s*["'`](#|\.)[\w-]+["'`]/;
+const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
+const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
+/** Whole-file opt-out: `// waygraph-ignore-practices` */
+const IGNORE_ALL = /waygraph-ignore-practices/;
+/** Per-kind opt-out: `// waygraph-ignore: multi-input, combined-action` */
+const IGNORE_KINDS = /waygraph-ignore:\s*([^\n*]+)/;
+function walkBlockAndFlowFiles(projectDir, walkDir) {
+    return walkDir(projectDir, SCAN_GLOB);
+}
+function ignoredKindsForFile(src) {
+    if (IGNORE_ALL.test(src))
+        return "all";
+    const m = IGNORE_KINDS.exec(src);
+    if (!m)
+        return new Set();
+    const kinds = new Set();
+    for (const token of m[1].split(/[,;\s]+/)) {
+        const t = token.trim();
+        if (t)
+            kinds.add(t);
+    }
+    return kinds;
+}
+function isIgnored(kind, ignore) {
+    return ignore === "all" || ignore.has(kind);
+}
+function countMatches(src, re) {
+    re.lastIndex = 0;
+    return (src.match(re) ?? []).length;
+}
+export function collectPracticeWarnings(projectDir, walkDir, opts) {
+    if (opts?.disabled)
+        return [];
+    const warnings = [];
+    for (const file of walkBlockAndFlowFiles(projectDir, walkDir)) {
+        const rel = relative(projectDir, file).replace(/\\/g, "/");
+        const src = readFileSync(file, "utf-8");
+        const ignore = ignoredKindsForFile(src);
+        if (!isIgnored("wildcard-checkpoint", ignore) && WILDCARD_CHECKPOINT.test(src)) {
+            warnings.push({
+                kind: "wildcard-checkpoint",
+                file: rel,
+                detail: 'uses Checkpoint<string> in a Block helper generic — prefer a typed Checkpoint from src/states/ (e.g. defineMethodBlock<LoginPage, LoginPage>)',
+            });
+        }
+        if (!isIgnored("assert-no-type-arg", ignore) && ASSERT_NO_TYPE_ARG.test(src)) {
+            warnings.push({
+                kind: "assert-no-type-arg",
+                file: rel,
+                detail: "defineAssertBlock({…}) without an explicit type argument — add defineAssertBlock<YourCheckpoint>({…}) so defineFlow typing stays honest",
+            });
+        }
+        const isMethodOrEffect = METHOD_OR_EFFECT_FILE.test(rel) || METHOD_OR_EFFECT_DEFINE.test(src);
+        if (isMethodOrEffect) {
+            const fills = countMatches(src, /\.fill\s*\(/g);
+            const clicks = countMatches(src, /\.click\s*\(/g);
+            if (!isIgnored("multi-input", ignore) && fills >= 2) {
+                warnings.push({
+                    kind: "multi-input",
+                    file: rel,
+                    detail: `Method/Effect act() has ${fills} .fill() calls — one distinct input per Block (split into separate defineMethodBlock files, e.g. fill-username + fill-password + submit-login)`,
+                });
+            }
+            if (!isIgnored("combined-action", ignore) && fills >= 1 && clicks >= 1) {
+                warnings.push({
+                    kind: "combined-action",
+                    file: rel,
+                    detail: "Method/Effect act() mixes .fill() and .click() — fill and submit must be separate Blocks (see examples/saucedemo login split)",
+                });
+            }
+            const genericMatch = METHOD_EFFECT_GENERIC.exec(src);
+            const isTransition = !!genericMatch && genericMatch[1] !== genericMatch[2];
+            if (isTransition &&
+                !isIgnored("empty-verify", ignore) &&
+                (!HAS_VERIFY_KEY.test(src) || EMPTY_VERIFY_ARRAY.test(src))) {
+                warnings.push({
+                    kind: "empty-verify",
+                    file: rel,
+                    detail: `transition Block (${genericMatch[1]} → ${genericMatch[2]}) has no verify checks — resolve() moving ` +
+                        "to a new Checkpoint is never confirmed by anything; add a Trait (or defineAssertBlock right after it), " +
+                        "or opt out explicitly with // waygraph-ignore: empty-verify if that's intentional",
+                });
+            }
+        }
+        if (!isIgnored("overcomplex-selector", ignore) &&
+            (TEXT_MATCHES_PSEUDO.test(src) || HAS_TEXT_REGEX_PSEUDO.test(src) || XPATH_LOCATOR.test(src))) {
+            const via = TEXT_MATCHES_PSEUDO.test(src)
+                ? ":text-matches(...)"
+                : HAS_TEXT_REGEX_PSEUDO.test(src)
+                    ? ":has-text(/regex/)"
+                    : "an XPath locator";
+            warnings.push({
+                kind: "overcomplex-selector",
+                file: rel,
+                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)) {
+            // 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 / *.sel.ts file — " +
+                        "add/reuse the selector there instead of a new one-off literal",
+                });
+            }
+        }
+        if (!isIgnored("empty-verify", ignore) && IS_ASSERT_BLOCK.test(src) && EMPTY_VERIFY_ARRAY.test(src)) {
+            warnings.push({
+                kind: "empty-verify",
+                file: rel,
+                detail: "defineAssertBlock's verify array is empty — an assert Block whose only job is checking will pass " +
+                    "trivially forever; fill in real Traits or remove the stub",
+            });
+        }
+    }
+    return warnings;
+}
+export function practiceKindLabel(kind) {
+    switch (kind) {
+        case "wildcard-checkpoint":
+            return "wildcard Checkpoint<string>";
+        case "assert-no-type-arg":
+            return "assert block missing type arg";
+        case "multi-input":
+            return "multiple inputs in one Block";
+        case "combined-action":
+            return "fill and click in one Block";
+        case "empty-verify":
+            return "empty verify — transition unconfirmed";
+        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/*.sel.ts file already exists here";
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+export function formatPracticeWarnings(projectDir, warnings) {
+    const lines = [];
+    for (const w of warnings) {
+        lines.push(`waygraph practices: ${w.file} (${practiceKindLabel(w.kind)}) — ${w.detail}`);
+    }
+    if (warnings.length === 0) {
+        lines.push(`waygraph practices: no bad-practice patterns under ${projectDir}`);
+    }
+    else {
+        lines.push(`waygraph practices: ${warnings.length} bad-practice warning${warnings.length === 1 ? "" : "s"}`);
+    }
+    return lines;
+}

package/dist/auto-explore.d.ts

@@ -1,6 +1,6 @@
 import type { Page } from "@playwright/test";
 import type { Block, Checkpoint, WaygraphInstanceOption } from "./types.js";
-import { type WaygraphGraph, type WaygraphEdge } from "./graph.js";
+import { type WaygraphGraph, type WaygraphEdge } from "./analysis/graph.js";
 export interface ExploreContextOpts {
     blocksSelect?: import("./blocks-select.js").BlocksSelect;
     /** Absolute paths of extra Block trees to merge (host projectDir is always first). */

package/dist/auto-explore.js

@@ -1,6 +1,6 @@
 import { readdirSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { discoverGraph } from "./graph.js";
+import { discoverGraph } from "./analysis/graph.js";
 import { exploreRoots, injectTaggedFile } from "./block-inject.js";
 function walkDir(dir, pattern) {
     const results = [];

package/dist/auto-session/session.js

@@ -5,10 +5,10 @@ import { buildExploreContext, buildExploreMenu } from "../auto-explore.js";
 import { MemPage } from "../mem-page.js";
 import { Engine } from "../engine.js";
 import { detectHere, ensureLivePage, ensureMem, resolveBaseUrl, runOneBlock, seedDefaultMem } from "../auto-explore-run.js";
-import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../coverage-gap.js";
+import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../analysis/coverage-gap.js";
 import { runStubPhase } from "../highlights.js";
 import { verboseLog } from "../verbose-log.js";
-import { findBlockPathDetailed } from "../graph.js";
+import { findBlockPathDetailed } from "../analysis/graph.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
  * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a

package/dist/cli/util.d.ts

@@ -1,4 +1,11 @@
-/** This package's own installed root - dist/cli.js -> .. */
+/**
+ * This package's own installed root (contains `templates/`, sibling to `dist/`) - this file
+ * compiles to `dist/cli/util.js`, so it's TWO levels up, not one. Real regression once, from the
+ * 0.15.24 cli.ts split: this function was copied verbatim from its old top-level `src/cli.ts`
+ * location (one level: `dist/cli.js` -> `..`) into `src/cli/util.ts` (compiles one level deeper)
+ * without adjusting the path math - silently broke `waygraph init`/`try` (no build-level test
+ * caught it, since tests never ran the actual compiled dist/cli.js for these two commands).
+ */
 export declare function packageRoot(): string;
 /** Spawns with inherited stdio (the real npm/playwright output, visible) and resolves to its exit code. */
 export declare function runInherited(cmd: string, args: string[], cwd: string): Promise<number>;

package/dist/cli/util.js

@@ -10,9 +10,16 @@ import { spawn } from "node:child_process";
 // experience in under a minute, then gets pointed at the plain waygraph
 // source that produced it.
 // ---------------------------------------------------------------------------
-/** This package's own installed root - dist/cli.js -> .. */
+/**
+ * This package's own installed root (contains `templates/`, sibling to `dist/`) - this file
+ * compiles to `dist/cli/util.js`, so it's TWO levels up, not one. Real regression once, from the
+ * 0.15.24 cli.ts split: this function was copied verbatim from its old top-level `src/cli.ts`
+ * location (one level: `dist/cli.js` -> `..`) into `src/cli/util.ts` (compiles one level deeper)
+ * without adjusting the path math - silently broke `waygraph init`/`try` (no build-level test
+ * caught it, since tests never ran the actual compiled dist/cli.js for these two commands).
+ */
 export function packageRoot() {
-    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 }
 /** Spawns with inherited stdio (the real npm/playwright output, visible) and resolves to its exit code. */
 export function runInherited(cmd, args, cwd) {

package/dist/commands/check.js

@@ -1,10 +1,10 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { INLINE_SELECTOR_CALL, NAV_METHOD_CALLS, discoverBlocks, discoverFlows, importFlowFile, importModule, isBlockLike, isFlowLike, isNavBlockMarked, walkDir } from "../cli/discover.js";
 import { basename, relative, resolve } from "node:path";
-import { discoverGraph, findBlockPath, findOrphanBlocks } from "../graph.js";
+import { discoverGraph, findBlockPath, findOrphanBlocks } from "../analysis/graph.js";
 import { parseRunFlags, resolveBaseUrl } from "../cli/flags.js";
 import { runChain } from "../cli/run-chain.js";
-import { collectPracticeWarnings, practiceKindLabel } from "../practices-check.js";
+import { collectPracticeWarnings, practiceKindLabel } from "../analysis/practices-check.js";
 import { readFileSync } from "node:fs";
 async function validateFlows(projectDir) {
     const files = discoverFlows(projectDir);

package/dist/commands/map.js

@@ -1,6 +1,6 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { relative, resolve } from "node:path";
-import { checkMap } from "../map-check.js";
+import { checkMap } from "../analysis/map-check.js";
 export async function mapCase(args) {
     const proj = resolve(args[1] ?? process.cwd());
     const result = await checkMap(proj);

package/dist/commands/session.js

@@ -9,10 +9,10 @@ import { existsSync, statSync } from "node:fs";
 import { resolveInjectRoots } from "../block-inject.js";
 import { requestSession, resolveSessionMeta, runAttachLoop, runAutoServeCommand, spawnDetachedSession } from "../auto-session-ipc.js";
 import { pilotAttach, pilotStart } from "../pilot.js";
-import { parseHighlightShorthand } from "../highlight-shorthand.js";
+import { parseHighlightShorthand } from "../highlights/shorthand.js";
 import { isFileSelectToken, parseBlocksSelect } from "../blocks-select.js";
 import { runAutoExplore } from "../auto-explore-run.js";
-import { discoverGraph, findOrphanBlocks, toMermaid } from "../graph.js";
+import { discoverGraph, findOrphanBlocks, toMermaid } from "../analysis/graph.js";
 export async function sessionCase(args, command) {
     if (command === "browser") {
         const sub = args[1];

package/dist/commands/traverse.js

@@ -2,8 +2,8 @@
 import { resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { parseBlocksSelect } from "../blocks-select.js";
-import { parseMinEdgeCoverage } from "../traverse-coverage.js";
-import { runTraverse } from "../traverse-run.js";
+import { parseMinEdgeCoverage } from "../traverse/coverage.js";
+import { runTraverse } from "../traverse/run.js";
 export async function traverseCase(args) {
     if (args.includes("--step") || args.includes("--auto-next") || args.includes("--autoplay")) {
         console.error("waygraph traverse: --step / --auto-next not supported (not a demo)");

package/dist/engine/branch-regression.js

@@ -1,3 +1,4 @@
+import { WaygraphError } from "../errors.js";
 import { MemPage } from "../mem-page.js";
 import { seedMemStub } from "../mem-stub.js";
 function branchInfo(flow) {
@@ -47,7 +48,7 @@ export async function runBranchRegression(flow, context, mem = new MemPage(), op
     const results = [];
     const browser = cloneSession ? context.browser() : null;
     if (cloneSession && !browser) {
-        throw new Error("Waygraph runBranchRegression: cloneSession needs context.browser() (a persistent context " +
+        throw new WaygraphError("WG_BRANCH_REGRESSION_NO_BROWSER", "Waygraph runBranchRegression: cloneSession needs context.browser() (a persistent context " +
             "has none) - pass { cloneSession: false } to run the single live path in this context instead.");
     }
     /** `entryPage`, when given, is already positioned (cloned session + navigated) - reused as-is,

package/dist/engine/compose.js

@@ -1,8 +1,9 @@
 import { connect } from "../types.js";
+import { WaygraphError } from "../errors.js";
 import { findBlockIndex, modVerify, withVerify } from "./core.js";
 export function composeBlock(name, steps) {
     if (steps.length === 0) {
-        throw new Error(`composeBlock: "${name}" needs at least one step`);
+        throw new WaygraphError("WG_COMPOSE_EMPTY", `composeBlock: "${name}" needs at least one step`);
     }
     const chain = steps.reduce((a, b) => connect(a, b));
     return {
@@ -41,7 +42,7 @@ function wrapFfError(ffName, err) {
 }
 export function fastForwardComposeBlock(name, steps) {
     if (steps.length === 0) {
-        throw new Error(`fastForwardComposeBlock: "${name}" needs at least one step`);
+        throw new WaygraphError("WG_FASTFORWARD_EMPTY", `fastForwardComposeBlock: "${name}" needs at least one step`);
     }
     const base = composeBlock(name, steps);
     const origAct = base.instruction.act.bind(base.instruction);

package/dist/engine/core.js

@@ -1,14 +1,15 @@
+import { WaygraphError } from "../errors.js";
 export function findBlockIndex(middle, block) {
     if (typeof block === "number") {
         if (block < 0 || block >= middle.length) {
-            throw new Error(`Flow: no Block at index ${block} in this flow (has ${middle.length})`);
+            throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `Flow: no Block at index ${block} in this flow (has ${middle.length})`);
         }
         return block;
     }
     const blockName = typeof block === "string" ? block : block.name;
     const index = middle.findIndex((b) => b.name === blockName);
     if (index === -1) {
-        throw new Error(`Flow: no Block named "${blockName}" in this flow (has: ${middle.map((b) => b.name).join(", ")})`);
+        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `Flow: no Block named "${blockName}" in this flow (has: ${middle.map((b) => b.name).join(", ")})`);
     }
     return index;
 }
@@ -228,13 +229,13 @@ export function withStubOnError(block, stub) {
 export function modVerify(block, nameOrIndex, newCheck) {
     const verify = block.instruction.verify;
     if (typeof verify === "function") {
-        throw new Error(`modVerify: "${block.name}" has a function-form verify, which has no fixed list to address into - use withVerify to replace it wholesale instead`);
+        throw new WaygraphError("WG_MODVERIFY_FUNCTION_FORM", `modVerify: "${block.name}" has a function-form verify, which has no fixed list to address into - use withVerify to replace it wholesale instead`);
     }
     const traits = verify ?? [];
     const index = typeof nameOrIndex === "number" ? nameOrIndex : traits.findIndex((t) => t.name === nameOrIndex);
     const existing = traits[index];
     if (!existing) {
-        throw new Error(typeof nameOrIndex === "number"
+        throw new WaygraphError("WG_MODVERIFY_NOT_FOUND", typeof nameOrIndex === "number"
             ? `modVerify: "${block.name}" has no verify trait at index ${nameOrIndex} (has ${traits.length})`
             : `modVerify: "${block.name}" has no verify trait named "${nameOrIndex}" (has: ${traits.map((t) => t.name).join(", ") || "none"})`);
     }

package/dist/engine/engine-class.js

@@ -1,3 +1,4 @@
+import { WaygraphError } from "../errors.js";
 import { end, start } from "./run-graph.js";
 import { buildFlow } from "./flow.js";
 import { MemPage } from "../mem-page.js";
@@ -66,7 +67,7 @@ function assertMapKind(block, allowed, method) {
         return;
     const wanted = allowed.map((k) => MAP_KIND_FACTORY_HINT[k] ?? k).join(" or ");
     const found = kind ? `a Block of kind "${kind}"` : "an object with no waygraph kind marker at all";
-    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
+    throw new WaygraphError("WG_MAP_WRONG_KIND", `Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
         `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
         "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
 }
@@ -76,7 +77,7 @@ function assertMapSalt(block, allowed, method) {
         return;
     const wanted = allowed.map((s) => MAP_SALT_FACTORY_HINT[s] ?? s).join(" or ");
     const found = salt ? `a Block salted "${salt}"` : "an object with no waygraph salt marker at all";
-    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
+    throw new WaygraphError("WG_MAP_WRONG_SALT", `Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
         `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
         "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
 }
@@ -97,11 +98,11 @@ function assertMapOrigin(block, homeOrigin, expect, method) {
     }
     const isExternal = targetOrigin !== wantOrigin;
     if (expect === "internal" && isExternal) {
-        throw new Error(`Waygraph map: .gotoPage("${block.name}") targets ${targetOrigin}, which is NOT this map's ` +
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", `Waygraph map: .gotoPage("${block.name}") targets ${targetOrigin}, which is NOT this map's ` +
             `home origin (${wantOrigin}) - use .gotoExternal() for a genuinely cross-origin destination.`);
     }
     if (expect === "external" && !isExternal) {
-        throw new Error(`Waygraph map: .gotoExternal("${block.name}") targets ${targetOrigin}, which IS this map's ` +
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", `Waygraph map: .gotoExternal("${block.name}") targets ${targetOrigin}, which IS this map's ` +
             `home origin (${wantOrigin}) - use .gotoPage() for an internal destination.`);
     }
 }
@@ -114,7 +115,7 @@ function assertMapOrigin(block, homeOrigin, expect, method) {
 function buildBranchedFlow(before, routes) {
     const run = (async (contextOrMem, memOrConfig, options) => {
         if (contextOrMem instanceof MemPage) {
-            throw new Error("Waygraph map: a .branch()-ed Flow can't run via run(mem, config) - that convenience form " +
+            throw new WaygraphError("WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED", "Waygraph map: a .branch()-ed Flow can't run via run(mem, config) - that convenience form " +
                 "always closes its own browser/page before a branch's tag is even known. Call " +
                 "run(context, mem[, options]) instead, keeping the same page across the branch.");
         }
@@ -204,7 +205,7 @@ export class MapBuilder {
      */
     ffStart(name) {
         if (this.ff) {
-            throw new Error(`Waygraph map: .ffStart() while already inside "${this.ff.name}" - call .ffEnd() first`);
+            throw new WaygraphError("WG_MAP_FF_ALREADY_OPEN", `Waygraph map: .ffStart() while already inside "${this.ff.name}" - call .ffEnd() first`);
         }
         const ffName = typeof name === "string" && name.trim()
             ? name.trim()
@@ -220,10 +221,10 @@ export class MapBuilder {
      */
     ffEnd() {
         if (!this.ff) {
-            throw new Error("Waygraph map: .ffEnd() with no open .ffStart()");
+            throw new WaygraphError("WG_MAP_FF_NOT_OPEN", "Waygraph map: .ffEnd() with no open .ffStart()");
         }
         if (this.ff.buffer.length === 0) {
-            throw new Error(`Waygraph map: .ffEnd() for "${this.ff.name}" has no steps - add .gotoPage/.method/… inside the window`);
+            throw new WaygraphError("WG_MAP_FF_EMPTY", `Waygraph map: .ffEnd() for "${this.ff.name}" has no steps - add .gotoPage/.method/… inside the window`);
         }
         const composed = fastForwardComposeBlock(this.ff.name, 
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -279,7 +280,7 @@ export class MapBuilder {
      */
     method(block) {
         if (mapKindOf(block) === "assert") {
-            throw new Error(`Waygraph map: .method("${block.name}") got a defineAssertBlock - use .assert() for ` +
+            throw new WaygraphError("WG_MAP_WRONG_KIND", `Waygraph map: .method("${block.name}") got a defineAssertBlock - use .assert() for ` +
                 "self-loop verify steps (Assert Blocks share method salt internally but are not methods).");
         }
         assertMapSalt(block, ["method", "effect"], "method");
@@ -319,7 +320,7 @@ export class MapBuilder {
      */
     branch(routes) {
         if (this.steps.length === 0) {
-            throw new Error("Waygraph map: .branch() needs at least one prior step - nothing to branch from. " +
+            throw new WaygraphError("WG_MAP_BRANCH_NO_PRIOR_STEP", "Waygraph map: .branch() needs at least one prior step - nothing to branch from. " +
                 "Add .gotoPage()/.gotoExternal()/.method()/.assert() first.");
         }
         const before = this.end();
@@ -339,10 +340,10 @@ export class MapBuilder {
      */
     end() {
         if (this.ff) {
-            throw new Error(`Waygraph map: .end() while .ffStart("${this.ff.name}") is still open - call .ffEnd() first`);
+            throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", `Waygraph map: .end() while .ffStart("${this.ff.name}") is still open - call .ffEnd() first`);
         }
         if (this.steps.length === 0) {
-            throw new Error("Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
+            throw new WaygraphError("WG_MAP_EMPTY", "Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
                 ".assert()/.method() before .end()");
         }
         const chain = [start, ...this.steps, end];

package/dist/engine/flow.js

@@ -1,5 +1,6 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { connect } from "../types.js";
+import { WaygraphError } from "../errors.js";
 import { preflight, runGraph } from "./run-graph.js";
 import { resolveLauncher } from "./config.js";
 import { MemPage } from "../mem-page.js";
@@ -267,7 +268,7 @@ function locateInChain(flows, block) {
                 return { flowIndex: fi, localIndex: remaining };
             remaining -= len;
         }
-        throw new Error(`chainFlow: no Block at index ${block} across ${flows.length} chained flows`);
+        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `chainFlow: no Block at index ${block} across ${flows.length} chained flows`);
     }
     const blockName = typeof block === "string" ? block : block.name;
     for (let fi = 0; fi < flows.length; fi++) {
@@ -275,7 +276,7 @@ function locateInChain(flows, block) {
         if (localIndex !== -1)
             return { flowIndex: fi, localIndex };
     }
-    throw new Error(`chainFlow: no Block named "${blockName}" in any chained flow`);
+    throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `chainFlow: no Block named "${blockName}" in any chained flow`);
 }
 async function clearSessionState(context, page) {
     await context.clearCookies().catch(() => { });
@@ -311,7 +312,7 @@ async function clearSessionState(context, page) {
  */
 export function chainFlow(...flows) {
     if (flows.length === 0) {
-        throw new Error("chainFlow: give at least one Flow");
+        throw new WaygraphError("WG_CHAINFLOW_EMPTY", "chainFlow: give at least one Flow");
     }
     const run = async function run(contextOrMem, memOrConfig, options) {
         if (contextOrMem instanceof MemPage) {

package/dist/engine/run-graph.js

@@ -1,3 +1,4 @@
+import { WaygraphError } from "../errors.js";
 import { checkpoint } from "../types.js";
 import { runPrecondition, runVerify } from "../trait.js";
 /**
@@ -11,7 +12,7 @@ import { runPrecondition, runVerify } from "../trait.js";
 export function preflight(mem, block) {
     const missing = (block.requires ?? []).filter((k) => !mem.has(k));
     if (missing.length > 0) {
-        throw new Error(`preflight: MemPage is missing required key(s) before "${block.name}" can run: ${missing
+        throw new WaygraphError("WG_PREFLIGHT_MISSING_KEY", `preflight: MemPage is missing required key(s) before "${block.name}" can run: ${missing
             .map((k) => `"${k.name}"`)
             .join(", ")}`);
     }
@@ -85,7 +86,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
         let steps = 0;
         for (;;) {
             if (++steps > maxSteps) {
-                throw new Error(`runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`);
+                throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", `runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`);
             }
             await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
             await current.instruction.act(page, input, mem);
@@ -98,7 +99,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             const next = current.next?.(checkpoint);
             if (!next) {
                 if (terminals && !terminals.has(checkpoint.__state)) {
-                    throw new Error(`runGraph: "${current.name}" resolved to "${checkpoint.__state}", which is not a registered terminal (expected one of: ${[...terminals].join(", ")})`);
+                    throw new WaygraphError("WG_RUNGRAPH_NOT_TERMINAL", `runGraph: "${current.name}" resolved to "${checkpoint.__state}", which is not a registered terminal (expected one of: ${[...terminals].join(", ")})`);
                 }
                 return checkpoint;
             }