waygraph 0.15.49 → 0.15.51

package/dist/analysis/map-check.js

@@ -117,12 +117,15 @@ export async function checkMap(projectDir) {
                 continue; // only statically-urled Nav/Page Blocks are checkable
             let pathname;
             try {
-                pathname = new URL(navUrl).pathname;
+                // Relative URLs (the normal baseUrl case) are paths from the app root.
+                pathname = new URL(navUrl, "http://app.invalid/").pathname;
             }
             catch {
-                continue; // a relative/templated URL - not verbatim-checkable
+                continue;
             }
             const urlSegments = pathname.split("/").filter(Boolean);
+            if (urlSegments.at(-1) === "index.html")
+                urlSegments.pop(); // /docs/index.html is the docs/ folder
             const folderSegments = realSegments(relative(mapRoot, file));
             const matches = urlSegments.length === folderSegments.length && urlSegments.every((s, i) => s === folderSegments[i]);
             if (!matches) {

package/dist/analysis/practices-check.js

@@ -5,8 +5,20 @@
  */
 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*>/;
+/** Every define*Block<In, Out> / <Out> generic list - args may themselves be Checkpoint<...>. */
+const BLOCK_GENERICS = /\bdefine(?:Method|Effect|MemEffect|Page|Nav|MemNav|NavClick|Action)Block\s*<\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*(?:,\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*)?>/g;
+/**
+ * A wildcard Out (the Block's result is untyped). A wildcard In is fine - it's the documented
+ * "reachable from anywhere" form (graph.ts treats it like a NavBlock's "*").
+ */
+function hasWildcardOut(src) {
+    for (const m of src.matchAll(BLOCK_GENERICS)) {
+        const out = (m[2] ?? m[1]).trim();
+        if (/^Checkpoint\s*<\s*string\s*>$/.test(out))
+            return true;
+    }
+    return false;
+}
 /** 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. */
@@ -74,11 +86,12 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
         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)) {
+        if (!isIgnored("wildcard-checkpoint", ignore) && hasWildcardOut(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>)',
+                detail: "the Block's output is Checkpoint<string>, so its result is untyped — use a typed Checkpoint from " +
+                    "src/states/ (e.g. defineMethodBlock<LoginPage, LoggedIn>); a wildcard input is fine",
             });
         }
         if (!isIgnored("assert-no-type-arg", ignore) && ASSERT_NO_TYPE_ARG.test(src)) {

package/dist/auto-session/session.js

@@ -9,6 +9,7 @@ import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from
 import { runStubPhase } from "../highlights.js";
 import { verboseLog } from "./verbose-log.js";
 import { findBlockPathDetailed } from "../analysis/graph.js";
+import { chromiumExecutablePath } from "../browser-path.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
  * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a
@@ -54,7 +55,7 @@ export class AutoSession {
         this.headless = headless;
     }
     static async start(init) {
-        const baseURL = init.baseURL ?? resolveBaseUrl(init.projectDir);
+        const baseURL = init.baseURL ?? (await resolveBaseUrl(init.projectDir));
         const skipNav = init.skipInitialNavigation === true;
         const startUrl = skipNav ? undefined : (init.startUrl ?? baseURL);
         const exploreOpts = {
@@ -67,7 +68,7 @@ export class AutoSession {
         const headless = init.headless ?? true;
         const engine = new Engine({ headless });
         const { chromium } = await import("@playwright/test");
-        const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+        const executablePath = chromiumExecutablePath();
         // Real gap found live: a headed (--non-headless) session kept a fixed
         // 1280x720 content area even when the user maximized/fullscreened the
         // actual window - `viewport: null` alone only makes the PAGE track the

package/dist/browser-path.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
+ * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
+ */
+export declare function chromiumExecutablePath(): string | undefined;

package/dist/browser-path.js

@@ -0,0 +1,18 @@
+import { existsSync } from "node:fs";
+let warned = false;
+/**
+ * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
+ * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
+ */
+export function chromiumExecutablePath() {
+    const path = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    if (!path)
+        return undefined;
+    if (existsSync(path))
+        return path;
+    if (!warned) {
+        warned = true;
+        console.error(`waygraph: CHROME_PATH/CHROMIUM_PATH "${path}" does not exist - using Playwright's bundled Chromium`);
+    }
+    return undefined;
+}

package/dist/cli/flags.d.ts

@@ -1,3 +1,4 @@
+import { resolveBaseUrl } from "../config.js";
 interface RunFlags {
     step?: boolean;
     autoplay?: boolean;
@@ -73,16 +74,18 @@ export declare function applyRunFlags(flags: RunFlags, opts?: {
     allowDemoUi?: boolean;
 }): void;
 /**
- * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set:
- * package.json `waygraph.baseUrl` (or `baseURL`), then playwright.config `baseURL`.
+ * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set - see `../config.js`'s own
+ * `resolveBaseUrl` for the full resolution order (env / `.env` / `waygraph.config.*` /
+ * package.json / playwright.config). Re-exported here so existing importers of this module
+ * don't need to change their import path.
  */
-export declare function resolveBaseUrl(projectDir: string): string | undefined;
+export { resolveBaseUrl };
 /**
  * Friendly demo defaults: STEP on; headed only for live watch (no --video).
  * --video / --auto-play-video => headless unless --non-headless.
  * Call after applyRunFlags so explicit flags already won.
  */
-export declare function applyDemoDefaults(projectDir: string): void;
+export declare function applyDemoDefaults(projectDir: string): Promise<void>;
 export declare function resolveProjectDir(flags: RunFlags, fallbackIndex?: number): string;
 export declare function resolveSpec(flags: RunFlags): string | undefined;
 /** `shop.flow.ts` / `src/flows/cart-bulk.flow.ts` / absolute path — not a Checkpoint or export id. */
@@ -92,4 +95,3 @@ export declare function looksLikeFlowFileRef(ref: string): boolean;
  * `src/flows/shop.flow.ts` → `shopFlow`; leaves `loginFlow then nav-cart` alone.
  */
 export declare function expandSpecFlowFiles(projectDir: string, spec: string): Promise<string>;
-export {};

package/dist/cli/flags.js

@@ -1,7 +1,8 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { basename, join, relative, resolve } from "node:path";
+import { basename, relative, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { walkDir } from "./discover.js";
+import { resolveBaseUrl } from "../config.js";
 function takeFlagValue(argv, i, a, flag) {
     if (a.startsWith(flag + "=")) {
         return { value: a.slice(flag.length + 1), nextI: i };
@@ -310,42 +311,18 @@ export function applyRunFlags(flags, opts) {
     }
 }
 /**
- * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set:
- * package.json `waygraph.baseUrl` (or `baseURL`), then playwright.config `baseURL`.
+ * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set - see `../config.js`'s own
+ * `resolveBaseUrl` for the full resolution order (env / `.env` / `waygraph.config.*` /
+ * package.json / playwright.config). Re-exported here so existing importers of this module
+ * don't need to change their import path.
  */
-export function resolveBaseUrl(projectDir) {
-    const pkgPath = join(projectDir, "package.json");
-    if (existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-            const fromPkg = pkg.waygraph?.baseUrl ??
-                pkg.waygraph?.baseURL ??
-                pkg.config?.waygraph?.baseUrl ??
-                pkg.config?.waygraph?.baseURL;
-            if (typeof fromPkg === "string" && fromPkg.trim())
-                return fromPkg.trim();
-        }
-        catch {
-            // ignore malformed package.json - fall through to playwright
-        }
-    }
-    for (const name of ["playwright.config.ts", "playwright.config.mts", "playwright.config.js", "playwright.config.mjs"]) {
-        const p = join(projectDir, name);
-        if (!existsSync(p))
-            continue;
-        const src = readFileSync(p, "utf-8");
-        const m = src.match(/baseURL\s*:\s*["']([^"']+)["']/);
-        if (m?.[1])
-            return m[1];
-    }
-    return undefined;
-}
+export { resolveBaseUrl };
 /**
  * Friendly demo defaults: STEP on; headed only for live watch (no --video).
  * --video / --auto-play-video => headless unless --non-headless.
  * Call after applyRunFlags so explicit flags already won.
  */
-export function applyDemoDefaults(projectDir) {
+export async function applyDemoDefaults(projectDir) {
     if (process.env.WAYGRAPH_STEP === undefined)
         process.env.WAYGRAPH_STEP = "1";
     if (process.env.WAYGRAPH_STEP === "1" && process.env.WAYGRAPH_HEADED === undefined) {
@@ -363,7 +340,7 @@ export function applyDemoDefaults(projectDir) {
         }
     }
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(projectDir);
+        const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }

package/dist/cli/run-chain.js

@@ -41,7 +41,7 @@ mod.startRunner();
 export async function runChain(projectDir, spec) {
     const expanded = await expandSpecFlowFiles(projectDir, spec);
     if (process.env.WAYGRAPH_VIDEO && !process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(projectDir);
+        const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }
@@ -49,6 +49,7 @@ export async function runChain(projectDir, spec) {
     const scriptPath = join(projectDir, `.waygraph-chain-${process.pid}.mjs`);
     writeFileSync(scriptPath, CHAIN_RUNNER_BOOTSTRAP);
     try {
+        // webServer is started inside the child (runner/main.js), never here - see CHAIN_RUNNER_BOOTSTRAP.
         const code = await new Promise((res, rej) => {
             const child = spawn(process.execPath, ["--import", tsxEsm, scriptPath, projectDir, expanded], {
                 stdio: "inherit",

package/dist/commands/check.js

@@ -67,7 +67,7 @@ export async function runChainAuto(projectDir, fromTag, toTag) {
     const spec = path.join(" then ");
     console.error(`waygraph chain auto: ${fromTag} -> ${toTag} via ${spec}`);
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(projectDir);
+        const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }

package/dist/commands/init.js

@@ -2,6 +2,7 @@
 import { packageRoot } from "../cli/util.js";
 import { basename, join, relative, resolve } from "node:path";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 function initCommand(projectName) {
     if (!projectName) {
         console.error("waygraph init: missing <project-name>, e.g. waygraph init my-app");
@@ -30,8 +31,12 @@ function initCommand(projectName) {
         writeFileSync(join(targetDir, ".gitignore"), readFileSync(gitignoreSrc, "utf-8"));
         rmSync(gitignoreSrc);
     }
+    // Demo pages open via file://; the absolute path is only known once copied, so it's filled in here.
+    const appBaseUrl = pathToFileURL(join(targetDir, "src", "map", "(app_base)", "index.html")).href;
     const packageJsonPath = join(targetDir, "package.json");
     writeFileSync(packageJsonPath, readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", pkgName));
+    const playwrightConfigPath = join(targetDir, "playwright.config.ts");
+    writeFileSync(playwrightConfigPath, readFileSync(playwrightConfigPath, "utf-8").replaceAll("__APP_BASE_URL__", appBaseUrl));
     console.log(`Scaffolded ${pkgName}/`);
     console.log("");
     console.log(`  cd ${relative(process.cwd(), targetDir) || pkgName}`);

package/dist/commands/run.js

@@ -24,7 +24,7 @@ export async function runCase(args) {
         process.exit(1);
     }
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(proj);
+        const resolved = await resolveBaseUrl(proj);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }
@@ -60,13 +60,13 @@ export async function chainCase(args) {
     }
     const proj = resolve(flags.blocks ? (flags.positionals[0] ?? process.cwd()) : (flags.positionals[1] ?? process.cwd()));
     if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = resolveBaseUrl(proj);
+        const resolved = await resolveBaseUrl(proj);
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }
     // If caller asked for step overlay, behave like demo; else like run.
     if (flags.step === true || process.env.WAYGRAPH_STEP === "1") {
-        applyDemoDefaults(proj);
+        await applyDemoDefaults(proj);
     }
     await runChain(proj, spec);
     return;
@@ -92,7 +92,7 @@ export async function demoCase(args) {
     if (flags.step === undefined && process.env.WAYGRAPH_STEP === undefined) {
         process.env.WAYGRAPH_STEP = "1";
     }
-    applyDemoDefaults(proj);
+    await applyDemoDefaults(proj);
     console.error(`waygraph demo: STEP=${process.env.WAYGRAPH_STEP === "1" ? "on" : "off"}` +
         ` AUTO_NEXT=${process.env.WAYGRAPH_AUTOPLAY === "1" ? "on" : "off"}` +
         ` HEADED=${process.env.WAYGRAPH_HEADED === "0" ? "off" : "on"}` +

package/dist/commands/session.js

@@ -62,7 +62,7 @@ export async function sessionCase(args, command) {
                 console.error(`waygraph browser: no such directory: ${proj}`);
                 process.exit(1);
             }
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
             try {
                 const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
                 const result = await browserStart({
@@ -148,7 +148,7 @@ export async function sessionCase(args, command) {
             const flags = parseRunFlags(flagArgs);
             applyRunFlags(flags);
             const proj = resolve(flags.positionals[0] ?? process.cwd());
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
             try {
                 const result = await pilotStart({
                     projectDir: proj,
@@ -483,7 +483,7 @@ export async function sessionCase(args, command) {
             process.exit(1);
         }
         if (!process.env.WAYGRAPH_BASE_URL) {
-            const resolved = resolveBaseUrl(proj);
+            const resolved = await resolveBaseUrl(proj);
             if (resolved)
                 process.env.WAYGRAPH_BASE_URL = resolved;
         }
@@ -510,7 +510,7 @@ export async function sessionCase(args, command) {
             console.error("waygraph auto --detach requires --cli (headful has no session control)");
             process.exit(1);
         }
-        const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+        const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
         try {
             const meta = await spawnDetachedSession({
                 projectDir: proj,
@@ -535,7 +535,7 @@ export async function sessionCase(args, command) {
         }
         if (flags.blocks && isFileSelectToken(flags.blocks)) {
             const blocksSelect = parseBlocksSelect(flags.blocks);
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
             await runAutoExplore(proj, baseURL
                 ? { cli: cliPicker, baseURL, blocksSelect }
                 : { cli: cliPicker, blocksSelect });
@@ -565,7 +565,7 @@ export async function sessionCase(args, command) {
         }
         return;
     }
-    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
     await runAutoExplore(proj, baseURL ? { cli: cliPicker, baseURL } : { cli: cliPicker });
     return;
 }
@@ -578,7 +578,7 @@ export async function autoServeCase(args) {
         console.error("waygraph __auto-serve: missing --session-id");
         process.exit(1);
     }
-    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
     const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
     let headless;
     if (flags.headlessBrowser)

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+export interface WaygraphConfig {
+    /** Same value `resolveBaseUrl` would otherwise read from package.json's `waygraph.baseUrl`. */
+    baseUrl?: string;
+}
+/** Identity helper, purely for editor type-checking/autocomplete - same role `defineConfig` plays
+ * in a `playwright.config.ts` or `vite.config.ts`. `export default defineConfig({ ... })`. */
+export declare function defineConfig(config: WaygraphConfig): WaygraphConfig;
+/**
+ * Looks for the first `waygraph.config.*` in `projectDir` and imports it - `.ts` works
+ * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli.js` ever runs
+ * (the same mechanism that already lets a consumer's `.block.ts`/`.flow.ts` import directly), so
+ * no separate loader/transpile step is needed here. A broken config file throws loud, naming the
+ * file - silently swallowing it would make a missing `baseUrl` look like "nobody configured
+ * anything" instead of "your config file has a bug."
+ */
+export declare function loadWaygraphConfig(projectDir: string): Promise<WaygraphConfig | undefined>;
+/**
+ * Single source of truth for a project's base URL. Was three independently drifted copies
+ * (`src/cli/flags.ts`, `src/traverse/run.ts`, `src/session/auto-explore-run.ts`), each checking
+ * a slightly different subset of sources in a different order - real duplication, not just
+ * stylistic, since one copy skipped `config.waygraph.*` nesting and another checked
+ * `WAYGRAPH_BASE_URL` first instead of last. Checked in this order:
+ *
+ * 1. `WAYGRAPH_BASE_URL` - a real shell export, or one loaded from a `.env` file (see
+ *    `loadEnvFiles`, called here so every caller gets native `.env` support for free, not just
+ *    whichever command remembered to call it).
+ * 2. A `waygraph.config.*` file's `baseUrl`.
+ * 3. `package.json`'s `waygraph.baseUrl`/`baseURL` (`config.waygraph.*` also checked - a common
+ *    nested-config convention some tooling uses).
+ * 4. `playwright.config.*`'s own `baseURL` (regex-read as text, never imported - importing a
+ *    consumer's real playwright.config risks pulling in `@playwright/test`'s own global setup
+ *    as a side effect, which resolving a URL string has no business doing).
+ */
+export declare function resolveBaseUrl(projectDir: string): Promise<string | undefined>;

package/dist/config.js

@@ -0,0 +1,94 @@
+// waygraph.config.* - new, additive, optional. package.json's own "waygraph" field (baseUrl)
+// keeps working untouched; this is a second, richer place to put the same kind of project-level
+// setting, for consumers who'd rather have a real typed file than a JSON field. Real ask: "I
+// think its time to add waygraph config now."
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadEnvFiles } from "./env-file.js";
+/** Identity helper, purely for editor type-checking/autocomplete - same role `defineConfig` plays
+ * in a `playwright.config.ts` or `vite.config.ts`. `export default defineConfig({ ... })`. */
+export function defineConfig(config) {
+    return config;
+}
+const CONFIG_FILENAMES = [
+    "waygraph.config.ts",
+    "waygraph.config.mts",
+    "waygraph.config.mjs",
+    "waygraph.config.js",
+    "waygraph.config.cjs",
+];
+/**
+ * Looks for the first `waygraph.config.*` in `projectDir` and imports it - `.ts` works
+ * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli.js` ever runs
+ * (the same mechanism that already lets a consumer's `.block.ts`/`.flow.ts` import directly), so
+ * no separate loader/transpile step is needed here. A broken config file throws loud, naming the
+ * file - silently swallowing it would make a missing `baseUrl` look like "nobody configured
+ * anything" instead of "your config file has a bug."
+ */
+export async function loadWaygraphConfig(projectDir) {
+    for (const name of CONFIG_FILENAMES) {
+        const p = join(projectDir, name);
+        if (!existsSync(p))
+            continue;
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(p).href));
+        }
+        catch (err) {
+            throw new Error(`waygraph: failed to load ${name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return mod.default ?? mod;
+    }
+    return undefined;
+}
+/**
+ * Single source of truth for a project's base URL. Was three independently drifted copies
+ * (`src/cli/flags.ts`, `src/traverse/run.ts`, `src/session/auto-explore-run.ts`), each checking
+ * a slightly different subset of sources in a different order - real duplication, not just
+ * stylistic, since one copy skipped `config.waygraph.*` nesting and another checked
+ * `WAYGRAPH_BASE_URL` first instead of last. Checked in this order:
+ *
+ * 1. `WAYGRAPH_BASE_URL` - a real shell export, or one loaded from a `.env` file (see
+ *    `loadEnvFiles`, called here so every caller gets native `.env` support for free, not just
+ *    whichever command remembered to call it).
+ * 2. A `waygraph.config.*` file's `baseUrl`.
+ * 3. `package.json`'s `waygraph.baseUrl`/`baseURL` (`config.waygraph.*` also checked - a common
+ *    nested-config convention some tooling uses).
+ * 4. `playwright.config.*`'s own `baseURL` (regex-read as text, never imported - importing a
+ *    consumer's real playwright.config risks pulling in `@playwright/test`'s own global setup
+ *    as a side effect, which resolving a URL string has no business doing).
+ */
+export async function resolveBaseUrl(projectDir) {
+    loadEnvFiles(projectDir);
+    if (process.env.WAYGRAPH_BASE_URL)
+        return process.env.WAYGRAPH_BASE_URL;
+    const config = await loadWaygraphConfig(projectDir);
+    if (config?.baseUrl && config.baseUrl.trim())
+        return config.baseUrl.trim();
+    const pkgPath = join(projectDir, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            const fromPkg = pkg.waygraph?.baseUrl ??
+                pkg.waygraph?.baseURL ??
+                pkg.config?.waygraph?.baseUrl ??
+                pkg.config?.waygraph?.baseURL;
+            if (typeof fromPkg === "string" && fromPkg.trim())
+                return fromPkg.trim();
+        }
+        catch {
+            // ignore malformed package.json - fall through to playwright.config
+        }
+    }
+    for (const name of ["playwright.config.ts", "playwright.config.mts", "playwright.config.js", "playwright.config.mjs"]) {
+        const p = join(projectDir, name);
+        if (!existsSync(p))
+            continue;
+        const src = readFileSync(p, "utf-8");
+        const m = src.match(/baseURL\s*:\s*["']([^"']+)["']/);
+        if (m?.[1])
+            return m[1];
+    }
+    return undefined;
+}

package/dist/core/blocks/effect.d.ts

@@ -17,13 +17,10 @@ export type EffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): EffectBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
 };
 /** @deprecated Prefer {@link EffectBlock} - same type; Mem* was an early name. */
 export type MemEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = EffectBlock<In, Out>;

package/dist/core/blocks/method.d.ts

@@ -17,13 +17,10 @@ export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): MethodBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
 };
 /** @deprecated Prefer {@link MethodBlock} - same type; Action was the 0.7 name. */
 export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = MethodBlock<In, Out>;
@@ -80,11 +77,8 @@ export type AssertBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Out,
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): AssertBlock<Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
 };

package/dist/core/blocks/nav.d.ts

@@ -22,13 +22,10 @@ export type NavBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpo
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): NavBlock<Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
 };
 /**
  * `defineNavBlock`'s own options - exactly one of `url`/`click` required,

package/dist/core/blocks/page.d.ts

@@ -47,13 +47,10 @@ export type PageBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkp
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): PageBlock<Out>;
     stubBefore(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubAfter(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubOnError(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
     stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
 };
 /** @see {@link PageBlockOptions} */
 export declare function definePageBlock<Out extends Checkpoint<string>>(options: PageBlockOptions<Out>): PageBlock<Out>;

package/dist/core/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 { chromiumExecutablePath } from "../browser-path.js";
 import { WaygraphError, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_CHAINFLOW_EMPTY, } from "../errors.js";
 import { preflight, runGraph } from "./run-graph.js";
 import { resolveLauncher } from "./config.js";
@@ -33,11 +34,7 @@ export function buildFlow(middle, engineConfig) {
             preflight(mem, chain);
             const browserName = config.browserName ?? "chromium";
             const launch = resolveLauncher(browserName, config);
-            // If CHROME_PATH/CHROMIUM_PATH is set in the environment (e.g. a system
-            // or Flatpak Chromium), launch that instead of Playwright's own bundled
-            // binary - only for chromium (the env var names a Chromium build, not a
-            // Firefox/WebKit one), and a no-op default anywhere that env var isn't set.
-            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
+            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
             const browser = await launch.launch({
                 headless: config.headless ?? true,
                 ...(config.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
@@ -324,7 +321,7 @@ export function chainFlow(...flows) {
             // session reset, silently making withSessionReset a no-op).
             const browserName = config?.browserName ?? "chromium";
             const launch = resolveLauncher(browserName, config);
-            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
+            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
             const browser = await launch.launch({
                 headless: config?.headless ?? true,
                 ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),

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;