waygraph 0.15.53 → 0.16.0

package/dist/runner/session.js

@@ -0,0 +1,87 @@
+// The browser a run plays in: launched with the project's extensions, sized for the mode and an optional video.
+import { mkdirSync } from "node:fs";
+import { recordArtifact } from "../engine/run/events.js";
+import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "../runtime/browser.js";
+import { resolveVideoDir } from "../runtime/video-dir.js";
+import { ignorePageGone } from "../engine/page-gone.js";
+/** WAYGRAPH_VIDEO_VIEWPORT / --video-viewport: "1920x1080" or "1920,1080". */
+function parseVideoViewport(raw) {
+    const m = raw?.trim().match(/^(\d{3,5})[xX,](\d{3,5})$/);
+    if (!m)
+        return null;
+    const width = Number(m[1]);
+    const height = Number(m[2]);
+    if (width < 320 || height < 240 || width > 7680 || height > 4320)
+        return null;
+    return { width, height };
+}
+/**
+ * A demo window fills the screen (viewport null, maximized). A video is a fixed 16:9 capture (1920x1080 for a demo,
+ * 1280x720 for a run) with the device scale locked, so the recording keeps that size on HiDPI hosts.
+ */
+function viewportFor(options, videoSize) {
+    if (videoSize)
+        return { viewport: videoSize, deviceScaleFactor: 1 };
+    return options.mode === "demo" ? { viewport: null } : { viewport: { width: 1280, height: 720 } };
+}
+export async function openSession(projectDir, options, mem, launchSlowMo) {
+    const videoDir = options.video ? (options.video === "1" ? await resolveVideoDir(projectDir) : options.video) : null;
+    if (videoDir)
+        mkdirSync(videoDir, { recursive: true });
+    const videoSize = videoDir
+        ? (parseVideoViewport(options.videoViewport) ?? (options.mode === "demo" ? { width: 1920, height: 1080 } : { width: 1280, height: 720 }))
+        : null;
+    const { chromium } = await import("@playwright/test");
+    const executablePath = chromiumExecutablePath();
+    const { context, close: closeBrowser } = await launchContext({
+        launcher: chromium,
+        launch: {
+            headless: !options.headed,
+            ...(launchSlowMo !== undefined ? { slowMo: launchSlowMo } : {}),
+            args: options.mode === "demo" || videoSize ? ["--start-maximized"] : [],
+            ...(executablePath ? { executablePath } : {}),
+        },
+        context: {
+            ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+            hasTouch: true,
+            ...viewportFor(options, videoSize),
+            ...(videoDir ? { recordVideo: videoSize ? { dir: videoDir, size: videoSize } : { dir: videoDir } } : {}),
+        },
+        extensions: extensionPathsFromEnv(),
+    });
+    const page = (await context.newPage());
+    if (videoSize)
+        page.__wgVideoViewport = videoSize;
+    // The first step's panel shows over the real app, not a blank page.
+    if (options.baseURL)
+        await page.goto(options.baseURL).catch(ignorePageGone);
+    const close = async () => {
+        // A recording's last moment (a ring, the network panel) would be cut off mid-fade without a little room.
+        if (videoDir && !page.isClosed())
+            await new Promise((r) => setTimeout(r, 1800));
+        await context.close();
+        const video = await page.video()?.path().catch(() => null);
+        if (video) {
+            console.log("waygraph: video saved to " + video);
+            recordArtifact("video", video);
+        }
+        await closeBrowser();
+    };
+    return { session: { context, page, mem, baseURL: options.baseURL }, close };
+}
+/** A fresh session between episodes: no cookies, no storage, back on the base URL (so the page itself looks fresh too). */
+export async function resetPage(session) {
+    await session.context.clearCookies().catch(ignorePageGone);
+    await session.page
+        .evaluate(() => {
+        try {
+            localStorage.clear();
+            sessionStorage.clear();
+        }
+        catch {
+            /* storage blocked (e.g. about:blank) - nothing to clear anyway */
+        }
+    })
+        .catch(ignorePageGone);
+    await session.page.goto(session.baseURL || "about:blank").catch(ignorePageGone);
+}

