waygraph 0.12.14 → 0.12.15

package/README.md

@@ -233,6 +233,11 @@ Sign In narration.
 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,

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,9 +2,9 @@ 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";

package/dist/index.js

@@ -1,8 +1,8 @@
 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";

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/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/package.json

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