waygraph 0.12.23 → 0.12.25

package/dist/cli.js

@@ -207,6 +207,7 @@ import { tmpdir } from "node:os";
 import {
   resolveHighlightSlots,
   resolveSlides,
+  runStubPhase,
   resolveFixtureDwellMs,
   resolveSlideDwellMs,
   formatHighlightCaption,
@@ -1138,18 +1139,40 @@ async function ensureSelectorInView(page, selector) {
     const loc = page.locator(selector).first();
     await loc.scrollIntoViewIfNeeded().catch(() => {});
     await page
-      .evaluate((sel) => {
+      .evaluate(async (sel) => {
         const el = document.querySelector(sel);
         if (!el) return;
+        const waitScroll = (node, ms) =>
+          new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+              if (done) return;
+              done = true;
+              node.removeEventListener("scrollend", finish);
+              clearTimeout(t);
+              resolve();
+            };
+            const t = setTimeout(finish, ms);
+            try {
+              node.addEventListener("scrollend", finish, { once: true });
+            } catch {
+              /* scrollend unsupported - timeout only */
+            }
+          });
         try {
-          el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+          el.scrollIntoView({ block: "center", inline: "center", behavior: "smooth" });
         } catch {
           try {
-            el.scrollIntoView(true);
+            el.scrollIntoView({ block: "center", inline: "center" });
           } catch {
-            /* ignore */
+            try {
+              el.scrollIntoView(true);
+            } catch {
+              /* ignore */
+            }
           }
         }
+        await waitScroll(document.scrollingElement || document.documentElement, 500);
         let p = el.parentElement;
         while (p && p !== document.documentElement && p !== document.body) {
           const st = getComputedStyle(p);
@@ -1159,8 +1182,15 @@ async function ensureSelectorInView(page, selector) {
             const er = el.getBoundingClientRect();
             const pr = p.getBoundingClientRect();
             if (er.left < pr.left || er.right > pr.right || er.top < pr.top || er.bottom > pr.bottom) {
-              p.scrollLeft += er.left + er.width / 2 - (pr.left + pr.width / 2);
-              p.scrollTop += er.top + er.height / 2 - (pr.top + pr.height / 2);
+              const left = p.scrollLeft + (er.left + er.width / 2 - (pr.left + pr.width / 2));
+              const top = p.scrollTop + (er.top + er.height / 2 - (pr.top + pr.height / 2));
+              try {
+                p.scrollTo({ left, top, behavior: "smooth" });
+              } catch {
+                p.scrollLeft = left;
+                p.scrollTop = top;
+              }
+              await waitScroll(p, 500);
             }
           }
           p = p.parentElement;
@@ -1246,8 +1276,11 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           size: h.size,
           weight: h.weight,
         });
-        if (h.todos && h.todos.length) {
-          const rows = normalizeTodos(h.todos, h.todoIndex);
+        if ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length)) {
+          const rows =
+            opts && opts.todos && opts.todos.length
+              ? opts.todos
+              : normalizeTodos(h.todos, h.todoIndex);
           await page
             .evaluate((todos) => {
               const ul = document.getElementById("wg-todos");
@@ -2525,9 +2558,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       !!r.wasFastForward;
     const fixtures = r.highlightFixtures;
     const flowStyle = r.highlightStyle;
-    stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures }).map((h) =>
+    const stubBeforePhase = await runStubPhase(r.block, "stubBefore", { fixtures });
+    stubBeforeRef.current = stubBeforePhase.highlights.map((h) =>
       applyHighlightStyleDefaults(h, flowStyle),
     );
+    const stubBeforeTodos = stubBeforePhase.todos || [];
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
     // Auto-next: tuck stepper on NavBlocks so the page transition fills the frame.
@@ -2573,12 +2608,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeTitle: r.episodeTitle,
       stepperMode,
       forceCollapsed,
-      todos: (() => {
-        for (const h of stubBeforeRef.current || []) {
-          if (h.todos && h.todos.length) return normalizeTodos(h.todos, h.todoIndex);
-        }
-        return [];
-      })(),
+      todos: stubBeforeTodos,
       ...paceSpeak,
     });
     const edits = await gate();
@@ -2638,9 +2668,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
             }
           })
           .catch(() => {});