package/dist/{browser.js → runtime/browser.js}

@@ -1,6 +1,8 @@
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { envString } from "../engine/env.js";
+import { ignoreTimeout } from "../engine/page-gone.js";
 let warned = false;
 /**
  * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
@@ -20,7 +22,7 @@ export function chromiumExecutablePath() {
 }
 /** Unpacked extension directories, as resolved by `resolveExtensions` - also what `WAYGRAPH_EXTENSIONS` carries to child processes. */
 export function extensionPathsFromEnv() {
-    return (process.env.WAYGRAPH_EXTENSIONS ?? "").split(",").filter(Boolean);
+    return (envString("WAYGRAPH_EXTENSIONS") ?? "").split(",").filter(Boolean);
 }
 /**
  * Launches a browser and its first context. With `extensions` it uses a persistent context, the only
@@ -49,7 +51,7 @@ export async function launchContext(opts) {
     // An extension's background worker registers its page hooks, so wait for it before the first navigation.
     const hasWorker = extensions.some((dir) => JSON.parse(readFileSync(join(dir, "manifest.json"), "utf-8")).background?.service_worker !== undefined);
     if (hasWorker && context.serviceWorkers().length === 0) {
-        await context.waitForEvent("serviceworker", { timeout: 10_000 }).catch(() => undefined);
+        await context.waitForEvent("serviceworker", { timeout: 10_000 }).catch(ignoreTimeout);
     }
     return {
         browser: context.browser(),

package/dist/{env-file.js → runtime/env-file.js}

@@ -5,6 +5,8 @@
 // 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";
+import { envString, setEnv } from "../engine/env.js";
+import { takeGlobalFlag } from "./global-flag.js";
 /** `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) {
@@ -30,21 +32,14 @@ function parseEnvFile(content) {
 }
 /** The env mode: `--env <mode>` / `WAYGRAPH_ENV`, else `NODE_ENV`, else "development". */
 export function envMode() {
-    return process.env.WAYGRAPH_ENV || process.env.NODE_ENV || "development";
+    return envString("WAYGRAPH_ENV") || process.env.NODE_ENV || "development";
 }
 /** Removes `--env <mode>` / `--env=<mode>` from argv and records it as `WAYGRAPH_ENV`, so it never reaches a forwarded command. */
 export function takeEnvFlag(argv) {
-    const out = [];
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--env" && argv[i + 1] !== undefined)
-            process.env.WAYGRAPH_ENV = argv[++i];
-        else if (a.startsWith("--env="))
-            process.env.WAYGRAPH_ENV = a.slice("--env=".length);
-        else
-            out.push(a);
-    }
-    return out;
+    const { value, rest } = takeGlobalFlag(argv, "env");
+    if (value !== undefined)
+        setEnv("WAYGRAPH_ENV", value);
+    return rest;
 }
 /**
  * Loads `.env` / `.env.local` / `.env.<mode>` / `.env.<mode>.local` from a project's root, the layering

package/dist/{extensions.d.ts → runtime/extensions.d.ts}

@@ -1,9 +1,6 @@
 /** A known name (`"hoppscotch"`), a Chrome Web Store id, a path to an unpacked extension, or `{ id, sha256 }`. */
-export type ExtensionSpec = string | {
-    id?: string;
-    path?: string;
-    sha256?: string;
-};
+import type { ExtensionSpec } from "../engine/config.js";
+/** Names accepted in `extensions: [...]` mapped to their Chrome Web Store ids. */
 export declare const KNOWN_EXTENSIONS: Readonly<Record<string, string>>;
 /** Unpacks a .crx and pins the manifest `key`, so the extension keeps its store id (its origin is then stable, e.g. for an API allowlist). */
 export declare function unpackCrx(crx: Buffer, dest: string): void;

package/dist/{extensions.js → runtime/extensions.js}

