waygraph 0.12.7 → 0.12.9

package/dist/auto-explore-run.js

@@ -428,6 +428,7 @@ async function headfulPick(page, menu, library, mem, waitPick) {
           window.__wgPositionRing(
             { x: r.x, y: r.y, width: r.width, height: r.height },
             btn.textContent?.trim()?.slice(0, 80) || "target",
+            "auto",
           );
         });
         btn.addEventListener("mouseleave", () => {

package/dist/cli.d.ts

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / agent-dive / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.

package/dist/cli.js

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / agent-dive / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 import { runAutoExplore } from "./auto-explore-run.js";
 import { runAgentDive } from "./agent-dive.js";
+import { runTraverse } from "./traverse-run.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -395,7 +396,11 @@ function seedMemForFlow(mem, flowBlocks, json, label) {
 const RING_CSS =
   "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
   "border:2.5px solid #7C3AED;border-radius:10px;" +
-  "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease;}" +
+  "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease,border-color .15s,box-shadow .15s;}" +
+  // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
+  // Automation (verify fallback, unmatched fill/click) = yellow - so operators
+  // can ignore engine checks and only watch purple narration.
+  "#wg-ring[data-tone=auto]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
   // A real element, not a ::after pseudo-element - a pseudo-element's
   // position is CSS-relative to the ring's own box (left:0 always meant
   // "the ring's own left edge"), so it had no way to be clamped back onto
@@ -406,7 +411,8 @@ const RING_CSS =
   // window.__wgPositionRing in installOverlay.
   "#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:#7C3AED;color:#fff;" +
-  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
+  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease,background .15s,color .15s;}" +
+  "#wg-ring-label[data-tone=auto]{background:#EAB308;color:#1c1917;}" +
   // Mouse cursor icon that travels to a target before it's acted on, plus a
   // quick expanding ripple at the moment of a click - same idea as
   // help-center-clip-engine's #clip-cursor/#clip-ring (video-pipeline). The
@@ -424,6 +430,7 @@ const RING_CSS =
   "#wg-click-pulse{position:fixed;z-index:2147483647;width:14px;height:14px;" +
   "margin-left:-7px;margin-top:-7px;border-radius:50%;pointer-events:none;opacity:0;" +
   "border:2px solid #7C3AED;background:rgba(124,58,237,.25);}" +
+  "#wg-click-pulse[data-tone=auto]{border-color:#EAB308;background:rgba(234,179,8,.28);}" +
   "#wg-click-pulse.wg-pulse{animation:wg-pulse .5s ease-out;}" +
   "@keyframes wg-pulse{0%{opacity:.9;transform:scale(.4);}100%{opacity:0;transform:scale(2.4);}}" +
   "#wg-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
@@ -639,26 +646,13 @@ async function installOverlay(page, title) {
           const cursor = document.getElementById("wg-cursor");
           if (cursor) cursor.style.opacity = "0";
         };
-        window.__wgClickPulse = (x, y) => {
-          const pulse = document.getElementById("wg-click-pulse");
-          if (!pulse) return;
-          pulse.style.left = x + "px";
-          pulse.style.top = y + "px";
-          pulse.classList.remove("wg-pulse");
-          void pulse.offsetWidth;
-          pulse.classList.add("wg-pulse");
-        };
-        // Clamps the ring AND its label to stay fully on-screen, same
-        // width/height always - only the position moves. A target near a
-        // viewport edge (real case: "login success" highlight landing top
-        // right) used to just run the label text off-screen with no guard
-        // at all - same mistake as the banner had before its own
-        // left/center/right positions existed, not repeating it here by
-        // shrinking anything, only repositioning.
-        window.__wgPositionRing = (box, label) => {
+        window.__wgPositionRing = (box, label, tone) => {
           const ring = document.getElementById("wg-ring");
           const ringLabel = document.getElementById("wg-ring-label");
           if (!ring || !ringLabel) return;
+          const t = tone === "auto" ? "auto" : "planned";
+          ring.dataset.tone = t;
+          ringLabel.dataset.tone = t;
           const margin = 6;
           const vw = window.innerWidth;
           const vh = window.innerHeight;
@@ -690,6 +684,16 @@ async function installOverlay(page, title) {
           ringLabel.style.left = labelLeft + "px";
           ringLabel.style.top = labelTop + "px";
         };
+        window.__wgClickPulse = (x, y, tone) => {
+          const pulse = document.getElementById("wg-click-pulse");
+          if (!pulse) return;
+          pulse.dataset.tone = tone === "auto" ? "auto" : "planned";
+          pulse.style.left = x + "px";
+          pulse.style.top = y + "px";
+          pulse.classList.remove("wg-pulse");
+          void pulse.offsetWidth;
+          pulse.classList.add("wg-pulse");
+        };
         window.__wgHideRing = () => {
           // While a narrate() call owns the ring (mid multi-step action),
           // the auto-highlight click/fill patches' own end-of-step hide is
@@ -1030,7 +1034,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
     try {
       const box = await page.locator(h.selector).first().boundingBox();
       if (box) {
-        await showRing(page, box, h.label);
+        await showRing(page, box, h.label, h.tone || "planned");
         const authored = resolveFixtureDwellMs(h, { gatesFast });
         const legacyMs = i === list.length - 1 ? 200 : 900;
         const holdMs =
@@ -1052,7 +1056,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
             if (window.__wgHideRing) window.__wgHideRing();
             return;
           }
-          window.__wgPositionRing(el.getBoundingClientRect(), h.label);
+          window.__wgPositionRing(el.getBoundingClientRect(), h.label, h.tone || "planned");
         };
         reposition();
         window.__wgRingTrack = reposition;
@@ -1296,7 +1300,10 @@ function resolveDeclaredHighlights(block, resultTag) {
     }
   }
   if (!Array.isArray(highlights)) return [];
-  return highlights.filter((h) => h && typeof h.selector === "string" && typeof h.label === "string");
+  return highlights.filter((h) => h && typeof h.selector === "string" && typeof h.label === "string").map((h) => ({
+    ...h,
+    tone: h.tone === "auto" ? "auto" : "planned",
+  }));
 }
 
 /**
@@ -1326,12 +1333,12 @@ function extractVerifyHighlights(block, resultTag) {
     if (typeof name !== "string") continue;
     let m = /^visible\\((.+)\\)$/.exec(name);
     if (m) {
-      highlights.push({ selector: m[1], label: name });
+      highlights.push({ selector: m[1], label: name, tone: "auto" });
       continue;
     }
     m = /^text-equals\\((.+?),\\s*"/.exec(name);
     if (m) {
-      highlights.push({ selector: m[1], label: name });
+      highlights.push({ selector: m[1], label: name, tone: "auto" });
       continue;
     }
   }
@@ -1394,13 +1401,13 @@ async function markStepRunning(page, _opts) {
     .catch(() => {});
 }
 
-async function showRing(page, box, label) {
+async function showRing(page, box, label, tone) {
   await page
     .evaluate(
-      ({ box, label }) => {
-        if (window.__wgPositionRing) window.__wgPositionRing(box, label);
+      ({ box, label, tone }) => {
+        if (window.__wgPositionRing) window.__wgPositionRing(box, label, tone || "planned");
       },
-      { box, label },
+      { box, label, tone: tone || "planned" },
     )
     .catch(() => {});
 }
@@ -1430,8 +1437,8 @@ async function matchStubForLocator(page, locator, stubs) {
 
 async function captionForLocator(page, locator, stubs, fallback) {
   const matched = await matchStubForLocator(page, locator, stubs);
-  if (matched) return formatHighlightCaption(matched);
-  return fallback;
+  if (matched) return { label: formatHighlightCaption(matched), tone: "planned" };
+  return { label: fallback, tone: "auto" };
 }
 
 async function dwellMatchedStub(page, locator, stubs, pacing) {
@@ -1473,7 +1480,7 @@ async function presentSlides(page, slides, _gate, opts) {
     if (s.selector) {
       try {
         const box = await page.locator(s.selector).first().boundingBox();
-        if (box) await showRing(page, box, caption);
+        if (box) await showRing(page, box, caption, "planned");
       } catch {
         await hideRing(page);
       }
@@ -1704,11 +1711,11 @@ async function moveCursorTo(page, box, ms) {
   return { x, y };
 }
 
-async function clickPulseAt(page, x, y) {
+async function clickPulseAt(page, x, y, tone) {
   await page
-    .evaluate(({ x, y }) => {
-      if (window.__wgClickPulse) window.__wgClickPulse(x, y);
-    }, { x, y })
+    .evaluate(({ x, y, tone }) => {
+      if (window.__wgClickPulse) window.__wgClickPulse(x, y, tone || "planned");
+    }, { x, y, tone: tone || "planned" })
     .catch(() => {});
 }
 
@@ -1782,9 +1789,9 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
             ? "from mem: " + memTrack.lastKeyName
             : "writing from mem";
           const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
-          const label = await captionForLocator(page, this, stubs, fallback);
+          const cap = await captionForLocator(page, this, stubs, fallback);
           await moveCursorTo(page, box, cursorMs(500));
-          await showRing(page, box, label);
+          await showRing(page, box, cap.label, cap.tone);
           await dwellMatchedStub(page, this, stubs, pacing);
           await new Promise((res) => setTimeout(res, skipTheater() ? 0 : 200));
         } else if (box) {
@@ -1823,6 +1830,7 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
     const originalClick = proto.click;
     proto.click = async function (options) {
       let clickPoint = null;
+      let clickTone = "auto";
       try {
         await installOverlay(page);
         // Wait until the target is visible BEFORE measuring - otherwise
@@ -1852,9 +1860,10 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
             /* ignore */
           }
           const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
-          const label = await captionForLocator(page, this, stubs, fallback);
+          const cap = await captionForLocator(page, this, stubs, fallback);
+          clickTone = cap.tone;
           clickPoint = await moveCursorTo(page, box, cursorMs(600));
-          await showRing(page, box, label);
+          await showRing(page, box, cap.label, cap.tone);
           await dwellMatchedStub(page, this, stubs, pacing);
           // "pop for a few seconds" - Dan's own phrase, matching the
           // zsign demo-engine's ring-before-click pattern in
@@ -1864,12 +1873,13 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
           // Ring/caption already handled by narrate() - still move the
           // cursor + pulse the click point, just skip re-showing the ring.
           clickPoint = await moveCursorTo(page, box, cursorMs(200));
+          clickTone = "planned";
         }
       } catch {
         // best-effort - the real click below still runs either way
       }
       if (clickPoint) {
-        await clickPulseAt(page, clickPoint.x, clickPoint.y);
+        await clickPulseAt(page, clickPoint.x, clickPoint.y, clickTone);
         // clickPulseAt only triggers the CSS animation class - it doesn't
         // wait for it. Without a pause here, the real click (and any
         // resulting navigation/DOM change) fires while the ripple is still
@@ -2256,6 +2266,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           label: formatHighlightCaption(h),
           duration: h.duration,
           fastMode: h.fastMode,
+          tone: "planned",
         }));
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
           defaultHoldMs: 2000,
