waygraph 0.15.49 → 0.15.51

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;
@@ -464,9 +464,10 @@ export type StubLifecycleFn<Out extends Checkpoint<string>> = (ctx: StubCtx<Out>
  * Block stub authoring:
  * - **preferred:** open lifecycle `stubBefore(ctx) { ctx.todos(...); ctx.ring(...) }`
  * - **shorthand:** static slot map `{ email: { selector, label } }`
- * - **legacy:** `(out) => slotMap` still accepted (treated as highlights only)
+ *
+ * Exactly one function member, so an inline `stubAfter(ctx) {}` gets `ctx` typed.
  */
-export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | StubLifecycleFn<Out> | ((out: Out) => HighlightStubPhase);
+export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | StubLifecycleFn<Out>;
 /** Result of running a stub phase (rings + episode fixtures). */
 export type StubPhaseResult = {
     highlights: ResolvedHighlight[];

package/dist/index.d.ts

@@ -29,3 +29,8 @@ 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";
+export { withWebServer } from "./webserver.js";
+export { chromiumExecutablePath } from "./browser-path.js";
+export type { WebServerConfig } from "./webserver.js";

package/dist/index.js

@@ -14,3 +14,6 @@ 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";
+export { withWebServer } from "./webserver.js";
+export { chromiumExecutablePath } from "./browser-path.js";

package/dist/runner/inpage/banner.js

@@ -101,28 +101,36 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
             );
           };
           const home = b.dataset.home || b.dataset.pos || "left";
+          // Called every animation frame while a ring is followed - only log when the outcome changes.
+          const log = (state, line) => {
+            if (b.dataset.lastLog === state) return;
+            b.dataset.lastLog = state;
+            if (line) (window.__wgBannerLog = window.__wgBannerLog || []).push(line);
+          };
           b.dataset.pos = home;
           if (!hits()) {
             delete b.dataset.moved;
+            log("clear");
             return;
           }
           for (const cand of POSITIONS.filter((p) => p !== home)) {
             b.dataset.pos = cand;
             if (!hits()) {
               b.dataset.moved = home + ">" + cand;
-              (window.__wgBannerLog = window.__wgBannerLog || []).push("moved " + home + " -> " + cand + " (ring overlap)");
+              log("moved:" + cand, "moved " + home + " -> " + cand + " (ring overlap)");
               return;
             }
           }
           b.dataset.pos = home;
           b.dataset.moved = "none-free";
-          (window.__wgBannerLog = window.__wgBannerLog || []).push("overlap at every position (kept " + home + ")");
+          log("none-free", "overlap at every position (kept " + home + ")");
         };
         window.__wgBannerRestore = () => {
           const b = __wgById("wg-banner");
           if (!b) return;
           if (b.dataset.home) b.dataset.pos = b.dataset.home;
           delete b.dataset.moved;
+          delete b.dataset.lastLog;
         };
         // Dim the banner while a ring caption is the focus - same "auto opacity" effect the todo
         // dock already has via __wgTodosSetBehind, extended to the banner so both floating chrome

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/runner/main.js

@@ -9,8 +9,10 @@ import { runStepMode } from "./step-mode.js";
 import { connect } from "../types.js";
 import { MemPage } from "../mem-page.js";
 import { Engine, start, end, chainFlow, isFastForwardBlock, branchRoutes, runBranchRegression } from "../core.js";
+import { withWebServer } from "../webserver.js";
+import { chromiumExecutablePath } from "../browser-path.js";
 
