waygraph 0.12.9 → 0.12.11

package/README.md

@@ -215,11 +215,13 @@ overridable, not one giant Block with no per-step confirmation. `composedBlock.w
 `modStepVerify` patch one step from outside, addressed the same three ways
 `withBlockVerify`/`modBlockVerify` already are - a `composeBlock` result is a plain Block,
 so it drops straight into `defineFlow([start, ..., composed, ..., end])` like any other.
-`fastForwardComposeBlock(name, steps)` is the same shape marked for **demo pacing**: one
-opaque step (no per-inner gate) unless `waygraph demo --ff-expand`. Saucedemo
-`checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays expanded for
-Sign In narration. Traverse (later) reuses FF as a seed prefix - see
-`docs/proposals/traverse-ffcompose-rfc.md`.
+`fastForwardComposeBlock(name, steps)` is the same shape marked for **wall-clock
+fast-forward**: one opaque demo step that **blitzes** (no per-inner gate, no smooth
+cursor theater, Playwright slowMo off for that flow unless `WAYGRAPH_SLOWMO` is set)
+unless `waygraph demo --ff-expand`. Put **several** FF units in one Flow when you need
+to race past auth, then a heavy dashboard settle, then watch the interesting middle.
+Saucedemo `checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays
+expanded for Sign In narration. See `docs/proposals/traverse-ffcompose-rfc.md`.
 `spawnTab(entry, page, mem)` drives a genuinely separate second tab through its own
 Block/Flow, in the same browser context an existing `page` already belongs to - the
 pattern `observe()` could already reach for (it's the only phase allowed to touch

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

@@ -491,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
 // ---------------------------------------------------------------------------
@@ -1744,10 +1745,10 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
   // seconds. When slowMo is already doing the pacing, add none of our own;
   // only fall back to a small typing delay when slowMo is off entirely.
   //
-  // pacing.skipTheater (WAYGRAPH_FAST_BLOCKS only): near-zero cursor / pop /
-  // typing - blow past this block. --fast sets pacing.gatesFast instead
-  // and must NOT land here, or demo looks like plain waygraph run.
-  // stubBeforeRef.current = resolved stubBefore slots for the active block.
+  // pacing.skipTheater (WAYGRAPH_FAST_BLOCKS **or** FFCompose): near-zero
+  // cursor / pop / typing - blitz this step. --fast alone sets gatesFast only
+  // (shorter Next/autoplay gates) and must NOT skip theater, or the whole demo
+  // looks like plain waygraph run.
   const skipTheater = () => !!pacing.skipTheater;
   const typeDelay = () => (skipTheater() ? 0 : slowMo ? 0 : 30);
   // Click is a single action, not per-character, so it doesn't compound
@@ -1756,7 +1757,8 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
   // rather than stacking a full 1.2s on top of that.
   const clickPrePop = () => (skipTheater() ? 0 : slowMo ? 300 : 700);
   const clickPostPop = () => (skipTheater() ? 0 : slowMo ? 200 : 500);
-  const cursorMs = (full) => (skipTheater() ? Math.min(120, full) : full);
+  // FF / FAST_BLOCKS: no cursor travel animation (0). Plain theater keeps full.
+  const cursorMs = (full) => (skipTheater() ? 0 : full);
   // Locator.fill()/click() only ever see a raw call, no context of where
   // the value came from. Patching mem.get() to remember the most recently
   // read key's name (Blocks read-then-immediately-fill, e.g. const { email
@@ -1983,14 +1985,15 @@ async function resetPageState(context, page, baseURL) {
 async function runStepMode(engine, start, end, context, page, mem, resolved, slowMo, title, fastBlockNames, clearSession, baseURL) {
   // A shared, mutable pacing knob the interaction patches read live (per
   // call, not once at setup) - flipped per-block below so one block (e.g.
-  // WAYGRAPH_FAST_BLOCKS=login) can run through with none of the overlay's
-  // own added dwell while the rest of the chain keeps the full theatrical
-  // pace. Playwright's own slowMo is process-wide and untouched by this -
-  // only OUR added pauses (ring pop, cursor travel, typing delay) shrink
-  // when skipTheater is on.
+  // WAYGRAPH_FAST_BLOCKS=login or an FFCompose unit) can run through with
+  // none of the overlay's own added dwell while the rest of the chain keeps
+  // the full theatrical pace.
   // --fast / WAYGRAPH_DEMO_FAST: shorter auto-next / Next gates ONLY -
   // keeps smooth cursor travel (not akin to waygraph run).
-  // WAYGRAPH_FAST_BLOCKS: named blocks still skip theater (old blow-past).
+  // FFCompose + WAYGRAPH_FAST_BLOCKS: skipTheater (blitz overlay delays).
+  // When the flow has any opaque FF unit and WAYGRAPH_SLOWMO is unset,
+  // launch slowMo is 0 so Playwright itself does not re-tax every click
+  // inside the FF (that was the "30s login / cursor gone but still slow" bug).
   const demoFast = process.env.WAYGRAPH_DEMO_FAST === "1";
   const stepperMode = process.env.WAYGRAPH_STEPPER === "full" ? "full" : "carousel";
   const pacing = { gatesFast: demoFast, skipTheater: false };
@@ -2080,8 +2083,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     // gates too, not just skip its interaction dwell - otherwise autoplay
     // still stalls the full autoplayMs admiring a step that intentionally
     // ran too fast to watch.
-    const ms =
-      pacing.gatesFast || pacing.skipTheater ? Math.min(400, autoplayMs) : autoplayMs;
+    const ms = pacing.skipTheater
+      ? Math.min(80, autoplayMs)
+      : pacing.gatesFast
+        ? Math.min(400, autoplayMs)
+        : autoplayMs;
     let elapsed = 0;
     for (;;) {
       // Re-read the checkbox EVERY loop tick, not once up front - a human
@@ -2165,9 +2171,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       await resetPageState(context, page, baseURL);
     }
     // gatesFast: --fast (whole run) or FFCompose opaque steps (one short gate).
-    // skipTheater: only WAYGRAPH_FAST_BLOCKS - never --fast, never FF by default.
+    // skipTheater: WAYGRAPH_FAST_BLOCKS **or** FFCompose — wall-clock blitz
+    // (overlay delays). --fast alone never sets skipTheater.
     pacing.gatesFast = demoFast || !!r.block.fastForward;
-    pacing.skipTheater = fastBlockNames.has(r.block.name);
+    pacing.skipTheater = fastBlockNames.has(r.block.name) || !!r.block.fastForward;
     const fixtures = r.highlightFixtures;
     stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures });
     const isNavBlock = r.block.__waygraphKind === "nav";
@@ -2637,13 +2644,20 @@ async function main() {
   // nobody has to watch a live window for it to be right).
   const headed =
     process.env.WAYGRAPH_HEADED === "0" ? false : process.env.WAYGRAPH_HEADED === "1" || step;
-  // Step mode defaults to a visible pace (each fill/click actually shows on
-  // screen instead of snapping in) unless the human overrides it - an
-  // explicit WAYGRAPH_SLOWMO=0 still means "off".
+  // Step mode defaults to a visible Playwright pace (slowMo 350) UNLESS the
+  // flow has an opaque fastForwardComposeBlock — then default slowMo 0 so FF
+  // auth/seed actually blitzes (<10s target) instead of only hiding the cursor
+  // while every click still pays 350ms. Non-FF steps keep overlay theater
+  // (cursor/pop) for watchability. Explicit WAYGRAPH_SLOWMO always wins.
+  const hasOpaqueFf = resolved.some(
+    (r) => r && r.block && r.block.fastForward === true,
+  );
   const slowMo = process.env.WAYGRAPH_SLOWMO !== undefined
     ? Number(process.env.WAYGRAPH_SLOWMO)
     : step
-      ? 350
+      ? hasOpaqueFf
+        ? 0
+        : 350
       : undefined;
   const baseURL = process.env.WAYGRAPH_BASE_URL;
   const title = process.env.WAYGRAPH_TITLE;
@@ -2651,8 +2665,8 @@ async function main() {
   // should blow past the overlay's own added dwell (ring pop, cursor
   // travel, typing delay, and that block's own gates) - "I want the login
   // block to be faster than the rest of the demo," Dan's own phrase.
-  // Playwright's real slowMo is untouched; this only trims what waygraph
-  // itself adds on top of it. Distinct from --fast (gates only).
+  // FFCompose blocks get the same skipTheater automatically (no need to
+  // list them here). Distinct from --fast (gates only).
   const fastBlockNames = new Set(
     (process.env.WAYGRAPH_FAST_BLOCKS || "")
       .split(",")
@@ -3673,7 +3687,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)
@@ -3697,6 +3712,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;
@@ -3790,6 +3807,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];
@@ -3801,6 +3819,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);
@@ -3832,6 +3864,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
@@ -3840,6 +3873,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=...]
 `);
