waygraph 0.12.10 → 0.12.11

package/README.md

@@ -215,11 +215,13 @@ overridable, not one giant Block with no per-step confirmation. `composedBlock.w
 `modStepVerify` patch one step from outside, addressed the same three ways
 `withBlockVerify`/`modBlockVerify` already are - a `composeBlock` result is a plain Block,
 so it drops straight into `defineFlow([start, ..., composed, ..., end])` like any other.
-`fastForwardComposeBlock(name, steps)` is the same shape marked for **demo pacing**: one
-opaque step (no per-inner gate) unless `waygraph demo --ff-expand`. Saucedemo
-`checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays expanded for
-Sign In narration. Traverse (later) reuses FF as a seed prefix - see
-`docs/proposals/traverse-ffcompose-rfc.md`.
+`fastForwardComposeBlock(name, steps)` is the same shape marked for **wall-clock
+fast-forward**: one opaque demo step that **blitzes** (no per-inner gate, no smooth
+cursor theater, Playwright slowMo off for that flow unless `WAYGRAPH_SLOWMO` is set)
+unless `waygraph demo --ff-expand`. Put **several** FF units in one Flow when you need
+to race past auth, then a heavy dashboard settle, then watch the interesting middle.
+Saucedemo `checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays
+expanded for Sign In narration. See `docs/proposals/traverse-ffcompose-rfc.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

@@ -1745,10 +1745,10 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
   // seconds. When slowMo is already doing the pacing, add none of our own;
   // only fall back to a small typing delay when slowMo is off entirely.
   //
-  // pacing.skipTheater (WAYGRAPH_FAST_BLOCKS only): near-zero cursor / pop /
-  // typing - blow past this block. --fast sets pacing.gatesFast instead
-  // and must NOT land here, or demo looks like plain waygraph run.
-  // stubBeforeRef.current = resolved stubBefore slots for the active block.
+  // pacing.skipTheater (WAYGRAPH_FAST_BLOCKS **or** FFCompose): near-zero
+  // cursor / pop / typing - blitz this step. --fast alone sets gatesFast only
+  // (shorter Next/autoplay gates) and must NOT skip theater, or the whole demo
+  // looks like plain waygraph run.
   const skipTheater = () => !!pacing.skipTheater;
   const typeDelay = () => (skipTheater() ? 0 : slowMo ? 0 : 30);
   // Click is a single action, not per-character, so it doesn't compound
@@ -1757,7 +1757,8 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBefore
   // rather than stacking a full 1.2s on top of that.
   const clickPrePop = () => (skipTheater() ? 0 : slowMo ? 300 : 700);
   const clickPostPop = () => (skipTheater() ? 0 : slowMo ? 200 : 500);
-  const cursorMs = (full) => (skipTheater() ? Math.min(120, full) : full);
+  // FF / FAST_BLOCKS: no cursor travel animation (0). Plain theater keeps full.
+  const cursorMs = (full) => (skipTheater() ? 0 : full);
   // Locator.fill()/click() only ever see a raw call, no context of where
   // the value came from. Patching mem.get() to remember the most recently
   // read key's name (Blocks read-then-immediately-fill, e.g. const { email
@@ -1984,14 +1985,15 @@ async function resetPageState(context, page, baseURL) {
 async function runStepMode(engine, start, end, context, page, mem, resolved, slowMo, title, fastBlockNames, clearSession, baseURL) {
   // A shared, mutable pacing knob the interaction patches read live (per
   // call, not once at setup) - flipped per-block below so one block (e.g.
-  // WAYGRAPH_FAST_BLOCKS=login) can run through with none of the overlay's
-  // own added dwell while the rest of the chain keeps the full theatrical
-  // pace. Playwright's own slowMo is process-wide and untouched by this -
-  // only OUR added pauses (ring pop, cursor travel, typing delay) shrink
-  // when skipTheater is on.
+  // WAYGRAPH_FAST_BLOCKS=login or an FFCompose unit) can run through with
+  // none of the overlay's own added dwell while the rest of the chain keeps
+  // the full theatrical pace.
   // --fast / WAYGRAPH_DEMO_FAST: shorter auto-next / Next gates ONLY -
   // keeps smooth cursor travel (not akin to waygraph run).
-  // WAYGRAPH_FAST_BLOCKS: named blocks still skip theater (old blow-past).
+  // FFCompose + WAYGRAPH_FAST_BLOCKS: skipTheater (blitz overlay delays).
+  // When the flow has any opaque FF unit and WAYGRAPH_SLOWMO is unset,
+  // launch slowMo is 0 so Playwright itself does not re-tax every click
+  // 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 };
@@ -2081,8 +2083,11 @@ 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.gatesFast || pacing.skipTheater ? Math.min(400, autoplayMs) : autoplayMs;
+    const ms = pacing.skipTheater
+      ? Math.min(80, autoplayMs)
+      : pacing.gatesFast
+        ? Math.min(400, autoplayMs)
+        : autoplayMs;
     let elapsed = 0;
     for (;;) {
       // Re-read the checkbox EVERY loop tick, not once up front - a human
@@ -2166,9 +2171,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       await resetPageState(context, page, baseURL);
     }
     // gatesFast: --fast (whole run) or FFCompose opaque steps (one short gate).
-    // skipTheater: only WAYGRAPH_FAST_BLOCKS - never --fast, never FF by default.
+    // skipTheater: WAYGRAPH_FAST_BLOCKS **or** FFCompose — wall-clock blitz
+    // (overlay delays). --fast alone never sets skipTheater.
     pacing.gatesFast = demoFast || !!r.block.fastForward;
-    pacing.skipTheater = fastBlockNames.has(r.block.name);
+    pacing.skipTheater = fastBlockNames.has(r.block.name) || !!r.block.fastForward;
     const fixtures = r.highlightFixtures;
     stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures });
     const isNavBlock = r.block.__waygraphKind === "nav";
