waygraph 0.12.13 → 0.12.15

package/README.md

@@ -226,7 +226,18 @@ FFCompose into its inner Blocks so a broken login step is visible as its own pan
 Former FF inners keep blitz pacing so wall-clock stays comparable to opaque FF (same
 real acts). `--ff-expand` is the older expand-only flag (same flatten). Saucedemo
 `checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays expanded for
-Sign In narration. See `docs/proposals/traverse-ffcompose-rfc.md`.
+Sign In narration.
+
+`waygraph traverse` walks the Block graph (Phase B+D). `--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`.
+
+**Richer demo narration:** automation rings are **gray**; authored stubs/slides can use
+`tone: "info" | "warning" | "danger" | "success"` (iconified captions). Episode pacing:
+`withDemoPace(flow, "fast" | "slow" | "normal" | "blitz")` or `withBlockPace(block, ...)`
+(FFCompose stays blitz). Living objectives: `docs/proposals/OBJECTIVES.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/cli.js

@@ -211,6 +211,9 @@ import {
   formatHighlightCaption,
   hasAuthoredStubAfter,
   hasAuthoredStubOnError,
+  normalizeHighlightTone,
+  normalizeDemoPace,
+  resolveStepDemoPace,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -399,9 +402,13 @@ const RING_CSS =
   "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;}" +
   // 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);}" +
+  // Automation (verify fallback, unmatched fill/click) = gray - operators
+  // can ignore engine checks and watch purple + semantic tones.
+  "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
+  "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
+  "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
+  "#wg-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}" +
+  "#wg-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.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
@@ -413,7 +420,11 @@ const RING_CSS =
   "#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,background .15s,color .15s;}" +
-  "#wg-ring-label[data-tone=auto]{background:#EAB308;color:#1c1917;}" +
+  "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
+  "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
+  "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
+  "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
+  "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
   // 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
@@ -431,7 +442,11 @@ 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[data-tone=auto]{border-color:#9CA3AF;background:rgba(156,163,175,.28);}" +
+  "#wg-click-pulse[data-tone=info]{border-color:#3B82F6;background:rgba(59,130,246,.28);}" +
+  "#wg-click-pulse[data-tone=warning]{border-color:#EAB308;background:rgba(234,179,8,.28);}" +
+  "#wg-click-pulse[data-tone=danger]{border-color:#EF4444;background:rgba(239,68,68,.28);}" +
+  "#wg-click-pulse[data-tone=success]{border-color:#22C55E;background:rgba(34,197,94,.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%);" +
@@ -651,7 +666,11 @@ async function installOverlay(page, title) {
           const ring = document.getElementById("wg-ring");
           const ringLabel = document.getElementById("wg-ring-label");
           if (!ring || !ringLabel) return;
-          const t = tone === "auto" ? "auto" : "planned";
+          const raw = (tone || "planned") + "";
+          const t =
+            raw === "auto" || raw === "info" || raw === "warning" || raw === "danger" || raw === "success"
+              ? raw
+              : "planned";
           ring.dataset.tone = t;
           ringLabel.dataset.tone = t;
           const margin = 6;
@@ -688,7 +707,11 @@ async function installOverlay(page, title) {
         window.__wgClickPulse = (x, y, tone) => {
           const pulse = document.getElementById("wg-click-pulse");
           if (!pulse) return;
-          pulse.dataset.tone = tone === "auto" ? "auto" : "planned";
+          const raw = (tone || "planned") + "";
+          pulse.dataset.tone =
+            raw === "auto" || raw === "info" || raw === "warning" || raw === "danger" || raw === "success"
+              ? raw
+              : "planned";
           pulse.style.left = x + "px";
           pulse.style.top = y + "px";
           pulse.classList.remove("wg-pulse");
@@ -1303,7 +1326,7 @@ function resolveDeclaredHighlights(block, resultTag) {
   if (!Array.isArray(highlights)) return [];
   return highlights.filter((h) => h && typeof h.selector === "string" && typeof h.label === "string").map((h) => ({
     ...h,
-    tone: h.tone === "auto" ? "auto" : "planned",
+    tone: normalizeHighlightTone(h.tone),
   }));
 }
 
@@ -1438,14 +1461,22 @@ async function matchStubForLocator(page, locator, stubs) {
 
 async function captionForLocator(page, locator, stubs, fallback) {
   const matched = await matchStubForLocator(page, locator, stubs);
-  if (matched) return { label: formatHighlightCaption(matched), tone: "planned" };
+  if (matched) {
+    return {
+      label: formatHighlightCaption(matched),
+      tone: normalizeHighlightTone(matched.tone),
+    };
+  }
   return { label: fallback, tone: "auto" };
 }
 
 async function dwellMatchedStub(page, locator, stubs, pacing) {
   const matched = await matchStubForLocator(page, locator, stubs);
   if (!matched) return;
-  const ms = resolveFixtureDwellMs(matched, { gatesFast: !!(pacing && pacing.gatesFast) });
+  const ms = resolveFixtureDwellMs(matched, {
+    gatesFast: !!(pacing && pacing.gatesFast),
+    pace: pacing && pacing.demoPace,
+  });
   if (ms != null && ms > 0) {
     await new Promise((res) => setTimeout(res, ms));
   }
@@ -1466,22 +1497,26 @@ async function presentSlides(page, slides, _gate, opts) {
   const episodeNumber = opts && opts.episodeNumber;
   const episodeTitle = (opts && opts.episodeTitle) || "";
   const gatesFast = !!(opts && opts.fast);
+  const demoPace = normalizeDemoPace((opts && opts.pace) || (gatesFast ? "fast" : "normal"));
   const autoplayMs =
     opts && opts.autoplayMs
       ? Number(opts.autoplayMs)
       : process.env.WAYGRAPH_AUTOPLAY_MS
         ? Number(process.env.WAYGRAPH_AUTOPLAY_MS)
-        : 1800;
+        : demoPace === "slow"
+          ? 3500
+          : 1800;
   for (let i = 0; i < slides.length; i++) {
     const s = slides[i];
     const caption = formatHighlightCaption(s);
+    const slideTone = normalizeHighlightTone(s.tone);
     const isLast = i === slides.length - 1;
-    const dwellMs = resolveFixtureDwellMs(s, { gatesFast });
+    const dwellMs = resolveFixtureDwellMs(s, { gatesFast, pace: demoPace });
     await installOverlay(page, title);
     if (s.selector) {
       try {
         const box = await page.locator(s.selector).first().boundingBox();
-        if (box) await showRing(page, box, caption, "planned");
+        if (box) await showRing(page, box, caption, slideTone);
       } catch {
         await hideRing(page);
       }
@@ -1996,7 +2031,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   // 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 };
+  const pacing = { gatesFast: demoFast, gatesSlow: false, skipTheater: false, demoPace: "normal" };
   const stubBeforeRef = { current: [] };
   instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef);
   // Force the panel checkbox from this process's flags/env at run start.
@@ -2087,7 +2122,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       ? Math.min(80, autoplayMs)
       : pacing.gatesFast
         ? Math.min(400, autoplayMs)
-        : autoplayMs;
+        : pacing.gatesSlow
+          ? Math.max(autoplayMs * 2, 3500)
+          : autoplayMs;
     let elapsed = 0;
     for (;;) {
       // Re-read the checkbox EVERY loop tick, not once up front - a human
@@ -2171,10 +2208,33 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       await resetPageState(context, page, baseURL);
     }
     // gatesFast / skipTheater: opaque FF, former-FF inners (--ff-disabled/--ff-expand),
-    // or WAYGRAPH_FAST_BLOCKS. --fast alone = shorter gates only (keeps theater).
-    pacing.gatesFast = demoFast || !!r.block.fastForward || !!r.wasFastForward;
+    // WAYGRAPH_FAST_BLOCKS, or withDemoPace/withBlockPace. --fast alone = shorter
+    // gates only (keeps theater). Episode pace: block > flow > CLI --fast.
+    const stepPace = resolveStepDemoPace({
+      blockPace: r.block.demoPace,
+      flowPace: r.demoPace,
+      fastForward: !!r.block.fastForward,
+      wasFastForward: !!r.wasFastForward,
+    });
+    const cliFast = demoFast || fastBlockNames.has(r.block.name);
+    pacing.demoPace =
+      stepPace === "normal" && cliFast
+        ? fastBlockNames.has(r.block.name)
+          ? "blitz"
+          : "fast"
+        : stepPace;
+    pacing.gatesFast =
+      pacing.demoPace === "blitz" ||
+      pacing.demoPace === "fast" ||
+      !!r.block.fastForward ||
+      !!r.wasFastForward ||
+      demoFast;
+    pacing.gatesSlow = pacing.demoPace === "slow";
     pacing.skipTheater =
-      fastBlockNames.has(r.block.name) || !!r.block.fastForward || !!r.wasFastForward;
+      pacing.demoPace === "blitz" ||
+      fastBlockNames.has(r.block.name) ||
+      !!r.block.fastForward ||
+      !!r.wasFastForward;
     const fixtures = r.highlightFixtures;
     stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures });
     const isNavBlock = r.block.__waygraphKind === "nav";
@@ -2273,7 +2333,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           label: formatHighlightCaption(h),
           duration: h.duration,
           fastMode: h.fastMode,
-          tone: "planned",
+          tone: normalizeHighlightTone(h.tone),
         }));
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
           defaultHoldMs: 2000,
@@ -2333,6 +2393,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         title,
         blockName: r.block.name,
         fast: pacing.gatesFast,
+        pace: pacing.demoPace,
         episodeNumber: r.episodeNumber,
         episodeTitle: r.episodeTitle,
         autoplayMs,
@@ -2346,7 +2407,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           label: formatHighlightCaption(h),
           duration: h.duration,
           fastMode: h.fastMode,
-          tone: "planned",
+          tone: normalizeHighlightTone(h.tone),
         }),
       );
     } else {
@@ -2531,6 +2592,7 @@ async function main() {
         exportName: bi.name,
         seedMem: idx === 0 ? seedMem : undefined,
         highlightFixtures: flow.highlightFixtures,
+        demoPace: flow.demoPace,
         expectedFailureReason:
           flow.expectedFailureReason && idx === blockInfos.length - 1
             ? flow.expectedFailureReason
@@ -2599,6 +2661,7 @@ async function main() {
           episodeTitle: flow.title || seg.ref,
           expectedFailureReason: flow.expectedFailureReason,
           highlightFixtures: flow.highlightFixtures,
+          demoPace: flow.demoPace,
           seedMem: () => seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref),
         });
       } else {
@@ -2608,6 +2671,7 @@ async function main() {
           episodeNumber: undefined,
           episodeTitle: undefined,
           highlightFixtures: undefined,
+          demoPace: undefined,
           seedMem: () => seedMemForBlock(mem, r, seg.json),
         });
       }