@@ -2328,6 +2339,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           label: formatHighlightCaption(h),
           duration: h.duration,
           fastMode: h.fastMode,
+          tone: "planned",
         }),
       );
     } else {
@@ -3661,6 +3673,12 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
+  waygraph traverse [project]              Serial graph crawl (Phase B)
+                 --from <Checkpoint>       Seed / start checkpoint
+                 --data '{...}'            Mem seed
+                 --max-steps N             Cap Block runs (default 50)
+                 --max-visits N            Cap visits per node (default 2)
+                 --non-headless            Show browser
   waygraph agent-dive [--loop claude|opencode|cursor|vscode] [--prompts]
                  Initialize coding-agent defs (Playwright init-agents analogue)
   waygraph try [demo|auto|auto:cli]        One-shot saucedemo in a temp dir
@@ -3759,6 +3777,97 @@ async function main() {
             initCommand(args[1] ?? "");
             break;
         }
+        case "traverse": {
+            if (args.includes("--step") || args.includes("--auto-next") || args.includes("--autoplay")) {
+                console.error("waygraph traverse: --step / --auto-next not supported (not a demo)");
+                process.exit(1);
+            }
+            const rest = args.slice(1);
+            let from;
+            let data;
+            let maxSteps;
+            let maxVisits;
+            let maxEdge;
+            let headed = false;
+            let baseUrl;
+            let projectDir = process.cwd();
+            for (let i = 0; i < rest.length; i++) {
+                const a = rest[i];
+                if (a === "--from" || a.startsWith("--from=")) {
+                    from = a.startsWith("--from=") ? a.slice(7) : rest[++i];
+                    continue;
+                }
+                if (a === "--data" || a.startsWith("--data=")) {
+                    data = a.startsWith("--data=") ? a.slice(7) : rest[++i];
+                    continue;
+                }
+                if (a === "--max-steps" || a.startsWith("--max-steps=")) {
+                    const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
+                    maxSteps = Number(v);
+                    continue;
+                }
+                if (a === "--max-visits" || a.startsWith("--max-visits=")) {
+                    const v = a.startsWith("--max-visits=") ? a.slice(13) : rest[++i];
+                    maxVisits = Number(v);
+                    continue;
+                }
+                if (a === "--max-visits-per-edge" || a.startsWith("--max-visits-per-edge=")) {
+                    const v = a.startsWith("--max-visits-per-edge=")
+                        ? a.slice("--max-visits-per-edge=".length)
+                        : rest[++i];
+                    maxEdge = Number(v);
+                    continue;
+                }
+                if (a === "--non-headless" || a === "--headed") {
+                    headed = true;
+                    continue;
+                }
+                if (a === "--base-url" || a.startsWith("--base-url=")) {
+                    baseUrl = a.startsWith("--base-url=") ? a.slice(11) : rest[++i];
+                    continue;
+                }
+                if (a === "--help" || a === "-h") {
+                    console.log(`waygraph traverse [project] [flags]
+
+Serial graph crawl (RFC Phase B). Walks unused legal edges until a leaf,
+budget kill, or first broken edge.
+
+  --from <Checkpoint>     start checkpoint (optional)
+  --data '{...}'          Mem seed JSON
+  --max-steps N           default 50
+  --max-visits N          per-node visit cap (default 2)
+  --max-visits-per-edge N default 1
+  --non-headless          show browser
+  --base-url URL
+
+PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
+FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
+`);
+                    process.exit(0);
+                }
+                if (!a.startsWith("-")) {
+                    projectDir = resolve(a);
+                }
+            }
+            if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
+                console.error(`waygraph traverse: no such directory: ${projectDir}`);
+                process.exit(1);
+            }
+            const code = await runTraverse(projectDir, {
+                ...(from ? { from } : {}),
+                ...(data ? { data } : {}),
+                ...(maxSteps !== undefined && Number.isFinite(maxSteps) ? { maxSteps } : {}),
+                ...(maxVisits !== undefined && Number.isFinite(maxVisits)
+                    ? { maxVisitsPerNode: maxVisits }
+                    : {}),
+                ...(maxEdge !== undefined && Number.isFinite(maxEdge)
+                    ? { maxVisitsPerEdge: maxEdge }
+                    : {}),
+                headed,
+                ...(baseUrl ? { baseURL: baseUrl } : {}),
+            });
+            process.exit(code);
+        }
         case "agent-dive":
         case "init-agents": {
             // Playwright analogue: npx playwright init-agents --loop <provider>

package/dist/engine.d.ts

@@ -467,6 +467,48 @@ export declare class Engine {
         Block<H, I>,
         EndMarker
     ]): Flow<I>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        Block<H, I>,
