waygraph 0.15.53 → 0.16.0

package/dist/demo/stepper/interaction-patch.js

@@ -0,0 +1,323 @@
+import { installOverlay } from "../overlay/overlay.js";
+import { applyHighlightZoom, captionForLocator, dwellMatchedStub, ensureLocatorInView, hideRing, matchStubIndexForLocator, showRing, wasJustNarrated } from "../overlay/rings.js";
+import { syncTodoDockAdvance } from "./todo-advance.js";
+import { clickPulseAt, moveCursorTo } from "../overlay/cursor.js";
+import { demoHighlight } from "./demo-log.js";
+import { repaintOverlay } from "../overlay/reattach.js";
+import { setLocatorTheater } from "../overlay/locator-theater.js";
+import { envNumber } from "../../engine/env.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef, deviceRef) {
+    // Playwright's own slowMo ALREADY pauses after every single low-level
+    // action it dispatches - and pressSequentially() fires one such action
+    // PER CHARACTER. Also giving pressSequentially its own fixed delay
+    // double-paces every keystroke (45ms + slowMo's own ~350ms, per
+    // character) - an ordinary 22-character email alone stretched past 8
+    // seconds. When slowMo is already doing the pacing, add none of our own;
+    // only fall back to a small typing delay when slowMo is off entirely.
+    //
+    // pacing.skipTheater (WAYGRAPH_FAST_BLOCKS **or** FFCompose): near-zero
+    // cursor / pop / typing - blitz this step. --fast alone sets gatesFast only
+    // (shorter Next/autoplay gates) and must NOT skip theater, or the whole demo
+    // looks like plain waygraph run.
+    const skipTheater = () => !!pacing.skipTheater;
+    // `slowMo` here is the demo's own beat: ms to rest after each action (once per call, never per keystroke). The browser
+    // itself is launched with slowMo 0 in step mode, so a step whose pace is blitz really does run at full speed.
+    const beat = () => (skipTheater() ? 0 : slowMo || 0);
+    const pause = (ms) => (ms > 0 ? new Promise((res) => setTimeout(res, ms)) : undefined);
+    // Per-character typing delay (WAYGRAPH_TYPING_MS, default 30). 0 for blitz steps.
+    const typingMs = () => {
+        if (skipTheater())
+            return 0;
+        const n = envNumber("WAYGRAPH_TYPING_MS");
+        return n !== undefined && n >= 0 ? n : 30;
+    };
+    const typeDelay = typingMs;
+    const keyboard = page.keyboard;
+    if (!keyboard.__wgBeatPatched) {
+        keyboard.__wgBeatPatched = true;
+        const originalType = keyboard.type.bind(keyboard);
+        keyboard.type = async (text, options) => {
+            await originalType(text, { delay: typingMs(), ...(options || {}) });
+            await pause(beat());
+        };
+        const originalPress = keyboard.press.bind(keyboard);
+        keyboard.press = async (key, options) => {
+            await originalPress(key, options);
+            await pause(beat());
+        };
+        const originalInsertText = keyboard.insertText.bind(keyboard);
+        keyboard.insertText = async (text) => {
+            await originalInsertText(text);
+            await pause(beat());
+        };
+    }
+    // Click is a single action, not per-character, so it doesn't compound
+    // the same way - but slowMo still adds its own pause around the actual
+    // click, so trim our own explicit "pop" pauses when it's already active
+    // rather than stacking a full 1.2s on top of that.
+    const clickPrePop = () => (skipTheater() ? 0 : slowMo ? 300 : 700);
+    const clickPostPop = () => (skipTheater() ? 0 : slowMo ? 200 : 500);
+    // FF / FAST_BLOCKS: no cursor travel animation (0). Plain theater keeps full.
+    const cursorMs = (full) => (skipTheater() ? 0 : full);
+    // Locator.fill()/click() only ever see a raw call, no context of where
+    // the value came from. Patching mem.get() to remember the most recently
+    // read key's name (Blocks read-then-immediately-fill, e.g. const { email
+    // } = mem.get(LoginInput.key); ...fill(email)) lets the fill patch below
+    // label the ring with the real key, not a generic "writing from mem".
+    // Patches this ONE mem instance only, not MemPage's shared prototype -
+    // there's exactly one mem per chain run.
+    const memTrack = { lastKeyName: null, at: 0 };
+    const originalGet = mem.get.bind(mem);
+    mem.get = (key) => {
+        memTrack.lastKeyName = key && key.name;
+        memTrack.at = Date.now();
+        return originalGet(key);
+    };
+    const WAIT_CAP_FLOOR_MS = 700;
+    const WAIT_CAP_FRACTION = 0.3;
+    const scaledWaitCap = (declared) => Math.min(declared, Math.max(WAIT_CAP_FLOOR_MS, declared * WAIT_CAP_FRACTION));
+    setLocatorTheater(page, {
+        async beforeFill(locator, options) {
+            await installOverlay(page);
+            await locator.waitFor({
+                state: "visible",
+                timeout: (options && options.timeout) || 30000,
+            }).catch(ignoreTimeout);
+            // Smooth scroll before measuring - otherwise off-screen fields
+            // teleport when Playwright's fill actionability scrolls.
+            await ensureLocatorInView(locator, { instant: skipTheater() });
+            const box = await locator.boundingBox();
+            let typeLabel = "input";
+            try {
+                const meta = await locator.evaluate((el) => {
+                    const id = (el.id || "").toLowerCase();
+                    const name = (el.getAttribute("name") || "").toLowerCase();
+                    const ph = (el.getAttribute("placeholder") || "").toLowerCase();
+                    const ty = (el.getAttribute("type") || "text").toLowerCase();
+                    if (ty === "password" || /pass/.test(id + name + ph))
+                        return "password";
+                    if (/user|email|login/.test(id + name + ph))
+                        return "username";
+                    if (ty && ty !== "text")
+                        return ty;
+                    return id || name || ph || "input";
+                });
+                if (meta)
+                    typeLabel = String(meta);
+            }
+            catch {
+                /* ignore */
+            }
+            if (box && !(await wasJustNarrated(page))) {
+                // Only trust the "last mem.get()" as THIS fill's source if it
+                // happened recently - a stale read from several actions ago is
+                // more likely unrelated than actually describing this field.
+                const fallback = memTrack.lastKeyName && Date.now() - memTrack.at < 3000
+                    ? "from mem: " + memTrack.lastKeyName
+                    : "writing from mem";
+                const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+                const cap = await captionForLocator(page, locator, stubs, fallback);
+                const stubIdx = await matchStubIndexForLocator(page, locator, stubs);
+                const stub = stubIdx >= 0 ? stubs[stubIdx] : null;
+                await syncTodoDockAdvance(page, todoDockRef, stubIdx, stub);
+                await moveCursorTo(page, box, cursorMs(500));
+                if (stub) {
+                    await applyHighlightZoom(page, stub.selector, stub.zoom, stub.zoomOut);
+                }
+                demoHighlight({
+                    selector: stub && stub.selector,
+                    label: cap.label,
+                    tone: cap.tone || (stub && stub.tone) || "planned",
+                    color: stub && stub.color,
+                    focus: !!(stub && stub.focus),
+                    zoom: stub && stub.zoom,
+                    zoomOut: stub && stub.zoomOut,
+                    gesture: stub && stub.gesture,
+                    weight: cap.weight,
+                    size: cap.size,
+                }, "fill");
+                await showRing(page, box, cap.label, cap.tone, {
+                    size: cap.size,
+                    weight: cap.weight,
+                    selector: stub && stub.selector ? stub.selector : undefined,
+                    focus: !!(stub && stub.focus),
+                });
+                await dwellMatchedStub(page, locator, stubs, pacing);
+                await new Promise((res) => setTimeout(res, skipTheater() ? 0 : 200));
+                if (cap && cap.label)
+                    typeLabel = String(cap.label).slice(0, 40);
+            }
+            else if (box) {
+                // Ring/caption already handled by narrate() - still move the
+                // cursor there, just skip re-showing the ring with a generic label.
+                await moveCursorTo(page, box, cursorMs(200));
+            }
+            await page
+                .evaluate((label) => {
+                if (window.__wgSetTypingBadge)
+                    window.__wgSetTypingBadge(true, label);
+            }, typeLabel)
+                .catch(ignorePageGone);
+        },
+        typingDelay: typeDelay,
+        async afterFill() {
+            await page
+                .evaluate(() => {
+                if (window.__wgSetTypingBadge)
+                    window.__wgSetTypingBadge(false);
+            })
+                .catch(ignorePageGone);
+            // Fade the ring back out once this field is actually done, instead
+            // of leaving it lit until the next Block's own before-panel clears
+            // it - it was sticking around through the whole rest of the step.
+            await hideRing(page);
+            await repaintOverlay(page);
+            await pause(beat());
+        },
+        async beforeClick(locator, options) {
+            let clickPoint = null;
+            let clickTone = "auto";
+            await installOverlay(page);
+            // Wait until the target is visible BEFORE measuring - otherwise
+            // defineNavBlock({ click }) (and any slow-to-appear control) skips
+            // the cursor entirely: boundingBox was null, then originalClick
+            // waited and clicked with no demo animation.
+            await locator.waitFor({
+                state: "visible",
+                timeout: (options && options.timeout) || 30000,
+            }).catch(ignoreTimeout);
+            // Smooth-scroll off-screen targets before cursor/ring. Playwright's
+            // own click scroll is instant and reads as a teleport under --fast.
+            await ensureLocatorInView(locator, { instant: skipTheater() });
+            const box = await locator.boundingBox();
+            const narrated = box ? await wasJustNarrated(page) : false;
+            if (box && !narrated) {
+                let fallback = "click";
+                try {
+                    const text = (await locator.textContent())?.trim();
+                    if (text && text.length > 0 && text.length <= 30)
+                        fallback = text;
+                }
+                catch {
+                    // element has no simple text (an icon button, say) - generic label is fine
+                }
+                // Prefer "nav: …" when this locator is a NavBlock click target
+                // (set on page by runStepMode just before act).
+                const navLabel = await page.evaluate(() => window.__wgPendingNavClickLabel || null).catch(ignorePageGone);
+                if (navLabel)
+                    fallback = String(navLabel);
+                const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+                const cap = await captionForLocator(page, locator, stubs, fallback);
+                const stubIdx = await matchStubIndexForLocator(page, locator, stubs);
+                const stub = stubIdx >= 0 ? stubs[stubIdx] : null;
+                await syncTodoDockAdvance(page, todoDockRef, stubIdx, stub);
+                clickTone = cap.tone;
+                clickPoint = await moveCursorTo(page, box, cursorMs(600));
+                if (stub) {
+                    await applyHighlightZoom(page, stub.selector, stub.zoom, stub.zoomOut);
+                }
+                demoHighlight({
+                    selector: stub && stub.selector,
+                    label: cap.label,
+                    tone: cap.tone || (stub && stub.tone) || "planned",
+                    color: stub && stub.color,
+                    focus: !!(stub && stub.focus),
+                    zoom: stub && stub.zoom,
+                    zoomOut: stub && stub.zoomOut,
+                    gesture: stub && stub.gesture,
+                    weight: cap.weight,
+                    size: cap.size,
+                }, "click");
+                await showRing(page, box, cap.label, cap.tone, {
+                    size: cap.size,
+                    weight: cap.weight,
+                    selector: stub && stub.selector ? stub.selector : undefined,
+                    focus: !!(stub && stub.focus),
+                });
+                await dwellMatchedStub(page, locator, stubs, pacing);
+                // "pop for a few seconds" - the user's own phrase, matching the
+                // zsign demo-engine's ring-before-click pattern in
+                // services/help-center-clip-engine's video-pipeline.
+                await new Promise((res) => setTimeout(res, clickPrePop()));
+            }
+            else if (box) {
+                // Ring/caption already handled by narrate() - still move the
+                // cursor + pulse the click point, just skip re-showing the ring.
+                clickPoint = await moveCursorTo(page, box, cursorMs(200));
+                clickTone = "planned";
+            }
+            if (clickPoint) {
+                await clickPulseAt(page, clickPoint.x, clickPoint.y, clickTone);
+                // clickPulseAt only triggers the CSS animation class - it doesn't
+                // wait for it. Without a pause here, the real click (and any
+                // resulting navigation/DOM change) fires while the ripple is still
+                // mid-animation, sometimes cutting it off before it's even visible.
+                // Wait out the same .5s the "@keyframes wg-pulse" rule uses, so the
+                // mock click visually completes before the real one fires.
+                await new Promise((res) => setTimeout(res, skipTheater() ? 0 : 500));
+            }
+            // Touch theater (0.13+): prefer Locator.tap / long-press when device
+            // touchMode is on (context launched with hasTouch). gesture on stub
+            // wins: tap | hold | click.
+            const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+            const touch = !!(deviceRef && deviceRef.current && deviceRef.current.touchMode);
+            const idx = await matchStubIndexForLocator(page, locator, stubs).catch(() => -1);
+            const stub = idx >= 0 ? stubs[idx] : null;
+            if (stub && (stub.gesture === "tap" || stub.gesture === "hold" || stub.gesture === "click"))
+                return stub.gesture;
+            return touch ? "tap" : "click";
+        },
+        holdMs: () => (skipTheater() ? 0 : 600),
+        async afterClick() {
+            await new Promise((res) => setTimeout(res, clickPostPop()));
+            await hideRing(page);
+            // Full document navigation drops #wg-todo-dock + rings; restore carry.
+            await repaintOverlay(page);
+            await pause(beat());
+        },
+        // Caps any Locator.waitFor()/page.waitForTimeout() timeout during step
+        // mode - a Block polling for something that will NEVER happen (e.g. "is
+        // there an unverified-account banner" on an account that IS verified)
+        // has no choice but to wait out its own hardcoded timeout in full before
+        // concluding "no". Only the WAIT gets capped, never the real outcome -
+        // if the thing genuinely appears at 800ms into a 5000ms wait, waitFor
+        // still resolves at 800ms same as always; this only shortens the "it's
+        // just never going to happen" case. Plain setTimeout()-based sleep()
+        // helpers some Blocks use for their own pacing are NOT Playwright calls
+        // at all and can't be touched this way - a real, disclosed limit, not
+        // silently ignored.
+        // Pushed down to 700ms earlier this session based on login.block.ts
+        // alone - every waitFor() there is a "give up gracefully" pattern
+        // (wrapped in .catch()/Promise.race, a timeout IS the expected negative
+        // result). That's a different kind of wait than a REQUIRED
+        // synchronization point with no catch - e.g. overview-metrics.block.ts
+        // waits (uncaught) for a "Loading pending actions..." placeholder to
+        // actually appear before it's safe to check for an error, a real
+        // hydration signal the block's own comment calls "deterministic,"
+        // not a probe. A flat 700ms cap broke that block outright on this
+        // shared, loaded box (a real 3-block chain run threw instead of
+        // catching). Bumping the SAME flat cap to 4000ms to cover it just
+        // reintroduced most of the original torture on login.block.ts's own
+        // 5000ms unverified-email check - 4000ms is barely better than the real
+        // 5000ms it's capping.
+        //
+        // A single flat number can't serve both: it has no way to tell "safe to
+        // cut short" from "must actually happen" apart from the outside. But
+        // each call site's OWN declared timeout is already a real signal of
+        // which kind it is - a Block author who wrote timeout: 5000 for a quick
+        // conditional check and one who wrote timeout: 15000 for a real
+        // hydration wait weren't picking the same number by accident. Scale the
+        // cap off that instead of a single constant: 30% of whatever was
+        // declared, never below a 700ms floor (the value already proven safe
+        // for the fast/common case), and never above what was declared in the
+        // first place. login's 5000ms check -> 1500ms (still 3.5s faster than
+        // uncapped). overview-metrics' 15000ms wait -> 4500ms (more headroom
+        // than the flat 4000ms fix, not less).
+        capWait: scaledWaitCap,
+        // A plain sleep (not a "wait for condition X") never has a hidden
+        // "must actually happen" requirement attached - always safe to cut
+        // to the floor, no scaling needed.
+        capSleep: (ms) => Math.min(ms, WAIT_CAP_FLOOR_MS),
+    });
+}

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