-async function main() {
+async function runMain() {
   const projectDir = process.argv[2];
   const spec = process.argv[3];
     const mem = new MemPage();
@@ -285,11 +287,7 @@ async function main() {
     // launched at Chromium's own default size/position, which stayed put
     // where it was for a previous, larger monitor and looked chopped off on
     // a smaller one. Maximizing fills whatever screen it's actually on.
-    // Same CHROME_PATH/CHROMIUM_PATH rule as Engine.run(mem): prefer the
-    // system/Flatpak Chromium when set, otherwise Playwright's bundled build.
-    // Without this, STEP mode always launched a different-looking browser than
-    // headed Engine runs / waygraph-demo.mjs (which already resolve Flatpak).
-    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH || undefined;
+    const executablePath = chromiumExecutablePath();
     // Maximized for interactive step, and for fixed video viewport so the
     // locked record size can actually fit (otherwise .webm gets grey pad).
     const browser = await chromium.launch({
@@ -446,6 +444,12 @@ async function runAllBranchesMode(chainFlows, mem, baseURL, headed, engine) {
   void engine;
 }
 
+// Here, not in the host CLI: importing playwright.config loads the project's own @playwright/test,
+// which would collide with the CLI's copy.
+async function main() {
+  await withWebServer(process.argv[2], runMain);
+}
+
 export function startRunner() {
   main().catch((err) => {
     console.error(err && err.stack ? err.stack : String(err));

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,16 @@
 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";
+import { withWebServer } from "../webserver.js";
+import { chromiumExecutablePath } from "../browser-path.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 {
@@ -561,7 +542,13 @@ function printCliMenu(menu, library) {
 }
 async function cliPick(menu, rl) {
     while (true) {
-        const ans = (await rl.question("Choose: ")).trim().toLowerCase();
+        let ans;
+        try {
+            ans = (await rl.question("Choose: ")).trim().toLowerCase();
+        }
+        catch {
+            return { type: "quit" }; // stdin ended (piped / Ctrl-D) - same as q
+        }
         if (ans === "q" || ans === "quit")
             return { type: "quit" };
         const n = Number(ans);
@@ -575,9 +562,12 @@ async function cliPick(menu, rl) {
  * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
  */
 export async function runAutoExplore(projectDir, options = {}) {
+    await withWebServer(projectDir, () => runAutoExploreCore(projectDir, options));
+}
+async function runAutoExploreCore(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) {
@@ -588,7 +578,7 @@ export async function runAutoExplore(projectDir, options = {}) {
     seedDefaultMem(library.byName, mem);
     const engine = cli ? new Engine({ headless: true }) : new Engine({ headless: false, slowMo: 250 });
     const { chromium } = await import("@playwright/test");
-    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    const executablePath = chromiumExecutablePath();
     const launchOpts = {
         headless: cli,
         args: cli ? [] : ["--start-maximized"],

package/dist/traverse/run.js

@@ -1,29 +1,11 @@
-/**
- * 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;
-    }
-}
+import { chromiumExecutablePath } from "../browser-path.js";
 function seedMem(library, mem, dataJson) {
     const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
     let envParsed = {};
@@ -257,7 +239,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
@@ -272,7 +254,7 @@ export async function runTraverse(projectDir, options = {}) {
     const leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
     const { chromium } = await import("@playwright/test");
-    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    const executablePath = chromiumExecutablePath();
     const launchOpts = {
         headless: !headed,
     };

package/dist/types.d.ts

@@ -284,15 +284,12 @@ export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<s
      */
     stubBefore(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
     stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
-    stubBefore(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
     /** Demo narration after resolve. Prefer ctx callbacks over slot-map objects. */
     stubAfter(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
     stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
-    stubAfter(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
     /** Demo narration when the step fails / expected-failure path. */
     stubOnError(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
     stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
-    stubOnError(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
 };
 /**
  * Structural (not imported) twin of `engine.ts`'s `Layout` - `types.ts` sits

package/dist/webserver.d.ts

@@ -0,0 +1,14 @@
+/** The subset of Playwright's `TestConfigWebServer` this drives - same field names. */
+export interface WebServerConfig {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    port?: number;
+    url?: string;
+    reuseExistingServer?: boolean;
+    timeout?: number;
+    stdout?: "pipe" | "ignore";
+    stderr?: "pipe" | "ignore";
+}
+/** Runs `fn` with the project's `webServer` (if any) up; only servers this call started get stopped. */
+export declare function withWebServer<T>(projectDir: string, fn: () => Promise<T>): Promise<T>;

package/dist/webserver.js

@@ -0,0 +1,91 @@
+// Starts/stops a project's own playwright.config `webServer` 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";
+const CONFIG_FILES = [
+    "playwright.config.ts",
+    "playwright.config.mts",
+    "playwright.config.mjs",
+    "playwright.config.js",
+    "playwright.config.cjs",
+];
+async function loadWebServerConfigs(projectDir) {
+    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 [];
+}
+async function isUp(target) {
+    try {
+        return (await fetch(target)).status < 500;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitUntilUp(target, timeoutMs) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (await isUp(target))
+            return;
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    throw new Error(`waygraph: webServer "${target}" not ready after ${timeoutMs}ms`);
+}
+async function startWebServers(configs, projectDir) {
+    const started = [];
+    for (const cfg of configs) {
+        const target = cfg.url ?? (cfg.port ? `http://localhost:${cfg.port}` : undefined);
+        if (!target)
+            throw new Error(`waygraph: webServer needs "url" or "port"`);
+        if (cfg.reuseExistingServer !== false && (await isUp(target)))
+            continue;
+        // detached = own process group, so stop() kills the shell AND whatever it exec'd.
+        const child = spawn(cfg.command, {
+            shell: true,
+            detached: true,
+            cwd: cfg.cwd ? join(projectDir, cfg.cwd) : projectDir,
+            env: { ...process.env, ...cfg.env },
+            stdio: ["ignore", cfg.stdout === "pipe" ? "inherit" : "ignore", cfg.stderr === "ignore" ? "ignore" : "inherit"],
+        });
+        started.push(child);
+        await waitUntilUp(target, cfg.timeout ?? 60_000);
+    }
+    return started;
+}
+function stopWebServers(started) {
+    for (const child of started) {
+        try {
+            if (typeof child.pid === "number")
+                process.kill(-child.pid, "SIGTERM");
+        }
+        catch {
+            /* already exited */
+        }
+    }
+}
+/** Runs `fn` with the project's `webServer` (if any) up; only servers this call started get stopped. */
+export async function withWebServer(projectDir, fn) {
+    const started = await startWebServers(await loadWebServerConfigs(projectDir), projectDir);
+    try {
+        return await fn();
+    }
+    finally {
+        stopWebServers(started);
+    }
+}

package/examples/routed-demo/package.json

@@ -6,11 +6,11 @@
   "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": "npm run fixture:test",
+    "test": "playwright test",
     "fixture": "node scripts/fixture-server.mjs",
-    "fixture:test": "node scripts/with-fixture.mjs npx playwright test",
     "graph": "waygraph graph",
-    "auto:cli": "node scripts/with-fixture.mjs waygraph auto --cli"
+    "map": "waygraph map",
+    "auto:cli": "waygraph auto --cli"
   },
   "waygraph": {
     "baseUrl": "http://127.0.0.1:4277"

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

@@ -1,7 +1,5 @@
 import { defineConfig } from "@playwright/test";
-
-const PORT = process.env.WAYGRAPH_FIXTURE_PORT || "4277";
-const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+import { chromiumExecutablePath } from "waygraph";
 
 export default defineConfig({
   testDir: "./tests",
@@ -9,13 +7,15 @@ export default defineConfig({
   workers: 1,
   timeout: 30_000,
   reporter: [["list"], ["html", { open: "never" }]],
+  webServer: {
+    command: "node scripts/fixture-server.mjs",
+    url: "http://127.0.0.1:4277/dashboard",
+    reuseExistingServer: !process.env.CI,
+  },
   use: {
     headless: true,
-    baseURL: process.env.WAYGRAPH_BASE_URL || `http://${HOST}:${PORT}`,
+    baseURL: "http://127.0.0.1:4277",
     trace: "retain-on-failure",
-    launchOptions: {
-      executablePath: process.env.CHROME_PATH || process.env.CHROMIUM_PATH,
-      args: ["--no-sandbox", "--disable-dev-shm-usage"],
-    },
+    launchOptions: { executablePath: chromiumExecutablePath() },
   },
 });

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

@@ -1,37 +1,18 @@
-#!/usr/bin/env node
-/**
- * Tiny static server for this example's offline fixture pages.
- * Mirrors templates/scaffold's own scripts/fixture-server.mjs exactly.
- */
+// 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.
 import { createServer } from "node:http";
 import { readFileSync, existsSync } from "node:fs";
-import { join, dirname, extname, normalize } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../src/pages");
-const PORT = Number(process.env.WAYGRAPH_FIXTURE_PORT || 4277);
-const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+const PAGES = join(import.meta.dirname, "../src/pages");
 
-const TYPES = {
-  ".html": "text/html; charset=utf-8",
-};
-
-const server = createServer((req, res) => {
-  const raw = (req.url || "/").split("?")[0] || "/";
-  const rel = raw === "/" ? "dashboard.html" : raw.replace(/^\//, "");
-  const full = normalize(join(ROOT, rel));
-  if (!full.startsWith(ROOT) || !existsSync(full)) {
-    res.writeHead(404, { "content-type": "text/plain" });
-    res.end("not found");
+createServer((req, res) => {
+  const path = (req.url || "/").split("?")[0];
+  const name = path === "/" ? "dashboard" : path.slice(1);
+  const file = join(PAGES, `${name}.html`);
+  if (!/^[a-z-]+$/.test(name) || !existsSync(file)) {
+    res.writeHead(404).end("not found");
     return;
   }
-  const type = TYPES[extname(full)] || "application/octet-stream";
-  res.writeHead(200, { "content-type": type });
-  res.end(readFileSync(full));
-});
-
-server.listen(PORT, HOST, () => {
-  if (process.env.WAYGRAPH_FIXTURE_QUIET !== "1") {
-    console.error(`waygraph fixture: http://${HOST}:${PORT}/dashboard.html`);
-  }
-});
+  res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(readFileSync(file));
+}).listen(4277, "127.0.0.1");

package/examples/routed-demo/src/map/(app_base)/dashboard/_sel.ts

@@ -1,6 +1,4 @@
-export const DASHBOARD_URL =
-  process.env.WAYGRAPH_DASHBOARD_URL ??
-  `http://${process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1"}:${process.env.WAYGRAPH_FIXTURE_PORT || "4277"}/dashboard.html`;
+export const DASHBOARD_URL = "/dashboard";
 
 export const DashboardSel = {
   heading: "#dashboard-heading",

package/examples/routed-demo/src/map/(external)/docs/_sel.ts

@@ -1,6 +1,4 @@
-export const DOCS_URL =
-  process.env.WAYGRAPH_DOCS_URL ??
-  `http://${process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1"}:${process.env.WAYGRAPH_FIXTURE_PORT || "4277"}/docs.html`;
+export const DOCS_URL = "/docs";
 
 export const DocsSel = {
   heading: "#docs-heading",

package/examples/routed-demo/src/pages/dashboard.html

@@ -5,6 +5,6 @@
   <h1 id="dashboard-heading">Dashboard</h1>
   <button id="widget-btn" onclick="document.getElementById('widget-out').textContent = 'clicked'">Click widget</button>
   <div id="widget-out"></div>
-  <a id="go-docs" href="/docs.html">Docs</a>
+  <a id="go-docs" href="/docs">Docs</a>
 </body>
 </html>

package/examples/routed-demo/src/pages/docs.html

@@ -3,6 +3,6 @@
 <head><title>Routed demo - docs</title></head>
 <body>
   <h1 id="docs-heading">Docs</h1>
-  <a id="go-dashboard" href="/dashboard.html">Back to dashboard</a>
+  <a id="go-dashboard" href="/dashboard">Back to dashboard</a>
 </body>
 </html>

package/examples/saucedemo/playwright.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from "@playwright/test";
+import { chromiumExecutablePath } from "waygraph";
 
 export default defineConfig({
   testDir: "./tests",
@@ -11,9 +12,7 @@ export default defineConfig({
     baseURL: "https://www.saucedemo.com",
     trace: "retain-on-failure",
     launchOptions: {
-      // Canonical Chromium on this machine is the Flatpak install - never let
-      // Playwright download its own bundled binary. See .agent/manager-agent.md.
-      executablePath: process.env.CHROME_PATH || process.env.CHROMIUM_PATH,
+      executablePath: chromiumExecutablePath(),
       args: ["--no-sandbox", "--disable-dev-shm-usage"],
     },
   },