@@ -3853,6 +3890,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 } : {}),
@@ -3865,6 +3905,7 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                     : {}),
                 headed,
                 ...(baseUrl ? { baseURL: baseUrl } : {}),
+                ...(blocksSelect ? { blocksSelect } : {}),
             });
             process.exit(code);
         }
@@ -4024,13 +4065,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

@@ -351,10 +351,13 @@ export declare function composeBlock<In extends Checkpoint<string>, B extends Ch
 export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, F>, Block<F, Out>]): ComposedBlock<In, Out>;
 /**
  * Same shape as {@link composeBlock}, marked {@link FastForwardComposedBlock.fastForward}
- * so demo/run/traverse treat it as **one opaque step** (no per-inner gate/ring)
- * unless `--ff-expand` / `WAYGRAPH_FF_EXPAND=1`. Inner acts still run for real;
+ * so demo/run/traverse treat it as **one opaque step** that **blitzes wall-clock**
+ * (skip overlay theater + no Playwright slowMo on that step's acts) unless
+ * `--ff-expand` / `WAYGRAPH_FF_EXPAND=1`. Inner acts still run for real;
  * failures are prefixed `ff-name > …` so the locus names both the FF unit and
- * the inner step. Prefer this for boring prefixes (auth, seed) on demo Flows.
+ * the inner step. Prefer this for boring or heavy-check prefixes (auth, seed,
+ * dashboard settle) — you may put **several** FF units in one Flow with normal
+ * Blocks between them.
  * @example fastForwardComposeBlock("ff-owner-auth", [NavLoginBlock, SubmitLoginForFlow])
  */
 export interface FastForwardComposedBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> extends ComposedBlock<In, Out> {

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/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.9",
+  "version": "0.12.11",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",