-        const errHighlights = resolveHighlightSlots(r.block, "stubOnError", {
+        const errPhase = await runStubPhase(r.block, "stubOnError", {
           fixtures: fixturesOnError,
-        }).map((h) => {
+          error: err,
+        });
+        const errHighlights = errPhase.highlights.map((h) => {
           const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
           return {
             selector: styled.selector,
@@ -2650,14 +2682,13 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
             tone: styled.tone,
             size: styled.size,
             weight: styled.weight,
-            todos: styled.todos,
-            todoIndex: styled.todoIndex,
             zoom: styled.zoom,
           };
         });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
           defaultHoldMs: 2000,
           pace: pacing.demoPace,
+          todos: errPhase.todos,
         });
       }
       // A thrown act()/observe()/a failed verify Trait used to just crash
@@ -2723,24 +2754,26 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       });
     }
     let highlights;
+    let stubAfterTodos = [];
     if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
-      highlights = resolveHighlightSlots(r.block, "stubAfter", { out: result, fixtures: fixturesAfter }).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,
-            todos: styled.todos,
-            todoIndex: styled.todoIndex,
-            zoom: styled.zoom,
-          };
-        },
-      );
+      const afterPhase = await runStubPhase(r.block, "stubAfter", {
+        out: result,
+        fixtures: fixturesAfter,
+      });
+      stubAfterTodos = afterPhase.todos || [];
+      highlights = afterPhase.highlights.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,
+          zoom: styled.zoom,
+        };
+      });
     } else {
       highlights = extractVerifyHighlights(r.block, result.__state).map((h) =>
         applyHighlightStyleDefaults(h, r.highlightStyle),
@@ -2765,12 +2798,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
       stepperMode,
-      todos: (() => {
-        for (const h of highlights || []) {
-          if (h.todos && h.todos.length) return normalizeTodos(h.todos, h.todoIndex);
-        }
-        return [];
-      })(),
+      todos: stubAfterTodos,
       // After a nav under auto-next, stay compact until the next action block expands.
       forceCollapsed: !!process.env.WAYGRAPH_VIDEO || ((await currentAutoplay()) && isNavBlock),
     });

package/dist/engine.d.ts