@@ -2638,13 +2644,20 @@ async function main() {
   // nobody has to watch a live window for it to be right).
   const headed =
     process.env.WAYGRAPH_HEADED === "0" ? false : process.env.WAYGRAPH_HEADED === "1" || step;
-  // Step mode defaults to a visible pace (each fill/click actually shows on
-  // screen instead of snapping in) unless the human overrides it - an
-  // explicit WAYGRAPH_SLOWMO=0 still means "off".
+  // Step mode defaults to a visible Playwright pace (slowMo 350) UNLESS the
+  // flow has an opaque fastForwardComposeBlock — then default slowMo 0 so FF
+  // auth/seed actually blitzes (<10s target) instead of only hiding the cursor
+  // while every click still pays 350ms. Non-FF steps keep overlay theater
+  // (cursor/pop) for watchability. Explicit WAYGRAPH_SLOWMO always wins.
+  const hasOpaqueFf = resolved.some(
+    (r) => r && r.block && r.block.fastForward === true,
+  );
   const slowMo = process.env.WAYGRAPH_SLOWMO !== undefined
     ? Number(process.env.WAYGRAPH_SLOWMO)
     : step
-      ? 350
+      ? hasOpaqueFf
+        ? 0
+        : 350
       : undefined;
   const baseURL = process.env.WAYGRAPH_BASE_URL;
   const title = process.env.WAYGRAPH_TITLE;
@@ -2652,8 +2665,8 @@ async function main() {
   // should blow past the overlay's own added dwell (ring pop, cursor
   // travel, typing delay, and that block's own gates) - "I want the login
   // block to be faster than the rest of the demo," Dan's own phrase.
-  // Playwright's real slowMo is untouched; this only trims what waygraph
-  // itself adds on top of it. Distinct from --fast (gates only).
+  // FFCompose blocks get the same skipTheater automatically (no need to
+  // list them here). Distinct from --fast (gates only).
   const fastBlockNames = new Set(
     (process.env.WAYGRAPH_FAST_BLOCKS || "")
       .split(",")

package/dist/engine.d.ts

@@ -351,10 +351,13 @@ export declare function composeBlock<In extends Checkpoint<string>, B extends Ch
 export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, F>, Block<F, Out>]): ComposedBlock<In, Out>;
 /**
  * Same shape as {@link composeBlock}, marked {@link FastForwardComposedBlock.fastForward}
- * so demo/run/traverse treat it as **one opaque step** (no per-inner gate/ring)
- * unless `--ff-expand` / `WAYGRAPH_FF_EXPAND=1`. Inner acts still run for real;
+ * so demo/run/traverse treat it as **one opaque step** that **blitzes wall-clock**
+ * (skip overlay theater + no Playwright slowMo on that step's acts) unless
+ * `--ff-expand` / `WAYGRAPH_FF_EXPAND=1`. Inner acts still run for real;
  * failures are prefixed `ff-name > …` so the locus names both the FF unit and
- * the inner step. Prefer this for boring prefixes (auth, seed) on demo Flows.
+ * the inner step. Prefer this for boring or heavy-check prefixes (auth, seed,
+ * dashboard settle) — you may put **several** FF units in one Flow with normal
+ * Blocks between them.
  * @example fastForwardComposeBlock("ff-owner-auth", [NavLoginBlock, SubmitLoginForFlow])
  */
 export interface FastForwardComposedBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> extends ComposedBlock<In, Out> {

package/package.json

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