waygraph 0.15.54 → 0.16.1

package/dist/demo/stepper/panel-before.js

@@ -0,0 +1,241 @@
+// The demo panel before a step: episode and step chips, pace, the mem it reads (editable), and the Run gate.
+import { envFlag, envString } from "../../engine/env.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+import { installOverlay } from "../overlay/overlay.js";
+import { miniStepLabel } from "./step-panels.js";
+export async function renderBeforeStep(page, info) {
+    await installOverlay(page, info.title, info.bannerUi, info.caption, info.networkTabVisible);
+    // A ring left highlighting the PREVIOUS step's element (and its live
+    // resize/scroll tracker) shouldn't linger once a new step's own panel is
+    // up - only relevant when a Block's act() doesn't navigate away, since a
+    // real navigation already wipes document.documentElement's children.
+    await page
+        .evaluate(() => {
+        if (window.__wgRingTrack) {
+            window.removeEventListener("resize", window.__wgRingTrack);
+            window.removeEventListener("scroll", window.__wgRingTrack, true);
+            window.__wgRingTrack = null;
+        }
+        if (window.__wgHideRing)
+            window.__wgHideRing();
+        if (window.__wgHideCursor)
+            window.__wgHideCursor();
+    })
+        .catch(ignorePageGone);
+    // miniStepLabel / todosHtmlFromInfo are Node-only — browser evaluate has no closure.
+    const payload = { ...info, stepLabel: miniStepLabel(info) };
+    await page
+        .evaluate((info) => {
+        // Reused in place, not removed + recreated, every step - the old
+        // remove()-then-fade-back-in cycle was a real flash on every single
+        // transition (the user: "the appear and disappear... hurts eyes and
+        // dizzy"). Updating one persistent element's content has nothing to
+        // flash - it only ever fades in ONCE, the first time this page
+        // genuinely has no panel yet (a real navigation wiped the whole
+        // document, or this is the very first step).
+        let panel = __wgById("wg-panel");
+        const isNewPanel = !panel;
+        if (!panel) {
+            panel = document.createElement("div");
+            panel.id = "wg-panel";
+        }
+        const pct = Math.round((info.index / info.total) * 100);
+        // A real tab bar, not a single text line - every episode this chain
+        // touches, the current one reading as active (the user: "if episode 1 is
+        // active, the episode 2 tab is inactive"). Absent entirely for an ad
+        // hoc block chain with no named Flows.
+        const episodes = info.allEpisodes && info.allEpisodes.length > 0
+            ? __wgEl("div", { id: "wg-episodes" }, info.allEpisodes.map((e) => {
+                const cls = e.episodeNumber < (info.episodeNumber ?? 0) ? "wg-ep-done"
+                    : e.episodeNumber === info.episodeNumber ? "wg-ep-current"
+                        : "wg-ep-upcoming";
+                // The gentle one-time glow only plays on the tab actually
+                // being entered right now, not on every render of it.
+                const enteredCls = info.justEnteredEpisode && e.episodeNumber === info.episodeNumber
+                    ? " wg-ep-entered"
+                    : "";
+                return __wgEl("span", { class: "wg-ep-tab " + cls + enteredCls }, "Episode " + e.episodeNumber + ": " + (e.episodeTitle || ""));
+            }))
+            : null;
+        // Scoped to THIS episode's own blocks (info.allNames is already the
+        // episode-local subset the caller computed) - moduleIndex is this
+        // step's position WITHIN that subset, not the whole chain's index -
+        // "in episode 2 it shows 2nd to the last... it should start from the
+        // first block" (the user).
+        const modulesClass = info.stepperMode === "full" ? "wg-modules-full" : "wg-modules-carousel";
+        const modules = info.allNames.map((name, idx) => {
+            const cls = idx < info.moduleIndex ? "wg-mod-done" : idx === info.moduleIndex ? "wg-mod-current" : "wg-mod-upcoming";
+            const desc = info.allDescriptions && info.allDescriptions[idx];
+            return __wgEl("span", { class: "wg-mod " + cls, title: desc || undefined }, String(name));
+        });
+        const pace = info.paceBadge || info.paceLabel
+            ? __wgEl("div", { class: "wg-pace", data: { paceKind: info.paceKind || "normal" } }, __wgEl("span", { class: "wg-pace-badge" }, info.paceBadge || "1x"), __wgEl("span", null, info.paceLabel || ""))
+            : null;
+        const keys = info.keys.length === 0
+            ? [__wgEl("div", { class: "wg-key" }, "(no MemKeys required)")]
+            : info.keys.map((k) => {
+                const field = __wgEl("textarea", { data: { key: k.name }, attrs: { rows: 2 } });
+                field.value = k.value;
+                return __wgEl("div", { class: "wg-key" }, __wgEl("label", null, k.name), field, __wgEl("div", { class: "wg-key-pretty", data: { prettyFor: k.name } }));
+            });
+        let autoNow = false;
+        try {
+            autoNow = localStorage.getItem("wg-autoplay") === "1";
+        }
+        catch {
+            /* private mode / blocked storage - defaults to manual */
+        }
+        const autoplay = __wgEl("input", { id: "wg-autoplay-cb", attrs: { type: "checkbox" } });
+        autoplay.checked = autoNow;
+        // Todos render into floating #wg-todo-dock via __wgSyncTodos - never
+        // inside .wg-body (would vanish under --mini / Hide collapse).
+        __wgSet(panel, __wgEl("div", { id: "wg-progress" }, __wgEl("div", { id: "wg-progress-bar", style: "width:" + pct + "%" })), episodes, pace, __wgEl("div", { id: "wg-modules", class: modulesClass }, modules), __wgEl("h3", null, "Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName), info.description ? __wgEl("div", { class: "wg-narration" }, info.description) : null, keys, __wgEl("div", { class: "wg-autoplay-row" }, __wgEl("label", null, autoplay, " Auto-advance")), __wgEl("div", { id: "wg-gate-manual", style: autoNow ? "display:none" : "" }, __wgEl("button", { id: "wg-run" }, "Run this step \u25B6")), __wgEl("div", { id: "wg-gate-auto", class: "wg-auto", style: autoNow ? "" : "display:none" }, "Auto-advancing..."));
+        if (isNewPanel) {
+            __wgAdd(panel);
+            requestAnimationFrame(() => panel.classList.add("wg-in"));
+        }
+        else {
+            panel.classList.add("wg-in");
+        }
+        if (window.__wgWirePanelChrome) {
+            window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
+                stepLabel: info.stepLabel || "",
+                forceCollapsed: info.forceCollapsed === true ? true : undefined,
+                fastForward: !!info.fastForward,
+                isApi: !!info.isApi,
+            });
+        }
+        if (window.__wgSyncTodos) {
+            const sync = info.todoSync || (info.todos && info.todos.length ? "set" : "keep");
+            // Prefer dock-only payload. Passing list:[] with a dock used to clear
+            // marks a frame later (empty-list clear path).
+            if (sync === "keep" && !info.todoDock) {
+                /* leave floating dock alone */
+            }
+            else {
+                const payload = {
+                    sync: sync,
+                    dock: info.todoDock || null,
+                    pos: info.todoPos || null,
+                    todoId: info.todoId || (info.todoDock && info.todoDock.id) || null,
+                };
+                if (!info.todoDock && info.todos && info.todos.length) {
+                    payload.list = info.todos;
+                }
+                window.__wgSyncTodos(payload);
+            }
+        }
+        if (window.__wgStampModal) {
+            window.__wgStampModal(panel, "panel", {
+                phase: "before",
+                step: info.index + 1,
+                total: info.total,
+                block: info.blockName || "",
+                ready: true,
+            });
+        }
+        // Live, human-readable preview of what a MemKey's raw JSON will
+        // actually write - object fields become "Field: value" lines
+        // (camelCase split the same way state tags already are); a
+        // non-object payload (a plain string/number/array) is shown as-is.
+        // Hidden entirely in JSON mode - shares the SAME global toggle the
+        // result display's own Pretty/JSON buttons already set, not a
+        // second, separate preference.
+        const prettyMemValue = (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return [__wgEl("em", null, "(invalid JSON)")];
+            }
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return [JSON.stringify(parsed)];
+            }
+            return Object.entries(parsed).map(([field, value]) => {
+                const label = field.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/^./, (c) => c.toUpperCase());
+                return __wgEl("div", { class: "wg-key-pretty-row" }, __wgEl("span", { class: "wg-key-pretty-label" }, label + ":"), " " + String(value));
+            });
+        };
+        const applyKeyPretty = () => {
+            const prettyOn = window.__wgPretty !== false;
+            panel.querySelectorAll("textarea[data-key]").forEach((ta) => {
+                const previewEl = ta.parentElement?.querySelector(".wg-key-pretty");
+                if (!previewEl)
+                    return;
+                previewEl.style.display = prettyOn ? "" : "none";
+                if (prettyOn)
+                    __wgSet(previewEl, prettyMemValue(ta.value));
+            });
+        };
+        applyKeyPretty();
+        panel.querySelectorAll("textarea[data-key]").forEach((ta) => {
+            ta.addEventListener("input", applyKeyPretty);
+        });
+        const runBtn = __wgById("wg-run");
+        if (runBtn) {
+            runBtn.addEventListener("click", () => {
+                const edits = {};
+                panel.querySelectorAll("textarea[data-key]").forEach((el) => {
+                    edits[el.getAttribute("data-key") ?? ""] = el.value;
+                });
+                window.__wgNext(edits);
+            });
+        }
+        // Live toggle - flips localStorage immediately so an in-flight gate()
+        // poll (on the Node side) picks it up within its next poll slice,
+        // without needing this whole panel to re-render. A manual click
+        // still always wins over an active autoplay wait, whichever the
+        // checkbox says - this is the "hybrid" control: autoplay is a
+        // default, not a lockout.
+        const cb = __wgById("wg-autoplay-cb");
+        if (cb) {
+            cb.addEventListener("change", () => {
+                try {
+                    localStorage.setItem("wg-autoplay", cb.checked ? "1" : "0");
+                }
+                catch {
+                    /* private mode / blocked storage - toggle still works this page */
+                }
+                const manual = __wgById("wg-gate-manual");
+                const auto = __wgById("wg-gate-auto");
+                if (manual)
+                    manual.style.display = cb.checked ? "none" : "";
+                if (auto)
+                    auto.style.display = cb.checked ? "" : "none";
+            });
+        }
+    }, payload)
+        .catch(ignorePageGone);
+    if (envString("WAYGRAPH_PROVE_SHOT") || envFlag("WAYGRAPH_PROVE_EXIT")) {
+        // Default: prove once on first painted panel. PROVE_EVERY=1 re-checks
+        // every step (noisy; useful when hunting a mid-chain blank).
+        const proveEvery = envFlag("WAYGRAPH_PROVE_EVERY");
+        const already = globalThis.__wgProveDone;
+        if (!already || proveEvery || envFlag("WAYGRAPH_PROVE_EXIT")) {
+            await page.waitForTimeout(500).catch(ignoreTimeout);
+            const shot = envString("WAYGRAPH_PROVE_SHOT");
+            if (shot)
+                await page.screenshot({ path: shot }).catch(ignorePageGone);
+            const ok = await page
+                .evaluate(() => {
+                const beacons = typeof window.__wgOverlayBeacon === "function" ? window.__wgOverlayBeacon() : [];
+                const panel = beacons.find((b) => b.modal === "panel" && b.ready && b.visible);
+                const textOk = panel && panel.textLen >= 12;
+                const opacityOk = panel && Number(panel.opacity) > 0.5;
+                return {
+                    ok: !!(panel && textOk && opacityOk),
+                    beacons,
+                    hasRun: !!__wgById("wg-run"),
+                    readyAttr: __wgById("wg-panel")?.getAttribute("data-wg-ready") || null,
+                };
+            })
+                .catch((e) => ({ ok: false, reason: String(e instanceof Error ? e.message : e) }));
+            console.error("WAYGRAPH_PROVE " + JSON.stringify(ok));
+            globalThis.__wgProveDone = true;
+            if (envFlag("WAYGRAPH_PROVE_EXIT")) {
+                process.exit(ok && ok.ok ? 0 : 2);
+            }
+        }
+    }
+}

