waygraph 0.15.49 → 0.15.50

package/dist/auto-session/session.js

@@ -54,7 +54,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 = {

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;
     }

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/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/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/highlights/types.d.ts

@@ -165,9 +165,9 @@ export type StubPhaseFixtures = {
     /** Banner UX: collision (move away from a ring it overlaps), hidden. See {@link BannerUiOpts}. */
     bannerUi?: BannerUiOpts;
     /**
-     * Bottom subtitle-bar caption (ported from zsign's help-center-clip-engine) - a full-width,
-     * bottom-anchored gradient scrim with centered text, distinct from the banner (top, card-shaped).
-     * Omit/clear to hide it; set again to change the text, fading out/in.
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill, distinct from the banner (top, card-shaped). Omit/clear to hide it; set again
+     * to change the text, fading out/in.
      */
     caption?: string;
     /**
@@ -421,9 +421,9 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
      */
     bannerUi(opts: BannerUiOpts): void;
     /**
-     * Bottom subtitle-bar caption (ported from zsign's help-center-clip-engine) - a full-width,
-     * bottom-anchored gradient scrim with centered text; distinct from {@link StubCtx.title}, which
-     * is the top card. Fades in/out on change. Pass `""` (or call {@link StubCtx.hideCaption}) to clear.
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill; distinct from {@link StubCtx.title}, which is the top banner card. Fades in/out
+     * on change. Pass `""` (or call {@link StubCtx.hideCaption}) to clear.
      * @example ctx.caption("Click Add to cart to continue");
      */
     caption(text: string): void;

package/dist/index.d.ts

@@ -29,3 +29,5 @@ export { AutoSession, stubFilePath } from "./auto-session.js";
 export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnapshotSection, ApplyPickResult, ApplyPathResult, TraceStep, ConsoleLogEntry, StorageSnapshot, ServiceWorkerRegistrationInfo, CookieInfo, StubFileKind, } from "./auto-session.js";
 export { pilotStart } from "./session/pilot.js";
 export type { PilotStartResult } from "./session/pilot.js";
+export { defineConfig, resolveBaseUrl } from "./config.js";
+export type { WaygraphConfig } from "./config.js";

package/dist/index.js

@@ -14,3 +14,4 @@ export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, form
 export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./session/overlay-beacon.js";
 export { AutoSession, stubFilePath } from "./auto-session.js";
 export { pilotStart } from "./session/pilot.js";
+export { defineConfig, resolveBaseUrl } from "./config.js";

package/dist/runner/inpage/caption.js

@@ -1,6 +1,6 @@
 // In-page installer (page.evaluate target) - must stay self-contained, no module-scope closure.