@@ -0,0 +1,21 @@
+import type { DemoPace } from "../../engine/stub/pace.js";
+export interface Pacing {
+    /** Shorter Next gates (keeps the smooth cursor). */
+    gatesFast: boolean;
+    gatesSlow: boolean;
+    /** Skip the overlay's added dwell entirely (blitz, fast-forward, WAYGRAPH_FAST_BLOCKS). */
+    skipTheater: boolean;
+    demoPace: DemoPace;
+}
+export declare function newPacing(demoFast: boolean): Pacing;
+interface PacedStep {
+    block: {
+        name: string;
+        demoPace?: DemoPace | string | number | null;
+        fastForward?: boolean;
+    };
+    demoPace?: DemoPace | undefined;
+    wasFastForward?: boolean | undefined;
+}
+export declare function paceStep(pacing: Pacing, step: PacedStep, demoFast: boolean, fastBlocks: Set<string>): void;
+export {};

package/dist/demo/stepper/pacing.js

@@ -0,0 +1,23 @@
+import { demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, normalizeDemoPace, resolveStepDemoPace } from "../narration/demo-pace.js";
+import { envString } from "../../engine/env.js";
+export function newPacing(demoFast) {
+    return { gatesFast: demoFast, gatesSlow: false, skipTheater: false, demoPace: "normal" };
+}
+const isSet = (pace) => pace != null && pace !== "";
+export function paceStep(pacing, step, demoFast, fastBlocks) {
+    const defaultPace = envString("WAYGRAPH_DEMO_PACE") ? normalizeDemoPace(envString("WAYGRAPH_DEMO_PACE")) : undefined;
+    const fastForward = !!step.block.fastForward || !!step.wasFastForward;
+    const flowPace = step.demoPace ?? defaultPace;
+    const stepPace = resolveStepDemoPace({
+        ...(step.block.demoPace !== undefined ? { blockPace: step.block.demoPace } : {}),
+        ...(flowPace !== undefined ? { flowPace } : {}),
+        fastForward: !!step.block.fastForward,
+        wasFastForward: !!step.wasFastForward,
+    });
+    const authoredPace = isSet(step.block.demoPace) || isSet(step.demoPace) || defaultPace != null;
+    const listedFast = fastBlocks.has(step.block.name);
+    pacing.demoPace = stepPace === "normal" && (demoFast || listedFast) && !authoredPace ? (listedFast ? "blitz" : "fast") : stepPace;
+    pacing.gatesFast = demoPaceIsFast(pacing.demoPace) || fastForward || (!authoredPace && demoFast);
+    pacing.gatesSlow = demoPaceIsSlow(pacing.demoPace);
+    pacing.skipTheater = demoPaceIsBlitz(pacing.demoPace) || listedFast || fastForward;
+}

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

@@ -0,0 +1,11 @@
+import type { WgPage } from "../types.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 declare function presentSlides(page: WgPage, slides: any, _gate: any, opts: any): 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, _gate, 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, s.zoomOut);
+                // 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: !!s.focus,
+                    });
+                }
+            }
+            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,21 @@
+import type { WgPage } from "../types.js";
+export declare function renderBeforeStep(page: WgPage, info: any): Promise<void>;
+/**
+ * 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: any): Promise<any>;
+export declare function renderAfterStep(page: WgPage, info: any): Promise<void>;
+/**
+ * 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: any, resultTag: any): {
+    selector: string | undefined;
+    label: string;
+    tone: string;
+}[];