waygraph 0.12.8 → 0.12.10

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

@@ -4,6 +4,8 @@ export interface AutoExploreOptions {
     baseURL?: string;
     /** Initial URL when the page is blank (defaults to baseURL). */
     startUrl?: string;
+    /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
 }
 /**
  * Saucedemo-only defaults. Exact key names only — never substring `"login"`

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", () => {
@@ -490,7 +491,11 @@ export async function runAutoExplore(projectDir, options = {}) {
     const cli = options.cli === true;
     const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
     const startUrl = options.startUrl ?? baseURL;
-    const { graph, library } = await buildExploreContext(projectDir);
+    const { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
+    if (options.blocksSelect) {
+        console.error(`waygraph auto: --blocks ${options.blocksSelect.raw} → ` +
+            `${library.byName.size} block(s), ${graph.edges.length} edge(s)`);
+    }
     const mem = new MemPage();
     seedDefaultMem(library.byName, mem);
     const engine = cli ? new Engine({ headless: true }) : new Engine({ headless: false, slowMo: 250 });

package/dist/auto-explore.d.ts

@@ -32,7 +32,9 @@ export interface ExploreMenu {
 /**
  * Import every `*.block.ts` export keyed by runtime Block `.name`.
  */
-export declare function loadBlockLibrary(projectDir: string): Promise<{
+export declare function loadBlockLibrary(projectDir: string, opts?: {
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
+}): Promise<{
     byName: Map<string, BlockEntry>;
     navBlocks: BlockEntry[];
 }>;
@@ -46,7 +48,9 @@ export declare function exploreChoices(graph: WaygraphGraph, here: string | null
 export declare function buildExploreMenu(page: Page, graph: WaygraphGraph, library: {
     byName: Map<string, BlockEntry>;
 }, here: string | null): Promise<ExploreMenu>;
-export declare function buildExploreContext(projectDir: string): Promise<{
+export declare function buildExploreContext(projectDir: string, opts?: {
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
+}): Promise<{
     graph: WaygraphGraph;
     library: Awaited<ReturnType<typeof loadBlockLibrary>>;
 }>;

package/dist/auto-explore.js

@@ -81,11 +81,17 @@ async function wildcardActionRunnable(page, entry, here) {
 /**
  * Import every `*.block.ts` export keyed by runtime Block `.name`.
  */
-export async function loadBlockLibrary(projectDir) {
+export async function loadBlockLibrary(projectDir, opts) {
+    const { matchBlocksSelect } = await import("./blocks-select.js");
     const byName = new Map();
     const navBlocks = [];
+    const select = opts?.blocksSelect;
     for (const file of walkDir(projectDir, /\.block\.ts$/)) {
-        const relFile = relative(projectDir, file);
+        const relFile = relative(projectDir, file).replace(/\\/g, "/");
+        // Glob/bare: path filter before import. Regex: need block name — filter after.
+        if (select && select.kind !== "regex" && !matchBlocksSelect(select, { relFile })) {
+            continue;
+        }
         let mod;
         try {
             mod = await importModule(file);
@@ -100,6 +106,10 @@ export async function loadBlockLibrary(projectDir) {
         for (const [exportName, exported] of Object.entries(mod)) {
             if (!isBlockLike(exported))
                 continue;
+            if (select &&
+                !matchBlocksSelect(select, { relFile, blockName: exported.name })) {
+                continue;
+            }
             const kind = isNavBlockMarked(exported) ? "nav" : "action";
             const entry = {
                 block: exported,
@@ -317,11 +327,11 @@ export async function buildExploreMenu(page, graph, library, here) {
     }
     return { here, sections, flat };
 }
-export async function buildExploreContext(projectDir) {
+export async function buildExploreContext(projectDir, opts) {
     // Sequential: parallel import of the same *.block.ts tree raced Playwright's
     // dual-copy guard in some installs and left graph edges without library entries
     // (LoginPage → "No moves").
-    const library = await loadBlockLibrary(projectDir);
-    const graph = await discoverGraph(projectDir);
+    const library = await loadBlockLibrary(projectDir, opts);
+    const graph = await discoverGraph(projectDir, opts);
     return { graph, library };
 }

package/dist/blocks-select.d.ts

@@ -0,0 +1,22 @@
+export type BlocksSelectKind = "regex" | "glob" | "bare";
+export interface BlocksSelect {
+    kind: BlocksSelectKind;
+    /** Original token. */
+    raw: string;
+    /** For regex: compiled without wrapping slashes. For glob: pattern as given. */
+    pattern: string;
+    re?: RegExp;
+}
+/** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
+export declare function isFileSelectToken(token: string): boolean;
+export declare function parseBlocksSelect(token: string): BlocksSelect;
+/** Glob → RegExp (simple: ** / * / ? only; no brace expansion). */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchBlocksSelect(select: BlocksSelect, opts: {
+    relFile: string;
+    blockName?: string;
+}): boolean;
+export declare function filterByBlocksSelect<T extends {
+    file: string;
+    block?: string;
+}>(items: T[], select: BlocksSelect | undefined, projectDir: string): T[];

package/dist/blocks-select.js

@@ -0,0 +1,85 @@
+/**
+ * Shared `--blocks` select grammar (RFC Phase C).
+ *
+ * - `/pattern/`  -> regex on relative file path OR block name
+ * - has `*`/`**` -> glob on relative file path (POSIX-ish)
+ * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
+ */
+import { relative } from "node:path";
+/** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
+export function isFileSelectToken(token) {
+    if (!token)
+        return false;
+    if (token.length >= 2 && token.startsWith("/") && token.endsWith("/") && token.length > 2) {
+        return true;
+    }
+    return token.includes("*");
+}
+export function parseBlocksSelect(token) {
+    const raw = token.trim();
+    if (raw.length >= 2 && raw.startsWith("/") && raw.endsWith("/")) {
+        const body = raw.slice(1, -1);
+        return { kind: "regex", raw, pattern: body, re: new RegExp(body) };
+    }
+    if (raw.includes("*")) {
+        return { kind: "glob", raw, pattern: raw };
+    }
+    return { kind: "bare", raw, pattern: raw };
+}
+/** Glob → RegExp (simple: ** / * / ? only; no brace expansion). */
+export function globToRegExp(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*" && glob[i + 1] === "*") {
+            out += ".*";
+            i++;
+            if (glob[i + 1] === "/")
+                i++;
+            continue;
+        }
+        if (c === "*") {
+            out += "[^/]*";
+            continue;
+        }
+        if (c === "?") {
+            out += "[^/]";
+            continue;
+        }
+        if (".+^${}()|[]\\".includes(c))
+            out += "\\" + c;
+        else
+            out += c;
+    }
+    return new RegExp("^" + out + "$");
+}
+export function matchBlocksSelect(select, opts) {
+    const file = opts.relFile.replace(/\\/g, "/");
+    const name = opts.blockName ?? "";
+    if (select.kind === "regex") {
+        const re = select.re ?? new RegExp(select.pattern);
+        return re.test(file) || (name !== "" && re.test(name));
+    }
+    if (select.kind === "glob") {
+        return globToRegExp(select.pattern.replace(/\\/g, "/")).test(file);
+    }
+    // bare: match block name equality (case-sensitive) or path substring
+    if (name && name === select.pattern)
+        return true;
+    if (file.includes(select.pattern))
+        return true;
+    return false;
+}
+export function filterByBlocksSelect(items, select, projectDir) {
+    if (!select)
+        return items;
+    return items.filter((it) => {
+        const relFile = it.file.startsWith(projectDir)
+            ? relative(projectDir, it.file)
+            : it.file;
+        return matchBlocksSelect(select, {
+            relFile: relFile.replace(/\\/g, "/"),
+            ...(it.block !== undefined ? { blockName: it.block } : {}),
+        });
+    });
+}

package/dist/cli.js

@@ -21,6 +21,7 @@ import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./gra
 import { runAutoExplore } from "./auto-explore-run.js";
 import { runAgentDive } from "./agent-dive.js";
 import { runTraverse } from "./traverse-run.js";
+import { isFileSelectToken, parseBlocksSelect, } from "./blocks-select.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -396,7 +397,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
@@ -407,7 +412,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
@@ -425,6 +431,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%);" +
@@ -640,26 +647,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;
@@ -691,6 +685,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
@@ -1031,7 +1035,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 =
@@ -1053,7 +1057,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;
@@ -1297,7 +1301,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",
+  }));
 }
 
 /**
@@ -1327,12 +1334,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;
     }
   }
@@ -1395,13 +1402,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(() => {});
 }
@@ -1431,8 +1438,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) {
@@ -1474,7 +1481,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);
       }
@@ -1705,11 +1712,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(() => {});
 }
 
@@ -1783,9 +1790,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) {
@@ -1824,6 +1831,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
@@ -1853,9 +1861,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
@@ -1865,12 +1874,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
@@ -2257,6 +2267,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,
@@ -2329,6 +2340,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           label: formatHighlightCaption(h),
           duration: h.duration,
           fastMode: h.fastMode,
+          tone: "planned",
         }),
       );
     } else {
@@ -3662,7 +3674,8 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
-  waygraph traverse [project]              Serial graph crawl (Phase B)
+  waygraph traverse [project]              Serial graph crawl (Phase B+)
+                 --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
                  --from <Checkpoint>       Seed / start checkpoint
                  --data '{...}'            Mem seed
                  --max-steps N             Cap Block runs (default 50)
@@ -3686,6 +3699,8 @@ Examples:
   waygraph auto src/flows/shop.flow.ts --data '{...}'   # run by file (same as run)
   waygraph auto --cli --data '{"saucedemo.credentials":{...}}'
   waygraph auto --blocks LoginPage OrderComplete
+  waygraph auto --blocks '/mailpit/'                     # Phase C filtered explore
+  waygraph traverse --blocks '**/mailpit/**/*.block.ts'  # Phase C filtered crawl
   waygraph run  --blocks "loginFlow then add-all-to-cart" --data '{...}' --video
 
 Aliases (compat): \`chain <spec>\` -> run --blocks; \`chain auto A B\` -> auto --blocks A B;
@@ -3779,6 +3794,7 @@ async function main() {
             let maxEdge;
             let headed = false;
             let baseUrl;
+            let blocksFilter;
             let projectDir = process.cwd();
             for (let i = 0; i < rest.length; i++) {
                 const a = rest[i];
@@ -3790,6 +3806,20 @@ async function main() {
                     data = a.startsWith("--data=") ? a.slice(7) : rest[++i];
                     continue;
                 }
+                if (a === "--blocks" || a.startsWith("--blocks=")) {
+                    if (a.startsWith("--blocks=")) {
+                        blocksFilter = a.slice("--blocks=".length);
+                    }
+                    else {
+                        const v = rest[++i];
+                        if (!v || v.startsWith("-")) {
+                            console.error("waygraph traverse: --blocks needs a glob, /regex/, or path substring");
+                            process.exit(1);
+                        }
+                        blocksFilter = v;
+                    }
+                    continue;
+                }
                 if (a === "--max-steps" || a.startsWith("--max-steps=")) {
                     const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
                     maxSteps = Number(v);
@@ -3821,6 +3851,7 @@ async function main() {
 Serial graph crawl (RFC Phase B). Walks unused legal edges until a leaf,
 budget kill, or first broken edge.
 
+  --blocks <glob|/regex/|substr>  Phase C: filter *.block.ts discovery
   --from <Checkpoint>     start checkpoint (optional)
   --data '{...}'          Mem seed JSON
   --max-steps N           default 50
@@ -3829,6 +3860,10 @@ budget kill, or first broken edge.
   --non-headless          show browser
   --base-url URL
 
+Examples:
+  waygraph traverse --blocks '**/mailpit/**/*.block.ts'
+  waygraph traverse --blocks '/mailpit|login/'
+
 PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
 FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
 `);
@@ -3842,6 +3877,9 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                 console.error(`waygraph traverse: no such directory: ${projectDir}`);
                 process.exit(1);
             }
+            const blocksSelect = blocksFilter
+                ? parseBlocksSelect(blocksFilter)
+                : undefined;
             const code = await runTraverse(projectDir, {
                 ...(from ? { from } : {}),
                 ...(data ? { data } : {}),
@@ -3854,9 +3892,9 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                     : {}),
                 headed,
                 ...(baseUrl ? { baseURL: baseUrl } : {}),
+                ...(blocksSelect ? { blocksSelect } : {}),
             });
-            process.exitCode = code;
-            break;
+            process.exit(code);
         }
         case "agent-dive":
         case "init-agents": {
@@ -4014,13 +4052,23 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                 process.exit(1);
             }
             // auto --blocks From To  (graph path-find + run)