package/dist/demo/stepper/slides.d.ts

@@ -0,0 +1,23 @@
+import type { WgPage } from "../types.js";
+import { type WaygraphSlide } from "../../engine/stub/ring.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+/** Where the slides sit (title, Block, episode) and how fast they advance. */
+export interface SlidesOptions {
+    title?: string | undefined;
+    blockName?: string | undefined;
+    episodeNumber?: number | undefined;
+    episodeTitle?: string | undefined;
+    fast?: boolean | undefined;
+    pace?: DemoPace | undefined;
+    autoplayMs?: number | undefined;
+}
+/**
+ * Multi-step yap captions - not block lifecycle. Each slide waits for Next
+ * (or auto-next), optional ring via slide.selector.
+ *
+ * Advance wait does NOT use exposeFunction/gate(): after a real navigation
+ * (e.g. finish-order -> checkout-complete) the panel can render while
+ * __wgNext is momentarily wedged, which left "Next slide" looking live but
+ * doing nothing. In-page data-wg-acked + autoplay poll is the source of truth.
+ */
+export declare function presentSlides(page: WgPage, slides: readonly WaygraphSlide[], opts?: SlidesOptions): Promise<void>;

package/dist/demo/stepper/slides.js

@@ -0,0 +1,233 @@
+import { demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeDemoPace, resolveFixtureDwellMs } from "../narration/demo-pace.js";
+import { formatHighlightCaption } from "../narration/style.js";
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../engine/stub/ring.js";
+import { installOverlay } from "../overlay/overlay.js";
+import { applyHighlightZoom, ensureSelectorInView, hideRing, showRing } from "../overlay/rings.js";
+import { demoPaceKind } from "./demo-log.js";
+import { envFlag, envNumber, envString } from "../../engine/env.js";
+/**
+ * Multi-step yap captions - not block lifecycle. Each slide waits for Next
+ * (or auto-next), optional ring via slide.selector.
+ *
+ * Advance wait does NOT use exposeFunction/gate(): after a real navigation
+ * (e.g. finish-order -> checkout-complete) the panel can render while
+ * __wgNext is momentarily wedged, which left "Next slide" looking live but
+ * doing nothing. In-page data-wg-acked + autoplay poll is the source of truth.
+ */
+export async function presentSlides(page, slides, opts) {
+    const title = (opts && opts.title) || "waygraph demo";
+    const blockName = (opts && opts.blockName) || "";
+    const episodeNumber = opts && opts.episodeNumber;
+    const episodeTitle = (opts && opts.episodeTitle) || "";
+    const gatesFast = !!(opts && opts.fast);
+    const demoPace = normalizeDemoPace((opts && opts.pace) || (gatesFast ? "fast" : "normal"));
+    const baseAutoplay = opts && opts.autoplayMs
+        ? Number(opts.autoplayMs)
+        : (envNumber("WAYGRAPH_AUTOPLAY_MS") ?? 1800);
+    const autoplayMs = demoPaceGateMs(demoPace, baseAutoplay);
+    for (let i = 0; i < slides.length; i++) {
+        const s = slides[i];
+        const caption = formatHighlightCaption(s);
+        const slideTone = normalizeHighlightTone(s.tone);
+        const slideStyle = {
+            size: normalizeHighlightSize(s.size),
+            weight: normalizeHighlightWeight(s.weight),
+        };
+        const isLast = i === slides.length - 1;
+        const dwellMs = resolveFixtureDwellMs(s, { gatesFast, pace: demoPace });
+        await installOverlay(page, title);
+        if (s.selector) {
+            try {
+                await ensureSelectorInView(page, s.selector);
+                await applyHighlightZoom(page, s.selector, s.zoom, undefined);
+                // Playwright's own locator (>> piercing / :has-text() / :visible support), not a raw
+                // querySelector string - see rings.js's showRing for the same fix, same reason. count()
+                // gate: Locator.evaluate() has no timeout option and auto-waits ~30s for a match to
+                // appear - count() never waits, keeping this an immediate "does it exist now" check.
+                const sLoc = page.locator(s.selector).first();
+                const box = (await sLoc.count().catch(() => 0)) > 0
+                    ? await sLoc
+                        .evaluate((el) => {
+                        const r = el.getBoundingClientRect();
+                        return { x: r.x, y: r.y, width: r.width, height: r.height };
+                    })
+                        .catch(() => null)
+                    : null;
+                if (box && box.width > 0 && box.height > 0) {
+                    await showRing(page, box, caption, slideTone, {
+                        ...slideStyle,
+                        selector: s.selector,
+                        focus: false,
+                    });
+                }
+            }
+            catch {
+                await hideRing(page);
+            }
+        }
+        else {
+            await hideRing(page);
+        }
+        await page.evaluate((info) => {
+            let panel = __wgById("wg-panel");
+            const isNew = !panel;
+            if (!panel) {
+                panel = document.createElement("div");
+                panel.id = "wg-panel";
+            }
+            panel.classList.remove("wg-error", "wg-expected");
+            // Do not clear wg-collapsed - WirePanelChrome honors Hide (localStorage)
+            // unless forceCollapsed:true (--mini / --video).
+            const episodeLine = info.episodeNumber !== undefined && info.episodeNumber !== null
+                ? __wgEl("div", { class: "wg-episode" }, "Episode " + info.episodeNumber + (info.episodeTitle ? ": " + info.episodeTitle : "") + " · yap slides")
+                : null;
+            const pace = info.paceBadge || info.paceLabel
+                ? __wgEl("div", { class: "wg-pace", data: { paceKind: info.paceKind || "normal" } }, __wgEl("span", { class: "wg-pace-badge" }, info.paceBadge || "1x"), __wgEl("span", null, info.paceLabel || ""))
+                : null;
+            const autoplay = __wgEl("input", { id: "wg-autoplay-cb", attrs: { type: "checkbox" } });
+            autoplay.checked = !!info.autoNow;
+            const run = __wgEl("button", { id: "wg-run", attrs: { type: "button" } }, info.isLast ? "Continue \u25B6" : "Next slide \u25B6");
+            run.disabled = info.dwellMs != null;
+            __wgSet(panel, __wgEl("div", { class: "wg-chrome" }, __wgEl("span", { class: "wg-chrome-title" }, "waygraph demo"), __wgEl("button", { class: "wg-hide-btn", data: { wgToggle: "1" }, attrs: { type: "button" } }, "Hide")), __wgEl("div", { class: "wg-body" }, episodeLine, pace, __wgEl("h3", null, "Slide " + (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : "")), info.tag ? __wgEl("div", { style: "border:none;padding:0;margin:0 0 6px;font-size:11px;color:#c9a6ff" }, info.tag) : null, __wgEl("div", { class: "wg-narration" }, String(info.caption)), info.detail ? __wgEl("div", { class: "wg-result-pretty", style: "margin:0 0 12px;color:#f0e8ff" }, info.detail) : null, info.dwellMs != null
+                ? __wgEl("div", { class: "wg-auto", id: "wg-dwell-hint", style: "margin:0 0 8px" }, "Hold " + (info.dwellMs / 1000).toFixed(1) + "s before next...")
+                : null, __wgEl("div", { class: "wg-autoplay-row" }, __wgEl("label", null, autoplay, " Auto-advance")), __wgEl("div", { id: "wg-gate-manual", style: info.autoNow ? "display:none" : "" }, run), __wgEl("div", { id: "wg-gate-auto", class: "wg-auto", style: info.autoNow ? "" : "display:none" }, "Auto-advancing...")));
+            if (isNew) {
+                __wgAdd(panel);
+                requestAnimationFrame(() => panel.classList.add("wg-in"));
+            }
+            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 ? " \u00b7 " + info.blockName : ""),
+                    // Video / --mini: compact pill. Else omit so Hide sticks.
+                    forceCollapsed: info.forceCollapsed === true ? true : undefined,
+                });
+            }
+            if (window.__wgStampModal) {
+                window.__wgStampModal(panel, "panel", {
+                    phase: "slide",
+                    step: info.index + 1,
+                    total: info.total,
+                    block: info.blockName || "",
+                    ready: true,
+                });
+            }
+            let autoNow = false;
+            try {
+                autoNow = localStorage.getItem("wg-autoplay") === "1";
+            }
+            catch {
+                /* ignore */
+            }
+            const cb = __wgById("wg-autoplay-cb");
+            if (cb) {
+                cb.checked = autoNow;
+                cb.addEventListener("change", () => {
+                    try {
+                        localStorage.setItem("wg-autoplay", cb.checked ? "1" : "0");
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    const manual = __wgById("wg-gate-manual");
+                    const auto = __wgById("wg-gate-auto");
+                    if (manual)
+                        manual.style.display = cb.checked ? "none" : "";
+                    if (auto)
+                        auto.style.display = cb.checked ? "" : "none";
+                });
+            }
+            const manual = __wgById("wg-gate-manual");
+            const auto = __wgById("wg-gate-auto");
+            if (manual)
+                manual.style.display = autoNow ? "none" : "";
+            if (auto)
+                auto.style.display = autoNow ? "" : "none";
+            const runBtn = __wgById("wg-run");
+            if (runBtn) {
+                runBtn.removeAttribute("data-wg-acked");
+                runBtn.addEventListener("click", (e) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    if (runBtn.disabled)
+                        return;
+                    runBtn.setAttribute("data-wg-acked", "1");
+                });
+            }
+            if (info.dwellMs != null && info.dwellMs > 0) {
+                const unlockAt = Date.now() + info.dwellMs;
+                const tick = () => {
+                    const left = Math.max(0, unlockAt - Date.now());
+                    const hint = __wgById("wg-dwell-hint");
+                    const btn = __wgById("wg-run");
+                    if (left <= 0) {
+                        if (hint)
+                            hint.remove();
+                        if (btn)
+                            btn.disabled = false;
+                        return;
+                    }
+                    if (hint)
+                        hint.textContent = "Hold " + (left / 1000).toFixed(1) + "s before next...";
+                    setTimeout(tick, 100);
+                };
+                setTimeout(tick, 100);
+            }
+        }, {
+            index: i,
+            total: slides.length,
+            caption: s.caption,
+            detail: s.detail || "",
+            tag: s.tag || "",
+            blockName,
+            isLast,
+            autoNow: false,
+            dwellMs,
+            episodeNumber: episodeNumber !== undefined ? episodeNumber : null,
+            episodeTitle,
+            paceBadge: formatDemoPaceBadge(demoPace, baseAutoplay),
+            paceLabel: formatDemoPaceLabel(demoPace, baseAutoplay),
+            paceKind: demoPaceKind(demoPace),
+            forceCollapsed: !!envString("WAYGRAPH_VIDEO") ||
+                envFlag("WAYGRAPH_MINI")
+                ? true
+                : undefined,
+        });
+        const started = Date.now();
+        // When duration is set: floor both manual Next and auto-next to dwellMs.
+        // When unset: auto uses autoplayMs, manual Next is immediate.
+        const autoWaitMs = dwellMs != null ? dwellMs : autoplayMs;
+        for (;;) {
+            const acked = await page
+                .evaluate(() => {
+                const btn = __wgById("wg-run");
+                return !!(btn && btn.getAttribute("data-wg-acked") === "1");
+            })
+                .catch(() => false);
+            if (acked) {
+                if (dwellMs == null || Date.now() - started >= dwellMs)
+                    break;
+            }
+            const auto = await page
+                .evaluate(() => {
+                try {
+                    return localStorage.getItem("wg-autoplay") === "1";
+                }
+                catch {
+                    return false;
+                }
+            })
+                .catch(() => false);
+            if (auto && Date.now() - started >= autoWaitMs)
+                break;
+            await new Promise((res) => setTimeout(res, 100));
+        }
+    }
+    await hideRing(page);
+}