@@ -4,12 +4,14 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { homedir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { inflateRawSync } from "node:zlib";
+import { envString } from "../engine/env.js";
+/** Names accepted in `extensions: [...]` mapped to their Chrome Web Store ids. */
 export const KNOWN_EXTENSIONS = {
     hoppscotch: "amknoiejhlmhancpahfcfcfhllgkpbld",
 };
 const STORE_ID = /^[a-p]{32}$/;
 function cacheDir() {
-    const base = process.env.WAYGRAPH_CACHE_DIR ?? join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "waygraph");
+    const base = envString("WAYGRAPH_CACHE_DIR") ?? join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "waygraph");
     return join(base, "extensions");
 }
 /** Reads the end-of-central-directory record and extracts every entry; rejects paths that escape `dest`. */

package/dist/runtime/full-launch.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/full-launch.js

@@ -0,0 +1,34 @@
+import { setOwnContextLauncher } from "../engine/run/launch.js";
+import { resolveLauncher } from "../engine/config.js";
+import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "./browser.js";
+import { resolveExtensions } from "./extensions.js";
+import { loadWaygraphConfig } from "./waygraph-config.js";
+import { envString } from "../engine/env.js";
+// An Engine's own browser follows the selected config (--config), the Chromium override and the configured extensions.
+setOwnContextLauncher(async (engineConfig) => {
+    // A config chosen with `--config` / WAYGRAPH_CONFIG wins over the one the Engine was built with.
+    const chosen = envString("WAYGRAPH_CONFIG") ? await loadWaygraphConfig(process.cwd()) : undefined;
+    const config = chosen
+        ? {
+            ...engineConfig,
+            ...(chosen.baseUrl !== undefined ? { baseUrl: chosen.baseUrl } : {}),
+            ...(chosen.extensions !== undefined ? { extensions: chosen.extensions } : {}),
+        }
+        : engineConfig;
+    const browserName = config?.browserName ?? "chromium";
+    const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
+    const baseURL = config?.baseUrl ?? envString("WAYGRAPH_BASE_URL");
+    return launchContext({
+        launcher: resolveLauncher(browserName, config),
+        launch: {
+            headless: config?.headless ?? true,
+            ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+            ...(executablePath ? { executablePath } : {}),
+        },
+        context: {
+            ...(baseURL ? { baseURL } : {}),
+            ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
+        },
+        extensions: await resolveExtensions(config?.extensions ?? extensionPathsFromEnv(), process.cwd()),
+    });
+});

package/dist/runtime/global-flag.d.ts

@@ -0,0 +1,5 @@
+/** The value of `--<name> <v>` / `--<name>=<v>` (the last one wins) and argv without it. */
+export declare function takeGlobalFlag(argv: string[], name: string): {
+    value: string | undefined;
+    rest: string[];
+};

package/dist/runtime/global-flag.js

@@ -0,0 +1,18 @@
+// Options any command takes (`--config`, `--env`): read with node:util's parseArgs and taken out of argv, so they never
+// reach a command that forwards its arguments (waygraph test -> playwright test).
+import { parseArgs } from "node:util";
+/** The value of `--<name> <v>` / `--<name>=<v>` (the last one wins) and argv without it. */
+export function takeGlobalFlag(argv, name) {
+    const { tokens } = parseArgs({ args: argv, options: { [name]: { type: "string" } }, strict: false, allowPositionals: true, tokens: true });
+    let value;
+    const drop = new Set();
+    for (const t of tokens) {
+        if (t.kind !== "option" || t.name !== name || typeof t.value !== "string")
+            continue;
+        value = t.value;
+        drop.add(t.index);
+        if (!t.inlineValue)
+            drop.add(t.index + 1);
+    }
+    return { value, rest: argv.filter((_, i) => !drop.has(i)) };
+}

package/dist/{playwright-config.d.ts → runtime/playwright-config.d.ts}

@@ -1,4 +1,4 @@
 import type { PlaywrightTestConfig } from "@playwright/test";
-import type { WaygraphConfig } from "./config.js";
+import type { WaygraphConfig } from "./waygraph-config.js";
 /** The test runner's config for a project, built from its waygraph config. `waygraph test` uses this when there is no playwright.config. */
 export declare function playwrightConfigFrom(config: WaygraphConfig, projectDir: string, baseURL: string | undefined): PlaywrightTestConfig;