+        Block<I, J>,
+        EndMarker
+    ]): Flow<J>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        Block<H, I>,
+        Block<I, J>,
+        Block<J, K>,
+        EndMarker
+    ]): Flow<K>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        Block<H, I>,
+        Block<I, J>,
+        Block<J, K>,
+        Block<K, L>,
+        EndMarker
+    ]): Flow<L>;
 }
 /**
  * Attaches routing to `block` without touching its act/observe/resolve/verify -

package/dist/engine.js

@@ -139,7 +139,7 @@ export async function narrate(locator, caption, action) {
                 .evaluate(({ box, caption }) => {
                 const w = globalThis;
                 if (w.__wgPositionRing)
-                    w.__wgPositionRing(box, caption);
+                    w.__wgPositionRing(box, caption, "planned");
                 // The CLI's own automatic per-fill/per-click narration checks
                 // this before showing (and overwriting) its own guess - an
                 // explicitly authored caption should win, not get immediately

package/dist/step-overlay.d.ts

@@ -3,18 +3,18 @@ import type { MemPage } from "./mem-page.js";
 export declare function installDemoChrome(page: Page, title?: string, options?: {
     banner?: boolean;
 }): Promise<void>;
-/** Demo cursor + ring on fill/click during auto explore headful runs. */
+/** Demo cursor + ring on fill/click during auto explore headful runs (automation = yellow). */
 export declare function instrumentInteractionHighlighting(page: Page, mem: MemPage, slowMo: number): void;
 declare global {
     interface Window {
         __wgMoveCursorTo?: (x: number, y: number, ms?: number) => void;
-        __wgClickPulse?: (x: number, y: number) => void;
+        __wgClickPulse?: (x: number, y: number, tone?: string) => void;
         __wgPositionRing?: (box: {
             x: number;
             y: number;
             width: number;
             height: number;
-        }, label: string) => void;
+        }, label: string, tone?: string) => void;
         __wgHideRing?: () => void;
         __wgPendingNavClickLabel?: string;
         __wgWirePanelChrome?: (panel: HTMLElement, storageKey: string, chromeTitle?: string) => void;

