waygraph 0.15.50 → 0.15.51

package/dist/analysis/map-check.js

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

package/dist/analysis/practices-check.js

@@ -5,8 +5,20 @@
  */
 import { readFileSync, readdirSync } from "node:fs";
 import { dirname, relative } from "node:path";
-/** define*Block<…Checkpoint<string>…> — prefer project Checkpoint types. */
-const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
+/** Every define*Block<In, Out> / <Out> generic list - args may themselves be Checkpoint<...>. */
+const BLOCK_GENERICS = /\bdefine(?:Method|Effect|MemEffect|Page|Nav|MemNav|NavClick|Action)Block\s*<\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*(?:,\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*)?>/g;
+/**
+ * A wildcard Out (the Block's result is untyped). A wildcard In is fine - it's the documented
+ * "reachable from anywhere" form (graph.ts treats it like a NavBlock's "*").
+ */
+function hasWildcardOut(src) {
+    for (const m of src.matchAll(BLOCK_GENERICS)) {
+        const out = (m[2] ?? m[1]).trim();
+        if (/^Checkpoint\s*<\s*string\s*>$/.test(out))
+            return true;
+    }
+    return false;
+}
 /** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
 const ASSERT_NO_TYPE_ARG = /\bdefineAssertBlock\s*\(\s*\{/;
 /** defineAssertBlock, any form - used to scope the empty-verify check below. */
@@ -74,11 +86,12 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
         const rel = relative(projectDir, file).replace(/\\/g, "/");
         const src = readFileSync(file, "utf-8");
         const ignore = ignoredKindsForFile(src);
-        if (!isIgnored("wildcard-checkpoint", ignore) && WILDCARD_CHECKPOINT.test(src)) {
+        if (!isIgnored("wildcard-checkpoint", ignore) && hasWildcardOut(src)) {
             warnings.push({
                 kind: "wildcard-checkpoint",
                 file: rel,
-                detail: 'uses Checkpoint<string> in a Block helper generic — prefer a typed Checkpoint from src/states/ (e.g. defineMethodBlock<LoginPage, LoginPage>)',
+                detail: "the Block's output is Checkpoint<string>, so its result is untyped — use a typed Checkpoint from " +
+                    "src/states/ (e.g. defineMethodBlock<LoginPage, LoggedIn>); a wildcard input is fine",
             });
         }
         if (!isIgnored("assert-no-type-arg", ignore) && ASSERT_NO_TYPE_ARG.test(src)) {

package/dist/auto-session/session.js

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

package/dist/browser-path.d.ts

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

package/dist/browser-path.js

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

package/dist/cli/run-chain.js

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

package/dist/commands/init.js

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

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

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

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

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

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

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

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

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

package/dist/core/flow.js

@@ -1,5 +1,6 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { connect } from "../types.js";
+import { chromiumExecutablePath } from "../browser-path.js";
 import { WaygraphError, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_CHAINFLOW_EMPTY, } from "../errors.js";
 import { preflight, runGraph } from "./run-graph.js";
 import { resolveLauncher } from "./config.js";
@@ -33,11 +34,7 @@ export function buildFlow(middle, engineConfig) {
             preflight(mem, chain);
             const browserName = config.browserName ?? "chromium";
             const launch = resolveLauncher(browserName, config);
-            // If CHROME_PATH/CHROMIUM_PATH is set in the environment (e.g. a system
-            // or Flatpak Chromium), launch that instead of Playwright's own bundled
-            // binary - only for chromium (the env var names a Chromium build, not a
-            // Firefox/WebKit one), and a no-op default anywhere that env var isn't set.
-            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
+            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
             const browser = await launch.launch({
                 headless: config.headless ?? true,
                 ...(config.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
@@ -324,7 +321,7 @@ export function chainFlow(...flows) {
             // session reset, silently making withSessionReset a no-op).
             const browserName = config?.browserName ?? "chromium";
             const launch = resolveLauncher(browserName, config);
-            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
+            const executablePath = browserName === "chromium" ? chromiumExecutablePath() : undefined;
             const browser = await launch.launch({
                 headless: config?.headless ?? true,
                 ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),

package/dist/highlights/types.d.ts

@@ -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

@@ -31,3 +31,6 @@ 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

@@ -15,3 +15,5 @@ export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL,
 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/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.js

@@ -6,6 +6,8 @@ import { MemPage } from "../mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { installDemoChrome, instrumentInteractionHighlighting } from "./step-overlay.js";
 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 };
@@ -540,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);
@@ -554,6 +562,9 @@ 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 ?? (await resolveBaseUrl(projectDir)) ?? process.env.WAYGRAPH_BASE_URL;
@@ -567,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

@@ -5,6 +5,7 @@ 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";
+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 = {};
@@ -253,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");