+            // auto --blocks '/regex/' or '**/*.block.ts'  (Phase C file select → explore)
             if (command === "auto" && (flags.blocksFromTo || flags.blocks)) {
                 if (flags.blocksFromTo) {
                     const [fromTag, toTag] = flags.blocksFromTo;
                     await runChainAuto(proj, fromTag, toTag);
                     break;
                 }
+                if (flags.blocks && isFileSelectToken(flags.blocks)) {
+                    const blocksSelect = parseBlocksSelect(flags.blocks);
+                    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+                    await runAutoExplore(proj, baseURL
+                        ? { cli: cliPicker, baseURL, blocksSelect }
+                        : { cli: cliPicker, blocksSelect });
+                    break;
+                }
                 console.error("waygraph auto --blocks expects <fromCheckpoint> <toCheckpoint>\n" +
+                    "  or file select: --blocks '**/mailpit/**/*.block.ts' / --blocks '/mailpit/'\n" +
                     '  e.g. waygraph auto --blocks LoginPage OrderComplete\n' +
                     '  for a hand-named chain use: waygraph run --blocks "a then b"\n' +
                     "  or: waygraph auto src/flows/shop.flow.ts");

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

@@ -1,3 +1,4 @@
+import { type BlocksSelect } from "./blocks-select.js";
 /**
  * The state-machine shape `waygraph auto` discovers from a project's own
  * Blocks - Checkpoints are nodes, Blocks are edges. Kept as plain data (not
@@ -67,4 +68,6 @@ export declare function findBlockPath(graph: WaygraphGraph, fromTag: string, toT
  * already is for `check`, unlike `chain`, which spawns a child process
  * specifically because it also EXECUTES Blocks, not just imports them.
  */
-export declare function discoverGraph(projectDir: string): Promise<WaygraphGraph>;
+export declare function discoverGraph(projectDir: string, opts?: {
+    blocksSelect?: BlocksSelect;
+}): Promise<WaygraphGraph>;

package/dist/graph.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, dirname, relative, resolve } from "node:path";
+import { matchBlocksSelect, } from "./blocks-select.js";
 /**
  * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
  * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`
@@ -296,8 +297,15 @@ function extractDefineBlockGenerics(src) {
  * already is for `check`, unlike `chain`, which spawns a child process
  * specifically because it also EXECUTES Blocks, not just imports them.
  */