package/dist/{playwright.config.js → runtime/playwright.config.js}

@@ -1,6 +1,7 @@
 // Loaded by `waygraph test` (playwright test -c) for projects that keep their settings in config/waygraph.config.ts.
 import { defineConfig } from "@playwright/test";
-import { loadWaygraphConfig, resolveBaseUrl } from "./config.js";
+import { loadWaygraphConfig, resolveBaseUrl } from "./waygraph-config.js";
 import { playwrightConfigFrom } from "./playwright-config.js";
-const projectDir = process.env.WAYGRAPH_PROJECT_DIR ?? process.cwd();
+import { envString } from "../engine/env.js";
+const projectDir = envString("WAYGRAPH_PROJECT_DIR") ?? process.cwd();
 export default defineConfig(playwrightConfigFrom((await loadWaygraphConfig(projectDir)) ?? {}, projectDir, await resolveBaseUrl(projectDir)));

package/dist/runtime/run-log.d.ts

@@ -0,0 +1,2 @@
+/** The folder run logs go to for a project unless the config or the environment says otherwise. */
+export declare function defaultRunLogDir(projectDir: string): string;

package/dist/runtime/run-log.js

@@ -0,0 +1,17 @@
+// Writes every run event to `<dir>/<runId>.jsonl` when WAYGRAPH_RUN_LOG names a folder (the CLI sets it to the project's
+// `.waygraph/runs`; `runLog: false` in the config turns it off). This is the run history Waygraph UI reads.
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { onRunEvent } from "../engine/run/events.js";
+import { envString } from "../engine/env.js";
+onRunEvent((event) => {
+    const dir = envString("WAYGRAPH_RUN_LOG");
+    if (!dir || dir === "0")
+        return;
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, `${event.runId}.jsonl`), JSON.stringify(event) + "\n");
+});
+/** The folder run logs go to for a project unless the config or the environment says otherwise. */
+export function defaultRunLogDir(projectDir) {
+    return join(projectDir, ".waygraph", "runs");
+}

