waygraph 0.15.50 → 0.15.52

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

@@ -1,4 +1,4 @@
 /** In-page installer (page.evaluate target) - see core.js's own header. Installs the shared ring
- * primitive (__wgEnsureRingEl/__wgPaintRingAt/__wgHideRingAt), cursor, click-pulse, focus veil,
+ * primitive (__wgEnsureRingEl/__wgPaintRingAt), cursor, click-pulse, focus veil,
  * and the #wg-ring singleton every surface's "current action" ring uses. */
 export function installCore(args: Record<string, unknown>): void;

package/dist/runner/inpage/core.js

@@ -72,7 +72,14 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ring.style.width = width + "px";
           ring.style.height = height + "px";
           ring.style.opacity = "1";
-          ringLabel.textContent = label || "";
+          if (labelId === "wg-ring-label") {
+            // The demo ring's caption is drawn from data-label (CSS ::after), not DOM text, so the page's own
+            // text selectors (getByText, text=...) never match waygraph's overlay twice.
+            ringLabel.dataset.label = label || "";
+            ringLabel.textContent = "";
+          } else {
+            ringLabel.textContent = label || "";
+          }
           ringLabel.style.opacity = "1";
           const lw = ringLabel.offsetWidth;
           const lh = ringLabel.offsetHeight;
@@ -104,12 +111,6 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ringLabel.style.top = labelTop + "px";
           return [ring, ringLabel];
         };
