waygraph 0.12.16 → 0.12.18

package/README.md

@@ -236,9 +236,11 @@ snapshot, partitions edges by hash, and claims via in-process edge leases (audit
 
 **Richer demo narration:** automation rings are **gray**; authored stubs/slides can use
 `tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus
-`size: "sm" | "md" | "lg"` and `weight: "normal" | "bold"`. Episode pacing:
-`withDemoPace(flow, "fast" | "slow" | "normal" | "blitz")` or `withBlockPace(block, ...)`
-(FFCompose stays blitz). Living objectives: `docs/proposals/OBJECTIVES.md`.
+`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" | 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

@@ -215,7 +215,12 @@ import {
   normalizeDemoPace,
   normalizeHighlightSize,
   normalizeHighlightWeight,
+  applyHighlightStyleDefaults,
   resolveStepDemoPace,
+  demoPaceGateMs,
+  demoPaceIsBlitz,
+  demoPaceIsFast,
+  demoPaceIsSlow,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -1072,6 +1077,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 {
@@ -1081,7 +1087,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;
@@ -1138,7 +1144,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.
@@ -2159,13 +2167,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
@@ -2248,36 +2253,40 @@ 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;
     const fixtures = r.highlightFixtures;
-    stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures });
+    const flowStyle = r.highlightStyle;
+    stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures }).map((h) =>
+      applyHighlightStyleDefaults(h, flowStyle),
+    );
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
     // Auto-next: tuck stepper on NavBlocks so the page transition fills the frame.
@@ -2369,17 +2378,21 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           .catch(() => {});
         const errHighlights = resolveHighlightSlots(r.block, "stubOnError", {
           fixtures: fixturesOnError,
-        }).map((h) => ({
-          selector: h.selector,
-          label: formatHighlightCaption(h),
-          duration: h.duration,
-          fastMode: h.fastMode,
-          tone: normalizeHighlightTone(h.tone),
-          size: normalizeHighlightSize(h.size),
-          weight: normalizeHighlightWeight(h.weight),
-        }));
+        }).map((h) => {
+          const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
+          return {
+            selector: styled.selector,
+            label: formatHighlightCaption(styled),
+            duration: styled.duration,
+            fastMode: styled.fastMode,
+            tone: styled.tone,
+            size: styled.size,
+            weight: styled.weight,
+          };
+        });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
           defaultHoldMs: 2000,
+          pace: pacing.demoPace,
         });
       }
       // A thrown act()/observe()/a failed verify Trait used to just crash
@@ -2430,7 +2443,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       .catch(() => {});
     result = stepOutcome.result;
     const fixturesAfter = r.highlightFixtures;
