waygraph 0.12.22 → 0.12.24

package/dist/cli.js

@@ -207,6 +207,7 @@ import { tmpdir } from "node:os";
 import {
   resolveHighlightSlots,
   resolveSlides,
+  runStubPhase,
   resolveFixtureDwellMs,
   resolveSlideDwellMs,
   formatHighlightCaption,
@@ -224,6 +225,7 @@ import {
   demoPaceIsSlow,
   formatDemoPaceBadge,
   formatDemoPaceLabel,
+  normalizeTodos,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -507,6 +509,14 @@ const RING_CSS =
   "#wg-panel .wg-pace[data-pace-kind=blitz] .wg-pace-badge{background:#22C55E;color:#052e16;}" +
   "#wg-panel .wg-pace[data-pace-kind=ms] .wg-pace-badge{background:#3B82F6;color:#fff;}" +
   "#wg-panel .wg-narration{margin:0 0 12px;font:italic 14px/1.4 system-ui,sans-serif;color:#f0e8ff;}" +
+  "#wg-todos{list-style:none;margin:0 0 12px;padding:8px 10px;background:#0f0620;border-radius:8px;" +
+  "border:1px solid #3a2a60;}" +
+  "#wg-todos li{display:flex;gap:8px;align-items:flex-start;margin:0 0 6px;font:600 12.5px/1.35 system-ui,sans-serif;}" +
+  "#wg-todos li:last-child{margin-bottom:0;}" +
+  "#wg-todos .wg-todo-mark{flex:0 0 auto;width:1.1em;text-align:center;}" +
+  "#wg-todos .wg-todo-done{color:#6ee7b7;text-decoration:line-through;opacity:.85;}" +
+  "#wg-todos .wg-todo-current{color:#fff;}" +
+  "#wg-todos .wg-todo-pending{color:#9a7ad1;}" +
   "#wg-progress{height:4px;background:#2a1650;border-radius:2px;margin:0 0 12px;overflow:hidden;}" +
   "#wg-progress-bar{height:100%;background:#7C3AED;border-radius:2px;transition:width .3s ease;}" +
   // A real tab bar for episodes - the currently-active episode reads as
@@ -767,6 +777,31 @@ async function installOverlay(page, title) {
           const ringLabel = document.getElementById("wg-ring-label");
           if (ring) ring.style.opacity = "0";
           if (ringLabel) ringLabel.style.opacity = "0";
+          if (window.__wgClearZoom) window.__wgClearZoom();
+        };
+        window.__wgClearZoom = () => {
+          document.querySelectorAll("[data-wg-zoomed=\\"1\\"]").forEach((el) => {
+            el.style.removeProperty("transform");
+            el.style.removeProperty("transform-origin");
+            el.style.removeProperty("transition");
+            el.style.removeProperty("z-index");
+            el.style.removeProperty("position");
+            delete el.dataset.wgZoomed;
+          });
+        };
+        window.__wgApplyZoom = (sel, scale) => {
+          if (window.__wgClearZoom) window.__wgClearZoom();
+          const n = Number(scale);
+          if (!Number.isFinite(n) || n <= 1.001) return;
+          const el = document.querySelector(sel);
+          if (!el) return;
+          const st = getComputedStyle(el);
+          if (st.position === "static") el.style.position = "relative";
+          el.style.zIndex = "2147483645";
+          el.style.transition = "transform .35s ease";
+          el.style.transformOrigin = "center center";
+          el.style.transform = "scale(" + n + ")";
+          el.dataset.wgZoomed = "1";
         };
         const POSITIONS = ["left", "center", "right"];
         const applyPos = (el, pos) => {
@@ -988,7 +1023,8 @@ async function renderBeforeStep(page, info) {
         paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
-        narrationHtml;
+        narrationHtml +
+        todosHtmlFromInfo(info, esc);
       if (info.keys.length === 0) {
         html += "<div class=\\"wg-key\\">(no MemKeys required)</div>";
       }
@@ -1021,12 +1057,7 @@ async function renderBeforeStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel:
-            (info.index + 1) +
-            " / " +
-            info.total +
-            (info.blockName ? " · " + info.blockName : "") +
-            (info.paceBadge ? " · " + info.paceBadge : ""),
+          stepLabel: miniStepLabel(info),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1103,6 +1134,102 @@ async function renderBeforeStep(page, info) {
     .catch(() => {});
 }
 
+async function ensureSelectorInView(page, selector) {
+  try {
+    const loc = page.locator(selector).first();
+    await loc.scrollIntoViewIfNeeded().catch(() => {});
+    await page
+      .evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return;
+        try {
+          el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+        } catch {
+          try {
+            el.scrollIntoView(true);
+          } catch {
+            /* ignore */
+          }
+        }
+        let p = el.parentElement;
+        while (p && p !== document.documentElement && p !== document.body) {
+          const st = getComputedStyle(p);
+          const ox = st.overflowX;
+          const oy = st.overflowY;
+          if (/(auto|scroll|overlay)/.test(ox) || /(auto|scroll|overlay)/.test(oy)) {
+            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);
+            }
+          }
+          p = p.parentElement;
+        }
+      }, selector)
+      .catch(() => {});
+  } catch {
+    /* best-effort */
+  }
+}
+
+async function applyHighlightZoom(page, selector, zoom) {
+  const z = Number(zoom);
+  if (!Number.isFinite(z) || z <= 1.001) {
+    await page.evaluate(() => {
+      if (window.__wgClearZoom) window.__wgClearZoom();
+    }).catch(() => {});
+    return;
+  }
+  await page
+    .evaluate(
+      ({ sel, scale }) => {
+        if (window.__wgApplyZoom) window.__wgApplyZoom(sel, scale);
+      },
+      { sel: selector, scale: z },
+    )
+    .catch(() => {});
+}
+
+function todosHtmlFromInfo(info, escFn) {
+  const list = info.todos || [];
+  if (!list.length) return "";
+  return (
+    "<ul id=\\"wg-todos\\">" +
+    list
+      .map((t) => {
+        const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
+        const mark = t.done ? "\\u2713" : t.current ? "\\u2192" : "\\u25CB";
+        return (
+          "<li class=\\"" +
+          cls +
+          "\\"><span class=\\"wg-todo-mark\\">" +
+          mark +
+          "</span><span>" +
+          escFn(t.text || "") +
+          "</span></li>"
+        );
+      })
+      .join("") +
+    "</ul>"
+  );
+}
+
+function miniStepLabel(info) {
+  const ep =
+    info.episodeNumber !== undefined && info.episodeNumber !== null
+      ? "Ep " + info.episodeNumber + " \\u00b7 "
+      : "";
+  return (
+    ep +
+    (info.index + 1) +
+    " / " +
+    info.total +
+    (info.blockName ? " \\u00b7 " + info.blockName : "") +
+    (info.paceBadge ? " \\u00b7 " + info.paceBadge : "")
+  );
+}
+
 async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   const list = highlights || [];
   // defaultHoldMs: when set (fail path), use instead of legacy 900/200 so BUG
