waygraph 0.12.18 → 0.12.20

package/README.md

@@ -228,11 +228,14 @@ real acts). `--ff-expand` is the older expand-only flag (same flatten). Saucedem
 `checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays expanded for
 Sign In narration.
 
-`waygraph traverse` walks the Block graph (Phase B+D). `--parallel N` (default
+`waygraph traverse` walks the Block graph (Phase B-E). `--parallel N` (default
 `--session clone`) bootstraps one context, forks N workers with `storageState` + mem
 snapshot, partitions edges by hash, and claims via in-process edge leases (audit under
-`.waygraph-traverse/`). `--session inherit` is refused when `parallel > 1`. See
-`docs/proposals/traverse-ffcompose-rfc.md`.
+`.waygraph-traverse/`). `--session inherit` is refused when `parallel > 1`. Phase E
+writes `.waygraph-traverse/coverage.json` and prints `[Coverage edges=H/T ratio=R%...]`;
+`--min-edge-coverage 80%` fails the suite with exit 2 when the ratio is below the gate
+(even if every worker leaf-PASSed). `--coverage-out PATH` / `--no-coverage-report` adjust
+the JSON. See `docs/proposals/traverse-ffcompose-rfc.md`.
 
 **Richer demo narration:** automation rings are **gray**; authored stubs/slides can use
 `tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus

package/dist/auto-explore-run.js

