waygraph 0.12.17 → 0.12.19

package/README.md

@@ -238,8 +238,9 @@ snapshot, partitions edges by hash, and claims via in-process edge leases (audit
 `tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus
 `size: "sm" | "md" | "lg"` and `weight: "normal" | "bold"`. Flow episode defaults:
 `withHighlightStyle(flow, { size, weight, tone? })` (slot/fixture wins). Episode pacing:
-`withDemoPace(flow, "fast" | "slow" | "normal" | "blitz")` or `withBlockPace(block, ...)`
-(FFCompose stays blitz). Living objectives: `docs/proposals/OBJECTIVES.md`.
+`withDemoPace(flow, "fast" | "slow" | "normal" | "blitz" | number)` or `withBlockPace(block, ...)`
+(`number` `<=20` = scale vs normal, e.g. `0.5` / `2`; `>20` = absolute ms, e.g. `4500`).
+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

@@ -217,6 +217,12 @@ import {
   normalizeHighlightWeight,
   applyHighlightStyleDefaults,
   resolveStepDemoPace,
+  demoPaceGateMs,
+  demoPaceIsBlitz,
+  demoPaceIsFast,
+  demoPaceIsSlow,
+  formatDemoPaceBadge,
+  formatDemoPaceLabel,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -487,6 +493,18 @@ const RING_CSS =
   // block chain shows no episode heading at all.
   "#wg-panel .wg-episode{margin:0 0 6px;font:700 15px system-ui,sans-serif;color:#fff;" +
   "padding-bottom:6px;border-bottom:1px solid rgba(124,58,237,.35);}" +
+  // Pace chip - numbers speak in the overlay (2.5x / 4500ms / slow).
+  "#wg-panel .wg-pace{display:inline-flex;align-items:center;gap:8px;margin:0 0 10px;" +
+  "padding:6px 10px;border-radius:8px;background:rgba(124,58,237,.22);" +
+  "border:1px solid rgba(124,58,237,.45);font:600 12px/1.35 system-ui,sans-serif;color:#f0e8ff;}" +
+  "#wg-panel .wg-pace-badge{display:inline-block;padding:2px 8px;border-radius:999px;" +
+  "background:#7C3AED;color:#fff;font:800 11px/1.2 system-ui,sans-serif;letter-spacing:.04em;" +
+  "text-transform:uppercase;}" +
+  "#wg-panel .wg-pace[data-pace-kind=slow] .wg-pace-badge," +
+  "#wg-panel .wg-pace[data-pace-kind=num-slow] .wg-pace-badge{background:#EAB308;color:#1c1917;}" +
+  "#wg-panel .wg-pace[data-pace-kind=fast] .wg-pace-badge," +
+  "#wg-panel .wg-pace[data-pace-kind=blitz] .wg-pace-badge{background:#22C55E;color:#052e16;}" +
+  "#wg-panel .wg-pace[data-pace-kind=ms] .wg-pace-badge{background:#3B82F6;color:#fff;}" +
   "#wg-panel .wg-narration{margin:0 0 12px;font:italic 14px/1.4 system-ui,sans-serif;color:#f0e8ff;}" +
   "#wg-progress{height:4px;background:#2a1650;border-radius:2px;margin:0 0 12px;overflow:hidden;}" +
   "#wg-progress-bar{height:100%;background:#7C3AED;border-radius:2px;transition:width .3s ease;}" +
@@ -953,9 +971,20 @@ async function renderBeforeStep(page, info) {
       const narrationHtml = info.description
         ? "<div class=\\"wg-narration\\">" + esc(info.description) + "</div>"
         : "";
+      const paceHtml =
+        info.paceBadge || info.paceLabel
+          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+            esc(info.paceKind || "normal") +
+            "\\"><span class=\\"wg-pace-badge\\">" +
+            esc(info.paceBadge || "1x") +
+            "</span><span>" +
+            esc(info.paceLabel || "") +
+            "</span></div>"
+          : "";
       let html =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
+        paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
         narrationHtml;
@@ -991,7 +1020,12 @@ async function renderBeforeStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          stepLabel:
+            (info.index + 1) +
+            " / " +
+            info.total +
+            (info.blockName ? " · " + info.blockName : "") +
+            (info.paceBadge ? " · " + info.paceBadge : ""),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1073,6 +1107,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   // defaultHoldMs: when set (fail path), use instead of legacy 900/200 so BUG
   // rings stay visible ~2s before the error panel (PIA stubOnError RFC).
   const defaultHoldMs = opts && opts.defaultHoldMs != null ? opts.defaultHoldMs : null;
+  const pace = opts && opts.pace !== undefined ? opts.pace : undefined;
   for (let i = 0; i < list.length; i++) {
     const h = list[i];
     try {
@@ -1082,7 +1117,7 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           size: h.size,
           weight: h.weight,
         });
-        const authored = resolveFixtureDwellMs(h, { gatesFast });
+        const authored = resolveFixtureDwellMs(h, { gatesFast, pace });
         const legacyMs = i === list.length - 1 ? 200 : 900;
         const holdMs =
           authored != null ? authored : defaultHoldMs != null ? defaultHoldMs : legacyMs;
@@ -1139,7 +1174,9 @@ async function renderAfterStep(page, info) {
   // it highlights something [else] and next," not just the first one.
   // duration / fastMode on stubAfter (or flow fixtures) override the legacy
   // 900ms / 200ms holds when set.
-  await cycleHighlightRings(page, highlights, gatesFast, null);
+  await cycleHighlightRings(page, highlights, gatesFast, {
+    pace: info.pace,
+  });
   await page
     .evaluate((info) => {
       // Reused in place - see renderBeforeStep's own comment on this.
@@ -1207,9 +1244,20 @@ async function renderAfterStep(page, info) {
             .join("") +
           "</div>"
         : "";
+      const paceHtml =
+        info.paceBadge || info.paceLabel
+          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+            escA(info.paceKind || "normal") +
+            "\\"><span class=\\"wg-pace-badge\\">" +
+            escA(info.paceBadge || "1x") +
+            "</span><span>" +
+            escA(info.paceLabel || "") +
+            "</span></div>"
+          : "";
       panel.innerHTML =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
+        paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
         resultHtml +
@@ -1220,7 +1268,12 @@ async function renderAfterStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          stepLabel:
+            (info.index + 1) +
+            " / " +
+            info.total +
+            (info.blockName ? " · " + info.blockName : "") +
+            (info.paceBadge ? " · " + info.paceBadge : ""),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1322,7 +1375,12 @@ async function renderStepError(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          stepLabel:
+            (info.index + 1) +
+            " / " +
+            info.total +
+            (info.blockName ? " · " + info.blockName : "") +
+            (info.paceBadge ? " · " + info.paceBadge : ""),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1530,14 +1588,13 @@ async function presentSlides(page, slides, _gate, opts) {
   const episodeTitle = (opts && opts.episodeTitle) || "";
   const gatesFast = !!(opts && opts.fast);
   const demoPace = normalizeDemoPace((opts && opts.pace) || (gatesFast ? "fast" : "normal"));
-  const autoplayMs =
+  const baseAutoplay =
     opts && opts.autoplayMs
       ? Number(opts.autoplayMs)
       : process.env.WAYGRAPH_AUTOPLAY_MS
         ? Number(process.env.WAYGRAPH_AUTOPLAY_MS)
-        : demoPace === "slow"
-          ? 3500
-          : 1800;
+        : 1800;
+  const autoplayMs = demoPaceGateMs(demoPace, baseAutoplay);
   for (let i = 0; i < slides.length; i++) {
     const s = slides[i];
     const caption = formatHighlightCaption(s);
@@ -1577,11 +1634,22 @@ async function presentSlides(page, slides, _gate, opts) {
               (info.episodeTitle ? ": " + esc(info.episodeTitle) : "") +
               " · yap slides</div>"
             : "";
+        const paceHtml =
+          info.paceBadge || info.paceLabel
+            ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+              esc(info.paceKind || "normal") +
+              "\\"><span class=\\"wg-pace-badge\\">" +
+              esc(info.paceBadge || "1x") +
+              "</span><span>" +
+              esc(info.paceLabel || "") +
+              "</span></div>"
+            : "";
         panel.innerHTML =
           "<div class=\\"wg-chrome\\"><span class=\\"wg-chrome-title\\">waygraph demo</span>" +
           "<button type=\\"button\\" class=\\"wg-hide-btn\\" data-wg-toggle=\\"1\\">Hide</button></div>" +
           "<div class=\\"wg-body\\">" +
           episodeLine +
+          paceHtml +
           "<h3>Slide " +
           (info.index + 1) +
           " / " +
@@ -1699,6 +1767,9 @@ async function presentSlides(page, slides, _gate, opts) {
         dwellMs,
         episodeNumber: episodeNumber !== undefined ? episodeNumber : null,
         episodeTitle,
+        paceBadge: formatDemoPaceBadge(demoPace, baseAutoplay),
+        paceLabel: formatDemoPaceLabel(demoPace, baseAutoplay),
+        paceKind: demoPaceKind(demoPace),
       },
     );
     const started = Date.now();
@@ -1731,6 +1802,25 @@ async function presentSlides(page, slides, _gate, opts) {
   await hideRing(page);
 }
 
+function demoPaceKind(pace) {
+  const p = normalizeDemoPace(pace);
+  if (typeof p === "number" && p > 20) return "ms";
+  if (typeof p === "number") return demoPaceIsSlow(p) ? "num-slow" : demoPaceIsFast(p) ? "fast" : "normal";
+  if (p === "blitz" || p === "fast" || p === "slow") return p;
+  return "normal";
+}
+
+function paceSpeakFields(pace, baseAutoplayMs) {
+  const p = normalizeDemoPace(pace);
+  const base = Number.isFinite(baseAutoplayMs) && baseAutoplayMs > 0 ? baseAutoplayMs : 1800;
+  return {
+    pace: p,
+    paceBadge: formatDemoPaceBadge(p, base),
+    paceLabel: formatDemoPaceLabel(p, base),
+    paceKind: demoPaceKind(p),
+  };
+}
+
 async function hideRing(page) {
   await page
     .evaluate(() => {
@@ -2160,13 +2250,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     // gates too, not just skip its interaction dwell - otherwise autoplay
     // still stalls the full autoplayMs admiring a step that intentionally
     // ran too fast to watch.
-    const ms = pacing.skipTheater
-      ? Math.min(80, autoplayMs)
-      : pacing.gatesFast
-        ? Math.min(400, autoplayMs)
-        : pacing.gatesSlow
-          ? Math.max(autoplayMs * 2, 3500)
-          : autoplayMs;
+    const ms = demoPaceGateMs(
+      pacing.skipTheater ? "blitz" : pacing.demoPace,
+      autoplayMs,
+    );
     let elapsed = 0;
     for (;;) {
       // Re-read the checkbox EVERY loop tick, not once up front - a human
@@ -2249,31 +2336,32 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     if ((clearSession || r.resetSession) && i > 0) {
       await resetPageState(context, page, baseURL);
     }
-    // gatesFast / skipTheater: opaque FF, former-FF inners (--ff-disabled/--ff-expand),
-    // WAYGRAPH_FAST_BLOCKS, or withDemoPace/withBlockPace. --fast alone = shorter
-    // gates only (keeps theater). Episode pace: block > flow > CLI --fast.
+    // Episode pace: block > flow > CLI --fast (only when no authored pace).
+    // Authoring wins: withDemoPace("slow"|2|4500) keeps slow dwell even under --fast.
     const stepPace = resolveStepDemoPace({
       blockPace: r.block.demoPace,
       flowPace: r.demoPace,
       fastForward: !!r.block.fastForward,
       wasFastForward: !!r.wasFastForward,
     });
+    const authoredPace =
+      (r.block.demoPace != null && r.block.demoPace !== "") ||
+      (r.demoPace != null && r.demoPace !== "");
     const cliFast = demoFast || fastBlockNames.has(r.block.name);
     pacing.demoPace =
-      stepPace === "normal" && cliFast
+      stepPace === "normal" && cliFast && !authoredPace
         ? fastBlockNames.has(r.block.name)
           ? "blitz"
           : "fast"
         : stepPace;
     pacing.gatesFast =
-      pacing.demoPace === "blitz" ||
-      pacing.demoPace === "fast" ||
+      demoPaceIsFast(pacing.demoPace) ||
       !!r.block.fastForward ||
       !!r.wasFastForward ||
-      demoFast;
-    pacing.gatesSlow = pacing.demoPace === "slow";
+      (!authoredPace && demoFast);
+    pacing.gatesSlow = demoPaceIsSlow(pacing.demoPace);
     pacing.skipTheater =
-      pacing.demoPace === "blitz" ||
+      demoPaceIsBlitz(pacing.demoPace) ||
       fastBlockNames.has(r.block.name) ||
       !!r.block.fastForward ||
       !!r.wasFastForward;
@@ -2297,6 +2385,20 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       }
       return { name: k.name, value };
     });
+    const paceSpeak = paceSpeakFields(pacing.demoPace, autoplayMs);
+    if (process.env.WAYGRAPH_JSON !== "1") {
+      console.log(
+        "waygraph demo: step " +
+          (i + 1) +
+          "/" +
+          resolved.length +
+          " " +
+          r.block.name +
+          " · " +
+          paceSpeak.paceLabel +
+          (r.episodeNumber ? " · episode " + r.episodeNumber : ""),
+      );
+    }
     await renderBeforeStep(page, {
       index: i,
       total: resolved.length,
@@ -2313,6 +2415,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeTitle: r.episodeTitle,
       stepperMode,
       forceCollapsed,
+      ...paceSpeak,
     });
     const edits = await gate();
     for (const k of requires) {
@@ -2387,6 +2490,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
           defaultHoldMs: 2000,
+          pace: pacing.demoPace,
         });
       }
       // A thrown act()/observe()/a failed verify Trait used to just crash
@@ -2480,6 +2584,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       resultTag: JSON.stringify(result),
       highlights,
       gatesFast: pacing.gatesFast,
+      pace: pacing.demoPace,
+      ...paceSpeakFields(pacing.demoPace, autoplayMs),
       isLast: i === resolved.length - 1,
       allNames: moduleNames,
       allDescriptions: moduleDescriptions,

package/dist/engine.d.ts

@@ -269,6 +269,9 @@ export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out
  * 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")
+ * @example withDemoPace(happyFlow, 0.5)  // 2x faster than normal
+ * @example withDemoPace(gapFlow, 2.5)    // 2.5x slower
+ * @example withDemoPace(gapFlow, 4500)   // absolute ~4.5s gates/dwells
  */
 export declare function withDemoPace<Out extends Checkpoint<string>>(flow: Flow<Out>, pace: DemoPace): Flow<Out>;
 /**

package/dist/engine.js

@@ -357,6 +357,9 @@ export function withTitle(flow, title) {
  * 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")
+ * @example withDemoPace(happyFlow, 0.5)  // 2x faster than normal
+ * @example withDemoPace(gapFlow, 2.5)    // 2.5x slower
+ * @example withDemoPace(gapFlow, 4500)   // absolute ~4.5s gates/dwells
  */
 export function withDemoPace(flow, pace) {
     const demoPace = pace;

package/dist/highlights.d.ts

@@ -106,12 +106,14 @@ 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)
+ * - `fast` - shorter gates, keep cursor theater (~0.33x normal)
+ * - `normal` - default demo pace (1x)
+ * - `slow` - longer autoplay + fixture dwell (~2x)
+ * - `number` - scale vs normal when `<= 20` (e.g. `0.5`, `1.5`, `3`);
+ *   absolute gate/dwell ms when `> 20` (e.g. `4500`)
  */
-export type DemoPace = "blitz" | "fast" | "normal" | "slow";
-export declare function normalizeDemoPace(raw: unknown): DemoPace;
+export type DemoPaceName = "blitz" | "fast" | "normal" | "slow";
+export type DemoPace = DemoPaceName | number;
 /** Default fixture dwell when `duration: true`. */
 export declare const FIXTURE_DURATION_MS_DEFAULT = 2000;
 /** Default fixture dwell under `--fast` when duration is enabled. */
@@ -122,9 +124,31 @@ export declare const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
 export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
 export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
+export declare function normalizeDemoPace(raw: unknown): DemoPace;
+/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
+export declare function demoPaceScale(pace: DemoPace): number;
+export declare function demoPaceIsBlitz(pace: DemoPace): boolean;
+/** True when pace should use the short-gate / fast fixture path (not slow authored). */
+export declare function demoPaceIsFast(pace: DemoPace): boolean;
+export declare function demoPaceIsSlow(pace: DemoPace): boolean;
+/** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
+export declare function demoPaceGateMs(pace: DemoPace, baseAutoplayMs: number): number;
+/**
+ * Short chip for the demo panel (e.g. `2.5x`, `4500ms`, `slow`).
+ * Always printable - numbers speak in the UI, not only in code.
+ */
+export declare function formatDemoPaceBadge(pace: DemoPace, baseAutoplayMs?: number): string;
+/**
+ * Loud one-line pace description for panel + console
+ * (e.g. `pace 2.5x (~4500ms gates)` / `pace 4500ms gates (~2.25x)`).
+ */
+export declare function formatDemoPaceLabel(pace: DemoPace, baseAutoplayMs?: number): string;
 /**
  * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
  * or `null` when duration is unset (caller keeps legacy timing).
+ *
+ * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`
+ * (`gatesFast`). `--fast` only shortens when pace is unset/normal.
  */
 export declare function resolveFixtureDwellMs(fixture: FixtureDurationFields, opts?: {
     gatesFast?: boolean;
@@ -140,8 +164,8 @@ export declare function resolveSlideDwellMs(slide: FixtureDurationFields, opts?:
  * Opaque FF / wasFastForward always win as blitz.
  */
 export declare function resolveStepDemoPace(opts: {
-    blockPace?: DemoPace | string | null;
-    flowPace?: DemoPace | string | null;
+    blockPace?: DemoPace | string | number | null;
+    flowPace?: DemoPace | string | number | null;
     fastForward?: boolean;
     wasFastForward?: boolean;
 }): DemoPace;

package/dist/highlights.js

@@ -79,18 +79,6 @@ 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. */
@@ -101,24 +89,157 @@ export const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
 export const SLIDE_DURATION_MS_DEFAULT = FIXTURE_DURATION_MS_DEFAULT;
 /** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
 export const SLIDE_DURATION_FAST_MS_DEFAULT = FIXTURE_DURATION_FAST_MS_DEFAULT;
+export function normalizeDemoPace(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
+        return raw;
+    if (typeof raw === "string") {
+        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";
+        if (t === "normal" || t === "default" || t === "1x")
+            return "normal";
+        // "2x" / "0.5x"
+        if (t.endsWith("x")) {
+            const n = Number(t.slice(0, -1));
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+        const n = Number(t);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return "normal";
+}
+/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
+export function demoPaceScale(pace) {
+    if (typeof pace === "number") {
+        if (pace > 20)
+            return Math.min(10, Math.max(0.05, pace / FIXTURE_DURATION_MS_DEFAULT));
+        return Math.min(10, Math.max(0.05, pace));
+    }
+    if (pace === "blitz")
+        return 0.05;
+    if (pace === "fast")
+        return 0.33;
+    if (pace === "slow")
+        return 2;
+    return 1;
+}
+export function demoPaceIsBlitz(pace) {
+    return pace === "blitz" || (typeof pace === "number" && pace > 0 && pace <= 0.1);
+}
+/** True when pace should use the short-gate / fast fixture path (not slow authored). */
+export function demoPaceIsFast(pace) {
+    if (demoPaceIsBlitz(pace))
+        return true;
+    if (pace === "fast")
+        return true;
+    if (typeof pace === "number" && pace <= 20)
+        return pace < 0.75;
+    return false;
+}
+export function demoPaceIsSlow(pace) {
+    if (pace === "slow")
+        return true;
+    if (typeof pace === "number") {
+        if (pace > 20)
+            return pace >= 3000;
+        return pace > 1.25;
+    }
+    return false;
+}
+/** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
+export function demoPaceGateMs(pace, baseAutoplayMs) {
+    if (demoPaceIsBlitz(pace))
+        return Math.min(80, baseAutoplayMs);
+    if (typeof pace === "number" && pace > 20) {
+        return Math.min(30000, Math.max(80, Math.round(pace)));
+    }
+    const scale = demoPaceScale(pace);
+    return Math.min(30000, Math.max(80, Math.round(baseAutoplayMs * scale)));
+}
+/**
+ * Short chip for the demo panel (e.g. `2.5x`, `4500ms`, `slow`).
+ * Always printable - numbers speak in the UI, not only in code.
+ */
+export function formatDemoPaceBadge(pace, baseAutoplayMs = 1800) {
+    const p = normalizeDemoPace(pace);
+    if (typeof p === "number" && p > 20)
+        return `${Math.round(p)}ms`;
+    if (typeof p === "number") {
+        const s = Number.isInteger(p) ? String(p) : String(Math.round(p * 100) / 100);
+        return `${s}x`;
+    }
+    if (p === "blitz")
+        return "blitz";
+    if (p === "fast")
+        return "fast";
+    if (p === "slow")
+        return "slow";
+    void baseAutoplayMs;
+    return "1x";
+}
+/**
+ * Loud one-line pace description for panel + console
+ * (e.g. `pace 2.5x (~4500ms gates)` / `pace 4500ms gates (~2.25x)`).
+ */
+export function formatDemoPaceLabel(pace, baseAutoplayMs = 1800) {
+    const p = normalizeDemoPace(pace);
+    const gate = demoPaceGateMs(p, baseAutoplayMs);
+    const scale = demoPaceScale(p);
+    const scaleTxt = Number.isInteger(scale) ? String(scale) : (Math.round(scale * 100) / 100).toString();
+    if (typeof p === "number" && p > 20) {
+        return `pace ${Math.round(p)}ms gates (~${scaleTxt}x)`;
+    }
+    if (typeof p === "number") {
+        const s = Number.isInteger(p) ? String(p) : String(Math.round(p * 100) / 100);
+        return `pace ${s}x (~${gate}ms gates)`;
+    }
+    if (p === "blitz")
+        return `pace blitz (~${gate}ms, skip theater)`;
+    if (p === "fast")
+        return `pace fast (~${scaleTxt}x, ~${gate}ms gates)`;
+    if (p === "slow")
+        return `pace slow (~${scaleTxt}x, ~${gate}ms gates)`;
+    return `pace normal (1x, ~${gate}ms gates)`;
+}
 /**
  * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
  * or `null` when duration is unset (caller keeps legacy timing).
+ *
+ * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`
+ * (`gatesFast`). `--fast` only shortens when pace is unset/normal.
  */
 export function resolveFixtureDwellMs(fixture, opts) {
     if (fixture.duration === undefined || fixture.duration === false)
         return null;
-    const pace = normalizeDemoPace(opts?.pace ?? (opts?.gatesFast ? "fast" : "normal"));
+    const pace = opts?.pace !== undefined && opts.pace !== null
+        ? 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 (pace === "blitz" || pace === "fast" || opts?.gatesFast)
-        return fastMs;
     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 (typeof pace === "number") {
+        if (pace > 20)
+            return Math.round(pace);
+        return Math.max(0, Math.round(normalMs * Math.min(10, Math.max(0.05, pace))));
+    }
+    if (pace === "blitz" || pace === "fast")
+        return fastMs;
+    // CLI --fast only when author left pace at normal
+    if (opts?.gatesFast && pace === "normal")
+        return fastMs;
     if (pace === "slow")
         return Math.max(normalMs, FIXTURE_DURATION_SLOW_MS_DEFAULT);
     return normalMs;

package/dist/index.d.ts

@@ -3,8 +3,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, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, 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, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, } from "./highlights.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/dist/index.js

@@ -2,7 +2,7 @@ export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";

package/package.json

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