@@ -1112,12 +1239,50 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   for (let i = 0; i < list.length; i++) {
     const h = list[i];
     try {
+      await ensureSelectorInView(page, h.selector);
+      await applyHighlightZoom(page, h.selector, h.zoom);
       const box = await page.locator(h.selector).first().boundingBox();
       if (box) {
         await showRing(page, box, h.label, h.tone || "planned", {
           size: h.size,
           weight: h.weight,
         });
+        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");
+              if (!ul) return;
+              ul.innerHTML = todos
+                .map((t) => {
+                  const cls = t.current
+                    ? "wg-todo-current"
+                    : t.done
+                      ? "wg-todo-done"
+                      : "wg-todo-pending";
+                  const mark = t.done ? "\\u2713" : t.current ? "\\u2192" : "\\u25CB";
+                  const esc = (s) =>
+                    String(s)
+                      .replace(/&/g, "&amp;")
+                      .replace(/</g, "&lt;")
+                      .replace(/>/g, "&gt;");
+                  return (
+                    "<li class=\\"" +
+                    cls +
+                    "\\"><span class=\\"wg-todo-mark\\">" +
+                    mark +
+                    "</span><span>" +
+                    esc(t.text || "") +
+                    "</span></li>"
+                  );
+                })
+                .join("");
+            }, rows)
+            .catch(() => {});
+        }
         const authored = resolveFixtureDwellMs(h, { gatesFast, pace });
         const legacyMs = i === list.length - 1 ? 200 : 900;
         const holdMs =
