waygraph 0.15.47 → 0.15.50

package/dist/{engine/engine-class.js → core/map-builder.js}

@@ -1,47 +1,7 @@
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_MAP_WRONG_KIND, MSG_MAP_WRONG_SALT, MSG_MAP_WRONG_ORIGIN_INTERNAL, MSG_MAP_WRONG_ORIGIN_EXTERNAL, MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED, MSG_MAP_FF_ALREADY_OPEN, MSG_MAP_FF_NOT_OPEN, MSG_MAP_FF_EMPTY, MSG_MAP_METHOD_GOT_ASSERT, MSG_MAP_BRANCH_NO_PRIOR_STEP, MSG_MAP_FF_NOT_CLOSED, MSG_MAP_EMPTY, } from "../errors.js";
 import { end, start } from "./run-graph.js";
-import { buildFlow } from "./flow.js";
 import { MemPage } from "../mem-page.js";
 import { fastForwardComposeBlock } from "./compose.js";
-/**
- * Holds engine-level configuration shared across every flow defined from it -
- * for now, just how to launch a browser when a Flow owns its own
- * (`headless`/`browserName`/`slowMo`); traits/interstitials/watchers land here
- * in a later change.
- * @example const engine = new Engine({ headless: false, slowMo: 250 });
- */
-export class Engine {
-    config;
-    constructor(config = {}) {
-        this.config = config;
-    }
-    defineFlow(blocks) {
-        return buildFlow(blocks.slice(1, -1), this.config);
-    }
-    /**
-     * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
-     * see {@link MapBuilder}. Real, direct request this responds to: pia/zsign's
-     * own agents kept hand-editing/hand-composing Blocks into ad hoc shapes
-     * ("locks" convention tried, still got broken) - `map()` forces every step
-     * through this Engine's own `define*Block` factories (checked by the same
-     * `__waygraphKind`/`__waygraphSalt` runtime markers `graph.ts`/`map-check.ts`
-     * already trust), so a hand-rolled plain-object Block can never silently
-     * pass as a real navigation/assertion/method step. `homeOrigin`, if given,
-     * also gates `.gotoPage()`/`.gotoExternal()` against each Nav/Page Block's
-     * own static `url` (skipped, honestly, for click-based/dynamic nav - not
-     * statically checkable, same limitation `map-check.ts` already documents).
-     * @example
-     * const flow = engine.map({ homeOrigin: "https://app.example.com" })
-     *   .start()
-     *   .gotoPage(NavHomeBlock)
-     *   .assert(AssertHelloBlock)
-     *   .gotoExternal(NavMailpitBlock)
-     *   .end();
-     */
-    map(options) {
-        return MapBuilder.begin(this, options?.homeOrigin);
-    }
-}
 function mapKindOf(block) {
     return block?.__waygraphKind;
 }