-    const slides = resolveSlides(r.block, { out: result, fixtures: fixturesAfter });
+    const slides = resolveSlides(r.block, { out: result, fixtures: fixturesAfter }).map((s) =>
+      applyHighlightStyleDefaults(s, r.highlightStyle),
+    );
     if (slides.length > 0) {
       await presentSlides(page, slides, gate, {
         title,
@@ -2445,18 +2460,23 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     let highlights;
     if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
       highlights = resolveHighlightSlots(r.block, "stubAfter", { out: result, fixtures: fixturesAfter }).map(
-        (h) => ({
-          selector: h.selector,
-          label: formatHighlightCaption(h),
-          duration: h.duration,
-          fastMode: h.fastMode,
-          tone: normalizeHighlightTone(h.tone),
-          size: normalizeHighlightSize(h.size),
-          weight: normalizeHighlightWeight(h.weight),
-        }),
+        (h) => {
+          const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
+          return {
+            selector: styled.selector,
+            label: formatHighlightCaption(styled),
+            duration: styled.duration,
+            fastMode: styled.fastMode,
+            tone: styled.tone,
+            size: styled.size,
+            weight: styled.weight,
+          };
+        },
       );
     } else {
-      highlights = extractVerifyHighlights(r.block, result.__state);
+      highlights = extractVerifyHighlights(r.block, result.__state).map((h) =>
+        applyHighlightStyleDefaults(h, r.highlightStyle),
+      );
     }
     await renderAfterStep(page, {
       index: i,
@@ -2466,6 +2486,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       resultTag: JSON.stringify(result),
       highlights,
       gatesFast: pacing.gatesFast,
+      pace: pacing.demoPace,
       isLast: i === resolved.length - 1,
       allNames: moduleNames,
       allDescriptions: moduleDescriptions,
@@ -2638,6 +2659,7 @@ async function main() {
         seedMem: idx === 0 ? seedMem : undefined,
         highlightFixtures: flow.highlightFixtures,
         demoPace: flow.demoPace,
+        highlightStyle: flow.highlightStyle,
         expectedFailureReason:
           flow.expectedFailureReason && idx === blockInfos.length - 1
             ? flow.expectedFailureReason
@@ -2707,6 +2729,7 @@ async function main() {
           expectedFailureReason: flow.expectedFailureReason,
           highlightFixtures: flow.highlightFixtures,
           demoPace: flow.demoPace,
+          highlightStyle: flow.highlightStyle,
           seedMem: () => seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref),
         });
       } else {
@@ -2717,6 +2740,7 @@ async function main() {
           episodeTitle: undefined,
           highlightFixtures: undefined,
           demoPace: undefined,
+          highlightStyle: undefined,
           seedMem: () => seedMemForBlock(mem, r, seg.json),
         });
       }
@@ -2742,6 +2766,7 @@ async function main() {
         episodeTitle: meta.episodeTitle,
         highlightFixtures: meta.highlightFixtures,
         demoPace: meta.demoPace,
+        highlightStyle: meta.highlightStyle,
         expectedFailureReason:
           meta.expectedFailureReason && remainingInFlow === 1 ? meta.expectedFailureReason : undefined,
         seedMem: isFirstOfSegment ? meta.seedMem : undefined,

package/dist/engine.d.ts

@@ -3,6 +3,7 @@ import type { Block, Checkpoint, Instruction, DefinedBlock, ActionPage, Waygraph
 import { MemPage } from "./mem-page.js";
 import type { MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
+import { type HighlightStyleDefaults, type DemoPace } from "./highlights.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
@@ -191,6 +192,11 @@ export interface Flow<Out extends Checkpoint<string>> {
      * `run()` ignores; step/demo applies per Block in the episode.
      */
     readonly demoPace?: import("./highlights.js").DemoPace;
+    /**
+     * Default highlight size/weight/tone for this Flow's episode (`withHighlightStyle`).
+     * Per-slot stub/fixture values win. `run()` ignores.
+     */
+    readonly highlightStyle?: import("./highlights.js").HighlightStyleDefaults;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -263,13 +269,22 @@ 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>;
+/**
+ * Default highlight look for a Flow episode (size / weight / optional tone).
+ * Per-slot stub or {@link withHighlightFixtures} values win when set.
+ * @example withHighlightStyle(withDemoPace(gapFlow, "slow"), { size: "lg", weight: "bold" })
  */
-export declare function withDemoPace<Out extends Checkpoint<string>>(flow: Flow<Out>, pace: import("./highlights.js").DemoPace): Flow<Out>;
+export declare function withHighlightStyle<Out extends Checkpoint<string>>(flow: Flow<Out>, style: HighlightStyleDefaults): 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>;
+export declare function withBlockPace<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, pace: 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

@@ -2,6 +2,7 @@ import { chromium, firefox, webkit } from "@playwright/test";
 import { connect, checkpoint } from "./types.js";
 import { MemPage } from "./mem-page.js";
 import { runVerify, runPrecondition } from "./trait.js";
+import { normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, } from "./highlights.js";
 const LAUNCHERS = { chromium, firefox, webkit };
 /**
  * Resolves which `BrowserType` actually launches for a `mem`-only run (no
@@ -356,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;
@@ -366,6 +370,24 @@ export function withDemoPace(flow, pace) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withDemoPace(flow.modBlockVerify(block, nameOrIndex, newCheck), demoPace),
     };
 }
+/**
+ * Default highlight look for a Flow episode (size / weight / optional tone).
+ * Per-slot stub or {@link withHighlightFixtures} values win when set.
+ * @example withHighlightStyle(withDemoPace(gapFlow, "slow"), { size: "lg", weight: "bold" })
+ */
+export function withHighlightStyle(flow, style) {
+    const highlightStyle = {
+        ...(style.tone !== undefined ? { tone: normalizeHighlightTone(style.tone) } : {}),
+        ...(style.size !== undefined ? { size: normalizeHighlightSize(style.size) } : {}),
+        ...(style.weight !== undefined ? { weight: normalizeHighlightWeight(style.weight) } : {}),
+    };
+    return {
+        ...flow,
+        highlightStyle,
+        withBlockVerify: (block, verify) => withHighlightStyle(flow.withBlockVerify(block, verify), highlightStyle),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightStyle(flow.modBlockVerify(block, nameOrIndex, newCheck), highlightStyle),
+    };
+}
 /**
  * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
  * @example withBlockPace(composeBlock("gap-review", [...]), "slow")

package/dist/highlights.d.ts

@@ -79,6 +79,22 @@ export type HighlightTone = "planned" | "auto" | "info" | "warning" | "danger" |
 export type HighlightSize = "sm" | "md" | "lg";
 /** Label font weight. */
 export type HighlightWeight = "normal" | "bold";
+/** Optional Flow-level defaults for demo rings (episode-wide). Stub/fixture wins. */
+export type HighlightStyleDefaults = {
+    tone?: HighlightTone;
+    size?: HighlightSize;
+    weight?: HighlightWeight;
+};
+/** Apply Flow defaults under per-slot authored values (slot wins when set). */
+export declare function applyHighlightStyleDefaults<T extends {
+    tone?: HighlightTone | string;
+    size?: HighlightSize | string;
+    weight?: HighlightWeight | string;
+}>(slot: T, defaults?: HighlightStyleDefaults | null): T & {
+    tone: HighlightTone;
+    size: HighlightSize;
+    weight: HighlightWeight;
+};
 /** Map author aliases (`error` -> danger) to a canonical tone. */
 export declare function normalizeHighlightTone(raw: unknown): HighlightTone;
 /** Map size aliases to sm/md/lg. */
@@ -90,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. */
@@ -106,9 +124,21 @@ 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;
 /**
  * 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;
@@ -124,8 +154,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

@@ -8,6 +8,25 @@
  * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
  * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
+/** Apply Flow defaults under per-slot authored values (slot wins when set). */
+export function applyHighlightStyleDefaults(slot, defaults) {
+    const tone = slot.tone !== undefined && slot.tone !== ""
+        ? normalizeHighlightTone(slot.tone)
+        : defaults?.tone !== undefined
+            ? normalizeHighlightTone(defaults.tone)
+            : "planned";
+    const size = slot.size !== undefined && slot.size !== ""
+        ? normalizeHighlightSize(slot.size)
+        : defaults?.size !== undefined
+            ? normalizeHighlightSize(defaults.size)
+            : "md";
+    const weight = slot.weight !== undefined && slot.weight !== ""
+        ? normalizeHighlightWeight(slot.weight)
+        : defaults?.weight !== undefined
+            ? normalizeHighlightWeight(defaults.weight)
+            : "normal";
+    return { ...slot, tone, size, weight };
+}
 const TONE_ICONS = {
     planned: "",
     auto: "",
@@ -60,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. */
@@ -82,24 +89,112 @@ 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)));
+}
 /**
  * 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

@@ -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, withDemoPace, withBlockPace, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, 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, DemoPace, } 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, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export 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

@@ -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, withDemoPace, withBlockPace, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, 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 { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { 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.16",
+  "version": "0.12.18",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",