@@ -1261,6 +1426,7 @@ async function renderAfterStep(page, info) {
         paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
+        todosHtmlFromInfo(info, escA) +
         resultHtml +
         gateHtml;
       if (isNewPanel) {
@@ -1269,12 +1435,7 @@ async function renderAfterStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel:
-            (info.index + 1) +
-            " / " +
-            info.total +
-            (info.blockName ? " · " + info.blockName : "") +
-            (info.paceBadge ? " · " + info.paceBadge : ""),
+          stepLabel: miniStepLabel(info),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1376,12 +1537,7 @@ async function renderStepError(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel:
-            (info.index + 1) +
-            " / " +
-            info.total +
-            (info.blockName ? " · " + info.blockName : "") +
-            (info.paceBadge ? " · " + info.paceBadge : ""),
+          stepLabel: miniStepLabel(info),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1609,6 +1765,8 @@ async function presentSlides(page, slides, _gate, opts) {
     await installOverlay(page, title);
     if (s.selector) {
       try {
+        await ensureSelectorInView(page, s.selector);
+        await applyHighlightZoom(page, s.selector, s.zoom);
         const box = await page.locator(s.selector).first().boundingBox();
         if (box) await showRing(page, box, caption, slideTone, slideStyle);
       } catch {
@@ -1696,11 +1854,14 @@ async function presentSlides(page, slides, _gate, opts) {
         if (window.__wgWirePanelChrome) {
           window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
             stepLabel:
+              (info.episodeNumber !== undefined && info.episodeNumber !== null
+                ? "Ep " + info.episodeNumber + " \\u00b7 "
+                : "") +
               "Slide " +
               (info.index + 1) +
               " / " +
               info.total +
-              (info.blockName ? " · " + info.blockName : ""),
+              (info.blockName ? " \\u00b7 " + info.blockName : ""),
             forceCollapsed: false,
           });
         }
@@ -2368,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.
@@ -2416,6 +2579,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeTitle: r.episodeTitle,
       stepperMode,
       forceCollapsed,
+      todos: stubBeforeTodos,
       ...paceSpeak,
     });
     const edits = await gate();
@@ -2475,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,
@@ -2487,11 +2653,13 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
             tone: styled.tone,
             size: styled.size,
             weight: styled.weight,
+            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
@@ -2557,21 +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,
-          };
-        },
-      );
+      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),
@@ -2596,6 +2769,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
       stepperMode,
+      todos: stubAfterTodos,
       // After a nav under auto-next, stay compact until the next action block expands.
       forceCollapsed: !!process.env.WAYGRAPH_VIDEO || ((await currentAutoplay()) && isNavBlock),
     });
@@ -2690,7 +2864,7 @@ async function runChainedFlows(chainFlow, chainFlows, context, mem, page) {
 /** Parses WAYGRAPH_VIDEO_VIEWPORT / --video-viewport: "1920x1080" or "1920,1080". */
 function parseVideoViewport(raw) {
   if (!raw || !raw.trim()) return null;
-  const m = raw.trim().match(/^(\d{3,5})[xX,](\d{3,5})$/);
+  const m = raw.trim().match(/^(\\d{3,5})[xX,](\\d{3,5})$/);
   if (!m) return null;
   const width = Number(m[1]);
   const height = Number(m[2]);
@@ -2981,7 +3155,13 @@ async function main() {
       ...(executablePath ? { executablePath } : {}),
     });
     const contextOpts = fixedVideoViewport
-      ? { baseURL, viewport: fixedVideoViewport }
+      ? {
+          baseURL,
+          viewport: fixedVideoViewport,
+          // Lock DPR so --video-viewport 800x450 stays 800x450 in the .webm
+          // (HiDPI hosts otherwise scale recordVideo to e.g. 1920x1080).
+          deviceScaleFactor: 1,
+        }
       : step
         ? { baseURL, viewport: null }
         : { baseURL, viewport: { width: 1280, height: 720 } };

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).
  *