package/dist/step-overlay.js

@@ -1,8 +1,11 @@
 const RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
-    "border:2.5px solid #7C3AED;border-radius:10px;box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease;}" +
+    "border:2.5px solid #7C3AED;border-radius:10px;box-shadow:0 0 0 4px rgba(124,58,237,.16);" +
+    "transition:opacity .3s ease,border-color .15s,box-shadow .15s;}" +
+    "#wg-ring[data-tone=auto]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
     "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
     "white-space:nowrap;padding:4px 9px;border-radius:7px;background:#7C3AED;color:#fff;" +
-    "font:600 12px/1.2 system-ui,sans-serif;transition:opacity .3s ease;}" +
+    "font:600 12px/1.2 system-ui,sans-serif;transition:opacity .3s ease,background .15s,color .15s;}" +
+    "#wg-ring-label[data-tone=auto]{background:#EAB308;color:#1c1917;}" +
     "#wg-cursor{position:fixed;z-index:2147483647;width:24px;height:24px;pointer-events:none;" +
     "left:0;top:0;opacity:0;margin:0;" +
     "transition:transform var(--wg-cursor-ms,600ms) cubic-bezier(.22,1,.36,1),opacity .2s ease;" +
@@ -10,6 +13,7 @@ const RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none
     "#wg-click-pulse{position:fixed;z-index:2147483647;width:14px;height:14px;" +
     "margin-left:-7px;margin-top:-7px;border-radius:50%;pointer-events:none;opacity:0;" +
     "border:2px solid #7C3AED;background:rgba(124,58,237,.25);}" +