@@ -194,20 +194,23 @@ async function runOneBlock(engine, entry, context, page, mem, headful) {
     const flow = engine.defineFlow([start, entry.block, end]);
     const BLOCK_TIMEOUT_MS = 45_000;
     let timer;
+    let result;
     try {
-        await Promise.race([
+        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 - ` +
                     "click Quit and retry, or check network / mem credentials")), BLOCK_TIMEOUT_MS);
             }),
         ]);
+        result = ran.result;
     }
     finally {
         if (timer)
             clearTimeout(timer);
     }
     await page.evaluate("delete window.__wgPendingNavClickLabel").catch(() => { });
+    return result;
 }
 const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
     "max-width:min(92vw,720px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
@@ -540,13 +543,16 @@ export async function runAutoExplore(projectDir, options = {}) {
         }
         wiredPage = target;
     }
+    let here = null;
     try {
         for (;;) {
             page = await ensureLivePage(context, page, startUrl);
             await wirePage(page);
             const pickWait = armPickWait();
             pickSlot.resolve = pickWait.resolve;
-            const here = await detectHere(page, library.navBlocks);
+            if (here === null) {
+                here = await detectHere(page, library.navBlocks);
+            }
             if (cli)
                 console.error("waygraph auto: scanning page for moves ...");
             const menu = await buildExploreMenu(page, graph, library, here);
@@ -595,10 +601,11 @@ export async function runAutoExplore(projectDir, options = {}) {
                 }
                 const pickLabel = edge.label ?? entry.block.name;
                 console.error(`waygraph auto: running [${pick.index + 1}] ${pickLabel} ...`);
-                await runOneBlock(engine, entry, context, page, mem, !cli);
-                const landed = await detectHere(page, library.navBlocks);
-                lastRunNote = `${entry.block.name} -> ${landed ?? edge.to}`;
-                console.error(`waygraph auto: ran ${entry.block.name} -> ${landed ?? edge.to}`);
+                const result = await runOneBlock(engine, entry, context, page, mem, !cli);
+                // Trust block output over locate() - nav verify traits collide on /dashboard.
+                here = result.__state ?? edge.to;
+                lastRunNote = `${entry.block.name} -> ${here}`;
+                console.error(`waygraph auto: ran ${entry.block.name} -> ${here}`);
             }
             catch (err) {
                 lastRunNote = `${entry.block.name} failed`;

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 { parseMinEdgeCoverage } from "./traverse-coverage.js";
 import { isFileSelectToken, parseBlocksSelect, } from "./blocks-select.js";
 // ---------------------------------------------------------------------------
 // Filesystem
@@ -221,6 +222,8 @@ import {
   demoPaceIsBlitz,
   demoPaceIsFast,
   demoPaceIsSlow,
+  formatDemoPaceBadge,
+  formatDemoPaceLabel,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -491,6 +494,18 @@ const RING_CSS =
   // block chain shows no episode heading at all.
   "#wg-panel .wg-episode{margin:0 0 6px;font:700 15px system-ui,sans-serif;color:#fff;" +
   "padding-bottom:6px;border-bottom:1px solid rgba(124,58,237,.35);}" +
+  // Pace chip - numbers speak in the overlay (2.5x / 4500ms / slow).
+  "#wg-panel .wg-pace{display:inline-flex;align-items:center;gap:8px;margin:0 0 10px;" +
+  "padding:6px 10px;border-radius:8px;background:rgba(124,58,237,.22);" +
+  "border:1px solid rgba(124,58,237,.45);font:600 12px/1.35 system-ui,sans-serif;color:#f0e8ff;}" +
+  "#wg-panel .wg-pace-badge{display:inline-block;padding:2px 8px;border-radius:999px;" +
+  "background:#7C3AED;color:#fff;font:800 11px/1.2 system-ui,sans-serif;letter-spacing:.04em;" +
+  "text-transform:uppercase;}" +
+  "#wg-panel .wg-pace[data-pace-kind=slow] .wg-pace-badge," +
+  "#wg-panel .wg-pace[data-pace-kind=num-slow] .wg-pace-badge{background:#EAB308;color:#1c1917;}" +
+  "#wg-panel .wg-pace[data-pace-kind=fast] .wg-pace-badge," +
+  "#wg-panel .wg-pace[data-pace-kind=blitz] .wg-pace-badge{background:#22C55E;color:#052e16;}" +
+  "#wg-panel .wg-pace[data-pace-kind=ms] .wg-pace-badge{background:#3B82F6;color:#fff;}" +
   "#wg-panel .wg-narration{margin:0 0 12px;font:italic 14px/1.4 system-ui,sans-serif;color:#f0e8ff;}" +
   "#wg-progress{height:4px;background:#2a1650;border-radius:2px;margin:0 0 12px;overflow:hidden;}" +
   "#wg-progress-bar{height:100%;background:#7C3AED;border-radius:2px;transition:width .3s ease;}" +
@@ -957,9 +972,20 @@ async function renderBeforeStep(page, info) {
       const narrationHtml = info.description
         ? "<div class=\\"wg-narration\\">" + esc(info.description) + "</div>"
         : "";
+      const paceHtml =
+        info.paceBadge || info.paceLabel
+          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+            esc(info.paceKind || "normal") +
+            "\\"><span class=\\"wg-pace-badge\\">" +
+            esc(info.paceBadge || "1x") +
+            "</span><span>" +
+            esc(info.paceLabel || "") +
+            "</span></div>"
+          : "";
       let html =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
+        paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
         narrationHtml;
@@ -995,7 +1021,12 @@ async function renderBeforeStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          stepLabel:
+            (info.index + 1) +
+            " / " +
+            info.total +
+            (info.blockName ? " · " + info.blockName : "") +
+            (info.paceBadge ? " · " + info.paceBadge : ""),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1214,9 +1245,20 @@ async function renderAfterStep(page, info) {
             .join("") +
           "</div>"
         : "";
+      const paceHtml =
+        info.paceBadge || info.paceLabel
+          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+            escA(info.paceKind || "normal") +
+            "\\"><span class=\\"wg-pace-badge\\">" +
+            escA(info.paceBadge || "1x") +
+            "</span><span>" +
+            escA(info.paceLabel || "") +
+            "</span></div>"
+          : "";
       panel.innerHTML =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
+        paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
         resultHtml +
@@ -1227,7 +1269,12 @@ async function renderAfterStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          stepLabel:
+            (info.index + 1) +
+            " / " +
+            info.total +
+            (info.blockName ? " · " + info.blockName : "") +
+            (info.paceBadge ? " · " + info.paceBadge : ""),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1329,7 +1376,12 @@ async function renderStepError(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          stepLabel:
+            (info.index + 1) +
+            " / " +
+            info.total +
+            (info.blockName ? " · " + info.blockName : "") +
+            (info.paceBadge ? " · " + info.paceBadge : ""),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1537,14 +1589,13 @@ async function presentSlides(page, slides, _gate, opts) {
   const episodeTitle = (opts && opts.episodeTitle) || "";
   const gatesFast = !!(opts && opts.fast);
   const demoPace = normalizeDemoPace((opts && opts.pace) || (gatesFast ? "fast" : "normal"));
-  const autoplayMs =
+  const baseAutoplay =
     opts && opts.autoplayMs
       ? Number(opts.autoplayMs)
       : process.env.WAYGRAPH_AUTOPLAY_MS
         ? Number(process.env.WAYGRAPH_AUTOPLAY_MS)
-        : demoPace === "slow"
-          ? 3500
-          : 1800;
+        : 1800;
+  const autoplayMs = demoPaceGateMs(demoPace, baseAutoplay);
   for (let i = 0; i < slides.length; i++) {
     const s = slides[i];
     const caption = formatHighlightCaption(s);
@@ -1584,11 +1635,22 @@ async function presentSlides(page, slides, _gate, opts) {
               (info.episodeTitle ? ": " + esc(info.episodeTitle) : "") +
               " · yap slides</div>"
             : "";
+        const paceHtml =
+          info.paceBadge || info.paceLabel
+            ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+              esc(info.paceKind || "normal") +
+              "\\"><span class=\\"wg-pace-badge\\">" +
+              esc(info.paceBadge || "1x") +
+              "</span><span>" +
+              esc(info.paceLabel || "") +
+              "</span></div>"
+            : "";
         panel.innerHTML =
           "<div class=\\"wg-chrome\\"><span class=\\"wg-chrome-title\\">waygraph demo</span>" +
           "<button type=\\"button\\" class=\\"wg-hide-btn\\" data-wg-toggle=\\"1\\">Hide</button></div>" +
           "<div class=\\"wg-body\\">" +
           episodeLine +
+          paceHtml +
           "<h3>Slide " +
           (info.index + 1) +
           " / " +
@@ -1706,6 +1768,9 @@ async function presentSlides(page, slides, _gate, opts) {
         dwellMs,
         episodeNumber: episodeNumber !== undefined ? episodeNumber : null,
         episodeTitle,
+        paceBadge: formatDemoPaceBadge(demoPace, baseAutoplay),
+        paceLabel: formatDemoPaceLabel(demoPace, baseAutoplay),
+        paceKind: demoPaceKind(demoPace),
       },
     );
     const started = Date.now();
@@ -1738,6 +1803,25 @@ async function presentSlides(page, slides, _gate, opts) {
   await hideRing(page);
 }
 
+function demoPaceKind(pace) {
+  const p = normalizeDemoPace(pace);
+  if (typeof p === "number" && p > 20) return "ms";
+  if (typeof p === "number") return demoPaceIsSlow(p) ? "num-slow" : demoPaceIsFast(p) ? "fast" : "normal";
+  if (p === "blitz" || p === "fast" || p === "slow") return p;
+  return "normal";
+}
+
+function paceSpeakFields(pace, baseAutoplayMs) {
+  const p = normalizeDemoPace(pace);
+  const base = Number.isFinite(baseAutoplayMs) && baseAutoplayMs > 0 ? baseAutoplayMs : 1800;
+  return {
+    pace: p,
+    paceBadge: formatDemoPaceBadge(p, base),
+    paceLabel: formatDemoPaceLabel(p, base),
+    paceKind: demoPaceKind(p),
+  };
+}
+
 async function hideRing(page) {
   await page
     .evaluate(() => {
@@ -2302,6 +2386,20 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       }
       return { name: k.name, value };
     });
+    const paceSpeak = paceSpeakFields(pacing.demoPace, autoplayMs);
+    if (process.env.WAYGRAPH_JSON !== "1") {
+      console.log(
+        "waygraph demo: step " +
+          (i + 1) +
+          "/" +
+          resolved.length +
+          " " +
+          r.block.name +
+          " · " +
+          paceSpeak.paceLabel +
+          (r.episodeNumber ? " · episode " + r.episodeNumber : ""),
+      );
+    }
     await renderBeforeStep(page, {
       index: i,
       total: resolved.length,
@@ -2318,6 +2416,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeTitle: r.episodeTitle,
       stepperMode,
       forceCollapsed,
+      ...paceSpeak,
     });
     const edits = await gate();
     for (const k of requires) {
@@ -2487,6 +2586,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       highlights,
       gatesFast: pacing.gatesFast,
       pace: pacing.demoPace,
+      ...paceSpeakFields(pacing.demoPace, autoplayMs),
       isLast: i === resolved.length - 1,
       allNames: moduleNames,
       allDescriptions: moduleDescriptions,
@@ -3851,7 +3951,7 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
-  waygraph traverse [project]              Graph crawl (Phase B+D)
+  waygraph traverse [project]              Graph crawl (Phase B-E)
                  --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
                  --parallel N              Phase D: N clone workers (max 4)
                  --session clone|inherit   Phase D: default clone
@@ -3977,6 +4077,9 @@ async function main() {
             let blocksFilter;
             let parallel;
             let session;
+            let minEdgeCoverageRaw;
+            let coverageOut;
+            let noCoverageReport = false;
             let projectDir = process.cwd();
             for (let i = 0; i < rest.length; i++) {
                 const a = rest[i];
@@ -4016,6 +4119,22 @@ async function main() {
                     session = v;
                     continue;
                 }
+                if (a === "--min-edge-coverage" || a.startsWith("--min-edge-coverage=")) {
+                    minEdgeCoverageRaw = a.startsWith("--min-edge-coverage=")
+                        ? a.slice("--min-edge-coverage=".length)
+                        : rest[++i];
+                    continue;
+                }
+                if (a === "--coverage-out" || a.startsWith("--coverage-out=")) {
+                    coverageOut = a.startsWith("--coverage-out=")
+                        ? a.slice("--coverage-out=".length)
+                        : rest[++i];
+                    continue;
+                }
+                if (a === "--no-coverage-report") {
+                    noCoverageReport = true;
+                    continue;
+                }
                 if (a === "--max-steps" || a.startsWith("--max-steps=")) {
                     const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
                     maxSteps = Number(v);
@@ -4044,12 +4163,15 @@ async function main() {
                 if (a === "--help" || a === "-h") {
                     console.log(`waygraph traverse [project] [flags]
 
-Graph crawl (RFC Phase B+D). Walks unused legal edges until a leaf,
+Graph crawl (RFC Phase B-E). Walks unused legal edges until a leaf,
 budget kill, or first broken edge. --parallel N uses session clone + edge leases.
 
   --blocks <glob|/regex/|substr>  Phase C: filter *.block.ts discovery
   --parallel N            Phase D: N clone workers (default 1, max 4)
   --session clone|inherit Phase D: default clone; inherit refused if parallel>1
+  --min-edge-coverage X   Phase E: suite gate 0.8 | 80% | 80 (exit 2 if below)
+  --coverage-out PATH     Phase E: write JSON (default .waygraph-traverse/coverage.json)
+  --no-coverage-report    Phase E: print Coverage line only (no JSON file)
   --from <Checkpoint>     start checkpoint (optional)
   --data '{...}'          Mem seed JSON
   --max-steps N           default 50 (per worker)
@@ -4061,9 +4183,11 @@ budget kill, or first broken edge. --parallel N uses session clone + edge leases
 Examples:
   waygraph traverse --blocks '**/mailpit/**/*.block.ts'
   waygraph traverse --parallel 2 --session clone --max-steps 20
+  waygraph traverse --min-edge-coverage 80% --coverage-out ./cov.json
 
 PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
 FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
+COVER: [Coverage edges=H/T ratio=R% min=M% PASS|FAIL]
 `);
                     process.exit(0);
                 }
@@ -4078,6 +4202,15 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
             const blocksSelect = blocksFilter
                 ? parseBlocksSelect(blocksFilter)
                 : undefined;
+            let minEdgeCoverage;
+            if (minEdgeCoverageRaw !== undefined) {
+                const parsed = parseMinEdgeCoverage(minEdgeCoverageRaw);
+                if (parsed === null) {
+                    console.error(`waygraph traverse: --min-edge-coverage expects 0.8, 80%, or 80 (got ${JSON.stringify(minEdgeCoverageRaw)})`);
+                    process.exit(1);
+                }
+                minEdgeCoverage = parsed;
+            }
             const code = await runTraverse(projectDir, {
                 ...(from ? { from } : {}),
                 ...(data ? { data } : {}),
@@ -4093,6 +4226,9 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                 ...(blocksSelect ? { blocksSelect } : {}),
                 ...(parallel !== undefined && Number.isFinite(parallel) ? { parallel } : {}),
                 ...(session ? { session } : {}),
+                ...(minEdgeCoverage !== undefined ? { minEdgeCoverage } : {}),
+                ...(coverageOut ? { coverageOut: resolve(coverageOut) } : {}),
+                ...(noCoverageReport ? { noCoverageReport: true } : {}),
             });
             process.exit(code);
         }

package/dist/highlights.d.ts

@@ -133,6 +133,16 @@ export declare function demoPaceIsFast(pace: DemoPace): boolean;
 export declare function demoPaceIsSlow(pace: DemoPace): boolean;
 /** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
 export declare function demoPaceGateMs(pace: DemoPace, baseAutoplayMs: number): number;
+/**
+ * Short chip for the demo panel (e.g. `2.5x`, `4500ms`, `slow`).
+ * Always printable - numbers speak in the UI, not only in code.
+ */
+export declare function formatDemoPaceBadge(pace: DemoPace, baseAutoplayMs?: number): string;
+/**
+ * Loud one-line pace description for panel + console
+ * (e.g. `pace 2.5x (~4500ms gates)` / `pace 4500ms gates (~2.25x)`).
+ */
+export declare function formatDemoPaceLabel(pace: DemoPace, baseAutoplayMs?: number): string;
 /**
  * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
  * or `null` when duration is unset (caller keeps legacy timing).

package/dist/highlights.js

@@ -162,6 +162,51 @@ export function demoPaceGateMs(pace, baseAutoplayMs) {
     const scale = demoPaceScale(pace);
     return Math.min(30000, Math.max(80, Math.round(baseAutoplayMs * scale)));
 }
+/**
+ * Short chip for the demo panel (e.g. `2.5x`, `4500ms`, `slow`).
+ * Always printable - numbers speak in the UI, not only in code.
+ */
+export function formatDemoPaceBadge(pace, baseAutoplayMs = 1800) {
+    const p = normalizeDemoPace(pace);
+    if (typeof p === "number" && p > 20)
+        return `${Math.round(p)}ms`;
+    if (typeof p === "number") {
+        const s = Number.isInteger(p) ? String(p) : String(Math.round(p * 100) / 100);
+        return `${s}x`;
+    }
+    if (p === "blitz")
+        return "blitz";
+    if (p === "fast")
+        return "fast";
+    if (p === "slow")
+        return "slow";
+    void baseAutoplayMs;
+    return "1x";
+}
+/**
+ * Loud one-line pace description for panel + console
+ * (e.g. `pace 2.5x (~4500ms gates)` / `pace 4500ms gates (~2.25x)`).
+ */
+export function formatDemoPaceLabel(pace, baseAutoplayMs = 1800) {
+    const p = normalizeDemoPace(pace);
+    const gate = demoPaceGateMs(p, baseAutoplayMs);
+    const scale = demoPaceScale(p);
+    const scaleTxt = Number.isInteger(scale) ? String(scale) : (Math.round(scale * 100) / 100).toString();
+    if (typeof p === "number" && p > 20) {
+        return `pace ${Math.round(p)}ms gates (~${scaleTxt}x)`;
+    }
+    if (typeof p === "number") {
+        const s = Number.isInteger(p) ? String(p) : String(Math.round(p * 100) / 100);
+        return `pace ${s}x (~${gate}ms gates)`;
+    }
+    if (p === "blitz")
+        return `pace blitz (~${gate}ms, skip theater)`;
+    if (p === "fast")
+        return `pace fast (~${scaleTxt}x, ~${gate}ms gates)`;
+    if (p === "slow")
+        return `pace slow (~${scaleTxt}x, ~${gate}ms gates)`;
+    return `pace normal (1x, ~${gate}ms gates)`;
+}
 /**
  * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
  * or `null` when duration is unset (caller keeps legacy timing).

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 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, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
@@ -13,4 +13,6 @@ export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp,
 export type { BlocksSelect, BlocksSelectKind } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";
 export { runTraverse } from "./traverse-run.js";
-export type { TraverseOptions, TraverseSessionMode } from "./traverse-run.js";
+export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse-run.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
+export type { TraverseCoverageReport } from "./traverse-coverage.js";

package/dist/index.js

@@ -2,8 +2,9 @@ export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 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, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_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";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";
 export { runTraverse } from "./traverse-run.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";

package/dist/traverse-coverage.d.ts

@@ -0,0 +1,59 @@
+export interface TraverseCoverageReport {
+    version: 1;
+    generatedAt: string;
+    projectDir: string;
+    parallel: number;
+    /** Unique edge keys in the discovered graph (block names). */
+    edgesTotal: number;
+    /** Graph edges successfully walked this suite (after instance normalize). */
+    edgesHit: number;
+    /** edgesHit / edgesTotal (0 when total is 0). */
+    ratio: number;
+    /** Optional suite gate that was applied (0-1). */
+    minEdgeCoverage?: number;
+    /** true when minEdgeCoverage was set and ratio met it. */
+    coveragePass?: boolean;
+    /** Sorted graph edge keys that were hit. */
+    hit: string[];
+    /** Sorted graph edge keys never walked. */
+    missed: string[];
+    /** Raw worker hit keys (may include block::instanceId). */
+    rawHit?: string[];
+    workers?: Array<{
+        traverseId: string;
+        exitCode: number;
+        steps: number;
+        edgesHit: number;
+        leaf?: string;
+    }>;
+}
+/** Static graph edge key = Block runtime name. */
+export declare function edgeKeyFromGraphEdge(edge: {
+    block: string;
+}): string;
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export declare function collectGraphEdgeKeys(edges: ReadonlyArray<{
+    block: string;
+}>): string[];
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export declare function normalizeHitKey(hitKey: string, graphKeys: ReadonlySet<string>): string | null;
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export declare function parseMinEdgeCoverage(raw: unknown): number | null;
+export declare function buildCoverageReport(opts: {
+    projectDir: string;
+    parallel: number;
+    allEdgeKeys: readonly string[];
+    hitKeys: ReadonlySet<string> | readonly string[];
+    minEdgeCoverage?: number | null;
+    workers?: TraverseCoverageReport["workers"];
+}): TraverseCoverageReport;
+/** Greppable one-liner for agents/CI. */
+export declare function formatCoverageLine(report: TraverseCoverageReport): string;
+export declare function defaultCoverageOutPath(projectDir: string): string;
+export declare function writeCoverageReport(path: string, report: TraverseCoverageReport): void;

package/dist/traverse-coverage.js

@@ -0,0 +1,127 @@
+/**
+ * Phase E: traverse edge coverage report + suite gate.
+ * Coverage is independent of leaf PASS - a green leaf can still fail CI
+ * when --min-edge-coverage is set and ratio is too low.
+ *
+ * Denominator = unique static graph edge block names (FF inners stay as their
+ * own graph edges when discovered; RFC open Q deferred - no covered-via-prefix yet).
+ * A hit of `block::instanceId` counts as covering `block`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Static graph edge key = Block runtime name. */
+export function edgeKeyFromGraphEdge(edge) {
+    return edge.block;
+}
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export function collectGraphEdgeKeys(edges) {
+    const set = new Set();
+    for (const e of edges)
+        set.add(edgeKeyFromGraphEdge(e));
+    return [...set].sort();
+}
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export function normalizeHitKey(hitKey, graphKeys) {
+    if (graphKeys.has(hitKey))
+        return hitKey;
+    const base = hitKey.includes("::") ? hitKey.slice(0, hitKey.indexOf("::")) : hitKey;
+    if (graphKeys.has(base))
+        return base;
+    return null;
+}
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export function parseMinEdgeCoverage(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        if (raw < 0)
+            return null;
+        if (raw <= 1)
+            return raw;
+        if (raw <= 100)
+            return raw / 100;
+        return null;
+    }
+    if (typeof raw !== "string")
+        return null;
+    const t = raw.trim().toLowerCase();
+    if (!t)
+        return null;
+    if (t.endsWith("%")) {
+        const n = Number(t.slice(0, -1));
+        if (!Number.isFinite(n) || n < 0 || n > 100)
+            return null;
+        return n / 100;
+    }
+    const n = Number(t);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    if (n <= 1)
+        return n;
+    if (n <= 100)
+        return n / 100;
+    return null;
+}
+export function buildCoverageReport(opts) {
+    const all = [...new Set(opts.allEdgeKeys)].sort();
+    const graphSet = new Set(all);
+    const rawList = Array.isArray(opts.hitKeys) ? [...opts.hitKeys] : [...opts.hitKeys];
+    const covered = new Set();
+    for (const raw of rawList) {
+        const n = normalizeHitKey(raw, graphSet);
+        if (n)
+            covered.add(n);
+    }
+    const hit = all.filter((k) => covered.has(k));
+    const missed = all.filter((k) => !covered.has(k));
+    const edgesTotal = all.length;
+    const edgesHit = hit.length;
+    const ratio = edgesTotal === 0 ? 0 : edgesHit / edgesTotal;
+    const min = opts.minEdgeCoverage != null && Number.isFinite(opts.minEdgeCoverage)
+        ? Math.min(1, Math.max(0, opts.minEdgeCoverage))
+        : undefined;
+    const coveragePass = min === undefined ? undefined : ratio + 1e-12 >= min;
+    const coverageExtra = min !== undefined && coveragePass !== undefined
+        ? { minEdgeCoverage: min, coveragePass }
+        : {};
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        projectDir: opts.projectDir,
+        parallel: opts.parallel,
+        edgesTotal,
+        edgesHit,
+        ratio: Math.round(ratio * 10000) / 10000,
+        ...coverageExtra,
+        hit,
+        missed,
+        rawHit: [...new Set(rawList)].sort(),
+        ...(opts.workers ? { workers: opts.workers } : {}),
+    };
+}
+/** Greppable one-liner for agents/CI. */
+export function formatCoverageLine(report) {
+    const pct = (report.ratio * 100).toFixed(1);
+    const minPart = report.minEdgeCoverage !== undefined
+        ? ` min=${(report.minEdgeCoverage * 100).toFixed(1)}%` +
+            (report.coveragePass === false
+                ? " FAIL"
+                : report.coveragePass === true
+                    ? " PASS"
+                    : "")
+        : "";
+    return `[Coverage edges=${report.edgesHit}/${report.edgesTotal} ratio=${pct}%${minPart}]`;
+}
+export function defaultCoverageOutPath(projectDir) {
+    return join(projectDir, ".waygraph-traverse", "coverage.json");
+}
+export function writeCoverageReport(path, report) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(report, null, 2) + "\n", "utf-8");
+}

package/dist/traverse-run.d.ts

@@ -1,4 +1,10 @@
 export type TraverseSessionMode = "clone" | "inherit";
+export interface TraverseWorkerResult {
+    exitCode: number;
+    steps: number;
+    edgesHit: string[];
+    leaf?: string;
+}
 export interface TraverseOptions {
     baseURL?: string;
     startUrl?: string;
@@ -24,8 +30,18 @@ export interface TraverseOptions {
     parallel?: number;
     /** Phase D: clone (default) or inherit. Inherit refused when parallel > 1. */
     session?: TraverseSessionMode;
+    /**
+     * Phase E: fail suite (exit 2) when hit/total ratio is below this 0-1 fraction.
+     * Leaf PASS alone does not satisfy the gate.
+     */
+    minEdgeCoverage?: number;
+    /** Phase E: write coverage JSON here (default `.waygraph-traverse/coverage.json`). */
+    coverageOut?: string;
+    /** Phase E: skip writing coverage.json (still prints the Coverage line). */
+    noCoverageReport?: boolean;
 }
 /**
- * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL + Coverage lines.
+ * Exit: 0 leaf ok (+ coverage ok), 1 break/timeout, 2 coverage gate fail (Phase E).
  */
 export declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;

package/dist/traverse-run.js

@@ -9,6 +9,7 @@ import { MemPage } from "./mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { defaultMemValueForKey } from "./auto-explore-run.js";
 import { EdgeLeaseCoordinator } from "./traverse-lease.js";
+import { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, writeCoverageReport, } from "./traverse-coverage.js";
 function resolveBaseUrl(projectDir) {
     if (process.env.WAYGRAPH_BASE_URL)
         return process.env.WAYGRAPH_BASE_URL;
@@ -132,6 +133,7 @@ async function runTraverseWorker(opts) {
     const startedAt = Date.now();
     let lastHere = opts.from ?? null;
     let exitCode = 0;
+    let leaf;
     try {
         for (;;) {
             if (Date.now() - startedAt > timeoutMs) {
@@ -171,6 +173,7 @@ async function runTraverseWorker(opts) {
             });
             if (candidates.length === 0) {
                 const label = here ?? detected ?? "unknown";
+                leaf = label;
                 console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
                 console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
                 break;
@@ -227,10 +230,16 @@ async function runTraverseWorker(opts) {
     finally {
         console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
     }
-    return exitCode;
+    return {
+        exitCode,
+        steps,
+        edgesHit: [...edgesHit],
+        ...(leaf ? { leaf } : {}),
+    };
 }
 /**
- * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL + Coverage lines.
+ * Exit: 0 leaf ok (+ coverage ok), 1 break/timeout, 2 coverage gate fail (Phase E).
  */
 export async function runTraverse(projectDir, options = {}) {
     let parallel = Math.max(1, Math.floor(options.parallel ?? 1));
@@ -250,11 +259,16 @@ 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 minEdgeCoverage = options.minEdgeCoverage != null && Number.isFinite(options.minEdgeCoverage)
+        ? options.minEdgeCoverage
+        : undefined;
+    const coverageOut = options.coverageOut ?? defaultCoverageOutPath(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 allEdgeKeys = collectGraphEdgeKeys(graph.edges);
     const leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
     const { chromium } = await import("@playwright/test");
@@ -268,7 +282,46 @@ export async function runTraverse(projectDir, options = {}) {
     console.error(`waygraph traverse: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
         (baseURL ? ` base=${baseURL}` : "") +
         ` parallel=${parallel} session=${session}` +
-        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}`);
+        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}` +
+        (minEdgeCoverage !== undefined
+            ? ` minEdgeCoverage=${(minEdgeCoverage * 100).toFixed(1)}%`
+            : ""));
+    const emitCoverage = (workers) => {
+        const hitUnion = new Set();
+        for (const w of workers) {
+            for (const k of w.result.edgesHit)
+                hitUnion.add(k);
+        }
+        const report = buildCoverageReport({
+            projectDir,
+            parallel,
+            allEdgeKeys,
+            hitKeys: hitUnion,
+            ...(minEdgeCoverage !== undefined ? { minEdgeCoverage } : {}),
+            workers: workers.map(({ traverseId, result }) => ({
+                traverseId,
+                exitCode: result.exitCode,
+                steps: result.steps,
+                edgesHit: result.edgesHit.length,
+                ...(result.leaf ? { leaf: result.leaf } : {}),
+            })),
+        });
+        console.log(formatCoverageLine(report));
+        console.error(`waygraph traverse: coverage hit=${report.edgesHit}/${report.edgesTotal}` +
+            (report.missed.length
+                ? ` missed=${report.missed.slice(0, 8).join(",")}${report.missed.length > 8 ? "..." : ""}`
+                : "") +
+            (options.noCoverageReport ? "" : ` report=${coverageOut}`));
+        if (!options.noCoverageReport) {
+            writeCoverageReport(coverageOut, report);
+        }
+        if (report.coveragePass === false) {
+            console.error(`waygraph traverse: FAIL coverage gate ratio=${(report.ratio * 100).toFixed(1)}%` +
+                ` < min=${((report.minEdgeCoverage ?? 0) * 100).toFixed(1)}%`);
+            return 2;
+        }
+        return 0;
+    };
     try {
         if (parallel <= 1) {
             const contextOpts = {
@@ -284,8 +337,9 @@ export async function runTraverse(projectDir, options = {}) {
                 await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
                 await page.waitForLoadState("load").catch(() => { });
             }
-            const code = await runTraverseWorker({
-                traverseId: options.traverseId ?? "traverse-1",
+            const traverseId = options.traverseId ?? "traverse-1";
+            const result = await runTraverseWorker({
+                traverseId,
                 workerIndex: 0,
                 parallel: 1,
                 maxSteps,
@@ -305,7 +359,10 @@ export async function runTraverse(projectDir, options = {}) {
                 leases,
             });
             await context.close().catch(() => { });
-            return code;
+            const coverageCode = emitCoverage([{ traverseId, result }]);
+            if (result.exitCode !== 0)
+                return result.exitCode;
+            return coverageCode;
         }
         // Phase D: bootstrap one context for storageState, then N clones.
         const bootOpts = {
@@ -325,7 +382,7 @@ export async function runTraverse(projectDir, options = {}) {
         const memSnap = snapshotMem(library.byName, bootMem);
         await bootContext.close().catch(() => { });
         console.error(`waygraph traverse: forked ${parallel} clone workers (storageState + mem snapshot)`);
-        const codes = await Promise.all(Array.from({ length: parallel }, async (_, i) => {
+        const workerMeta = await Promise.all(Array.from({ length: parallel }, async (_, i) => {
             const traverseId = `traverse-${i + 1}`;
             const ctxOpts = {
                 viewport: { width: 1280, height: 720 },
@@ -341,7 +398,7 @@ export async function runTraverse(projectDir, options = {}) {
                 await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
             }
             try {
-                return await runTraverseWorker({
+                const result = await runTraverseWorker({
                     traverseId,
                     workerIndex: i,
                     parallel,
@@ -361,15 +418,20 @@ export async function runTraverse(projectDir, options = {}) {
                     mem,
                     leases,
                 });
+                return { traverseId, result };
             }
             finally {
                 await context.close().catch(() => { });
             }
         }));
-        const worst = codes.reduce((a, b) => Math.max(a, b), 0);
-        const pass = codes.filter((c) => c === 0).length;
+        const results = workerMeta.map((w) => w.result);
+        const worst = results.reduce((a, b) => Math.max(a, b.exitCode), 0);
+        const pass = results.filter((c) => c.exitCode === 0).length;
         console.error(`waygraph traverse: suite parallel=${parallel} pass=${pass}/${parallel} exit=${worst}`);
-        return worst;
+        const coverageCode = emitCoverage(workerMeta);
+        if (worst !== 0)
+            return worst;
+        return coverageCode;
     }
     finally {
         await browser.close().catch(() => { });

package/package.json

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