@@ -603,9 +603,9 @@ export type NavBlockOptions<Out extends Checkpoint<string>> = {
     checkpoint: Out["__state"];
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
-    stubBefore?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
-    stubAfter?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
-    stubOnError?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    stubBefore?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubAfter?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubOnError?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
     /** @deprecated Prefer stubAfter. */
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     /**
@@ -667,9 +667,9 @@ export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
     click: string | ((mem: MemPage) => string);
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
-    stubBefore?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
-    stubAfter?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
-    stubOnError?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    stubBefore?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubAfter?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubOnError?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
     /** @deprecated Prefer stubAfter. */
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
@@ -699,9 +699,9 @@ export type PageBlockOptions<Out extends Checkpoint<string>> = {
     /** Checkpoint tag for this screen (hub). */
     checkpoint: Out["__state"];
     verify?: Trait[] | ((out: Out) => Trait[]);
-    stubBefore?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
-    stubAfter?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
-    stubOnError?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    stubBefore?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubAfter?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubOnError?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
     /** @deprecated Prefer stubAfter. */
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     requires?: readonly MemKey<any>[];

package/dist/highlights.d.ts

@@ -2,6 +2,10 @@
  * Block stubBefore / stubAfter / stubOnError + flow highlightFixtures + demo slides.
  * Demo narration only - never affects runGraph pass/fail.
  *
+ * Stubs are **open block lifecycles** - prefer `stubBefore(ctx) { ... }`, not a
+ * closed slot object. Inside the fn authors set fixtures (todos, zoom) and rings.
+ * Object maps remain a shorthand for highlight-only slots.
+ *
  * Lifecycle (stubs) ≠ yap slides: stubs are fill/after/error rings tied to the block;
  * slides are multi-step captions with Next between them (long-process explain).
  *
@@ -26,7 +30,7 @@ export type FixtureDurationFields = {
 };
 /**
  * One checklist row for episode planning (demo panel).
- * Prefer {@link WaygraphHighlightStub.todoIndex} for sequential done/current.
+ * Set via {@link StubCtx.todos} / {@link StubCtx.todoIndex} inside the lifecycle.
  */
 export type WaygraphTodoItem = {
     text: string;
@@ -36,6 +40,14 @@ export type WaygraphTodoItem = {
     current?: boolean;
 };
 export type WaygraphTodoInput = string | WaygraphTodoItem;
+/** Episode-level fixtures authored inside stubBefore/After/OnError(ctx). */
+export type StubPhaseFixtures = {
+    todos?: readonly WaygraphTodoInput[];
+    /** Which todo is current (0-based). Rows before = done, after = pending. */
+    todoIndex?: number;
+    /** Default zoom for rings that omit their own zoom. */
+    zoom?: number;
+};
 /** One named highlight slot on a block (selector + caption). */
 export interface WaygraphHighlightStub extends FixtureDurationFields {
     selector: string;
@@ -63,26 +75,71 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      */
     weight?: HighlightWeight;
     /**
-     * Simple episode checklist (demo panel). Same lifecycle as this stub
-     * (stubBefore / stubAfter / stubOnError). Strings or `{ text, done?, current? }`.
-     */
-    todos?: readonly WaygraphTodoInput[];
-    /**
-     * Which todo is current (0-based). Rows before = done, after = pending.
-     * Authored `done`/`current` on an item still win when set.
-     * Bump in a stub phase function for sequential plans.
-     */
-    todoIndex?: number;
-    /**
-     * Magnify the target element while this ring is shown (e.g. `1.35`).
+     * Magnify this target while its ring is shown (e.g. `1.35`).
      * Cleared when the ring hides / next highlight starts. `1` or omit = off.
+     * Episode default: {@link StubCtx.zoom}.
      */
     zoom?: number;
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "todos" | "todoIndex" | "zoom"> & FixtureDurationFields;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
-export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | ((out: Out) => HighlightStubPhase);
+/**
+ * Open stub lifecycle context. Authors set rings + episode fixtures freely —
+ * not restricted to returning a closed slot object.
+ *
+ * @example
+ * stubBefore: (ctx) => {
+ *   ctx.todos(["Enter email", "Enter password", "Click Sign in"]);
+ *   ctx.todoIndex(0);
+ *   ctx.zoom(1.35);
+ *   ctx.highlights({
+ *     email: { selector: "#email", label: "Email" },
+ *     submit: { selector: "#login-button", label: "Sign in" },
+ *   });
+ * }
+ * // Sequential plan: bump todoIndex in a later phase / later block's stubBefore
+ * stubAfter: (ctx) => {
+ *   ctx.todos(["Enter email", "Enter password", "Click Sign in"]);
+ *   ctx.todoIndex(2);
+ *   ctx.ring("inventory", { selector: ".inventory_list", label: "Landed" });
+ * }
+ */
+export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
+    /** Present after resolve (stubAfter). Undefined for stubBefore. */
+    readonly out: Out | undefined;
+    /** Present on stubOnError when the step threw. */
+    readonly error: unknown | undefined;
+    /** Replace named highlight rings for this phase. */
+    highlights(slots: HighlightStubPhase): void;
+    /** Set / overwrite one named ring. */
+    ring(id: string, stub: WaygraphHighlightStub): void;
+    /** Episode checklist (demo panel). */
+    todos(items: readonly WaygraphTodoInput[]): void;
+    /** Current checklist index (bump for sequential plans). */
+    todoIndex(n: number): void;
+    /** Default zoom for rings without their own zoom. */
+    zoom(n: number): void;
+    /** Batch-set rings + episode fixtures. */
+    set(partial: {
+        highlights?: HighlightStubPhase;
+    } & StubPhaseFixtures): void;
+};
+export type StubLifecycleFn<Out extends Checkpoint<string>> = (ctx: StubCtx<Out>) => void | HighlightStubPhase | Promise<void | HighlightStubPhase>;
+/**
+ * Block stub authoring:
+ * - **preferred:** open lifecycle `stubBefore(ctx) { ctx.todos(...); ctx.ring(...) }`
+ * - **shorthand:** static slot map `{ email: { selector, label } }`
+ * - **legacy:** `(out) => slotMap` still accepted (treated as highlights only)
+ */
+export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | StubLifecycleFn<Out> | ((out: Out) => HighlightStubPhase);
+/** Result of running a stub phase (rings + episode fixtures). */
+export type StubPhaseResult = {
+    highlights: ResolvedHighlight[];
+    todos: WaygraphTodoItem[];
+    todoIndex?: number;
+    zoom?: number;
+};
 /**
  * One yap/slide in a multi-step demo caption sequence.
  * Not block lifecycle - demo pauses (Next / auto-next) between slides.
@@ -223,9 +280,21 @@ export type ResolvedHighlight = WaygraphHighlightStub;
  */
 export declare function normalizeTodos(todos: readonly WaygraphTodoInput[] | undefined, todoIndex?: number): WaygraphTodoItem[];
 /**
- * Resolve ordered highlight slots for a phase, merging flow fixtures over block stubs.
- * Shim: empty stubAfter + legacy `instruction.highlights` -> auto-keyed stubAfter.
- * `stubOnError` is fail-path only (demo step catch) - never run on success.
+ * Run an open stub lifecycle (preferred) or resolve a static slot map.
+ * Returns rings + episode fixtures (todos / todoIndex / zoom).
+ *
+ * @example
+ * const before = await runStubPhase(block, "stubBefore", { fixtures });
+ * // before.todos, before.highlights
+ */
+export declare function runStubPhase(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
+    out?: Checkpoint<string>;
+    error?: unknown;
+    fixtures?: HighlightFixtureMap;
+}): Promise<StubPhaseResult>;
+/**
+ * Sync resolve of highlight slots. Prefer {@link runStubPhase} for open
+ * async lifecycles + episode fixtures (todos/zoom).
  */
 export declare function resolveHighlightSlots(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
     out?: Checkpoint<string>;
@@ -248,12 +317,12 @@ export declare function formatHighlightCaption(h: {
     tone?: HighlightTone | string;
 }): string;
 /**
- * True when the block authored a non-empty stubAfter (after resolve + shim),
- * including legacy highlights. When true, demo should not use verify-trait fallback.
+ * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
+ * When true, demo should not use verify-trait fallback.
  */
 export declare function hasAuthoredStubAfter(block: Block<any, any>, out?: Checkpoint<string>, fixtures?: HighlightFixtureMap): boolean;
 /**
- * True when stubOnError resolves to at least one ring (block and/or flow fixture).
+ * True when stubOnError is authored (lifecycle fn and/or rings).
  * Demo fail path only - success never consults this.
  */
 export declare function hasAuthoredStubOnError(block: Block<any, any>, fixtures?: HighlightFixtureMap): boolean;

package/dist/highlights.js

@@ -2,6 +2,10 @@
  * Block stubBefore / stubAfter / stubOnError + flow highlightFixtures + demo slides.
  * Demo narration only - never affects runGraph pass/fail.
  *
+ * Stubs are **open block lifecycles** - prefer `stubBefore(ctx) { ... }`, not a
+ * closed slot object. Inside the fn authors set fixtures (todos, zoom) and rings.
+ * Object maps remain a shorthand for highlight-only slots.
+ *
  * Lifecycle (stubs) ≠ yap slides: stubs are fill/after/error rings tied to the block;
  * slides are multi-step captions with Next between them (long-process explain).
  *
@@ -314,25 +318,18 @@ export function normalizeTodos(todos, todoIndex) {
         return item;
     });
 }
-function pickTodoFields(base, patch) {
-    const out = {};
-    const todos = patch?.todos !== undefined ? patch.todos : base?.todos;
-    const todoIndex = patch?.todoIndex !== undefined ? patch.todoIndex : base?.todoIndex;
+function pickZoom(base, patch) {
     const zoom = patch?.zoom !== undefined ? patch.zoom : base?.zoom;
-    if (todos !== undefined)
-        out.todos = todos;
-    if (todoIndex !== undefined)
-        out.todoIndex = todoIndex;
     if (zoom !== undefined && Number.isFinite(zoom) && zoom > 0)
-        out.zoom = zoom;
-    return out;
+        return { zoom };
+    return {};
 }
 function mergeSlot(base, patch) {
     if (!base && !patch)
         return null;
     const dwell = pickDurationFields(base, patch);
     const style = pickStyleFields(base, patch);
-    const todos = pickTodoFields(base, patch);
+    const zoom = pickZoom(base, patch);
     if (!base && patch) {
         if (!patch.selector)
             return null;
@@ -343,7 +340,7 @@ function mergeSlot(base, patch) {
             ...(patch.tag ? { tag: patch.tag } : {}),
             ...style,
             ...dwell,
-            ...todos,
+            ...zoom,
         };
     }
     if (base && !patch) {
@@ -352,7 +349,7 @@ function mergeSlot(base, patch) {
             ...(base.tone ? { tone: normalizeHighlightTone(base.tone) } : {}),
             ...(base.size ? { size: normalizeHighlightSize(base.size) } : {}),
             ...(base.weight ? { weight: normalizeHighlightWeight(base.weight) } : {}),
-            ...pickTodoFields(base, undefined),
+            ...pickZoom(base, undefined),
         };
     }
     return {
@@ -366,9 +363,78 @@ function mergeSlot(base, patch) {
         ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
         ...style,
         ...dwell,
-        ...todos,
+        ...zoom,
     };
 }
+function createStubCtx(bag, opts) {
+    return {
+        out: opts.out,
+        error: opts.error,
+        highlights(slots) {
+            bag.highlights = { ...(slots || {}) };
+        },
+        ring(id, stub) {
+            bag.highlights = { ...bag.highlights, [id]: stub };
+        },
+        todos(items) {
+            bag.todos = items;
+        },
+        todoIndex(n) {
+            bag.todoIndex = n;
+        },
+        zoom(n) {
+            if (Number.isFinite(n) && n > 0)
+                bag.zoom = n;
+        },
+        set(partial) {
+            if (partial.highlights)
+                bag.highlights = { ...partial.highlights };
+            if (partial.todos !== undefined)
+                bag.todos = partial.todos;
+            if (partial.todoIndex !== undefined)
+                bag.todoIndex = partial.todoIndex;
+            if (partial.zoom !== undefined && Number.isFinite(partial.zoom) && partial.zoom > 0) {
+                bag.zoom = partial.zoom;
+            }
+        },
+    };
+}
+/** Lift legacy per-slot todos (0.12.23) onto the phase bag once. */
+function liftLegacySlotTodos(bag) {
+    if (bag.todos && bag.todos.length)
+        return;
+    for (const stub of Object.values(bag.highlights)) {
+        const legacy = stub;
+        if (legacy.todos && legacy.todos.length) {
+            bag.todos = legacy.todos;
+            if (legacy.todoIndex !== undefined)
+                bag.todoIndex = legacy.todoIndex;
+            return;
+        }
+    }
+}
+function applyDefaultZoom(slots, defaultZoom) {
+    if (defaultZoom === undefined || !(defaultZoom > 0))
+        return slots;
+    return slots.map((h) => (h.zoom !== undefined && h.zoom > 0 ? h : { ...h, zoom: defaultZoom }));
+}
+function mergePhaseMaps(phaseMap, fixturePhase) {
+    const slotIds = new Set([...Object.keys(phaseMap), ...Object.keys(fixturePhase || {})]);
+    const ordered = [...slotIds].sort((a, b) => {
+        const na = Number(a);
+        const nb = Number(b);
+        if (!Number.isNaN(na) && !Number.isNaN(nb))
+            return na - nb;
+        return a.localeCompare(b);
+    });
+    const resolved = [];
+    for (const id of ordered) {
+        const merged = mergeSlot(phaseMap[id], fixturePhase?.[id]);
+        if (merged)
+            resolved.push(merged);
+    }
+    return resolved;
+}
 function phaseFromLegacyHighlights(highlights) {
     const out = {};
     if (!highlights)
@@ -384,58 +450,121 @@ function phaseFromLegacyHighlights(highlights) {
     });
     return out;
 }
+function readStubRaw(block, phase) {
+    const instr = block.instruction;
+    if (phase === "stubBefore")
+        return instr.stubBefore;
+    if (phase === "stubAfter")
+        return instr.stubAfter;
+    return instr.stubOnError;
+}
+function applyLegacyHighlightsShim(block, phase, phaseMap, out) {
+    if (phase !== "stubAfter" || Object.keys(phaseMap).length > 0)
+        return phaseMap;
+    const instr = block.instruction;
+    if (!instr.highlights)
+        return phaseMap;
+    let legacy = instr.highlights;
+    if (typeof legacy === "function") {
+        try {
+            legacy = legacy(out ?? { __state: "" });
+        }
+        catch {
+            legacy = [];
+        }
+    }
+    return phaseFromLegacyHighlights(Array.isArray(legacy) ? legacy : []);
+}
 /**
- * Resolve ordered highlight slots for a phase, merging flow fixtures over block stubs.
- * Shim: empty stubAfter + legacy `instruction.highlights` -> auto-keyed stubAfter.
- * `stubOnError` is fail-path only (demo step catch) - never run on success.
+ * Run an open stub lifecycle (preferred) or resolve a static slot map.
+ * Returns rings + episode fixtures (todos / todoIndex / zoom).
+ *
+ * @example
+ * const before = await runStubPhase(block, "stubBefore", { fixtures });
+ * // before.todos, before.highlights
  */
-export function resolveHighlightSlots(block, phase, opts) {
-    const instr = block.instruction;
-    let raw = phase === "stubBefore"
-        ? instr.stubBefore
-        : phase === "stubAfter"
-            ? instr.stubAfter
-            : instr.stubOnError;
-    let phaseMap = {};
+export async function runStubPhase(block, phase, opts) {
+    const bag = { highlights: {} };
+    const ctx = createStubCtx(bag, {
+        ...(opts?.out !== undefined ? { out: opts.out } : {}),
+        ...(opts?.error !== undefined ? { error: opts.error } : {}),
+    });
+    const raw = readStubRaw(block, phase);
     if (typeof raw === "function") {
         try {
-            phaseMap = raw(opts?.out ?? { __state: "" }) || {};
+            const ret = await raw(ctx);
+            if (isStubPhase(ret)) {
+                bag.highlights = { ...bag.highlights, ...ret };
+            }
         }
         catch {
-            phaseMap = {};
+            /* best-effort */
+        }
+        // Compat: legacy `(out) => map` that expected Checkpoint (__state on arg)
+        if (Object.keys(bag.highlights).length === 0 && !bag.todos) {
+            try {
+                const legacyOut = (opts?.out ?? { __state: "" });
+                const ret2 = raw(legacyOut);
+                if (isStubPhase(ret2))
+                    bag.highlights = { ...ret2 };
+            }
+            catch {
+                /* ignore */
+            }
         }
     }
     else if (isStubPhase(raw)) {
-        phaseMap = { ...raw };
+        bag.highlights = { ...raw };
     }
-    if (phase === "stubAfter" && Object.keys(phaseMap).length === 0 && instr.highlights) {
-        let legacy = instr.highlights;
-        if (typeof legacy === "function") {
+    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
+    liftLegacySlotTodos(bag);
+    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
+    let highlights = mergePhaseMaps(bag.highlights, fixturePhase);
+    highlights = applyDefaultZoom(highlights, bag.zoom);
+    const todos = normalizeTodos(bag.todos, bag.todoIndex);
+    return {
+        highlights,
+        todos,
+        ...(bag.todoIndex !== undefined ? { todoIndex: bag.todoIndex } : {}),
+        ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
+    };
+}
+/**
+ * Sync resolve of highlight slots. Prefer {@link runStubPhase} for open
+ * async lifecycles + episode fixtures (todos/zoom).
+ */
+export function resolveHighlightSlots(block, phase, opts) {
+    const bag = { highlights: {} };
+    const raw = readStubRaw(block, phase);
+    if (typeof raw === "function") {
+        try {
+            const ctx = createStubCtx(bag, {
+                ...(opts?.out !== undefined ? { out: opts.out } : {}),
+            });
+            const ret = raw(ctx);
+            if (isStubPhase(ret)) {
+                bag.highlights = { ...bag.highlights, ...ret };
+            }
+        }
+        catch {
             try {
-                legacy = legacy(opts?.out ?? { __state: "" });
+                const legacyOut = (opts?.out ?? { __state: "" });
+                const ret2 = raw(legacyOut);
+                if (isStubPhase(ret2))
+                    bag.highlights = { ...ret2 };
             }
             catch {
-                legacy = [];
+                bag.highlights = {};
             }
         }
-        phaseMap = phaseFromLegacyHighlights(Array.isArray(legacy) ? legacy : []);
     }
-    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
-    const slotIds = new Set([...Object.keys(phaseMap), ...Object.keys(fixturePhase || {})]);
-    const ordered = [...slotIds].sort((a, b) => {
-        const na = Number(a);
-        const nb = Number(b);
-        if (!Number.isNaN(na) && !Number.isNaN(nb))
-            return na - nb;
-        return a.localeCompare(b);
-    });
-    const resolved = [];
-    for (const id of ordered) {
-        const merged = mergeSlot(phaseMap[id], fixturePhase?.[id]);
-        if (merged)
-            resolved.push(merged);
+    else if (isStubPhase(raw)) {
+        bag.highlights = { ...raw };
     }
-    return resolved;
+    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
+    liftLegacySlotTodos(bag);
+    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
+    return applyDefaultZoom(mergePhaseMaps(bag.highlights, fixturePhase), bag.zoom);
 }
 /**
  * Resolve multi-step yap slides: flow fixture `slides` wins when present,
@@ -470,21 +599,39 @@ export function formatHighlightCaption(h) {
         return `${icon}${tag}${primary} - ${h.detail}`;
     return `${icon}${tag}${primary}`;
 }
+function stubPhaseLooksAuthored(block, phase, fixtures) {
+    const raw = readStubRaw(block, phase);
+    if (typeof raw === "function")
+        return true;
+    if (isStubPhase(raw) && Object.keys(raw).length > 0)
+        return true;
+    const fx = fixtures?.[block.name]?.[phase];
+    if (fx && Object.keys(fx).length > 0)
+        return true;
+    return false;
+}
 /**
- * True when the block authored a non-empty stubAfter (after resolve + shim),
- * including legacy highlights. When true, demo should not use verify-trait fallback.
+ * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
+ * When true, demo should not use verify-trait fallback.
  */
 export function hasAuthoredStubAfter(block, out, fixtures) {
+    if (stubPhaseLooksAuthored(block, "stubAfter", fixtures))
+        return true;
+    const instr = block.instruction;
+    if (instr.highlights)
+        return true;
     return resolveHighlightSlots(block, "stubAfter", {
         ...(out !== undefined ? { out } : {}),
         ...(fixtures !== undefined ? { fixtures } : {}),
     }).length > 0;
 }
 /**
- * True when stubOnError resolves to at least one ring (block and/or flow fixture).
+ * True when stubOnError is authored (lifecycle fn and/or rings).
  * Demo fail path only - success never consults this.
  */
 export function hasAuthoredStubOnError(block, fixtures) {
+    if (stubPhaseLooksAuthored(block, "stubOnError", fixtures))
+        return true;
     return (resolveHighlightSlots(block, "stubOnError", {
         ...(fixtures !== undefined ? { fixtures } : {}),
     }).length > 0);

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, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, 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, WaygraphTodoItem, WaygraphTodoInput, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, } from "./highlights.js";
+export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, 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, WaygraphTodoItem, WaygraphTodoInput, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, } 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, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, 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, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";

package/dist/types.d.ts

@@ -2,7 +2,7 @@ import type { Page } from "@playwright/test";
 import type { MemPage, MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
 import type { HighlightStubPhaseOrFn, WaygraphHighlight, WaygraphSlidesOrFn } from "./highlights.js";
-export type { WaygraphHighlight, WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, HighlightStubPhase, HighlightStubPhaseOrFn, HighlightFixtureMap, ResolvedHighlight, } from "./highlights.js";
+export type { WaygraphHighlight, WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, HighlightStubPhase, HighlightStubPhaseOrFn, HighlightFixtureMap, ResolvedHighlight, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, WaygraphTodoItem, WaygraphTodoInput, } from "./highlights.js";
 /**
  * A Checkpoint is identified solely by its string tag - a phantom marker with no
  * embedded data. Two Checkpoints with the same tag are the same state everywhere.
@@ -90,22 +90,34 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      */
     verify?: Trait[] | ((out: Out) => Trait[]);
     /**
-     * Catch-all demo slots shown **before / during** `act` (fill/click rings).
-     * Named map; `{}` is valid. Flow {@link HighlightFixtureMap} overrides labels.
-     * @example stubBefore: { email: { selector: "#email", label: "Email" } }
+     * Open block lifecycle **before / during** `act` (demo rings + fixtures).
+     * Prefer `stubBefore(ctx) { ctx.todos(...); ctx.ring(...) }` — not a closed
+     * slot object. Object map `{ email: { selector, label } }` remains a shorthand.
+     * Flow {@link HighlightFixtureMap} still overrides ring labels.
+     * @example stubBefore: (ctx) => {
+     *   ctx.todos(["Email", "Password", "Submit"]);
+     *   ctx.todoIndex(0);
+     *   ctx.highlights({ email: { selector: "#email", label: "Email" } });
+     * }
      */
     stubBefore?: HighlightStubPhaseOrFn<Out>;
     /**
-     * Catch-all demo slots shown **after** resolve (step panel rings).
-     * Named map; `{}` is valid. Prefer this over legacy {@link Instruction.highlights}.
-     * @example stubAfter: { badge: { selector: ".cart", label: "Cart updated" } }
+     * Open block lifecycle **after** resolve (step panel rings + fixtures).
+     * Prefer `stubAfter(ctx) { ... }`. Object map shorthand still works.
+     * Prefer this over legacy {@link Instruction.highlights}.
+     * @example stubAfter: (ctx) => {
+     *   ctx.todoIndex(2);
+     *   ctx.ring("badge", { selector: ".cart", label: "Cart updated" });
+     * }
      */
     stubAfter?: HighlightStubPhaseOrFn<Out>;
     /**
-     * Demo slots shown when a **step throws** (failed verify / act error) -
+     * Open block lifecycle when a **step throws** (failed verify / act error) -
      * before the error panel. Success-only {@link Instruction.stubAfter} never runs
-     * here; authors keep distinct BUG/FAIL copy. Named map; `{}` is valid.
-     * @example stubOnError: { card: { selector: ".alt-1", label: "Card at failure" } }
+     * here. Prefer `stubOnError(ctx) { ... }`.
+     * @example stubOnError: (ctx) => {
+     *   ctx.ring("card", { selector: ".alt-1", label: "Card at failure", tag: "BUG" });
+     * }
      */
     stubOnError?: HighlightStubPhaseOrFn<Out>;
     /**

package/examples/saucedemo/package-lock.json

@@ -17,7 +17,7 @@
       }
     },
     "../..": {
-      "version": "0.12.4",
+      "version": "0.12.24",
       "license": "MIT",
       "dependencies": {
         "tsx": "^4.0.0"
@@ -26,7 +26,7 @@
         "waygraph": "bin/waygraph"
       },
       "devDependencies": {
-        "@playwright/test": "^1.55.0",
+        "@playwright/test": "^1.63.0",
         "@types/node": "^26.0.0",
         "typescript": "^5.6.0"
       },

package/examples/saucedemo/src/blocks/saucedemo-web/methods/submit-login.method.block.ts

@@ -45,20 +45,29 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
         : [Trait.visible('[data-test="error"]')],
-    stubBefore: {
-      username: { selector: "#user-name", label: "Username" },
-      password: { selector: "#password", label: "Password" },
-      submit: { selector: "#login-button", label: "Login" },
+    // Open lifecycle: set fixtures + rings inside the fn (not a closed slot object).
+    stubBefore: (ctx) => {
+      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoIndex(0);
+      ctx.highlights({
+        username: { selector: "#user-name", label: "Username" },
+        password: { selector: "#password", label: "Password" },
+        submit: { selector: "#login-button", label: "Login" },
+      });
+    },
+    stubAfter: (ctx) => {
+      // Sequential plan: bump index after a successful submit beat.
+      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoIndex(2);
     },
-    stubAfter: {},
     // Fail-path rings (demo step throw only) - locked-out / wrong-password
     // bug-repro narration; success never shows these.
-    stubOnError: {
-      error: {
+    stubOnError: (ctx) => {
+      ctx.ring("error", {
         selector: '[data-test="error"]',
         label: "Login error banner",
         duration: true,
-      },
+      });
     },
   },
 });

package/package.json

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

package/templates/quickstart/src/blocks/saucedemo-web/methods/submit-login.method.block.ts

@@ -45,18 +45,25 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
         : [Trait.visible('[data-test="error"]')],
-    stubBefore: {
-      username: { selector: "#user-name", label: "Username" },
-      password: { selector: "#password", label: "Password" },
-      submit: { selector: "#login-button", label: "Login" },
+    stubBefore: (ctx) => {
+      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoIndex(0);
+      ctx.highlights({
+        username: { selector: "#user-name", label: "Username" },
+        password: { selector: "#password", label: "Password" },
+        submit: { selector: "#login-button", label: "Login" },
+      });
     },
-    stubAfter: {},
-    stubOnError: {
-      error: {
+    stubAfter: (ctx) => {
+      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoIndex(2);
+    },
+    stubOnError: (ctx) => {
+      ctx.ring("error", {
         selector: '[data-test="error"]',
         label: "Login error banner",
         duration: true,
-      },
+      });
     },
   },
 });