@@ -2632,6 +2696,7 @@ async function main() {
         episodeNumber: meta.episodeNumber,
         episodeTitle: meta.episodeTitle,
         highlightFixtures: meta.highlightFixtures,
+        demoPace: meta.demoPace,
         expectedFailureReason:
           meta.expectedFailureReason && remainingInFlow === 1 ? meta.expectedFailureReason : undefined,
         seedMem: isFirstOfSegment ? meta.seedMem : undefined,
@@ -2674,8 +2739,8 @@ async function main() {
   if (step && hasFfBlitz && process.env.WAYGRAPH_SLOWMO === undefined && !jsonReport) {
     console.error(
       ffDisabled
-        ? "waygraph demo: --ff-disabled (expanded) → Playwright slowMo=0 on former FF steps (blitz; same acts as opaque FF)"
-        : "waygraph demo: opaque FFCompose in flow → Playwright slowMo=0 (blitz); set WAYGRAPH_SLOWMO to override",
+        ? "waygraph demo: --ff-disabled (expanded) -> Playwright slowMo=0 on former FF steps (blitz; same acts as opaque FF)"
+        : "waygraph demo: opaque FFCompose in flow -> Playwright slowMo=0 (blitz); set WAYGRAPH_SLOWMO to override",
     );
   }
   const baseURL = process.env.WAYGRAPH_BASE_URL;
@@ -3716,8 +3781,10 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
-  waygraph traverse [project]              Serial graph crawl (Phase B+)
+  waygraph traverse [project]              Graph crawl (Phase B+D)
                  --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
                  --from <Checkpoint>       Seed / start checkpoint
                  --data '{...}'            Mem seed
                  --max-steps N             Cap Block runs (default 50)
@@ -3743,6 +3810,7 @@ Examples:
   waygraph auto --blocks LoginPage OrderComplete
   waygraph auto --blocks '/mailpit/'                     # Phase C filtered explore
   waygraph traverse --blocks '**/mailpit/**/*.block.ts'  # Phase C filtered crawl
+  waygraph traverse --parallel 2 --session clone         # Phase D clone workers
   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;
@@ -3837,6 +3905,8 @@ async function main() {
             let headed = false;
             let baseUrl;
             let blocksFilter;
+            let parallel;
+            let session;
             let projectDir = process.cwd();
             for (let i = 0; i < rest.length; i++) {
                 const a = rest[i];
@@ -3862,6 +3932,20 @@ async function main() {
                     }
                     continue;
                 }
+                if (a === "--parallel" || a.startsWith("--parallel=")) {
+                    const v = a.startsWith("--parallel=") ? a.slice("--parallel=".length) : rest[++i];
+                    parallel = Number(v);
+                    continue;
+                }
+                if (a === "--session" || a.startsWith("--session=")) {
+                    const v = a.startsWith("--session=") ? a.slice("--session=".length) : rest[++i];
+                    if (v !== "clone" && v !== "inherit") {
+                        console.error('waygraph traverse: --session must be "clone" or "inherit"');
+                        process.exit(1);
+                    }
+                    session = v;
+                    continue;
+                }
                 if (a === "--max-steps" || a.startsWith("--max-steps=")) {
                     const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
                     maxSteps = Number(v);
@@ -3890,13 +3974,15 @@ async function main() {
                 if (a === "--help" || a === "-h") {
                     console.log(`waygraph traverse [project] [flags]
 
-Serial graph crawl (RFC Phase B). Walks unused legal edges until a leaf,
-budget kill, or first broken edge.
+Graph crawl (RFC Phase B+D). 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
   --from <Checkpoint>     start checkpoint (optional)
   --data '{...}'          Mem seed JSON
-  --max-steps N           default 50
+  --max-steps N           default 50 (per worker)
   --max-visits N          per-node visit cap (default 2)
   --max-visits-per-edge N default 1
   --non-headless          show browser
@@ -3904,7 +3990,7 @@ budget kill, or first broken edge.
 
 Examples:
   waygraph traverse --blocks '**/mailpit/**/*.block.ts'
-  waygraph traverse --blocks '/mailpit|login/'
+  waygraph traverse --parallel 2 --session clone --max-steps 20
 
 PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
 FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
@@ -3935,6 +4021,8 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                 headed,
                 ...(baseUrl ? { baseURL: baseUrl } : {}),
                 ...(blocksSelect ? { blocksSelect } : {}),
+                ...(parallel !== undefined && Number.isFinite(parallel) ? { parallel } : {}),
+                ...(session ? { session } : {}),
             });
             process.exit(code);
         }

package/dist/engine.d.ts

@@ -186,6 +186,11 @@ export interface Flow<Out extends Checkpoint<string>> {
      * block.name. `run()` never reads this; step/`demo` merges onto block stubs.
      */
     readonly highlightFixtures?: import("./highlights.js").HighlightFixtureMap;
+    /**
+     * Demo pacing for this Flow's episode (`withDemoPace`).
+     * `run()` ignores; step/demo applies per Block in the episode.
+     */
+    readonly demoPace?: import("./highlights.js").DemoPace;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -253,6 +258,18 @@ export declare function withSessionReset<Out extends Checkpoint<string>>(flow: F
  * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
  */
 export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
+/**
+ * Demo pacing for a whole Flow episode (fast review vs slow gap/wrong walkthrough).
+ * Non-destructive. `fastForwardComposeBlock` is always blitz for its own step;
+ * use this when an entire episode should be fast or slow.
+ * @example withDemoPace(withTitle(gapFlow, "Episode 2 - gaps"), "slow")
+ */
+export declare function withDemoPace<Out extends Checkpoint<string>>(flow: Flow<Out>, pace: import("./highlights.js").DemoPace): Flow<Out>;
+/**
+ * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
+ * @example withBlockPace(composeBlock("gap-review", [...]), "slow")
+ */
+export declare function withBlockPace<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, pace: import("./highlights.js").DemoPace): Block<In, Out>;
 /**
  * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
  * login attempt genuinely failing, demonstrating the app's own real

package/dist/engine.js

@@ -351,6 +351,31 @@ export function withTitle(flow, title) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
     };
 }
+/**
+ * Demo pacing for a whole Flow episode (fast review vs slow gap/wrong walkthrough).
+ * Non-destructive. `fastForwardComposeBlock` is always blitz for its own step;
+ * use this when an entire episode should be fast or slow.
+ * @example withDemoPace(withTitle(gapFlow, "Episode 2 - gaps"), "slow")
+ */
+export function withDemoPace(flow, pace) {
+    const demoPace = pace;
+    return {
+        ...flow,
+        demoPace,
+        withBlockVerify: (block, verify) => withDemoPace(flow.withBlockVerify(block, verify), demoPace),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withDemoPace(flow.modBlockVerify(block, nameOrIndex, newCheck), demoPace),
+    };
+}
+/**
+ * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
+ * @example withBlockPace(composeBlock("gap-review", [...]), "slow")
+ */
+export function withBlockPace(block, pace) {
+    return {
+        ...block,
+        demoPace: pace,
+    };
+}
 /**
  * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
  * login attempt genuinely failing, demonstrating the app's own real

package/dist/highlights.d.ts

@@ -33,9 +33,16 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
     detail?: string;
     /** Short badge, e.g. AC / BUG / GATE / YAP. */
     tag?: string;
+    /**
+     * Demo ring color + icon:
+     * - `planned` purple (authored narration, default)
+     * - `auto` gray (engine automation / verify fallback)
+     * - `info` blue · `warning` yellow · `danger` red · `success` green
+     */
+    tone?: HighlightTone;
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag"> & FixtureDurationFields;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | ((out: Out) => HighlightStubPhase);
 /**
@@ -49,11 +56,32 @@ export interface WaygraphSlide extends FixtureDurationFields {
     tag?: string;
     /** Optional ring while this slide is showing. */
     selector?: string;
+    tone?: HighlightTone;
 }
+/**
+ * Demo ring tones (iconified).
+ * Automation (`auto`) is gray so authored planned/info/warning/danger/success stand out.
+ */
+export type HighlightTone = "planned" | "auto" | "info" | "warning" | "danger" | "success";
+/** Map author aliases (`error` -> danger) to a canonical tone. */
+export declare function normalizeHighlightTone(raw: unknown): HighlightTone;
+/** Prefix label with a short ASCII icon for semantic tones. */
+export declare function toneIconPrefix(tone: HighlightTone): string;
+/**
+ * Demo pacing for a Flow episode or a Block/compose group.
+ * - `blitz` - FF-like: skip theater + short gates (same as fastForwardComposeBlock)
+ * - `fast` - shorter gates, keep cursor theater
+ * - `normal` - default demo pace
+ * - `slow` - longer autoplay + fixture dwell (gaps / wrongs review)
+ */
+export type DemoPace = "blitz" | "fast" | "normal" | "slow";
+export declare function normalizeDemoPace(raw: unknown): DemoPace;
 /** Default fixture dwell when `duration: true`. */
 export declare const FIXTURE_DURATION_MS_DEFAULT = 2000;
 /** Default fixture dwell under `--fast` when duration is enabled. */
 export declare const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
+/** Default fixture dwell under demo pace `slow` (gaps / wrongs review). */
+export declare const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
 /** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
 export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
@@ -64,11 +92,23 @@ export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
  */
 export declare function resolveFixtureDwellMs(fixture: FixtureDurationFields, opts?: {
     gatesFast?: boolean;
+    pace?: DemoPace;
 }): number | null;
 /** @deprecated Prefer {@link resolveFixtureDwellMs} */
 export declare function resolveSlideDwellMs(slide: FixtureDurationFields, opts?: {
     gatesFast?: boolean;
+    pace?: DemoPace;
 }): number | null;
+/**
+ * Effective demo pace for a step: block override > flow episode > normal.
+ * Opaque FF / wasFastForward always win as blitz.
+ */
+export declare function resolveStepDemoPace(opts: {
+    blockPace?: DemoPace | string | null;
+    flowPace?: DemoPace | string | null;
+    fastForward?: boolean;
+    wasFastForward?: boolean;
+}): DemoPace;
 export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
 /** Demo stub phase names (block instruction + flow fixtures). */
 export type HighlightStubPhaseName = "stubBefore" | "stubAfter" | "stubOnError";
@@ -85,6 +125,7 @@ export type HighlightFixtureMap = Record<string, {
 export interface WaygraphHighlight {
     selector: string;
     label: string;
+    tone?: HighlightTone;
 }
 export type ResolvedHighlight = WaygraphHighlightStub;
 /**
@@ -104,12 +145,13 @@ export declare function resolveSlides(block: Block<any, any>, opts?: {
     out?: Checkpoint<string>;
     fixtures?: HighlightFixtureMap;
 }): WaygraphSlide[];
-/** Caption for ring / slide UI (label|caption + optional detail/tag). */
+/** Caption for ring / slide UI (label|caption + optional detail/tag + tone icon). */
 export declare function formatHighlightCaption(h: {
     label?: string;
     caption?: string;
     detail?: string;
     tag?: string;
+    tone?: HighlightTone | string;
 }): string;
 /**
  * True when the block authored a non-empty stubAfter (after resolve + shim),

package/dist/highlights.js

@@ -8,10 +8,56 @@
  * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
  * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
+const TONE_ICONS = {
+    planned: "",
+    auto: "",
+    info: "i",
+    warning: "!",
+    danger: "x",
+    success: "+",
+};
+/** Map author aliases (`error` -> danger) to a canonical tone. */
+export function normalizeHighlightTone(raw) {
+    if (typeof raw !== "string")
+        return "planned";
+    const t = raw.trim().toLowerCase();
+    if (t === "auto" || t === "automation" || t === "engine")
+        return "auto";
+    if (t === "info" || t === "blue")
+        return "info";
+    if (t === "warning" || t === "warn" || t === "yellow")
+        return "warning";
+    if (t === "danger" || t === "error" || t === "red")
+        return "danger";
+    if (t === "success" || t === "ok" || t === "green")
+        return "success";
+    if (t === "planned" || t === "purple" || t === "authored")
+        return "planned";
+    return "planned";
+}
+/** Prefix label with a short ASCII icon for semantic tones. */
+export function toneIconPrefix(tone) {
+    const icon = TONE_ICONS[tone];
+    return icon ? `[${icon}] ` : "";
+}
+export function normalizeDemoPace(raw) {
+    if (typeof raw !== "string")
+        return "normal";
+    const t = raw.trim().toLowerCase();
+    if (t === "blitz" || t === "ff")
+        return "blitz";
+    if (t === "fast" || t === "quick")
+        return "fast";
+    if (t === "slow" || t === "careful" || t === "review")
+        return "slow";
+    return "normal";
+}
 /** Default fixture dwell when `duration: true`. */
 export const FIXTURE_DURATION_MS_DEFAULT = 2000;
 /** Default fixture dwell under `--fast` when duration is enabled. */
 export const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
+/** Default fixture dwell under demo pace `slow` (gaps / wrongs review). */
+export const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
 /** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
 export const SLIDE_DURATION_MS_DEFAULT = FIXTURE_DURATION_MS_DEFAULT;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
@@ -23,23 +69,40 @@ export const SLIDE_DURATION_FAST_MS_DEFAULT = FIXTURE_DURATION_FAST_MS_DEFAULT;
 export function resolveFixtureDwellMs(fixture, opts) {
     if (fixture.duration === undefined || fixture.duration === false)
         return null;
-    const fast = !!opts?.gatesFast;
+    const pace = normalizeDemoPace(opts?.pace ?? (opts?.gatesFast ? "fast" : "normal"));
     const fastMs = typeof fixture.fastMode === "number" && Number.isFinite(fixture.fastMode) && fixture.fastMode >= 0
         ? fixture.fastMode
         : FIXTURE_DURATION_FAST_MS_DEFAULT;
-    if (fast)
+    if (pace === "blitz" || pace === "fast" || opts?.gatesFast)
         return fastMs;
-    if (fixture.duration === true)
-        return FIXTURE_DURATION_MS_DEFAULT;
-    if (typeof fixture.duration === "number" && Number.isFinite(fixture.duration) && fixture.duration >= 0) {
-        return fixture.duration;
-    }
-    return FIXTURE_DURATION_MS_DEFAULT;
+    const normalMs = fixture.duration === true
+        ? FIXTURE_DURATION_MS_DEFAULT
+        : typeof fixture.duration === "number" && Number.isFinite(fixture.duration) && fixture.duration >= 0
+            ? fixture.duration
+            : FIXTURE_DURATION_MS_DEFAULT;
+    if (pace === "slow")
+        return Math.max(normalMs, FIXTURE_DURATION_SLOW_MS_DEFAULT);
+    return normalMs;
 }
 /** @deprecated Prefer {@link resolveFixtureDwellMs} */
 export function resolveSlideDwellMs(slide, opts) {
     return resolveFixtureDwellMs(slide, opts);
 }
+/**
+ * Effective demo pace for a step: block override > flow episode > normal.
+ * Opaque FF / wasFastForward always win as blitz.
+ */
+export function resolveStepDemoPace(opts) {
+    if (opts.fastForward || opts.wasFastForward)
+        return "blitz";
+    if (opts.blockPace != null && opts.blockPace !== "") {
+        return normalizeDemoPace(opts.blockPace);
+    }
+    if (opts.flowPace != null && opts.flowPace !== "") {
+        return normalizeDemoPace(opts.flowPace);
+    }
+    return "normal";
+}
 function isStubPhase(v) {
     return !!v && typeof v === "object" && !Array.isArray(v);
 }
@@ -65,6 +128,7 @@ function mergeSlot(base, patch) {
             label: patch.label,
             ...(patch.detail ? { detail: patch.detail } : {}),
             ...(patch.tag ? { tag: patch.tag } : {}),
+            ...(patch.tone ? { tone: normalizeHighlightTone(patch.tone) } : {}),
             ...dwell,
         };
     }
@@ -79,6 +143,11 @@ function mergeSlot(base, patch) {
                 ? { detail: base.detail }
                 : {}),
         ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
+        ...(patch.tone !== undefined
+            ? { tone: normalizeHighlightTone(patch.tone) }
+            : base.tone
+                ? { tone: normalizeHighlightTone(base.tone) }
+                : {}),
         ...dwell,
     };
 }
@@ -88,7 +157,11 @@ function phaseFromLegacyHighlights(highlights) {
         return out;
     highlights.forEach((h, i) => {
         if (h && typeof h.selector === "string" && typeof h.label === "string") {
-            out[String(i)] = { selector: h.selector, label: h.label };
+            out[String(i)] = {
+                selector: h.selector,
+                label: h.label,
+                ...(h.tone ? { tone: normalizeHighlightTone(h.tone) } : {}),
+            };
         }
     });
     return out;
@@ -169,13 +242,15 @@ export function resolveSlides(block, opts) {
         return [];
     return raw.filter((s) => s && typeof s.caption === "string" && s.caption.length > 0);
 }
-/** Caption for ring / slide UI (label|caption + optional detail/tag). */
+/** Caption for ring / slide UI (label|caption + optional detail/tag + tone icon). */
 export function formatHighlightCaption(h) {
-    const primary = h.caption ?? h.label ?? "";
+    const tone = normalizeHighlightTone(h.tone);
+    const icon = toneIconPrefix(tone);
+    const primary = (h.label ?? h.caption ?? "").trim();
     const tag = h.tag ? `[${h.tag}] ` : "";
     if (h.detail)
-        return `${tag}${primary} - ${h.detail}`;
-    return `${tag}${primary}`;
+        return `${icon}${tag}${primary} - ${h.detail}`;
+    return `${icon}${tag}${primary}`;
 }
 /**
  * True when the block authored a non-empty stubAfter (after resolve + shim),

package/dist/index.d.ts

@@ -2,12 +2,15 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 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, 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 type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, } from "./highlights.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, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, toneIconPrefix, resolveStepDemoPace, 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, DemoPace, } 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";
 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";
+export { EdgeLeaseCoordinator } from "./traverse-lease.js";
+export { runTraverse } from "./traverse-run.js";
+export type { TraverseOptions, TraverseSessionMode } from "./traverse-run.js";

package/dist/index.js

@@ -1,7 +1,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, 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 { 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, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, toneIconPrefix, resolveStepDemoPace, 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";

package/dist/step-overlay.d.ts

@@ -3,7 +3,7 @@ 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 (automation = yellow). */
+/** Demo cursor + ring on fill/click during auto explore headful runs (automation = gray). */
 export declare function instrumentInteractionHighlighting(page: Page, mem: MemPage, slowMo: number): void;
 declare global {
     interface Window {

package/dist/step-overlay.js

@@ -1,11 +1,20 @@
 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-color .15s,box-shadow .15s;}" +
-    "#wg-ring[data-tone=auto]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
+    // Automation = gray; semantic tones for authored highlights.
+    "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
+    "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
+    "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
+    "#wg-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}" +
+    "#wg-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.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,background .15s,color .15s;}" +
-    "#wg-ring-label[data-tone=auto]{background:#EAB308;color:#1c1917;}" +
+    "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
+    "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
+    "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
+    "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
+    "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
     "#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;" +
@@ -13,7 +22,11 @@ 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[data-tone=auto]{border-color:#9CA3AF;background:rgba(156,163,175,.28);}" +
+    "#wg-click-pulse[data-tone=info]{border-color:#3B82F6;background:rgba(59,130,246,.28);}" +
+    "#wg-click-pulse[data-tone=warning]{border-color:#EAB308;background:rgba(234,179,8,.28);}" +
+    "#wg-click-pulse[data-tone=danger]{border-color:#EF4444;background:rgba(239,68,68,.28);}" +
+    "#wg-click-pulse[data-tone=success]{border-color:#22C55E;background:rgba(34,197,94,.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;" +
@@ -65,7 +78,15 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             const pulse = document.getElementById("wg-click-pulse");
             if (!pulse)
                 return;
-            pulse.dataset.tone = tone === "auto" ? "auto" : "planned";
+            const raw = (tone || "planned") + "";
+            pulse.dataset.tone =
+                raw === "auto" ||
+                    raw === "info" ||
+                    raw === "warning" ||
+                    raw === "danger" ||
+                    raw === "success"
+                    ? raw
+                    : "planned";
             pulse.style.left = x + "px";
             pulse.style.top = y + "px";
             pulse.classList.remove("wg-pulse");
@@ -77,7 +98,14 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             const ringLabel = document.getElementById("wg-ring-label");
             if (!ring || !ringLabel)
                 return;
-            const t = tone === "auto" ? "auto" : "planned";
+            const raw = (tone || "planned") + "";
+            const t = raw === "auto" ||
+                raw === "info" ||
+                raw === "warning" ||
+                raw === "danger" ||
+                raw === "success"
+                ? raw
+                : "planned";
             ring.dataset.tone = t;
             ringLabel.dataset.tone = t;
             ring.style.left = box.x - 6 + "px";
@@ -136,7 +164,7 @@ async function clickPulseAt(page, x, y, tone = "auto") {
         .evaluate(({ x, y, tone }) => window.__wgClickPulse?.(x, y, tone), { x, y, tone })
         .catch(() => { });
 }
-/** Demo cursor + ring on fill/click during auto explore headful runs (automation = yellow). */
+/** Demo cursor + ring on fill/click during auto explore headful runs (automation = gray). */
 export function instrumentInteractionHighlighting(page, mem, slowMo) {
     const typeDelay = () => (slowMo ? 0 : 30);
     const clickPrePop = () => (slowMo ? 300 : 700);

package/dist/traverse-lease.d.ts

@@ -0,0 +1,18 @@
+export interface EdgeLeaseRecord {
+    workerId: string;
+    claimedAt: number;
+}
+export declare class EdgeLeaseCoordinator {
+    private readonly held;
+    private readonly dir;
+    constructor(opts?: {
+        projectDir?: string;
+        persist?: boolean;
+    });
+    /** True if this worker now owns `edgeKey` (or already owned it). */
+    tryClaim(edgeKey: string, workerId: string): boolean;
+    release(edgeKey: string, workerId: string): void;
+    /** Stable partition: same key always maps to the same worker index. */
+    static partitionIndex(edgeKey: string, parallel: number): number;
+    private flush;
+}

package/dist/traverse-lease.js

@@ -0,0 +1,62 @@
+/**
+ * Phase D: edge leases so parallel traverse workers never claim the same edge.
+ * In-process Map is authoritative for `--parallel` (same Node process).
+ * Optional JSON under `.waygraph-traverse/` is an audit trail only.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export class EdgeLeaseCoordinator {
+    held = new Map();
+    dir;
+    constructor(opts) {
+        if (opts?.persist && opts.projectDir) {
+            this.dir = join(opts.projectDir, ".waygraph-traverse");
+            if (!existsSync(this.dir))
+                mkdirSync(this.dir, { recursive: true });
+        }
+        else {
+            this.dir = null;
+        }
+    }
+    /** True if this worker now owns `edgeKey` (or already owned it). */
+    tryClaim(edgeKey, workerId) {
+        const cur = this.held.get(edgeKey);
+        if (cur && cur.workerId !== workerId)
+            return false;
+        this.held.set(edgeKey, { workerId, claimedAt: Date.now() });
+        this.flush();
+        return true;
+    }
+    release(edgeKey, workerId) {
+        const cur = this.held.get(edgeKey);
+        if (cur && cur.workerId === workerId) {
+            this.held.delete(edgeKey);
+            this.flush();
+        }
+    }
+    /** Stable partition: same key always maps to the same worker index. */
+    static partitionIndex(edgeKey, parallel) {
+        if (parallel <= 1)
+            return 0;
+        let h = 2166136261;
+        for (let i = 0; i < edgeKey.length; i++) {
+            h ^= edgeKey.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+        }
+        return (h >>> 0) % parallel;
+    }
+    flush() {
+        if (!this.dir)
+            return;
+        try {
+            const payload = {
+                updatedAt: new Date().toISOString(),
+                leases: Object.fromEntries(this.held),
+            };
+            writeFileSync(join(this.dir, "leases.json"), JSON.stringify(payload, null, 2));
+        }
+        catch {
+            /* audit only */
+        }
+    }
+}

package/dist/traverse-run.d.ts

@@ -1,3 +1,4 @@
+export type TraverseSessionMode = "clone" | "inherit";
 export interface TraverseOptions {
     baseURL?: string;
     startUrl?: string;
@@ -19,8 +20,12 @@ export interface TraverseOptions {
     traverseId?: string;
     /** Phase C: glob / regex / bare `--blocks` file select. */
     blocksSelect?: import("./blocks-select.js").BlocksSelect;
+    /** Phase D: parallel workers (default 1). Cap 4. */
+    parallel?: number;
+    /** Phase D: clone (default) or inherit. Inherit refused when parallel > 1. */
+    session?: TraverseSessionMode;
 }
 /**
- * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
  */
 export declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;

package/dist/traverse-run.js

@@ -1,6 +1,6 @@
 /**
- * Phase B: serial graph traverse (RFC traverse-ffcompose).
- * Walk unused legal edges until leaf / budget / break. No parallel yet.
+ * Phase B+D: graph traverse (serial or --parallel with --session clone).
+ * Walk unused legal edges until leaf / budget / break.
  */
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -8,6 +8,7 @@ import { Engine, start, end, locate } from "./engine.js";
 import { MemPage } from "./mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { defaultMemValueForKey } from "./auto-explore-run.js";
+import { EdgeLeaseCoordinator } from "./traverse-lease.js";
 function resolveBaseUrl(projectDir) {
     if (process.env.WAYGRAPH_BASE_URL)
         return process.env.WAYGRAPH_BASE_URL;
@@ -47,6 +48,32 @@ function seedMem(library, mem, dataJson) {
         }
     }
 }
+function snapshotMem(library, mem) {
+    const out = {};
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k) && !(k.name in out)) {
+                try {
+                    out[k.name] = mem.get(k);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+    }
+    return out;
+}
+function restoreMem(library, mem, snap, dataJson) {
+    seedMem(library, mem, dataJson);
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (k.name in snap) {
+                mem.set(k, snap[k.name]);
+            }
+        }
+    }
+}
 function missingMemKeys(entry, mem) {
     return (entry.block.requires ?? []).filter((k) => !mem.has(k));
 }
@@ -94,56 +121,18 @@ async function runOneBlock(engine, entry, context, page, mem) {
             clearTimeout(timer);
     }
 }
-/**
- * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
- */
-export async function runTraverse(projectDir, options = {}) {
-    const traverseId = options.traverseId ?? "traverse-1";
-    const maxSteps = options.maxSteps ?? 50;
-    const maxVisitsPerNode = options.maxVisitsPerNode ?? 2;
-    const maxVisitsPerEdge = options.maxVisitsPerEdge ?? 1;
-    const timeoutMs = options.timeoutMs ?? 15 * 60_000;
-    const headed = options.headed === true || process.env.WAYGRAPH_HEADED === "1";
-    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
-    const startUrl = options.startUrl ?? baseURL;
-    const { graph, library } = await buildExploreContext(projectDir, 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 });
-    const { chromium } = await import("@playwright/test");
-    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
-    const launchOpts = {
-        headless: !headed,
-    };
-    if (executablePath)
-        launchOpts.executablePath = executablePath;
-    const browser = await chromium.launch(launchOpts);
-    const contextOpts = {
-        viewport: { width: 1280, height: 720 },
-    };
-    if (baseURL)
-        contextOpts.baseURL = baseURL;
-    const context = await browser.newContext(contextOpts);
-    let page = await context.newPage();
+async function runTraverseWorker(opts) {
+    const { traverseId, workerIndex, parallel, maxSteps, maxVisitsPerNode, maxVisitsPerEdge, timeoutMs, graph, library, engine, context, mem, leases, } = opts;
+    let page = opts.page;
+    const startUrl = opts.startUrl;
     const nodeVisits = new Map();
     const edgeVisits = new Map();
     const edgesHit = new Set();
     let steps = 0;
     const startedAt = Date.now();
-    let lastHere = options.from ?? null;
+    let lastHere = opts.from ?? null;
     let exitCode = 0;
-    console.error(`waygraph traverse[${traverseId}]: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
-        (baseURL ? ` base=${baseURL}` : "") +
-        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}`);
     try {
-        if (startUrl) {
-            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-            await page.waitForLoadState("load").catch(() => { });
-        }
         for (;;) {
             if (Date.now() - startedAt > timeoutMs) {
                 console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
@@ -162,7 +151,7 @@ export async function runTraverse(projectDir, options = {}) {
                 }
             }
             const detected = await detectHere(page, library.navBlocks);
-            const here = lastHere ?? detected ?? options.from ?? null;
+            const here = lastHere ?? detected ?? opts.from ?? null;
             if (here && (nodeVisits.get(here) ?? 0) >= maxVisitsPerNode) {
                 console.log(`[Killed loop[${traverseId}] node=${here} visits=${nodeVisits.get(here)} max=${maxVisitsPerNode}]`);
                 exitCode = 1;
@@ -171,7 +160,14 @@ export async function runTraverse(projectDir, options = {}) {
             const menu = await buildExploreMenu(page, graph, library, here);
             const candidates = menu.flat.filter((edge) => {
                 const key = edgeKey(edge);
-                return (edgeVisits.get(key) ?? 0) < maxVisitsPerEdge;
+                if ((edgeVisits.get(key) ?? 0) >= maxVisitsPerEdge)
+                    return false;
+                if (parallel > 1) {
+                    if (EdgeLeaseCoordinator.partitionIndex(key, parallel) !== workerIndex) {
+                        return false;
+                    }
+                }
+                return true;
             });
             if (candidates.length === 0) {
                 const label = here ?? detected ?? "unknown";
@@ -186,6 +182,12 @@ export async function runTraverse(projectDir, options = {}) {
                     return aWild - bWild;
                 return edgeKey(a).localeCompare(edgeKey(b));
             })[0];
+            const key = edgeKey(pick);
+            if (!leases.tryClaim(key, traverseId)) {
+                // Another worker won a race (instance fan-out); treat as unavailable.
+                edgeVisits.set(key, maxVisitsPerEdge);
+                continue;
+            }
             const entry = library.byName.get(pick.block);
             if (!entry) {
                 console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${here ?? "?"} to=${pick.to} reason=not-loaded]`);
@@ -204,7 +206,6 @@ export async function runTraverse(projectDir, options = {}) {
                 const observed = typeof out === "object" && out && "__state" in out
                     ? String(out.__state)
                     : pick.to;
-                const key = edgeKey(pick);
                 edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
                 edgesHit.add(key);
                 if (here)
@@ -224,8 +225,153 @@ export async function runTraverse(projectDir, options = {}) {
         }
     }
     finally {
-        await browser.close().catch(() => { });
+        console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
     }
-    console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
     return exitCode;
 }
+/**
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
+ */
+export async function runTraverse(projectDir, options = {}) {
+    let parallel = Math.max(1, Math.floor(options.parallel ?? 1));
+    if (parallel > 4) {
+        console.error(`waygraph traverse: --parallel ${parallel} capped to 4`);
+        parallel = 4;
+    }
+    const session = options.session ?? (parallel > 1 ? "clone" : "clone");
+    if (parallel > 1 && session === "inherit") {
+        console.error("waygraph traverse: --session inherit is refused with --parallel > 1 (races); use --session clone");
+        return 1;
+    }
+    const maxSteps = options.maxSteps ?? 50;
+    const maxVisitsPerNode = options.maxVisitsPerNode ?? 2;
+    const maxVisitsPerEdge = options.maxVisitsPerEdge ?? 1;
+    const timeoutMs = options.timeoutMs ?? 15 * 60_000;
+    const headed = options.headed === true || process.env.WAYGRAPH_HEADED === "1";
+    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
+    const startUrl = options.startUrl ?? baseURL;
+    const { graph, library } = await buildExploreContext(projectDir, 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 leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
+    const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
+    const { chromium } = await import("@playwright/test");
+    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    const launchOpts = {
+        headless: !headed,
+    };
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    const browser = await chromium.launch(launchOpts);
+    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}`);
+    try {
+        if (parallel <= 1) {
+            const contextOpts = {
+                viewport: { width: 1280, height: 720 },
+            };
+            if (baseURL)
+                contextOpts.baseURL = baseURL;
+            const context = await browser.newContext(contextOpts);
+            const page = await context.newPage();
+            const mem = new MemPage();
+            seedMem(library.byName, mem, options.data);
+            if (startUrl) {
+                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+                await page.waitForLoadState("load").catch(() => { });
+            }
+            const code = await runTraverseWorker({
+                traverseId: options.traverseId ?? "traverse-1",
+                workerIndex: 0,
+                parallel: 1,
+                maxSteps,
+                maxVisitsPerNode,
+                maxVisitsPerEdge,
+                timeoutMs,
+                ...(options.from ? { from: options.from } : {}),
+                ...(startUrl ? { startUrl } : {}),
+                ...(baseURL ? { baseURL } : {}),
+                ...(options.data ? { data: options.data } : {}),
+                graph,
+                library,
+                engine,
+                context,
+                page,
+                mem,
+                leases,
+            });
+            await context.close().catch(() => { });
+            return code;
+        }
+        // Phase D: bootstrap one context for storageState, then N clones.
+        const bootOpts = {
+            viewport: { width: 1280, height: 720 },
+        };
+        if (baseURL)
+            bootOpts.baseURL = baseURL;
+        const bootContext = await browser.newContext(bootOpts);
+        const bootPage = await bootContext.newPage();
+        const bootMem = new MemPage();
+        seedMem(library.byName, bootMem, options.data);
+        if (startUrl) {
+            await bootPage.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+            await bootPage.waitForLoadState("load").catch(() => { });
+        }
+        const storageState = await bootContext.storageState();
+        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 traverseId = `traverse-${i + 1}`;
+            const ctxOpts = {
+                viewport: { width: 1280, height: 720 },
+                storageState,
+            };
+            if (baseURL)
+                ctxOpts.baseURL = baseURL;
+            const context = await browser.newContext(ctxOpts);
+            const page = await context.newPage();
+            const mem = new MemPage();
+            restoreMem(library.byName, mem, memSnap, options.data);
+            if (startUrl) {
+                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+            }
+            try {
+                return await runTraverseWorker({
+                    traverseId,
+                    workerIndex: i,
+                    parallel,
+                    maxSteps,
+                    maxVisitsPerNode,
+                    maxVisitsPerEdge,
+                    timeoutMs,
+                    ...(options.from ? { from: options.from } : {}),
+                    ...(startUrl ? { startUrl } : {}),
+                    ...(baseURL ? { baseURL } : {}),
+                    ...(options.data ? { data: options.data } : {}),
+                    graph,
+                    library,
+                    engine,
+                    context,
+                    page,
+                    mem,
+                    leases,
+                });
+            }
+            finally {
+                await context.close().catch(() => { });
+            }
+        }));
+        const worst = codes.reduce((a, b) => Math.max(a, b), 0);
+        const pass = codes.filter((c) => c === 0).length;
+        console.error(`waygraph traverse: suite parallel=${parallel} pass=${pass}/${parallel} exit=${worst}`);
+        return worst;
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}

package/dist/types.d.ts

@@ -209,6 +209,11 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * @example requires: [LoginCreds.key]
      */
     requires?: readonly MemKey<any>[];
+    /**
+     * Demo pacing for this Block or compose group (`withBlockPace`).
+     * Demo/step only - `runGraph` ignores. Prefer `fastForwardComposeBlock` for blitz.
+     */
+    demoPace?: import("./highlights.js").DemoPace;
     /**
      * Optional. When this Block's real choices depend on the live page
      * (which of several items to add to cart, which of several rows to

package/examples/saucedemo/.waygraph-traverse/leases.json

@@ -0,0 +1,29 @@
+{
+  "updatedAt": "2026-09-17T11:18:26.658Z",
+  "leases": {
+    "submit-login": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643826618
+    },
+    "add-all-to-cart": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643827327
+    },
+    "nav-cart": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643829570
+    },
+    "nav-continue-shopping": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643855282
+    },
+    "nav-item-detail::sauce-labs-backpack": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643857049
+    },
+    "nav-back-to-inventory": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643906658
+    }
+  }
+}

package/package.json

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