@@ -67,9 +27,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 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.");
+    throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_WRONG_KIND(method, block?.name ?? "?", wanted, found));
 }
 function assertMapSalt(block, allowed, method) {
     const salt = mapSaltOf(block);
@@ -77,9 +35,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 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.");
+    throw new WaygraphError("WG_MAP_WRONG_SALT", MSG_MAP_WRONG_SALT(method, block?.name ?? "?", wanted, found));
 }
 function assertMapOrigin(block, homeOrigin, expect, method) {
     if (!homeOrigin)
@@ -98,12 +54,10 @@ function assertMapOrigin(block, homeOrigin, expect, method) {
     }
     const isExternal = targetOrigin !== wantOrigin;
     if (expect === "internal" && isExternal) {
-        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.`);
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_INTERNAL(block.name, targetOrigin, wantOrigin));
     }
     if (expect === "external" && !isExternal) {
-        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.`);
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_EXTERNAL(block.name, targetOrigin, wantOrigin));
     }
 }
 /**
@@ -115,9 +69,7 @@ function assertMapOrigin(block, homeOrigin, expect, method) {
 function buildBranchedFlow(before, routes) {
     const run = (async (contextOrMem, memOrConfig, options) => {
         if (contextOrMem instanceof MemPage) {
-            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.");
+            throw new WaygraphError("WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED", MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED);
         }
         const context = contextOrMem;
         const mem = memOrConfig;
@@ -180,19 +132,25 @@ function buildBranchedFlow(before, routes) {
  * real, kind-correct Block in between.
  */
 export class MapBuilder {
-    engine;
+    defineFlow;
     steps;
     homeOrigin;
     ff;
-    constructor(engine, steps, homeOrigin, ff = null) {
-        this.engine = engine;
+    constructor(
+    // A plain defineFlow-shaped function, not the whole Engine - see DefineFlowFn's own comment.
+    defineFlow, steps, homeOrigin, 
+    // `auto: true` = opened implicitly by a `{ ff: true }` step flag, not an explicit .ffStart() -
+    // closes silently at the next non-flagged step (or at .end()/.branch()) instead of demanding a
+    // matching .ffEnd(), since the author never opened anything they'd need to remember to close.
+    ff = null) {
+        this.defineFlow = defineFlow;
         this.steps = steps;
         this.homeOrigin = homeOrigin;
         this.ff = ff;
     }
     /** @internal - use `engine.map()` or the standalone `map()` export. */
-    static begin(engine, homeOrigin) {
-        return new MapBuilder(engine, [], homeOrigin, null);
+    static begin(defineFlow, homeOrigin) {
+        return new MapBuilder(defineFlow, [], homeOrigin, null);
     }
     /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
     start() {
@@ -205,14 +163,15 @@ export class MapBuilder {
      */
     ffStart(name) {
         if (this.ff) {
-            throw new WaygraphError("WG_MAP_FF_ALREADY_OPEN", `Waygraph map: .ffStart() while already inside "${this.ff.name}" - call .ffEnd() first`);
+            throw new WaygraphError("WG_MAP_FF_ALREADY_OPEN", MSG_MAP_FF_ALREADY_OPEN(this.ff.name));
         }
         const ffName = typeof name === "string" && name.trim()
             ? name.trim()
             : `ff-${this.steps.length + 1}`;
-        return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
+        return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
             name: ffName,
             buffer: [],
+            auto: false,
         });
     }
     /**
@@ -221,54 +180,85 @@ export class MapBuilder {
      */
     ffEnd() {
         if (!this.ff) {
-            throw new WaygraphError("WG_MAP_FF_NOT_OPEN", "Waygraph map: .ffEnd() with no open .ffStart()");
+            throw new WaygraphError("WG_MAP_FF_NOT_OPEN", MSG_MAP_FF_NOT_OPEN);
         }
-        if (this.ff.buffer.length === 0) {
-            throw new WaygraphError("WG_MAP_FF_EMPTY", `Waygraph map: .ffEnd() for "${this.ff.name}" has no steps - add .gotoPage/.method/… inside the window`);
+        return this.closeFf();
+    }
+    /** Shared by the explicit {@link ffEnd} and the implicit close a `{ ff: true }` step flag triggers. */
+    closeFf() {
+        const ff = this.ff;
+        if (!ff)
+            return this;
+        if (ff.buffer.length === 0) {
+            throw new WaygraphError("WG_MAP_FF_EMPTY", MSG_MAP_FF_EMPTY(ff.name));
         }
-        const composed = fastForwardComposeBlock(this.ff.name, 
+        const composed = fastForwardComposeBlock(ff.name, 
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.ff.buffer);
-        return new MapBuilder(this.engine, [...this.steps, composed], this.homeOrigin, null);
+        ff.buffer);
+        return new MapBuilder(this.defineFlow, [...this.steps, composed], this.homeOrigin, null);
     }
-    appendStep(block) {
+    /**
+     * `ff`: inline fast-forward, no `.ffStart()/.ffEnd()` bracket needed - `.method(X, { ff: true })`
+     * marks just that step; consecutive `{ ff: true }` steps merge into ONE fast-forward block (same
+     * runtime result as the explicit bracket form), same as if they'd been wrapped in
+     * `.ffStart()/.ffEnd()`. A step WITHOUT the flag closes an auto-opened window first, so a plain
+     * step is never silently swept into one; an EXPLICIT `.ffStart()` window still behaves as before
+     * (stays open until its own `.ffEnd()`, regardless of whether a step passed `{ ff: true }`).
+     */
+    appendStep(block, ff) {
+        if (ff) {
+            const win = this.ff ?? { name: `ff-${this.steps.length + 1}`, buffer: [], auto: true };
+            return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
+                name: win.name,
+                buffer: [...win.buffer, block],
+                auto: win.auto,
+            });
+        }
+        if (this.ff && this.ff.auto) {
+            return this.closeFf().appendStep(block);
+        }
         if (this.ff) {
-            return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
+            // Explicit .ffStart() window still open - absorbs a plain step too, same as always.
+            return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
                 name: this.ff.name,
                 buffer: [...this.ff.buffer, block],
+                auto: false,
             });
         }
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin, null);
+        return new MapBuilder(this.defineFlow, [...this.steps, block], this.homeOrigin, null);
     }
     /**
      * Appends an internal navigation/page-arrival step - requires a Block from
      * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
      * anything else, including a `homeOrigin`-mismatched static `url`.
      * Compile-time: {@link NavBlock} or {@link PageBlock} only (not Assert/Method).
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
      */