package/dist/demo/stepper/step-panels.d.ts

@@ -0,0 +1,69 @@
+import type { SomeBlock } from "../../engine/block/block.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { HighlightStyleDefaults } from "../../engine/stub/ring.js";
+import type { TodoDockState, WaygraphTodoItem } from "../../engine/stub/todos.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { BannerUiState, WgPage } from "../types.js";
+/** What every step panel shows: where the step sits in the run and its episode, its pace, and how the panel looks. */
+export interface StepPanelInfo {
+    index: number;
+    total: number;
+    blockName: string;
+    allNames: readonly string[];
+    allDescriptions?: readonly string[] | undefined;
+    moduleIndex: number;
+    allEpisodes?: readonly {
+        episodeNumber: number;
+        episodeTitle: string;
+    }[] | undefined;
+    episodeNumber?: number | undefined;
+    episodeTitle?: string | undefined;
+    title?: string | undefined;
+    bannerUi?: BannerUiState | null | undefined;
+    caption?: string | undefined;
+    networkTabVisible?: boolean | undefined;
+    stepperMode?: "full" | "carousel" | undefined;
+    forceCollapsed?: boolean | undefined;
+    fastForward?: boolean | undefined;
+    isApi?: boolean | undefined;
+    paceBadge?: string | undefined;
+    paceLabel?: string | undefined;
+    paceKind?: string | undefined;
+}
+/** The todo dock a panel syncs when it paints. */
+export interface PanelTodos {
+    todos?: readonly WaygraphTodoItem[] | undefined;
+    todoDock?: TodoDockState | undefined;
+    todoSync?: "set" | "clear" | "keep" | undefined;
+    todoId?: string | undefined;
+    todoPos?: string | undefined;
+}
+/** A failed step: what threw (or the expected-failure result), its stubOnError narration, and the Retry/Stop gate. */
+export interface FailPanelOptions extends StepPanelInfo {
+    block: SomeBlock;
+    highlightStyle?: HighlightStyleDefaults | undefined;
+    error: unknown;
+    out?: Checkpoint<string>;
+    message: string;
+    expectedFailureReason?: string | undefined;
+    gatesFast?: boolean | undefined;
+    demoPace?: DemoPace | undefined;
+    gate: () => Promise<Record<string, string>>;
+    mem: MemPage;
+}
+export declare function miniStepLabel(info: Pick<StepPanelInfo, "episodeNumber" | "index" | "total" | "blockName" | "paceBadge">): string;
+/**
+ * stubOnError rings + amber "expected outcome" / red error panel, then wait
+ * for Stop/Retry. Used when a step throws OR when a `map({ expectedFailure })` flow's last
+ * block succeeds on the intentional fail branch (e.g. LoginPage + error banner).
+ */
+export declare function presentFailPanel(page: WgPage, opts: FailPanelOptions): Promise<Record<string, string>>;
+/**
+ * Recovers a DOM selector from a built-in Trait's own .name string -
+ * visible(sel) / text-equals(sel, "...") - since Trait.check itself is
+ * an opaque closure with no selector field of its own. Best-effort only: a
+ * hand-written bespoke Trait, or url-matches(...) (no DOM target), yields
+ * nothing to highlight, which is fine - the panel still shows the result.
+ */
+export declare function extractVerifyHighlights(block: SomeBlock, resultTag: string): import("../../engine/stub/ring.js").WaygraphHighlightStub[];