-// Bottom subtitle-bar caption, ported from zsign's help-center-clip-engine (see ui/css/caption.css's
-// own header) - same visual fixture, narration-timeline/TTS sync not ported yet.
+// Bottom narration caption - a white rounded card, not the dark zsign-ported scrim this started as
+// (see ui/css/caption.css's own header); narration-timeline/TTS sync not ported yet.
 export function showCaption(text) {
   let bar = __wgById("wg-caption-bar");
   if (!bar) {

package/dist/session/auto-explore-run.d.ts

@@ -3,6 +3,7 @@ import { Engine } from "../core.js";
 import { MemPage } from "../mem-page.js";
 import { type BlockEntry } from "./auto-explore.js";
 import type { Checkpoint } from "../types.js";
+import { resolveBaseUrl } from "../config.js";
 export interface AutoExploreOptions {
     /** Terminal menu (browser still runs for act()). Default false = headful picker panel. */
     cli?: boolean;
@@ -12,7 +13,9 @@ export interface AutoExploreOptions {
     /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
     blocksSelect?: import("../blocks-select.js").BlocksSelect;
 }
-export declare function resolveBaseUrl(projectDir: string): string | undefined;
+/** See `../config.js`'s own `resolveBaseUrl` - re-exported so existing importers of this module
+ * don't need to change their import path. */
+export { resolveBaseUrl };
 export declare function detectHere(page: Page, navBlocks: BlockEntry[]): Promise<string | null>;
 export declare function ensureLivePage(context: BrowserContext, page: Page, startUrl: string | undefined): Promise<Page>;
 /**

package/dist/session/auto-explore-run.js

@@ -1,35 +1,14 @@
 import { createInterface } from "node:readline/promises";
 import { ensureShadowRoot } from "../ui/shadow.js";
 import { stdin as input, stdout as output } from "node:process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import { Engine, start, end, locate } from "../core.js";
 import { MemPage } from "../mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { installDemoChrome, instrumentInteractionHighlighting } from "./step-overlay.js";
-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;
-            if (typeof fromPkg === "string" && fromPkg.trim())
-                return fromPkg.trim();
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    for (const name of ["playwright.config.ts", "playwright.config.mts", "playwright.config.js"]) {
-        const p = join(projectDir, name);
-        if (!existsSync(p))
-            continue;
-        const m = readFileSync(p, "utf-8").match(/baseURL\s*:\s*["']([^"']+)["']/);
-        if (m?.[1])
-            return m[1];
-    }
-    return undefined;
-}
+import { resolveBaseUrl } from "../config.js";
+/** See `../config.js`'s own `resolveBaseUrl` - re-exported so existing importers of this module
+ * don't need to change their import path. */
+export { resolveBaseUrl };
 /** URL-first - several Checkpoints share nav verify traits (e.g. LoggedIn = /inventory.html). */
 async function inferCheckpointFromUrl(page) {
     try {
@@ -577,7 +556,7 @@ async function cliPick(menu, rl) {
 export async function runAutoExplore(projectDir, options = {}) {
     lastRunNote = null;
     const cli = options.cli === true;
-    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
+    const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? process.env.WAYGRAPH_BASE_URL;
     const startUrl = options.startUrl ?? baseURL;
     const { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
     if (options.blocksSelect) {

package/dist/traverse/run.js

@@ -1,29 +1,10 @@
-/**
- * Phase B+D: graph traverse (serial or --parallel with --session clone).
- * Walk unused legal edges until leaf / budget / break.
- */
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
 import { Engine, start, end, locate } from "../core.js";
 import { MemPage } from "../mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "../session/auto-explore.js";
 import { defaultMemValueForKey } from "../session/auto-explore-run.js";
+import { resolveBaseUrl } from "../config.js";
 import { EdgeLeaseCoordinator } from "./lease.js";
 import { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, writeCoverageReport, } from "./coverage.js";
-function resolveBaseUrl(projectDir) {
-    if (process.env.WAYGRAPH_BASE_URL)
-        return process.env.WAYGRAPH_BASE_URL;
-    const pkgPath = join(projectDir, "package.json");
-    if (!existsSync(pkgPath))
-        return undefined;
-    try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        return pkg.waygraph?.baseUrl;
-    }
-    catch {
-        return undefined;
-    }
-}
 function seedMem(library, mem, dataJson) {
     const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
     let envParsed = {};
@@ -257,7 +238,7 @@ export async function runTraverse(projectDir, options = {}) {
     const maxVisitsPerEdge = options.maxVisitsPerEdge ?? 1;
     const timeoutMs = options.timeoutMs ?? 15 * 60_000;
     const headed = options.headed === true || process.env.WAYGRAPH_HEADED === "1";
-    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
+    const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? process.env.WAYGRAPH_BASE_URL;
     const startUrl = options.startUrl ?? baseURL;
     const minEdgeCoverage = options.minEdgeCoverage != null && Number.isFinite(options.minEdgeCoverage)
         ? options.minEdgeCoverage

package/examples/saucedemo/.waygraph-auto/161cc8dd.log

@@ -0,0 +1,22 @@
+[16:29:47.576] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[16:29:47.576] waygraph pilot: stub.before ctx.todos n=6 index=0
+[16:29:47.576] waygraph pilot: stub.before ctx.device(mobile)
+[16:29:47.576] waygraph pilot: stub.before ctx.zoom(1.35)
+[16:29:47.576] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[16:29:48.942] waygraph pilot: stub.after ctx.todos n=6 index=1
+[16:29:50.794] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[16:29:50.965] waygraph pilot: stub.after ctx.todos n=6 index=2
+[16:29:52.406] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[16:29:52.726] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[16:29:52.727] waygraph pilot: stub.after ctx.todos n=6 index=3
+[16:29:52.727] waygraph pilot: stub.after ctx.device(mobile)
+[16:29:52.727] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[16:29:54.148] waygraph pilot: ring not painted - selector matched nothing (or a zero-size element): .inventory_list
+[16:29:58.462] waygraph pilot: stub.before ctx.title("Open cart · landscape")
+[16:29:58.462] waygraph pilot: stub.before ctx.todos n=6 index=5
+[16:29:58.462] waygraph pilot: stub.before ctx.device(mobile)
+[16:29:58.462] waygraph pilot: stub.before ctx.zoom(1.4)
+[16:29:58.462] waygraph pilot: stub.before ring .shopping_cart_link tone=planned label="Cart"
+[16:29:58.870] waygraph pilot: stub.after ctx.title("Your cart · desktop")
+[16:29:58.871] waygraph pilot: stub.after ring .cart_item tone=success label="Cart items"
+[16:29:58.934] waygraph pilot: ring not painted - selector matched nothing (or a zero-size element): .cart_item

package/examples/saucedemo/.waygraph-auto/22048fff.log

@@ -0,0 +1,4 @@
+[16:29:18.968] waygraph pilot: highlight ring #user-name tone=planned label="Username"
+[16:29:18.969] waygraph pilot: highlight ring #password tone=info label="Password"
+[16:29:18.969] waygraph pilot: highlight ring #login-button tone=success label="Login"
+[16:29:23.306] waygraph pilot: highlight ring #user-name tone=planned label="Username"

package/examples/saucedemo/.waygraph-auto/7fcb512f.log

@@ -0,0 +1,22 @@
+[16:29:27.265] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[16:29:27.265] waygraph pilot: stub.before ctx.todos n=6 index=0
+[16:29:27.265] waygraph pilot: stub.before ctx.device(mobile)
+[16:29:27.266] waygraph pilot: stub.before ctx.zoom(1.35)
+[16:29:27.266] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[16:29:28.809] waygraph pilot: stub.after ctx.todos n=6 index=1
+[16:29:34.946] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[16:29:35.328] waygraph pilot: stub.after ctx.todos n=6 index=2
+[16:29:41.327] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[16:29:42.199] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[16:29:42.200] waygraph pilot: stub.after ctx.todos n=6 index=3
+[16:29:42.200] waygraph pilot: stub.after ctx.device(mobile)
+[16:29:42.200] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[16:29:50.154] waygraph pilot: stub.before ctx.title("Pick a product · tablet")
+[16:29:50.154] waygraph pilot: stub.before ctx.todos n=6 index=3
+[16:29:50.154] waygraph pilot: stub.before ctx.device(tablet)
+[16:29:50.154] waygraph pilot: stub.before ctx.zoom(1.35)
+[16:29:50.154] waygraph pilot: stub.before ring div.inventory_item:has(button[data-test="add-to-cart-sauce-labs-backpack"], button[data-test="remove-sauce-labs-backpack"]) .inventory_item_name tone=info label="Sauce Labs Backpack"
+[16:29:50.154] waygraph pilot: stub.before ring [data-test="add-to-cart-sauce-labs-backpack"] tone=success label="Add to cart"
+[16:29:51.029] waygraph pilot: stub.after ctx.title("In the cart")
+[16:29:51.029] waygraph pilot: stub.after ctx.todos n=6 index=4
+[16:29:51.029] waygraph pilot: stub.after ring .shopping_cart_badge tone=success label="Cart badge"

package/examples/saucedemo/.waygraph-auto/84dc6480.log

@@ -0,0 +1,6 @@
+[16:30:31.665] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[16:30:31.665] waygraph pilot: stub.before ctx.todos n=6 index=0
+[16:30:31.665] waygraph pilot: stub.before ctx.device(mobile)
+[16:30:31.665] waygraph pilot: stub.before ctx.zoom(1.35)
+[16:30:31.665] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[16:30:32.427] waygraph pilot: stub.after ctx.todos n=6 index=1

package/examples/saucedemo/.waygraph-auto/8a08b68d.log

@@ -0,0 +1,6 @@
+[16:30:12.884] waygraph pilot: highlight ctx.todos n=3 index=0
+[16:30:12.884] waygraph pilot: highlight ring #user-name tone=planned label="Username"
+[16:30:12.892] waygraph pilot: highlight ring #password tone=info label="Password"
+[16:30:17.796] waygraph pilot: highlight ring #no-such-element-waygraph tone=danger label="Gone"
+[16:30:17.817] waygraph pilot: ring not painted - selector matched nothing (or a zero-size element): #no-such-element-waygraph
+[16:30:20.108] waygraph pilot: highlight ring #login-button tone=success label="Login"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.49",
+  "version": "0.15.50",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/scaffold/src/flows/shop.flow.ts

@@ -5,21 +5,34 @@ import {
   withTitle,
   withHighlightFixtures,
   withSessionReset,
+  withMemStub,
+  registerMemStub,
 } from "waygraph";
 import { NavHomeBlock } from "../map/(app_base)/home/_nav.block.js";
 import { AddItemBlock } from "../map/(app_base)/home/_methods/add-item.effect.block.js";
 import { AssertItemAddedBlock } from "../map/(app_base)/home/_methods/assert-item-added.method.block.js";
 import { RemoveItemBlock } from "../map/(app_base)/home/_methods/remove-item.effect.block.js";
 import { ClearCartBlock } from "../map/(app_base)/home/_methods/clear-cart.method.block.js";
+import { SelectedItem } from "../states/demo.mem-keys.js";
 import "../map/(app_base)/home/_page.block.js";
 
 const engine = new Engine();
 
 /**
- * Effect + Method demo (set mem for add-item, or use `waygraph auto` which
- * fills SelectedItem via instanceOptions).
+ * memStub: a real fixture row (`alpha`/`Alpha`), registered once so this Flow never needs
+ * --data at all. Still override-able - `--data '{"demo.selectedItem":{"id":"beta",...}}'`
+ * wins over this registration, same as any other memStub (see docs/REFERENCE.md's own
+ * "memStub - fake values for requires" section).
+ */
+registerMemStub(SelectedItem.key, () => ({ id: "alpha", name: "Alpha" }));
+
+/**
+ * Effect + Method demo. `requires: [SelectedItem.key]` (on `add-item`) is filled automatically
+ * by the memStub registration above - no --data needed. Override it with real data, or use
+ * `waygraph auto` which fills SelectedItem via instanceOptions instead:
  *
- *   waygraph demo --blocks shopFlow --data '{"demo.selectedItem":{"id":"alpha","name":"Alpha"}}'
+ *   waygraph demo --blocks shopFlow                                    # memStub fills it
+ *   waygraph demo --blocks shopFlow --data '{"demo.selectedItem":{"id":"beta","name":"Beta"}}'
  *   waygraph auto   # after landing on home, pick Add Alpha / Add Beta / Remove ...
  *
  * Add -> assert it actually landed (mem-matched Remove button + cart count,
@@ -28,32 +41,34 @@ const engine = new Engine();
  * Clear cart (bulk Method, `clear-cart`) - keeps both the per-item and bulk
  * clear paths atomic and each wired into a real flow, not orphaned.
  */
-export const shopFlow = withHighlightFixtures(
-  withTitle(
-    withSessionReset(
-      engine.defineFlow([
-        start,
-        NavHomeBlock,
-        AddItemBlock,
-        AssertItemAddedBlock,
-        RemoveItemBlock,
-        AddItemBlock,
-        ClearCartBlock,
-        end,
-      ]),
+export const shopFlow = withMemStub(
+  withHighlightFixtures(
+    withTitle(
+      withSessionReset(
+        engine.defineFlow([
+          start,
+          NavHomeBlock,
+          AddItemBlock,
+          AssertItemAddedBlock,
+          RemoveItemBlock,
+          AddItemBlock,
+          ClearCartBlock,
+          end,
+        ]),
+      ),
+      "Scaffold: Shop (Effect + clear)",
     ),
-    "Scaffold: Shop (Effect + clear)",
-  ),
-  {
-    "add-item": {
-      stubAfter: {
-        cart: {
-          label: "AC · item in cart",
-          detail: "Cart count bumped after Add.",
-          tag: "AC",
-          duration: true,
+    {
+      "add-item": {
+        stubAfter: {
+          cart: {
+            label: "AC · item in cart",
+            detail: "Cart count bumped after Add.",
+            tag: "AC",
+            duration: true,
+          },
         },
       },
     },
-  },
+  ),
 );