-    gotoPage(block) {
+    gotoPage(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoPage");
         assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
-        return this.appendStep(block);
+        return this.appendStep(block, opts?.ff);
     }
     /**
      * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
      * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
      * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
      * Compile-time: {@link NavBlock} or {@link PageBlock} only.
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
      */
-    gotoExternal(block) {
+    gotoExternal(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoExternal");
         assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
-        return this.appendStep(block);
+        return this.appendStep(block, opts?.ff);
     }
     /**
      * Appends a self-loop verification step - requires a Block from
      * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
      */
-    assert(block) {
+    assert(block, opts) {
         assertMapKind(block, ["assert"], "assert");
-        return this.appendStep(block);
+        return this.appendStep(block, opts?.ff);
     }
     /**
      * Appends a non-navigating page action (submit, upload, add/remove an
@@ -277,14 +267,14 @@ export class MapBuilder {
      * Compile-time: {@link MethodBlock} or {@link EffectBlock} only - Assert
      * Blocks must use `.assert()`. Runtime also rejects `__waygraphKind =
      * "assert"` (those still carry method salt from the factory internals).
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
      */
-    method(block) {
+    method(block, opts) {
         if (mapKindOf(block) === "assert") {
-            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).");
+            throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_METHOD_GOT_ASSERT(block.name));
         }
         assertMapSalt(block, ["method", "effect"], "method");
-        return this.appendStep(block);
+        return this.appendStep(block, opts?.ff);
     }
     /**
      * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
@@ -320,13 +310,12 @@ export class MapBuilder {
      */
     branch(routes) {
         if (this.steps.length === 0) {
-            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.");
+            throw new WaygraphError("WG_MAP_BRANCH_NO_PRIOR_STEP", MSG_MAP_BRANCH_NO_PRIOR_STEP);
         }
         const before = this.end();
         const resolvedRoutes = {};
         for (const [tag, fn] of Object.entries(routes)) {
-            resolvedRoutes[tag] = fn ? fn(new MapBuilder(this.engine, [], this.homeOrigin, null)) : null;
+            resolvedRoutes[tag] = fn ? fn(new MapBuilder(this.defineFlow, [], this.homeOrigin, null)) : null;
         }
         return buildBranchedFlow(before, resolvedRoutes);
     }
@@ -336,26 +325,21 @@ export class MapBuilder {
      * `withTitle`/`withHighlightFixtures`/etc. decorator still apply exactly
      * as they do today; this builder only changes how the chain is assembled,
      * never what it produces. Throws if no step was ever added - an empty map
-     * isn't a flow.
+     * isn't a flow. An auto-opened `{ ff: true }` window (see {@link MapStepOpts})
+     * left open at `.end()` closes silently; an EXPLICIT `.ffStart()` left open
+     * still throws - the author opened that one and needs to close it themselves.
      */
     end() {
-        if (this.ff) {
-            throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", `Waygraph map: .end() while .ffStart("${this.ff.name}") is still open - call .ffEnd() first`);
+        if (this.ff && !this.ff.auto) {
+            throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", MSG_MAP_FF_NOT_CLOSED(this.ff.name));
+        }
+        if (this.ff && this.ff.auto) {
+            return this.closeFf().end();
         }
         if (this.steps.length === 0) {
-            throw new WaygraphError("WG_MAP_EMPTY", "Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
-                ".assert()/.method() before .end()");
+            throw new WaygraphError("WG_MAP_EMPTY", MSG_MAP_EMPTY);
         }
         const chain = [start, ...this.steps, end];
-        return this.engine.defineFlow(chain);
+        return this.defineFlow(chain);
     }
 }
-/**
- * Standalone convenience for `new Engine(config).map(options)` - use this
- * when a call site doesn't otherwise need its own `Engine` instance (no
- * shared `headless`/`slowMo`/`layouts` across several flows).
- * @example const flow = map({ homeOrigin: "https://app.example.com" }).gotoPage(NavHomeBlock).end();
- */
-export function map(options) {
-    return new Engine(options).map(options);
-}

package/dist/{engine → core}/run-graph.js

@@ -1,4 +1,4 @@
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_PREFLIGHT_MISSING_KEY, MSG_RUNGRAPH_MAX_STEPS, MSG_RUNGRAPH_NOT_TERMINAL } from "../errors.js";
 import { checkpoint } from "../types.js";
 import { runPrecondition, runVerify } from "../trait.js";
 /**
@@ -12,9 +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 WaygraphError("WG_PREFLIGHT_MISSING_KEY", `preflight: MemPage is missing required key(s) before "${block.name}" can run: ${missing
-            .map((k) => `"${k.name}"`)
-            .join(", ")}`);
+        throw new WaygraphError("WG_PREFLIGHT_MISSING_KEY", MSG_PREFLIGHT_MISSING_KEY(block.name, missing.map((k) => `"${k.name}"`).join(", ")));
     }
 }
 /**
@@ -86,7 +84,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
         let steps = 0;
         for (;;) {
             if (++steps > maxSteps) {
-                throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", `runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`);
+                throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", MSG_RUNGRAPH_MAX_STEPS(maxSteps));
             }
             await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
             await current.instruction.act(page, input, mem);
@@ -99,7 +97,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 WaygraphError("WG_RUNGRAPH_NOT_TERMINAL", `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", MSG_RUNGRAPH_NOT_TERMINAL(current.name, checkpoint.__state, [...terminals].join(", ")));
                 }
                 return checkpoint;
             }

package/dist/core.d.ts

@@ -0,0 +1,14 @@
+export * from "./core/config.js";
+export * from "./core/run-graph.js";
+export * from "./core/flow.js";
+export * from "./core/block.js";
+export * from "./core/compose.js";
+export * from "./core/engine.js";
+export * from "./core/map-builder.js";
+export * from "./core/blocks/nav.js";
+export * from "./core/blocks/method.js";
+export * from "./core/blocks/page.js";
+export * from "./core/blocks/effect.js";
+export * from "./core/blocks/api.js";
+export * from "./core/locate.js";
+export * from "./core/branch-regression.js";

package/dist/core.js

@@ -0,0 +1,15 @@
+// Barrel: the engine lives in src/core/ (see src/ARCHITECTURE.md). Kept so existing imports of "./core.js" don't change.
+export * from "./core/config.js";
+export * from "./core/run-graph.js";
+export * from "./core/flow.js";
+export * from "./core/block.js";
+export * from "./core/compose.js";
+export * from "./core/engine.js";
+export * from "./core/map-builder.js";
+export * from "./core/blocks/nav.js";
+export * from "./core/blocks/method.js";
+export * from "./core/blocks/page.js";
+export * from "./core/blocks/effect.js";
+export * from "./core/blocks/api.js";
+export * from "./core/locate.js";
+export * from "./core/branch-regression.js";

package/dist/env-file.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Auto-loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root,
+ * same layering Vite/Next use (`mode` defaults to `NODE_ENV`, falling back to "development"),
+ * merged into `process.env` in increasing priority. A real, already-set `process.env` value -
+ * whatever the shell actually exported - always wins over every file; a `.env` file only fills
+ * a gap, it never silently overrides something the caller explicitly set. Safe to call more
+ * than once (e.g. once eagerly at `cwd`, again once the real project dir is known) - loading
+ * twice is a no-op the second time for any key already filled.
+ */
+export declare function loadEnvFiles(projectDir: string, mode?: string): void;

package/dist/env-file.js

@@ -0,0 +1,58 @@
+// Native .env support - no `dotenv` dependency (same "bring nothing, read what's already there"
+// philosophy as mem-stub.ts's own Faker note: this is a ~20-line parser, not a new runtime dep).
+// Real, direct user ask: FE consumers keep their own .env and had to hack around waygraph not
+// reading it (manually re-exporting values, duplicating them into package.json's "waygraph"
+// field) to get waygraph to see the same config their actual app already uses.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** `KEY=value` lines only - no `${VAR}` expansion, no multiline values. Matches the common
+ * Vite/Next `.env` shape, not full dotenv-expand parity. */
+function parseEnvFile(content) {
+    const out = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const withoutExport = line.startsWith("export ") ? line.slice("export ".length) : line;
+        const eq = withoutExport.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = withoutExport.slice(0, eq).trim();
+        if (!key)
+            continue;
+        let value = withoutExport.slice(eq + 1).trim();
+        const quoted = (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"));
+        if (quoted)
+            value = value.slice(1, -1);
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Auto-loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root,
+ * same layering Vite/Next use (`mode` defaults to `NODE_ENV`, falling back to "development"),
+ * merged into `process.env` in increasing priority. A real, already-set `process.env` value -
+ * whatever the shell actually exported - always wins over every file; a `.env` file only fills
+ * a gap, it never silently overrides something the caller explicitly set. Safe to call more
+ * than once (e.g. once eagerly at `cwd`, again once the real project dir is known) - loading
+ * twice is a no-op the second time for any key already filled.
+ */
+export function loadEnvFiles(projectDir, mode = process.env.NODE_ENV || "development") {
+    const files = [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`];
+    for (const name of files) {
+        const p = join(projectDir, name);
+        if (!existsSync(p))
+            continue;
+        let parsed;
+        try {
+            parsed = parseEnvFile(readFileSync(p, "utf-8"));
+        }
+        catch {
+            continue; // unreadable file - never fail a run over an optional .env
+        }
+        for (const [key, value] of Object.entries(parsed)) {
+            if (process.env[key] === undefined)
+                process.env[key] = value;
+        }
+    }
+}

package/dist/errors.d.ts

@@ -9,102 +9,102 @@
  */
 export declare const WAYGRAPH_ERRORS: {
     readonly WG_PREFLIGHT_MISSING_KEY: {
-        readonly where: "engine/run-graph.ts - preflight()";
+        readonly where: "core/run-graph.ts - preflight()";
         readonly means: "A Flow/chain needs a MemKey that mem.set() never received before run() started.";
         readonly fix: "Pass --data / a mem.set() call for that key, or registerMemStub + --mem-stub for a fake value.";
     };
     readonly WG_RUNGRAPH_MAX_STEPS: {
-        readonly where: "engine/run-graph.ts - runGraph()";
+        readonly where: "core/run-graph.ts - runGraph()";
         readonly means: "A chain took more steps than maxSteps without reaching a Block with no .next() - almost always an unintended self-loop in branch()/next routing.";
         readonly fix: "Check the Block(s) involved in the loop; raise maxSteps only if the loop is genuinely intended.";
     };
     readonly WG_RUNGRAPH_NOT_TERMINAL: {
-        readonly where: "engine/run-graph.ts - runGraph()";
+        readonly where: "core/run-graph.ts - runGraph()";
         readonly means: "A Block with no .next() resolved to a Checkpoint that wasn't in the caller's declared `terminals` set.";
         readonly fix: "Add that Checkpoint to `terminals`, or fix the Block's resolve() - it landed somewhere the caller didn't expect.";
     };
     readonly WG_MAP_WRONG_KIND: {
-        readonly where: "engine/engine-class.ts - MapBuilder.gotoPage/gotoExternal/assert/method()";
+        readonly where: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal/assert/method()";
         readonly means: "A Block passed to a MapBuilder step method doesn't carry the __waygraphKind a real defineNavBlock/definePageBlock/defineAssertBlock/defineMethodBlock/defineEffectBlock stamps - either the wrong factory was used, or the object was hand-rolled instead of going through one.";
         readonly fix: "Use the factory the error names, or move this Block to the matching .gotoPage()/.assert()/.method() call.";
     };
     readonly WG_MAP_WRONG_SALT: {
-        readonly where: "engine/engine-class.ts - MapBuilder.method()";
+        readonly where: "core/map-builder.ts - MapBuilder.method()";
         readonly means: "A Block passed to .method() isn't a real Method/Effect Block (missing __waygraphSalt).";
         readonly fix: "Build it with defineMethodBlock/defineEffectBlock, or use .assert() if it's actually a defineAssertBlock.";
     };
     readonly WG_MAP_WRONG_ORIGIN: {
-        readonly where: "engine/engine-class.ts - MapBuilder.gotoPage/gotoExternal()";
+        readonly where: "core/map-builder.ts - MapBuilder.gotoPage/gotoExternal()";
         readonly means: "A Block's static `url` origin doesn't match what .gotoPage() (same-origin) or .gotoExternal() (cross-origin) expects, given this map()'s homeOrigin.";
         readonly fix: "Use .gotoExternal() for a genuinely different origin, .gotoPage() for the app's own homeOrigin, or fix the Block's url.";
     };
     readonly WG_MAP_FF_ALREADY_OPEN: {
-        readonly where: "engine/engine-class.ts - MapBuilder.ffStart()";
+        readonly where: "core/map-builder.ts - MapBuilder.ffStart()";
         readonly means: ".ffStart() was called while a previous .ffStart() window is still open.";
         readonly fix: "Call .ffEnd() before opening another fast-forward window.";
     };
     readonly WG_MAP_FF_EMPTY: {
-        readonly where: "engine/engine-class.ts - MapBuilder.ffEnd()";
+        readonly where: "core/map-builder.ts - MapBuilder.ffEnd()";
         readonly means: ".ffEnd() closed a window with zero steps inside it.";
         readonly fix: "Add at least one .gotoPage()/.method()/.assert() inside the .ffStart()/.ffEnd() window.";
     };
     readonly WG_MAP_FF_NOT_CLOSED: {
-        readonly where: "engine/engine-class.ts - MapBuilder.end()";
+        readonly where: "core/map-builder.ts - MapBuilder.end()";
         readonly means: ".end() was called while a .ffStart() window was still open.";
         readonly fix: "Call .ffEnd() before .end().";
     };
     readonly WG_MAP_FF_NOT_OPEN: {
-        readonly where: "engine/engine-class.ts - MapBuilder.ffEnd()";
+        readonly where: "core/map-builder.ts - MapBuilder.ffEnd()";
         readonly means: ".ffEnd() was called with no matching .ffStart().";
         readonly fix: "Remove the stray .ffEnd(), or add the .ffStart() it's meant to close.";
     };
     readonly WG_MAP_EMPTY: {
-        readonly where: "engine/engine-class.ts - MapBuilder.end()";
+        readonly where: "core/map-builder.ts - MapBuilder.end()";
         readonly means: ".end() was called with zero steps added.";
         readonly fix: "Add at least one .gotoPage()/.gotoExternal()/.assert()/.method() before .end().";
     };
     readonly WG_MAP_BRANCH_NO_PRIOR_STEP: {
-        readonly where: "engine/engine-class.ts - MapBuilder.branch()";
+        readonly where: "core/map-builder.ts - MapBuilder.branch()";
         readonly means: ".branch() was called before any step existed to branch FROM.";
         readonly fix: "Add a .gotoPage()/.gotoExternal()/.method()/.assert() before .branch().";
     };
     readonly WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED: {
-        readonly where: "engine/engine-class.ts - a .branch()-built Flow's run()";
+        readonly where: "core/map-builder.ts - a .branch()-built Flow's run()";
         readonly means: "run(mem, config) was called on a branched Flow - that convenience form always closes its own browser/page before the branch's tag is known, so the branch can never be reached.";
         readonly fix: "Call run(context, mem[, options]) instead, keeping the same page across the branch.";
     };
     readonly WG_BRANCH_REGRESSION_NO_BROWSER: {
-        readonly where: "engine/branch-regression.ts - runBranchRegression()";
+        readonly where: "core/branch-regression.ts - runBranchRegression()";
         readonly means: "cloneSession is on (the default) but context.browser() returned null - a persistent context has no Browser to clone a new context from.";
         readonly fix: "Pass { cloneSession: false } to run the single live path in this context instead.";
     };
     readonly WG_COMPOSE_EMPTY: {
-        readonly where: "engine/compose.ts - composeBlock()";
+        readonly where: "core/compose.ts - composeBlock()";
         readonly means: "composeBlock() was called with zero steps.";
         readonly fix: "Pass at least one Block.";
     };
     readonly WG_FASTFORWARD_EMPTY: {
-        readonly where: "engine/compose.ts - fastForwardComposeBlock()";
+        readonly where: "core/compose.ts - fastForwardComposeBlock()";
         readonly means: "A fast-forward window was closed with zero steps inside it.";
         readonly fix: "Add at least one Block between ffStart()/ffEnd() (or the equivalent Map builder call).";
     };
     readonly WG_FLOW_BLOCK_NOT_FOUND: {
-        readonly where: "engine/core.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)";
+        readonly where: "core/block.ts - findBlockIndex() (used by withBlockVerify/modBlockVerify/chainFlow)";
         readonly means: "The Block name/index/reference given doesn't exist in this Flow (or chained Flows).";
         readonly fix: "Check the name/index against flow.blocks() - it lists every Block this Flow actually has, tag-prefixed for branches.";
     };
     readonly WG_CHAINFLOW_EMPTY: {
-        readonly where: "engine/flow.ts - chainFlow()";
+        readonly where: "core/flow.ts - chainFlow()";
         readonly means: "chainFlow() was called with zero Flows.";
         readonly fix: "Pass at least one Flow.";
     };
     readonly WG_MODVERIFY_FUNCTION_FORM: {
-        readonly where: "engine/core.ts - modVerify()";
+        readonly where: "core/block.ts - modVerify()";
         readonly means: "modVerify() was called on a Block whose verify is a function (tag-driven), which has no fixed list to address an item into.";
         readonly fix: "Use withVerify() to replace the whole verify instead.";
     };
     readonly WG_MODVERIFY_NOT_FOUND: {
-        readonly where: "engine/core.ts - modVerify()";
+        readonly where: "core/block.ts - modVerify()";
         readonly means: "The Trait name/index given doesn't exist in this Block's verify list.";
         readonly fix: "Check the Block's actual verify list for the right name/index.";
     };
@@ -114,6 +114,40 @@ export declare const WAYGRAPH_ERRORS: {
         readonly fix: "Set it first, or use mem.has(key) to check before an optional read.";
     };
 };
+/**
+ * The actual text every `throw new WaygraphError(...)` site uses - one named export per throw
+ * site (several throw sites can share a `WAYGRAPH_ERRORS` code but always have their own distinct
+ * message here, since the same code can legitimately fire from more than one spot with different
+ * detail). Plain strings for a message with no runtime values; a function for one that needs them.
+ * `grep MSG_ src/errors.ts` finds every fixed string the engine can throw, in one place.
+ */
+export declare const MSG_PREFLIGHT_MISSING_KEY: (blockName: string, missingKeys: string) => string;
+export declare const MSG_RUNGRAPH_MAX_STEPS: (maxSteps: number) => string;
+export declare const MSG_RUNGRAPH_NOT_TERMINAL: (blockName: string, state: string, terminals: string) => string;
+export declare const MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX: (index: number, length: number) => string;
+export declare const MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME: (blockName: string, names: string) => string;
+export declare const MSG_MODVERIFY_FUNCTION_FORM: (blockName: string) => string;
+export declare const MSG_MODVERIFY_NOT_FOUND_BY_INDEX: (blockName: string, index: number, length: number) => string;
+export declare const MSG_MODVERIFY_NOT_FOUND_BY_NAME: (blockName: string, name: string, names: string) => string;
+export declare const MSG_MAP_WRONG_KIND: (method: string, blockName: string, wanted: string, found: string) => string;
+export declare const MSG_MAP_WRONG_SALT: (method: string, blockName: string, wanted: string, found: string) => string;
+export declare const MSG_MAP_WRONG_ORIGIN_INTERNAL: (blockName: string, targetOrigin: string, wantOrigin: string) => string;
+export declare const MSG_MAP_WRONG_ORIGIN_EXTERNAL: (blockName: string, targetOrigin: string, wantOrigin: string) => string;
+export declare const MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED: string;
+export declare const MSG_MAP_FF_ALREADY_OPEN: (ffName: string) => string;
+export declare const MSG_MAP_FF_NOT_OPEN = "Waygraph map: .ffEnd() with no open .ffStart()";
+export declare const MSG_MAP_FF_EMPTY: (ffName: string) => string;
+export declare const MSG_MAP_METHOD_GOT_ASSERT: (blockName: string) => string;
+export declare const MSG_MAP_BRANCH_NO_PRIOR_STEP: string;
+export declare const MSG_MAP_FF_NOT_CLOSED: (ffName: string) => string;
+export declare const MSG_MAP_EMPTY: string;
+export declare const MSG_BRANCH_REGRESSION_NO_BROWSER: string;
+export declare const MSG_MEM_READ_BEFORE_SET: (keyName: string) => string;
+export declare const MSG_COMPOSE_EMPTY: (name: string) => string;
+export declare const MSG_FASTFORWARD_EMPTY: (name: string) => string;
+export declare const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX: (index: number, count: number) => string;
+export declare const MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME: (blockName: string) => string;
+export declare const MSG_CHAINFLOW_EMPTY = "chainFlow: give at least one Flow";
 export type WaygraphErrorCode = keyof typeof WAYGRAPH_ERRORS;
 /** A thrown engine error with a stable, greppable `.code` - see WAYGRAPH_ERRORS for the full list. */
 export declare class WaygraphError extends Error {