waygraph 0.12.17 → 0.12.18

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,10 @@ import {
   normalizeHighlightWeight,
   applyHighlightStyleDefaults,
   resolveStepDemoPace,
+  demoPaceGateMs,
+  demoPaceIsBlitz,
+  demoPaceIsFast,
+  demoPaceIsSlow,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -1073,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 {
@@ -1082,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;
@@ -1139,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.
@@ -2160,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
@@ -2249,31 +2253,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;
@@ -2387,6 +2392,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 +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,

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,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;
@@ -140,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

@@ -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,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

@@ -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, 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, 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.18",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",