-export async function discoverGraph(projectDir) {
-    const files = discoverBlocks(projectDir);
+export async function discoverGraph(projectDir, opts) {
+    let files = discoverBlocks(projectDir);
+    const select = opts?.blocksSelect;
+    // Glob/bare: drop files early. Regex needs block names — filter per export below.
+    if (select && select.kind !== "regex") {
+        files = files.filter((file) => matchBlocksSelect(select, {
+            relFile: relative(projectDir, file).replace(/\\/g, "/"),
+        }));
+    }
     const nodeTags = new Set();
     const edges = [];
     const skipped = [];
@@ -326,6 +334,13 @@ export async function discoverGraph(projectDir) {
             if (!isBlockLike(exported))
                 continue;
             const blockName = exported.name;
+            if (select &&
+                !matchBlocksSelect(select, {
+                    relFile: relFile.replace(/\\/g, "/"),
+                    blockName,
+                })) {
+                continue;
+            }
             if (isNavBlockMarked(exported)) {
                 try {
                     // NavBlock / PageBlock resolve() ignores input - always checkpoint(tag).

package/dist/index.d.ts

@@ -9,3 +9,5 @@ export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGr
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
+export type { BlocksSelect, BlocksSelectKind } from "./blocks-select.js";

package/dist/index.js

@@ -4,3 +4,4 @@ export { Trait, urlMatches, textEquals, visible } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";

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

@@ -17,6 +17,8 @@ export interface TraverseOptions {
     headed?: boolean;
     /** Traverse id for greppable lines (default traverse-1). */
     traverseId?: string;
+    /** Phase C: glob / regex / bare `--blocks` file select. */
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
 }
 /**
  * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.

package/dist/traverse-run.js

@@ -106,7 +106,11 @@ export async function runTraverse(projectDir, options = {}) {
     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 { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
+    if (options.blocksSelect) {
+        console.error(`waygraph traverse: --blocks ${options.blocksSelect.raw} → ` +
+            `${library.byName.size} block(s), ${graph.edges.length} edge(s)`);
+    }
     const mem = new MemPage();
     seedMem(library.byName, mem, options.data);
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });

package/package.json

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