-        window.__wgHideRingAt = (ringId, labelId) => {
-          const ring = __wgById(ringId);
-          const label = __wgById(labelId);
-          if (ring) ring.style.opacity = "0";
-          if (label) label.style.opacity = "0";
-        };
         window.__wgEnsureRingEl("wg-ring", "wg-ring-label");
         if (!__wgById("wg-cursor")) {
           const cursor = document.createElement("div");

package/dist/runner/main.js

@@ -9,8 +9,11 @@ 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 { resolveVideoDir } from "../video-dir.js";
+import { chromiumExecutablePath, extensionPathsFromEnv, launchContext } from "../browser.js";
 
-async function main() {
+async function runMain() {
   const projectDir = process.argv[2];
   const spec = process.argv[3];
     const mem = new MemPage();
@@ -250,7 +253,7 @@ async function main() {
   const videoEnv = process.env.WAYGRAPH_VIDEO;
   let videoDir = null;
   if (videoEnv) {
-    videoDir = videoEnv === "1" ? join(projectDir, ".waygraph-videos") : videoEnv;
+    videoDir = videoEnv === "1" ? await resolveVideoDir(projectDir) : videoEnv;
     mkdirSync(videoDir, { recursive: true });
   }
   /** Fixed 16:9 capture for --video (demo QA and headless run). Step+video no longer maximizes. */
@@ -285,19 +288,9 @@ 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({
-      headless: !headed,
-      slowMo,
-      args: step || fixedVideoViewport ? ["--start-maximized"] : [],
-      ...(executablePath ? { executablePath } : {}),
-    });
     const contextOpts = fixedVideoViewport
       ? {
           baseURL,
@@ -315,7 +308,17 @@ async function main() {
         ? { dir: videoDir, size: fixedVideoViewport }
         : { dir: videoDir };
     }
-    const context = await browser.newContext(contextOpts);
+    const { context, close: closeBrowser } = await launchContext({
+      launcher: chromium,
+      launch: {
+        headless: !headed,
+        slowMo,
+        args: step || fixedVideoViewport ? ["--start-maximized"] : [],
+        ...(executablePath ? { executablePath } : {}),
+      },
+      context: contextOpts,
+      extensions: extensionPathsFromEnv(),
+    });
     let pageForVideo = null;
     try {
       if (step) {
@@ -371,7 +374,7 @@ async function main() {
       if (savedVideo) {
         console.log("waygraph: video saved to " + savedVideo);
       }
-      await browser.close();
+      await closeBrowser();
     }
   } else {
     if (chainFlows && chainFlows.length > 0) {
@@ -423,6 +426,9 @@ async function runAllBranchesMode(chainFlows, mem, baseURL, headed, engine) {
     process.exitCode = 1;
     return;
   }
+  if (extensionPathsFromEnv().length > 0) {
+    console.warn("waygraph run --all-branches: extensions are not loaded (branches run in cloned contexts)");
+  }
   const { chromium } = await import("@playwright/test");
   const browser = await chromium.launch({ headless: !headed });
   const cloneSession = process.env.WAYGRAPH_SHARED_SESSION !== "1";
@@ -446,6 +452,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/runner/rings.js

@@ -381,55 +381,6 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
 }
 
 
-/**
- * Paint a NAMED ring instance (ui/css/ring.css's shared `.wg-ring-el`/`.wg-ring-el-label`) at a
- * known viewport box - the primitive both the demo/auto singleton (`showRing`, always "wg-ring")
- * and Pilot's several simultaneous fixture rings (their own ids) paint through, so there is one
- * ring-rendering implementation, not two. No collision/follow/focus - those are `#wg-ring`'s own
- * extras (see `showRing`/`inpage/core.js`'s `__wgPositionRing`), meaningless for an independent
- * fixture ring that isn't "the current action."
- */
-export async function showRingAt(page, ringId, labelId, box, label, tone, style) {
-  const size = normalizeHighlightSize(style && style.size);
-  const weight = normalizeHighlightWeight(style && style.weight);
-  const color = style && style.color ? String(style.color) : "";
-  await page
-    .evaluate(
-      ({ ringId, labelId, box, label, tone, size, weight, color }) => {
-        if (window.__wgPaintRingAt) {
-          window.__wgPaintRingAt(ringId, labelId, box, label, tone, { size, weight, color });
-        }
-      },
-      { ringId, labelId, box, label, tone: tone || "planned", size, weight, color },
-    )
-    .catch(() => {});
-}
-
-/** Hide (not remove) a named ring instance painted via {@link showRingAt}. */
-export async function hideRingAt(page, ringId, labelId) {
-  await page
-    .evaluate(
-      ({ ringId, labelId }) => {
-        if (window.__wgHideRingAt) window.__wgHideRingAt(ringId, labelId);
-      },
-      { ringId, labelId },
-    )
-    .catch(() => {});
-}
-
-/** Remove a named ring instance entirely (Pilot's fixture rings are short-lived, not reused). */
-export async function removeRingAt(page, ringId, labelId) {
-  await page
-    .evaluate(
-      ({ ringId, labelId }) => {
-        __wgById(ringId)?.remove();
-        __wgById(labelId)?.remove();
-      },
-      { ringId, labelId },
-    )
-    .catch(() => {});
-}
-
 export async function showRing(page, box, label, tone, style) {
   const size = normalizeHighlightSize(style && style.size);
   const weight = normalizeHighlightWeight(style && style.weight);

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

@@ -5,7 +5,9 @@ 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";
-import { resolveBaseUrl } from "../config.js";
+import { configuredExtensions, resolveBaseUrl } from "../config.js";
+import { withWebServer } from "../webserver.js";
+import { chromiumExecutablePath, launchContext } from "../browser.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"],
@@ -576,13 +587,17 @@ export async function runAutoExplore(projectDir, options = {}) {
         launchOpts.slowMo = 250;
     if (executablePath)
         launchOpts.executablePath = executablePath;
-    const browser = await chromium.launch(launchOpts);
     const contextOpts = cli
         ? { viewport: { width: 1280, height: 720 } }
         : { viewport: null };
     if (baseURL)
         contextOpts.baseURL = baseURL;
-    const context = await browser.newContext(contextOpts);
+    const { close: closeBrowser, context } = await launchContext({
+        launcher: chromium,
+        launch: launchOpts,
+        context: contextOpts,
+        extensions: await configuredExtensions(projectDir),
+    });
     let page = await context.newPage();
     if (startUrl) {
         await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
@@ -681,6 +696,6 @@ export async function runAutoExplore(projectDir, options = {}) {
     finally {
         cliRl?.close();
         await context.close();
-        await browser.close();
+        await closeBrowser();
     }
 }

package/dist/session/auto-explore.js

@@ -169,7 +169,7 @@ export function exploreChoices(graph, here) {
     const out = [];
     for (const edge of graph.edges) {
         if (here === null) {
-            if (edge.kind !== "nav")
+            if (edge.kind !== "nav" || edge.from !== "*")
                 continue;
         }
         else if (edge.from !== here && edge.from !== "*") {
@@ -283,8 +283,9 @@ export async function buildExploreMenu(page, graph, library, here) {
             continue;
         if (here === null) {
             // Bootstrap only: URL deep-links as "Start here". Click-nav needs a live
-            // control so it cannot seed an unknown page.
-            if (!isUrlNav(entry))
+            // control so it cannot seed an unknown page, and a Nav with `from` needs
+            // that state first (e.g. signed in) so it cannot start one either.
+            if (!isUrlNav(entry) || edge.from !== "*")
                 continue;
             push(navigate, edge);
             continue;
@@ -295,7 +296,8 @@ export async function buildExploreMenu(page, graph, library, here) {
         // Graph still marks NavBlocks from:"*" for pathfinding/traverse; auto menu
         // only offers click-nav whose control is visible on this page (navRunnable).
         // Otherwise LoginForm lists every app route + mailpit as if legal moves.
-        if (isUrlNav(entry))
+        // A url Nav that declares `from` is only an edge from those pages, so it IS a real move here.
+        if (isUrlNav(entry) && edge.from === "*")
             continue;
         if (isBackEdge(edge) && (edge.from === here || edge.from === "*")) {
             push(back, edge);

package/dist/session/step-overlay.js

@@ -86,7 +86,9 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             ring.style.width = box.width + pad * 2 + "px";
             ring.style.height = box.height + pad * 2 + "px";
             ring.style.opacity = "1";
-            ringLabel.textContent = label;
+            // Drawn from data-label (CSS ::after), not DOM text, so the page's own text selectors never match it.
+            ringLabel.dataset.label = label;
+            ringLabel.textContent = "";
             ringLabel.style.left = box.x + "px";
             ringLabel.style.top = box.y + box.height + 8 + "px";
             ringLabel.style.opacity = "1";

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.js";
 function seedMem(library, mem, dataJson) {
     const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
     let envParsed = {};
@@ -252,8 +253,10 @@ export async function runTraverse(projectDir, options = {}) {
     const allEdgeKeys = collectGraphEdgeKeys(graph.edges);
     const leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
+    if (process.env.WAYGRAPH_EXTENSIONS)
+        console.error("waygraph traverse: extensions are not loaded (workers use plain contexts)");
     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/ui/components/ring.js

@@ -20,6 +20,7 @@ export function ringCss() {
         "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
         `max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:${p.labelBg};color:${p.labelFg};` +
         "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
+        "#wg-ring-label::after{content:attr(data-label);}" +
         toneRules("#wg-ring-label", (t) => `background:${t.labelBg};color:${t.labelFg};`) +
         // Gray = a real Playwright-driven instruction: mark it with a robot.
         `#wg-ring-label[data-tone=auto]::before{${ROBOT}}` +

package/dist/ui/overlay.css

@@ -86,6 +86,7 @@
   font: 600 12px/1.35 var(--wg-font); transition: opacity .3s ease;
   overflow: hidden; text-overflow: ellipsis; white-space: nowrap; box-shadow: 0 2px 8px rgba(0,0,0,.25);
 }
+#wg-ring-label::after { content: attr(data-label); }
 .wg-ring-el-label[data-tone=planned] { --wg-tone-bg: var(--wg-tone-planned-bg); --wg-tone-fg: var(--wg-tone-planned-fg); }
 .wg-ring-el-label[data-tone=auto]    { --wg-tone-bg: var(--wg-tone-auto-bg);    --wg-tone-fg: var(--wg-tone-auto-fg); }
 .wg-ring-el-label[data-tone=info]    { --wg-tone-bg: var(--wg-tone-info-bg);    --wg-tone-fg: var(--wg-tone-info-fg); }

package/dist/ui/shadow.d.ts

@@ -7,7 +7,7 @@
  * lookups check the shadow root first and fall back to the light DOM (the device stage shell and
  * host-page markers such as `[data-wg-zoomed]` intentionally stay in the light DOM).
  */
-import type { BrowserContext, Page } from "@playwright/test";
+import type { Page } from "@playwright/test";
 /**
  * `overlaySheet` is the ONE real-CSS bundle (`ui/stylesheet.ts` -> `dist/ui/overlay.css`, built on
  * Open Props - see `src/ui/css/README.md`) every surface shares; passed in from Node since in-page
@@ -16,5 +16,3 @@ import type { BrowserContext, Page } from "@playwright/test";
 export declare function installShadowRoot(overlaySheet?: string): void;
 /** Idempotent; call before any overlay install on a page. Installs the shared stylesheet bundle. */
 export declare function ensureShadowRoot(page: Page): Promise<void>;
-/** Also define the helpers on every future document (pilot overlay persists across navigations). */
-export declare function installShadowRootEverywhere(context: BrowserContext): Promise<void>;

package/dist/ui/shadow.js

@@ -44,7 +44,3 @@ export function installShadowRoot(overlaySheet) {
 export async function ensureShadowRoot(page) {
     await page.evaluate(installShadowRoot, getOverlaySheet()).catch(() => { });
 }
-/** Also define the helpers on every future document (pilot overlay persists across navigations). */
-export async function installShadowRootEverywhere(context) {
-    await context.addInitScript(installShadowRoot, getOverlaySheet());
-}

package/dist/ui/tokens.d.ts

@@ -18,14 +18,3 @@ export interface Tone {
 export declare const TONES: Record<ToneName, Tone>;
 /** Dark surface shared by panels, banner, docks, HUD chips. */
 export declare const SURFACE = "rgba(20,10,40,.94)";
-export declare const ACCENT = "#7C3AED";
-/** Secondary accent used on the dark surface (section titles, kinds). */
-export declare const ACCENT_SOFT = "#c9a6ff";
-/** Stacking order: one scale instead of magic numbers. */
-export declare const Z: {
-    readonly top: 2147483647;
-    readonly ring: 2147483646;
-    readonly fx: 2147483645;
-    readonly focus: 2147483644;
-    readonly dock: 2147483000;
-};

package/dist/ui/tokens.js

@@ -14,8 +14,3 @@ export const TONES = {
 };
 /** Dark surface shared by panels, banner, docks, HUD chips. */
 export const SURFACE = "rgba(20,10,40,.94)";
-export const ACCENT = "#7C3AED";
-/** Secondary accent used on the dark surface (section titles, kinds). */
-export const ACCENT_SOFT = "#c9a6ff";
-/** Stacking order: one scale instead of magic numbers. */
-export const Z = { top: 2147483647, ring: 2147483646, fx: 2147483645, focus: 2147483644, dock: 2147483000 };

package/dist/video-dir.d.ts

@@ -0,0 +1,8 @@
+/** The user's Downloads folder, or undefined when there is none (a server, a container). */
+export declare function downloadsDir(): string | undefined;
+/**
+ * Where `--video` recordings go: `WAYGRAPH_VIDEO_DIR`, else `video.dir` from the config (absolute, `~/…`, or relative to
+ * the project), else `<Downloads>/waygraph-videos/<project>`. With no usable Downloads folder, or on CI, it is
+ * `<project>/.waygraph-videos`. An explicit `--video <dir>` never reaches this.
+ */
+export declare function resolveVideoDir(projectDir: string): Promise<string>;

package/dist/video-dir.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { loadWaygraphConfig } from "./config.js";
+/** The user's Downloads folder, or undefined when there is none (a server, a container). */
+export function downloadsDir() {
+    const home = homedir();
+    let dir = process.env.XDG_DOWNLOAD_DIR;
+    if (!dir && process.platform === "linux") {
+        try {
+            const line = readFileSync(join(process.env.XDG_CONFIG_HOME ?? join(home, ".config"), "user-dirs.dirs"), "utf-8")
+                .split("\n")
+                .find((l) => l.startsWith("XDG_DOWNLOAD_DIR="));
+            dir = line?.slice("XDG_DOWNLOAD_DIR=".length).replace(/^"|"$/g, "").replace("$HOME", home);
+        }
+        catch {
+            /* no user-dirs file: use the conventional name */
+        }
+    }
+    dir ??= join(home, "Downloads");
+    return existsSync(dir) ? dir : undefined;
+}
+const expandHome = (p) => (p === "~" || p.startsWith("~/") ? join(homedir(), p.slice(1)) : p);
+/** True if a file can be created in `dir` (macOS asks permission for Downloads the first time; a denial surfaces here). */
+function writable(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const probe = join(dir, `.waygraph-probe-${process.pid}`);
+        writeFileSync(probe, "");
+        rmSync(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `--video` recordings go: `WAYGRAPH_VIDEO_DIR`, else `video.dir` from the config (absolute, `~/…`, or relative to
+ * the project), else `<Downloads>/waygraph-videos/<project>`. With no usable Downloads folder, or on CI, it is
+ * `<project>/.waygraph-videos`. An explicit `--video <dir>` never reaches this.
+ */
+export async function resolveVideoDir(projectDir) {
+    const fallback = join(projectDir, ".waygraph-videos");
+    const configured = process.env.WAYGRAPH_VIDEO_DIR || (await loadWaygraphConfig(projectDir))?.video?.dir;
+    if (configured) {
+        const dir = isAbsolute(expandHome(configured)) ? expandHome(configured) : resolve(projectDir, configured);
+        if (writable(dir))
+            return dir;
+        console.error(`waygraph: cannot write videos to ${dir} - using ${fallback}`);
+        return fallback;
+    }
+    const downloads = process.env.CI ? undefined : downloadsDir();
+    if (!downloads)
+        return fallback;
+    const dir = join(downloads, "waygraph-videos", basename(resolve(projectDir)));
+    if (writable(dir))
+        return dir;
+    console.error(`waygraph: cannot write to ${downloads} (denied?) - saving videos in ${fallback}`);
+    return fallback;
+}

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,95 @@
+// Starts/stops a project's `webServer` (waygraph.config, or a legacy playwright.config) around `waygraph run`/`demo`/`auto`,
+// the same block `waygraph test` already honors.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import { loadWaygraphConfig } from "./config.js";
+const CONFIG_FILES = [
+    "playwright.config.ts",
+    "playwright.config.mts",
+    "playwright.config.mjs",
+    "playwright.config.js",
+    "playwright.config.cjs",
+];
+async function loadWebServerConfigs(projectDir) {
+    const fromWaygraph = (await loadWaygraphConfig(projectDir))?.webServer;
+    if (fromWaygraph)
+        return Array.isArray(fromWaygraph) ? fromWaygraph : [fromWaygraph];
+    for (const name of CONFIG_FILES) {
+        const p = join(projectDir, name);
+        if (!existsSync(p))
+            continue;
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(p).href));
+        }
+        catch (err) {
+            throw new Error(`waygraph: failed to load ${name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const webServer = mod.default?.webServer;
+        if (!webServer)
+            return [];
+        return Array.isArray(webServer) ? webServer : [webServer];
+    }
+    return [];
+}
+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"