package/dist/{video-dir.js → runtime/video-dir.js}

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join, resolve } from "node:path";
-import { loadWaygraphConfig } from "./config.js";
+import { loadWaygraphConfig } from "./waygraph-config.js";
+import { envString } from "../engine/env.js";
 /** The user's Downloads folder, or undefined when there is none (a server, a container). */
 export function downloadsDir() {
     const home = homedir();
@@ -41,7 +42,7 @@ function writable(dir) {
  */
 export async function resolveVideoDir(projectDir) {
     const fallback = join(projectDir, ".waygraph-videos");
-    const configured = process.env.WAYGRAPH_VIDEO_DIR || (await loadWaygraphConfig(projectDir))?.video?.dir;
+    const configured = envString("WAYGRAPH_VIDEO_DIR") || (await loadWaygraphConfig(projectDir))?.video?.dir;
     if (configured) {
         const dir = isAbsolute(expandHome(configured)) ? expandHome(configured) : resolve(projectDir, configured);
         if (writable(dir))

package/dist/{config.d.ts → runtime/waygraph-config.d.ts}

@@ -1,7 +1,8 @@
 import type { PlaywrightTestConfig } from "@playwright/test";
-import type { ExtensionSpec } from "./extensions.js";
+import type { ExtensionSpec } from "../engine/config.js";
 import type { WebServerConfig } from "./webserver.js";
-import type { DemoPace } from "./highlights.js";
+import type { DemoPace } from "../engine/stub/pace.js";
+/** Where `--video` recordings are saved and at what size. */
 export interface VideoSettings {
     /** Where recordings are saved: absolute, `~/…`, or relative to the project. Default `~/Downloads/waygraph-videos/<project>` (the project's `.waygraph-videos/` where there is no Downloads folder, and on CI). */
     dir?: string;
@@ -40,6 +41,7 @@ export interface DemoSettings extends RunSettings {
     /** Shorter Next / auto-next gates; keeps the cursor and typing animation. */
     fast?: boolean;
 }
+/** The project config in `config/waygraph.config.ts`: base URL, extensions, run and demo settings, web server and the Playwright block. */
 export interface WaygraphConfig {
     /** Same value `resolveBaseUrl` would otherwise read from package.json's `waygraph.baseUrl`. */
     baseUrl?: string;
@@ -55,6 +57,8 @@ export interface WaygraphConfig {
     run?: RunSettings;
     /** Settings for `waygraph demo` only. They override the shared ones above. */
     demo?: DemoSettings;
+    /** Write each run's events to `.waygraph/runs/<runId>.jsonl` (the history Waygraph UI shows), or to this folder. Default true. */
+    runLog?: boolean | string;
     /** Folder of test files, relative to the project. Default `"tests"`. */
     testDir?: string;
     /** App to start around `waygraph test`, `run`, `demo` and `auto` (same fields as Playwright's `webServer`). */
@@ -77,7 +81,7 @@ export declare function defineConfig(config: WaygraphConfig | ((context: ConfigC
 export declare function takeConfigFlag(argv: string[]): string[];
 /**
  * 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
+ * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli/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
@@ -86,7 +90,7 @@ export declare function takeConfigFlag(argv: string[]): string[];
 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
+ * (`src/cli/flags.ts`, `src/live/traverse/traverse.ts`, `src/live/auto/auto.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:
@@ -95,11 +99,6 @@ export declare function loadWaygraphConfig(projectDir: string): Promise<Waygraph
  *    `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>;
 /** Unpacked extension directories for a run: `WAYGRAPH_EXTENSIONS` if set, else the config file's `extensions` (fetched on first use). */

package/dist/{config.js → runtime/waygraph-config.js}

@@ -2,12 +2,14 @@
 // 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 { existsSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { extensionPathsFromEnv } from "./browser.js";
 import { envMode, loadEnvFiles } from "./env-file.js";
 import { resolveExtensions } from "./extensions.js";
+import { envString, setEnv } from "../engine/env.js";
+import { takeGlobalFlag } from "./global-flag.js";
 /**
  * Typed identity helper, like `defineConfig` in `vite.config.ts`. Pass an object, or a function when values come
  * from `.env` files (`.env`, `.env.local`, `.env.<mode>`; pick the mode with `--env <mode>`):
@@ -27,7 +29,7 @@ const CONFIG_FILENAMES = [...CONFIG_NAMES.map((n) => join("config", n)), ...CONF
  * (`staging` -> `config/waygraph.staging.config.ts`, also tried in the project root). Without it, `waygraph.config.*`.
  */
 function configCandidates() {
-    const chosen = process.env.WAYGRAPH_CONFIG;
+    const chosen = envString("WAYGRAPH_CONFIG");
     if (!chosen)
         return CONFIG_FILENAMES;
     if (/[\\/]/.test(chosen) || /\.[cm]?[jt]s$/.test(chosen))
@@ -37,21 +39,14 @@ function configCandidates() {
 }
 /** Removes `--config <file>` / `--config=<file>` from argv and records it as `WAYGRAPH_CONFIG`, so every command reads that config. */
 export function takeConfigFlag(argv) {
-    const out = [];
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--config" && argv[i + 1] !== undefined)
-            process.env.WAYGRAPH_CONFIG = argv[++i];
-        else if (a.startsWith("--config="))
-            process.env.WAYGRAPH_CONFIG = a.slice("--config=".length);
-        else
-            out.push(a);
-    }
-    return out;
+    const { value, rest } = takeGlobalFlag(argv, "config");
+    if (value !== undefined)
+        setEnv("WAYGRAPH_CONFIG", value);
+    return rest;
 }
 /**
  * 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
+ * unmodified because `bin/waygraph` already registers `tsx/esm` before `dist/cli/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
@@ -62,8 +57,8 @@ export async function loadWaygraphConfig(projectDir) {
     for (const name of configCandidates()) {
         const p = isAbsolute(name) ? name : join(projectDir, name);
         if (!existsSync(p)) {
-            if (process.env.WAYGRAPH_CONFIG && name === process.env.WAYGRAPH_CONFIG) {
-                throw new Error(`waygraph: config "${process.env.WAYGRAPH_CONFIG}" not found (looked for ${p})`);
+            if (envString("WAYGRAPH_CONFIG") && name === envString("WAYGRAPH_CONFIG")) {
+                throw new Error(`waygraph: config "${envString("WAYGRAPH_CONFIG")}" not found (looked for ${p})`);
             }
             continue;
         }
@@ -82,7 +77,7 @@ export async function loadWaygraphConfig(projectDir) {
 }
 /**
  * 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
+ * (`src/cli/flags.ts`, `src/live/traverse/traverse.ts`, `src/live/auto/auto.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:
@@ -91,43 +86,14 @@ export async function loadWaygraphConfig(projectDir) {
  *    `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;
+    if (envString("WAYGRAPH_BASE_URL"))
+        return envString("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;
 }
 /** Unpacked extension directories for a run: `WAYGRAPH_EXTENSIONS` if set, else the config file's `extensions` (fetched on first use). */
@@ -143,18 +109,22 @@ export async function configuredExtensions(projectDir) {
  * (`WAYGRAPH_COMMAND`, set by the CLI). The `run` / `demo` section overrides the shared top-level values. A flag, a shell
  * variable or a `.env` value that is already set always wins, so the config only supplies defaults.
  */
-export function applyConfigEnv(config, command = process.env.WAYGRAPH_COMMAND) {
+export function applyConfigEnv(config, command = envString("WAYGRAPH_COMMAND")) {
     if (!config)
         return;
     const isDemo = command === "demo" || command === "try";
     const section = isDemo ? config.demo : command === "run" ? config.run : undefined;
     const set = (name, value) => {
-        if (value !== undefined && process.env[name] === undefined)
-            process.env[name] = value;
+        if (value !== undefined && envString(name) === undefined)
+            setEnv(name, value);
     };
     const flag = (b) => (b === undefined ? undefined : b ? "1" : "0");
     const video = { ...config.video, ...section?.video };
     const slowMo = section?.slowMo ?? config.slowMo;
+    if (config.runLog === false)
+        set("WAYGRAPH_RUN_LOG", "0");
+    else if (typeof config.runLog === "string")
+        set("WAYGRAPH_RUN_LOG", config.runLog);
     set("WAYGRAPH_VIDEO_DIR", video.dir);
     set("WAYGRAPH_VIDEO_VIEWPORT", video.viewport);
     set("WAYGRAPH_SLOWMO", slowMo === undefined ? undefined : String(slowMo));

package/dist/{webserver.js → runtime/webserver.js}

@@ -1,38 +1,13 @@
-// Starts/stops a project's `webServer` (waygraph.config, or a legacy playwright.config) around `waygraph run`/`demo`/`auto`,
+// Starts/stops a project's `webServer` (from config/waygraph.config.ts) around `waygraph run`/`demo`/`auto`,
 // the same block `waygraph test` already honors.
-import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
-import { loadWaygraphConfig } from "./config.js";
-const CONFIG_FILES = [
-    "playwright.config.ts",
-    "playwright.config.mts",
-    "playwright.config.mjs",
-    "playwright.config.js",
-    "playwright.config.cjs",
-];
+import { loadWaygraphConfig } from "./waygraph-config.js";
 async function loadWebServerConfigs(projectDir) {
     const fromWaygraph = (await loadWaygraphConfig(projectDir))?.webServer;
-    if (fromWaygraph)
-        return Array.isArray(fromWaygraph) ? fromWaygraph : [fromWaygraph];
-    for (const name of CONFIG_FILES) {
-        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)}`);
-        }
-        const webServer = mod.default?.webServer;
-        if (!webServer)
-            return [];
-        return Array.isArray(webServer) ? webServer : [webServer];
-    }
-    return [];
+    if (!fromWaygraph)
+        return [];
+    return Array.isArray(fromWaygraph) ? fromWaygraph : [fromWaygraph];
 }
 async function isUp(target) {
     try {

package/examples/routed-demo/config/waygraph.config.ts

@@ -0,0 +1,20 @@
+import { Engine, defineConfig } from "waygraph";
+
+const config = defineConfig({
+  baseUrl: "http://127.0.0.1:4277",
+  testDir: "./tests",
+  webServer: {
+    command: "node scripts/fixture-server.mjs",
+    url: "http://127.0.0.1:4277/dashboard",
+    reuseExistingServer: !process.env.CI,
+  },
+  playwright: {
+    workers: 1,
+    fullyParallel: false,
+    timeout: 30_000,
+    use: { headless: true, trace: "retain-on-failure" },
+  },
+});
+
+export default config;
+export const engine = new Engine(config);

package/examples/routed-demo/package.json

@@ -6,15 +6,12 @@
   "description": "Waygraph Map folder convention proof - (group)/<page>/page.block.ts + nav.block.ts + methods/*.block.ts, offline fixture, zero new engine code.",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "playwright test",
+    "test": "waygraph test",
     "fixture": "node scripts/fixture-server.mjs",
     "graph": "waygraph graph",
     "map": "waygraph map",
     "auto:cli": "waygraph auto --cli"
   },
-  "waygraph": {
-    "baseUrl": "http://127.0.0.1:4277"
-  },
   "dependencies": {
     "waygraph": "file:../.."
   },

package/examples/routed-demo/scripts/fixture-server.mjs

@@ -1,5 +1,5 @@
 // Stands in for this example's real app: serves src/pages/<name>.html at clean URLs (/dashboard, /docs).
-// Started and stopped by playwright.config.ts's webServer - waygraph run/demo/auto/test all honor it.
+// Started and stopped by config/waygraph.config.ts's webServer - waygraph run/demo/auto/test all honor it.
 import { createServer } from "node:http";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";

package/examples/routed-demo/src/flows/routed-demo-map.flow.ts

@@ -1,4 +1,4 @@
-import { Engine } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
 import { NavDashboardBlock } from "../map/(app_base)/dashboard/_nav.block.js";
 import { ClickWidgetBlock } from "../map/(app_base)/dashboard/_methods/click-widget.block.js";
 import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
@@ -6,14 +6,12 @@ import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
 import "../map/(app_base)/dashboard/_page.block.js";
 import "../map/(external)/docs/_page.block.js";
 
-const engine = new Engine();
 
 const homeOrigin = process.env.WAYGRAPH_BASE_URL || "http://127.0.0.1:4277";
 
 /**
  * Same real Blocks, same real Checkpoints, same real fixture server as
- * routed-demo.flow.ts - built with `engine.map()` instead of
- * `engine.defineFlow([start, ..., end])` to prove the fluent builder
+ * routed-demo.flow.ts - built with `engine.map()` to prove the fluent builder
  * against a real browser/DOM, not just the in-memory fakes
  * tests/nav/map-builder.spec.ts already covers in the main package.
  *

package/examples/routed-demo/src/flows/routed-demo.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
 import { NavDashboardBlock } from "../map/(app_base)/dashboard/_nav.block.js";
 import { ClickWidgetBlock } from "../map/(app_base)/dashboard/_methods/click-widget.block.js";
 import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
@@ -6,7 +6,6 @@ import { NavDocsBlock } from "../map/(external)/docs/_nav.block.js";
 import "../map/(app_base)/dashboard/_page.block.js";
 import "../map/(external)/docs/_page.block.js";
 
-const engine = new Engine();
 
 /** Smoke: dashboard -> click widget -> docs, all Blocks under the Waygraph Map folder convention. */
-export const routedDemoFlow = engine.defineFlow([start, NavDashboardBlock, ClickWidgetBlock, NavDocsBlock, end]);
+export const routedDemoFlow = engine.map().start().gotoPage(NavDashboardBlock).method(ClickWidgetBlock).gotoPage(NavDocsBlock).end();