+    "#wg-click-pulse[data-tone=auto]{border-color:#EAB308;background:rgba(234,179,8,.28);}" +
     "#wg-click-pulse.wg-pulse{animation:wg-pulse .5s ease-out;}" +
     "@keyframes wg-pulse{0%{opacity:.9;transform:scale(.4);}100%{opacity:0;transform:scale(2.4);}}" +
     "#wg-banner{position:fixed;z-index:2147483647;top:14px;left:14px;" +
@@ -24,7 +28,7 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
     const showBanner = options.banner !== false;
     await page.addStyleTag({ content: RING_CSS }).catch(() => { });
     await page
-        .evaluate(({ title, favicon }) => {
+        .evaluate(({ title, favicon, showBanner }) => {
         if (!document.getElementById("wg-ring")) {
             const ring = document.createElement("div");
             ring.id = "wg-ring";
@@ -57,21 +61,25 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             cursor.style.transform = "translate(" + x + "px," + y + "px)";
             cursor.style.opacity = "1";
         };
-        window.__wgClickPulse = (x, y) => {
+        window.__wgClickPulse = (x, y, tone) => {
             const pulse = document.getElementById("wg-click-pulse");
             if (!pulse)
                 return;
+            pulse.dataset.tone = tone === "auto" ? "auto" : "planned";
             pulse.style.left = x + "px";
             pulse.style.top = y + "px";
             pulse.classList.remove("wg-pulse");
             void pulse.offsetWidth;
             pulse.classList.add("wg-pulse");
         };
-        window.__wgPositionRing = (box, label) => {
+        window.__wgPositionRing = (box, label, tone) => {
             const ring = document.getElementById("wg-ring");
             const ringLabel = document.getElementById("wg-ring-label");
             if (!ring || !ringLabel)
                 return;
+            const t = tone === "auto" ? "auto" : "planned";
+            ring.dataset.tone = t;
+            ringLabel.dataset.tone = t;
             ring.style.left = box.x - 6 + "px";
             ring.style.top = box.y - 6 + "px";
             ring.style.width = box.width + 12 + "px";
@@ -111,16 +119,24 @@ async function moveCursorTo(page, box, ms) {
         await new Promise((r) => setTimeout(r, ms));
     return { x, y };
 }
-async function showRing(page, box, label) {
-    await page.evaluate(({ box, label }) => window.__wgPositionRing?.(box, label), { box, label }).catch(() => { });
+async function showRing(page, box, label, tone = "auto") {
+    await page
+        .evaluate(({ box, label, tone }) => window.__wgPositionRing?.(box, label, tone), {
+        box,
+        label,
+        tone,
+    })
+        .catch(() => { });
 }
 async function hideRing(page) {
     await page.evaluate(() => window.__wgHideRing?.()).catch(() => { });
 }
-async function clickPulseAt(page, x, y) {
-    await page.evaluate(({ x, y }) => window.__wgClickPulse?.(x, y), { x, y }).catch(() => { });
+async function clickPulseAt(page, x, y, tone = "auto") {
+    await page
+        .evaluate(({ x, y, tone }) => window.__wgClickPulse?.(x, y, tone), { x, y, tone })
+        .catch(() => { });
 }
-/** Demo cursor + ring on fill/click during auto explore headful runs. */
+/** Demo cursor + ring on fill/click during auto explore headful runs (automation = yellow). */
 export function instrumentInteractionHighlighting(page, mem, slowMo) {
     const typeDelay = () => (slowMo ? 0 : 30);
     const clickPrePop = () => (slowMo ? 300 : 700);
@@ -133,89 +149,81 @@ export function instrumentInteractionHighlighting(page, mem, slowMo) {
         memTrack.at = Date.now();
         return originalGet(key);
     };
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const proto = Object.getPrototypeOf(page.locator("html"));
     if (!proto.__wgFillPatched) {
         proto.__wgFillPatched = true;
-        // Keep unbound — originalFill.call(this, …) must receive the Locator as `this`, not the prototype.
         const originalFill = proto.fill;
         proto.fill = async function (value, options) {
-            const livePage = (typeof this.page === "function" ? this.page() : page);
             try {
-                await installDemoChrome(livePage);
+                await installDemoChrome(page, "", { banner: false });
                 const box = await this.boundingBox();
                 if (box) {
                     const label = memTrack.lastKeyName && Date.now() - memTrack.at < 3000
                         ? "from mem: " + memTrack.lastKeyName
-                        : "writing";
-                    await moveCursorTo(livePage, box, cursorMs(500));
-                    await showRing(livePage, box, label);
-                    await new Promise((r) => setTimeout(r, 200));
+                        : "writing from mem";
+                    await moveCursorTo(page, box, cursorMs(500));
+                    await showRing(page, box, label, "auto");
+                    await new Promise((res) => setTimeout(res, 200));
                 }
             }
             catch {
                 /* best-effort */
             }
-            // Prefer a single fill - clear+pressSequentially can hang when the auto
-            // panel steals focus mid-type (looks stuck on "Running: submit-login").
-            if (slowMo || typeDelay() === 0) {
-                await originalFill.call(this, value, options);
+            let result;
+            try {
+                await originalFill.call(this, "", {
+                    timeout: options?.timeout,
+                });
+                const seqOpts = { delay: typeDelay() };
+                const to = options?.timeout;
+                if (to !== undefined)
+                    seqOpts.timeout = to;
+                result = await this.pressSequentially(String(value), seqOpts);
             }
-            else {
-                try {
-                    await originalFill.call(this, "", options);
-                    const seqOpts = { delay: typeDelay() };
-                    if (options?.timeout !== undefined)
-                        seqOpts.timeout = options.timeout;
-                    await this.pressSequentially(String(value), seqOpts);
-                }
-                catch {
-                    await originalFill.call(this, value, options);
-                }
+            catch {
+                result = await originalFill.call(this, value, options);
             }
-            await hideRing(livePage);
+            await hideRing(page);
+            return result;
         };
     }
     if (!proto.__wgClickPatched) {
         proto.__wgClickPatched = true;
         const originalClick = proto.click;
         proto.click = async function (options) {
-            const livePage = (typeof this.page === "function" ? this.page() : page);
             let clickPoint = null;
             try {
-                await installDemoChrome(livePage);
-                await this.waitFor({ state: "visible", timeout: options?.timeout ?? 15000 }).catch(() => { });
+                await installDemoChrome(page, "", { banner: false });
+                await this.waitFor({
+                    state: "visible",
+                    timeout: options?.timeout || 30000,
+                }).catch(() => { });
                 const box = await this.boundingBox();
                 if (box) {
                     let label = "click";
                     try {
-                        const navLabel = await livePage.evaluate(() => window.__wgPendingNavClickLabel ?? null);
-                        if (navLabel)
-                            label = String(navLabel);
-                        else {
-                            const text = (await this.textContent())?.trim();
-                            if (text && text.length <= 30)
-                                label = text;
-                        }
+                        const text = (await this.textContent())?.trim();
+                        if (text && text.length > 0 && text.length <= 30)
+                            label = text;
                     }
                     catch {
                         /* ignore */
                     }
-                    clickPoint = await moveCursorTo(livePage, box, cursorMs(600));
-                    await showRing(livePage, box, label);
-                    await new Promise((r) => setTimeout(r, clickPrePop()));
+                    clickPoint = await moveCursorTo(page, box, cursorMs(600));
+                    await showRing(page, box, label, "auto");
+                    await new Promise((res) => setTimeout(res, clickPrePop()));
                 }
             }
             catch {
                 /* best-effort */
             }
             if (clickPoint) {
-                await clickPulseAt(livePage, clickPoint.x, clickPoint.y);
-                await new Promise((r) => setTimeout(r, 200));
+                await clickPulseAt(page, clickPoint.x, clickPoint.y, "auto");
+                await new Promise((res) => setTimeout(res, 80));
             }
             const result = await originalClick.call(this, options);
-            await new Promise((r) => setTimeout(r, clickPostPop()));
-            await hideRing(livePage).catch(() => { });
+            await new Promise((res) => setTimeout(res, clickPostPop()));
+            await hideRing(page);
             return result;
         };
     }

package/dist/traverse-run.d.ts

@@ -0,0 +1,24 @@
+export interface TraverseOptions {
+    baseURL?: string;
+    startUrl?: string;
+    /** Seed checkpoint label (optional - otherwise detect from page / nav). */
+    from?: string;
+    /** Global Mem seed JSON (or use WAYGRAPH_DATA / WAYGRAPH_AUTO_MEM). */
+    data?: string;
+    /** Max Block runs this traverse (default 50). */
+    maxSteps?: number;
+    /** Max times a checkpoint may be visited (default 2). */
+    maxVisitsPerNode?: number;
+    /** Max times an edge key (block::instanceId) may be taken (default 1). */
+    maxVisitsPerEdge?: number;
+    /** Wall-clock budget ms (default 15m). */
+    timeoutMs?: number;
+    /** Show browser (default headless). */
+    headed?: boolean;
+    /** Traverse id for greppable lines (default traverse-1). */
+    traverseId?: string;
+}
+/**
+ * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ */
+export declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;

package/dist/traverse-run.js

@@ -0,0 +1,227 @@
+/**
+ * Phase B: serial graph traverse (RFC traverse-ffcompose).
+ * Walk unused legal edges until leaf / budget / break. No parallel yet.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { Engine, start, end, locate } from "./engine.js";
+import { MemPage } from "./mem-page.js";
+import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
+import { defaultMemValueForKey } from "./auto-explore-run.js";
+function resolveBaseUrl(projectDir) {
+    if (process.env.WAYGRAPH_BASE_URL)
+        return process.env.WAYGRAPH_BASE_URL;
+    const pkgPath = join(projectDir, "package.json");
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.waygraph?.baseUrl;
+    }
+    catch {
+        return undefined;
+    }
+}
+function seedMem(library, mem, dataJson) {
+    const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
+    let envParsed = {};
+    if (raw) {
+        try {
+            envParsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`waygraph traverse: --data / WAYGRAPH_DATA is not valid JSON`);
+        }
+    }
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k))
+                continue;
+            if (k.name in envParsed) {
+                mem.set(k, envParsed[k.name]);
+                continue;
+            }
+            const def = defaultMemValueForKey(k.name);
+            if (def !== undefined)
+                mem.set(k, def);
+        }
+    }
+}
+function missingMemKeys(entry, mem) {
+    return (entry.block.requires ?? []).filter((k) => !mem.has(k));
+}
+function ensureMem(entry, mem) {
+    const missing = missingMemKeys(entry, mem);
+    if (missing.length === 0)
+        return;
+    throw new Error(`Block "${entry.block.name}" needs Mem keys: ${missing.map((k) => k.name).join(", ")} ` +
+        `(pass --data '{...}' or WAYGRAPH_DATA)`);
+}
+function edgeKey(edge) {
+    const id = edge.instanceOption?.id;
+    return id ? `${edge.block}::${id}` : edge.block;
+}
+async function detectHere(page, navBlocks) {
+    try {
+        const url = page.url();
+        if (url.includes("/login"))
+            return "PiaLogin";
+        if (url.includes("mailpit") || url.includes(":54324") || url.includes("/mailhog")) {
+            return "PiaMailpitGui";
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    const tags = navBlocks.map((n) => n.block);
+    return locate(page, tags, { timeoutMs: 1500 });
+}
+async function runOneBlock(engine, entry, context, page, mem) {
+    const flow = engine.defineFlow([start, entry.block, end]);
+    const BLOCK_TIMEOUT_MS = 45_000;
+    let timer;
+    try {
+        const ran = await Promise.race([
+            flow.run(context, mem, { page, closeOnFinish: false }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s`)), BLOCK_TIMEOUT_MS);
+            }),
+        ]);
+        return ran.result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ */
+export async function runTraverse(projectDir, options = {}) {
+    const traverseId = options.traverseId ?? "traverse-1";
+    const maxSteps = options.maxSteps ?? 50;
+    const maxVisitsPerNode = options.maxVisitsPerNode ?? 2;
+    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 startUrl = options.startUrl ?? baseURL;
+    const { graph, library } = await buildExploreContext(projectDir);
+    const mem = new MemPage();
+    seedMem(library.byName, mem, options.data);
+    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 launchOpts = {
+        headless: !headed,
+    };
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    const browser = await chromium.launch(launchOpts);
+    const contextOpts = {
+        viewport: { width: 1280, height: 720 },
+    };
+    if (baseURL)
+        contextOpts.baseURL = baseURL;
+    const context = await browser.newContext(contextOpts);
+    let page = await context.newPage();
+    const nodeVisits = new Map();
+    const edgeVisits = new Map();
+    const edgesHit = new Set();
+    let steps = 0;
+    const startedAt = Date.now();
+    let lastHere = options.from ?? null;
+    let exitCode = 0;
+    console.error(`waygraph traverse[${traverseId}]: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
+        (baseURL ? ` base=${baseURL}` : "") +
+        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}`);
+    try {
+        if (startUrl) {
+            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+            await page.waitForLoadState("load").catch(() => { });
+        }
+        for (;;) {
+            if (Date.now() - startedAt > timeoutMs) {
+                console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
+                exitCode = 1;
+                break;
+            }
+            if (steps >= maxSteps) {
+                console.log(`[Killed max-steps[${traverseId}] node=${lastHere ?? "?"} steps=${steps} max=${maxSteps}]`);
+                exitCode = 1;
+                break;
+            }
+            if (page.isClosed()) {
+                page = await context.newPage();
+                if (startUrl) {
+                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+                }
+            }
+            const detected = await detectHere(page, library.navBlocks);
+            const here = lastHere ?? detected ?? options.from ?? null;
+            if (here && (nodeVisits.get(here) ?? 0) >= maxVisitsPerNode) {
+                console.log(`[Killed loop[${traverseId}] node=${here} visits=${nodeVisits.get(here)} max=${maxVisitsPerNode}]`);
+                exitCode = 1;
+                break;
+            }
+            const menu = await buildExploreMenu(page, graph, library, here);
+            const candidates = menu.flat.filter((edge) => {
+                const key = edgeKey(edge);
+                return (edgeVisits.get(key) ?? 0) < maxVisitsPerEdge;
+            });
+            if (candidates.length === 0) {
+                const label = here ?? detected ?? "unknown";
+                console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
+                console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
+                break;
+            }
+            const pick = [...candidates].sort((a, b) => {
+                const aWild = a.from === "*" ? 1 : 0;
+                const bWild = b.from === "*" ? 1 : 0;
+                if (aWild !== bWild)
+                    return aWild - bWild;
+                return edgeKey(a).localeCompare(edgeKey(b));
+            })[0];
+            const entry = library.byName.get(pick.block);
+            if (!entry) {
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${here ?? "?"} to=${pick.to} reason=not-loaded]`);
+                exitCode = 1;
+                break;
+            }
+            const fromLabel = here ?? pick.from;
+            try {
+                if (pick.instanceOption) {
+                    mem.set(pick.instanceOption.key, pick.instanceOption.value);
+                }
+                ensureMem(entry, mem);
+                console.error(`waygraph traverse[${traverseId}]: step ${steps + 1} ${fromLabel} -[${pick.block}]-> ${pick.to}` +
+                    (pick.label ? ` (${pick.label})` : ""));
+                const out = await runOneBlock(engine, entry, context, page, mem);
+                const observed = typeof out === "object" && out && "__state" in out
+                    ? String(out.__state)
+                    : pick.to;
+                const key = edgeKey(pick);
+                edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
+                edgesHit.add(key);
+                if (here)
+                    nodeVisits.set(here, (nodeVisits.get(here) ?? 0) + 1);
+                lastHere = observed;
+                steps += 1;
+                if (observed !== pick.to && pick.to !== "*") {
+                    console.error(`waygraph traverse[${traverseId}]: WARN static to=${pick.to} observed=${observed}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${fromLabel} to=${pick.to}] ${msg}`);
+                exitCode = 1;
+                break;
+            }
+        }
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
+    return exitCode;
+}

package/package.json

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