@@ -24,6 +28,26 @@ export type FixtureDurationFields = {
      */
     fastMode?: number;
 };
+/**
+ * One checklist row for episode planning (demo panel).
+ * Set via {@link StubCtx.todos} / {@link StubCtx.todoIndex} inside the lifecycle.
+ */
+export type WaygraphTodoItem = {
+    text: string;
+    /** Explicit done. If omitted, derived from todoIndex (index < todoIndex). */
+    done?: boolean;
+    /** Explicit current. If omitted, derived from todoIndex (index === todoIndex). */
+    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;
@@ -50,11 +74,72 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      * Aliases: regular, strong.
      */
     weight?: HighlightWeight;
+    /**
+     * 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"> & 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.
@@ -69,6 +154,8 @@ export interface WaygraphSlide extends FixtureDurationFields {
     tone?: HighlightTone;
     size?: HighlightSize;
     weight?: HighlightWeight;
+    /** Magnify selector target while this slide is showing (same as stub zoom). */
+    zoom?: number;
 }
 /**
  * Demo ring tones (iconified).
@@ -189,9 +276,25 @@ export interface WaygraphHighlight {
 }
 export type ResolvedHighlight = WaygraphHighlightStub;
 /**
- * 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.
+ * Normalize checklist rows; apply todoIndex for sequential done/current.
+ */
+export declare function normalizeTodos(todos: readonly WaygraphTodoInput[] | undefined, todoIndex?: number): WaygraphTodoItem[];
+/**
+ * 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>;
@@ -214,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).
  *
@@ -289,11 +293,43 @@ function pickStyleFields(base, patch) {
         out.weight = normalizeHighlightWeight(weight);
     return out;
 }
+/**
+ * Normalize checklist rows; apply todoIndex for sequential done/current.
+ */
+export function normalizeTodos(todos, todoIndex) {
+    if (!todos || todos.length === 0)
+        return [];
+    const idx = todoIndex !== undefined && Number.isFinite(todoIndex) ? Math.floor(todoIndex) : undefined;
+    return todos.map((t, i) => {
+        const text = typeof t === "string" ? t.trim() : String(t?.text ?? "").trim();
+        const item = { text: text || `Item ${i + 1}` };
+        if (typeof t === "object" && t) {
+            if (t.done !== undefined)
+                item.done = !!t.done;
+            if (t.current !== undefined)
+                item.current = !!t.current;
+        }
+        if (idx !== undefined) {
+            if (item.done === undefined)
+                item.done = i < idx;
+            if (item.current === undefined)
+                item.current = i === idx;
+        }
+        return item;
+    });
+}
+function pickZoom(base, patch) {
+    const zoom = patch?.zoom !== undefined ? patch.zoom : base?.zoom;
+    if (zoom !== undefined && Number.isFinite(zoom) && zoom > 0)
+        return { zoom };
+    return {};
+}
 function mergeSlot(base, patch) {
     if (!base && !patch)
         return null;
     const dwell = pickDurationFields(base, patch);
     const style = pickStyleFields(base, patch);
+    const zoom = pickZoom(base, patch);
     if (!base && patch) {
         if (!patch.selector)
             return null;
@@ -304,6 +340,7 @@ function mergeSlot(base, patch) {
             ...(patch.tag ? { tag: patch.tag } : {}),
             ...style,
             ...dwell,
+            ...zoom,
         };
     }
     if (base && !patch) {
@@ -312,6 +349,7 @@ function mergeSlot(base, patch) {
             ...(base.tone ? { tone: normalizeHighlightTone(base.tone) } : {}),
             ...(base.size ? { size: normalizeHighlightSize(base.size) } : {}),
             ...(base.weight ? { weight: normalizeHighlightWeight(base.weight) } : {}),
+            ...pickZoom(base, undefined),
         };
     }
     return {
@@ -325,8 +363,78 @@ function mergeSlot(base, patch) {
         ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
         ...style,
         ...dwell,
+        ...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)
@@ -342,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,
@@ -428,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, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
-export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, } from "./highlights.js";
+export { 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, 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.22",
+  "version": "0.12.24",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",