waygraph 0.12.23 → 0.12.24

package/dist/cli.js

@@ -207,6 +207,7 @@ import { tmpdir } from "node:os";
 import {
   resolveHighlightSlots,
   resolveSlides,
+  runStubPhase,
   resolveFixtureDwellMs,
   resolveSlideDwellMs,
   formatHighlightCaption,
@@ -1246,8 +1247,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 +2529,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 +2579,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 +2639,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 +2653,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 +2725,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 +2769,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/package.json

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