waygraph 0.15.54 → 0.16.1

package/dist/demo/stepper/step-panels.js

@@ -0,0 +1,172 @@
+// The stepper's panels: before a step (what will happen, its mem), after it (the result and rings), and on failure.
+import { ignorePageGone } from "../../engine/page-gone.js";
+import { hasAuthoredStubOnError, runStubPhase } from "../narration/narration.js";
+import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
+import { installOverlay } from "../overlay/overlay.js";
+import { cycleHighlightRings } from "../overlay/rings.js";
+export 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 : ""));
+}
+/**
+ * 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 async function presentFailPanel(page, opts) {
+    const { block, error, index, total, blockName, message, allNames, allDescriptions, moduleIndex, allEpisodes, title, episodeNumber, episodeTitle, expectedFailureReason, stepperMode, gatesFast, demoPace, gate, mem, } = opts;
+    if (hasAuthoredStubOnError(block)) {
+        await page
+            .evaluate(() => {
+            if (window.__wgRingTrack) {
+                window.removeEventListener("resize", window.__wgRingTrack);
+                window.removeEventListener("scroll", window.__wgRingTrack, true);
+                window.__wgRingTrack = null;
+            }
+        })
+            .catch(ignorePageGone);
+        const errPhase = await runStubPhase(block, "stubOnError", {
+            error,
+            out: opts.out,
+            mem,
+        });
+        const errHighlights = errPhase.highlights.map((h) => {
+            const styled = applyHighlightStyleDefaults(h, opts.highlightStyle);
+            return { ...styled, label: formatHighlightCaption(styled), focus: !!styled.focus };
+        });
+        await cycleHighlightRings(page, errHighlights, !!gatesFast, {
+            defaultHoldMs: 2000,
+            pace: demoPace,
+            todos: errPhase.todos,
+        });
+    }
+    await renderStepError(page, {
+        index,
+        total,
+        blockName,
+        message,
+        allNames,
+        allDescriptions,
+        moduleIndex,
+        allEpisodes,
+        title,
+        episodeNumber,
+        episodeTitle,
+        expectedFailureReason,
+        stepperMode,
+    });
+    return gate();
+}
+/**
+ * A Block threw - act()/observe() rejected, or Flow.run's own verify Trait
+ * check failed. Shown instead of letting it crash the whole Node process
+ * silently from a human's point of view (the browser closes right after
+ * regardless - main()'s own try/finally - but not before this is visible).
+ */
+async function renderStepError(page, info) {
+    await installOverlay(page, info.title, info.bannerUi, info.caption, info.networkTabVisible);
+    const errorPayload = { ...info, stepLabel: miniStepLabel(info) };
+    await page
+        .evaluate((info) => {
+        // Reused in place - see renderBeforeStep's own comment on this.
+        let panel = __wgById("wg-panel");
+        const isNewPanel = !panel;
+        if (!panel) {
+            panel = document.createElement("div");
+            panel.id = "wg-panel";
+        }
+        const isExpected = !!info.expectedFailureReason;
+        const errClass = isExpected ? "wg-expected" : "wg-error";
+        panel.classList.remove("wg-error", "wg-expected");
+        panel.classList.add(errClass);
+        if (!isNewPanel)
+            panel.classList.add("wg-in");
+        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";
+                return __wgEl("span", { class: "wg-ep-tab " + cls }, "Episode " + e.episodeNumber + ": " + (e.episodeTitle || ""));
+            }))
+            : null;
+        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-current" : idx < info.moduleIndex ? "wg-mod-done" : "wg-mod-upcoming";
+            const desc = info.allDescriptions && info.allDescriptions[idx];
+            return __wgEl("span", { class: "wg-mod " + cls, title: desc || undefined }, String(name));
+        });
+        const retryLabel = info.episodeNumber !== undefined ? "Retry Episode " + info.episodeNumber : "Retry";
+        const headingText = isExpected
+            ? "Expected outcome - Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " failed as intended"
+            : "Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " threw";
+        __wgSet(panel, episodes, __wgEl("div", { id: "wg-modules", class: modulesClass }, modules), __wgEl("h3", { class: isExpected ? "wg-expected-heading" : "wg-error-heading" }, headingText), isExpected ? __wgEl("div", { class: "wg-expected-reason" }, String(info.expectedFailureReason)) : null, __wgEl("div", { class: "wg-error-msg" }, String(info.message)), __wgEl("div", { class: "wg-error-actions" }, __wgEl("button", { id: "wg-error-retry", class: "wg-error-retry" }, retryLabel), __wgEl("button", { id: "wg-run", class: "wg-error-stop" }, "Stop")));
+        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.__wgStampModal) {
+            window.__wgStampModal(panel, "panel", {
+                phase: "error",
+                step: info.index + 1,
+                total: info.total,
+                block: info.blockName || "",
+                ready: true,
+            });
+        }
+        const runBtn = __wgById("wg-run");
+        if (runBtn)
+            runBtn.addEventListener("click", () => window.__wgNext({}));
+        const retryBtn = __wgById("wg-error-retry");
+        if (retryBtn)
+            retryBtn.addEventListener("click", () => window.__wgNext({ __wgRetry: "1" }));
+    }, errorPayload)
+        .catch(ignorePageGone);
+}
+/**
+ * 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 function extractVerifyHighlights(block, resultTag) {
+    let verify = block.instruction && block.instruction.verify;
+    if (typeof verify === "function") {
+        try {
+            verify = verify({ __state: resultTag });
+        }
+        catch {
+            verify = [];
+        }
+    }
+    if (!Array.isArray(verify))
+        return [];
+    const highlights = [];
+    for (const t of verify) {
+        const name = t && t.name;
+        if (typeof name !== "string")
+            continue;
+        const selector = /^visible\((.+)\)$/.exec(name)?.[1] ?? /^text-equals\((.+?),\s*"/.exec(name)?.[1];
+        if (selector)
+            highlights.push({ selector, label: name, tone: "auto" });
+    }
+    return highlights;
+}

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

@@ -0,0 +1,24 @@
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { WgPage } from "../types.js";
+import type { StepperStep } from "./view.js";
+export interface Stepper {
+    /** After the page was reset between episodes: storage was wiped, so the auto-advance setting is put back. */
+    afterReset(): Promise<void>;
+    before(index: number): Promise<void>;
+    after(index: number, result: Checkpoint<string>): Promise<void>;
+    /** A step threw, or reached the failure its flow expects: show why, then the person picks Retry or Stop. */
+    failed(index: number, failure: {
+        error?: unknown;
+        result?: Checkpoint<string> | undefined;
+    }): Promise<"retry" | "stop">;
+    end(): Promise<void>;
+}
+export interface StepperOptions {
+    title: string | undefined;
+    /** Block names that skip the added dwell (WAYGRAPH_FAST_BLOCKS). */
+    fastBlocks: Set<string>;
+    /** Waygraph's own beat after each action, in ms. */
+    beat: number;
+}
+export declare function createStepper(page: WgPage, mem: MemPage, steps: readonly StepperStep[], options: StepperOptions): Promise<Stepper>;

package/dist/demo/stepper/stepper.js

@@ -0,0 +1,122 @@
+import { createOverlayStage } from "../overlay/overlay-stage.js";
+import { instrumentInteractionHighlighting } from "./interaction-patch.js";
+import { markStepRunning, restoreTheaterAfterNavigation, teardownOverlay } from "./teardown.js";
+import { keepOverlayOnNavigation } from "../overlay/reattach.js";
+import { presentFailPanel } from "./step-panels.js";
+import { installGate } from "./gate.js";
+import { newPacing, paceStep } from "./pacing.js";
+import { showBefore } from "./before.js";
+import { showAfter } from "./after.js";
+import { episodesOf, viewOf } from "./view.js";
+import { envFlag, envString } from "../../engine/env.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+export async function createStepper(page, mem, steps, options) {
+    const demoFast = envFlag("WAYGRAPH_DEMO_FAST");
+    const pacing = newPacing(demoFast);
+    const refs = { stubBefore: { current: [] }, todoDock: { current: undefined }, device: { current: undefined } };
+    instrumentInteractionHighlighting(page, mem, options.beat, pacing, refs.stubBefore, refs.todoDock, refs.device);
+    // A navigation inside a step (a redirect, a login bounce) repaints the overlay with the step's todos, device and ring.
+    keepOverlayOnNavigation(page, () => restoreTheaterAfterNavigation(page, refs.todoDock, refs.device, refs.stubBefore));
+    keepWindowSize(page);
+    const gate = await installGate(page, pacing, demoFast);
+    await gate.syncAutoplay();
+    const ctx = {
+        page,
+        mem,
+        steps,
+        stage: createOverlayStage(page, { todoDockRef: refs.todoDock, deviceRef: refs.device }),
+        gate,
+        pacing,
+        refs,
+        title: options.title,
+        stepperMode: envString("WAYGRAPH_STEPPER") === "full" ? "full" : "carousel",
+        stickyTitle: undefined,
+        allEpisodes: episodesOf(steps),
+    };
+    let view;
+    return {
+        afterReset: gate.syncAutoplay,
+        async before(index) {
+            view = viewOf(ctx, index);
+            paceStep(pacing, view.step, demoFast, options.fastBlocks);
+            await showBefore(ctx, view);
+            applyMemEdits(ctx, view, await gate.wait());
+            await markStepRunning(page);
+            await labelNavClick(page, view.step);
+        },
+        async after(_index, result) {
+            await stepRan(ctx);
+            await showAfter(ctx, view, result);
+        },
+        async failed(index, failure) {
+            await stepRan(ctx);
+            const step = view.step;
+            const edits = await presentFailPanel(page, {
+                block: step.block,
+                highlightStyle: step.highlightStyle,
+                error: failure.error,
+                ...(failure.result ? { out: failure.result } : {}),
+                index,
+                total: steps.length,
+                blockName: step.block.name,
+                message: failure.result
+                    ? "Resolved " + (failure.result.__state ?? JSON.stringify(failure.result)) + " (expected failure path)"
+                    : failure.error instanceof Error ? failure.error.message : String(failure.error),
+                allNames: view.moduleNames,
+                allDescriptions: view.moduleDescriptions,
+                moduleIndex: view.moduleIndex,
+                allEpisodes: ctx.allEpisodes,
+                title: options.title,
+                episodeNumber: step.episodeNumber,
+                episodeTitle: step.episodeTitle,
+                expectedFailureReason: step.expectedFailureReason,
+                stepperMode: ctx.stepperMode,
+                gatesFast: pacing.gatesFast,
+                demoPace: pacing.demoPace,
+                gate: gate.wait,
+                mem,
+            });
+            return edits && edits.__wgRetry ? "retry" : "stop";
+        },
+        end: () => teardownOverlay(page),
+    };
+}
+/**
+ * Some Blocks call page.setViewportSize() in their own act for their own tests; in a watched demo that would resize
+ * the window, so it does nothing here. An authored ctx.device() still resizes through __wgRealSetViewportSize.
+ */
+function keepWindowSize(page) {
+    page.__wgRealSetViewportSize = page.setViewportSize.bind(page);
+    page.setViewportSize = async () => { };
+}
+/** Values typed into the panel's mem fields replace the step's inputs (left as authored when not valid JSON). */
+function applyMemEdits(ctx, view, edits) {
+    for (const k of view.step.block.requires ?? []) {
+        if (edits[k.name] === undefined)
+            continue;
+        try {
+            ctx.mem.set(k, JSON.parse(edits[k.name]));
+        }
+        catch {
+            // left as-authored if the human's edit isn't valid JSON
+        }
+    }
+}
+/** A click-based Nav Block's cursor reads "nav: <block>", like any other Block's click. */
+async function labelNavClick(page, step) {
+    const label = step.block.__waygraphKind === "nav" && step.block.__waygraphNavClick !== undefined ? "nav: " + (step.block.name || "click") : undefined;
+    await page
+        .evaluate((l) => {
+        if (l)
+            window.__wgPendingNavClickLabel = l;
+        else
+            delete window.__wgPendingNavClickLabel;
+    }, label)
+        .catch(ignorePageGone);
+}
+/** The step finished: drop its nav label, and keep the todo dock it advanced for the steps after it. */
+async function stepRan(ctx) {
+    await ctx.page.evaluate(() => delete window.__wgPendingNavClickLabel).catch(ignorePageGone);
+    if (ctx.refs.todoDock.current)
+        ctx.stage.state.lastTodoDock = ctx.refs.todoDock.current;
+}

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

@@ -0,0 +1,47 @@
+import type { StepperRefs, WgPage } from "../types.js";
+/**
+ * Patches Locator.prototype.fill (via any real locator's own prototype
+ * chain - Playwright doesn't export the class directly) so every fill(),
+ * regardless of how the Block built that locator (page.locator, chained
+ * .getByLabel off a scoped form locator, etc.), highlights the real target
+ * first, then types it out character by character instead of snapping the
+ * whole value in - "when something is written from mem, it should
+ * highlight then slowly input." One-time patch (idempotent - guarded so a
+ * multi-step chain doesn't re-wrap an already-wrapped fill).
+ */
+/**
+ * Called once the gate resolves - manual click OR autoplay timeout, both
+ * covered from here rather than duplicating this in the in-page click
+ * handler - right before the Block's own act() actually starts. the user: "i
+ * want the button, step is running thing. so i wont be able to interrupt
+ * the playwright automation" - the "Run this step" button used to sit
+ * there still looking clickable for the entire multi-second duration a
+ * real act()/observe() takes, inviting a confusing extra click (harmless -
+ * __wgNext no-ops once already consumed - but looked live when it wasn't).
+ * Disables the button and mem-key textareas, and swaps whichever gate
+ * text was showing (manual button or "Auto-advancing...") to "Running...".
+ * ALWAYS collapses the panel while act() runs - leaving it expanded was a
+ * real bug: #wg-panel sits at z-index max with pointer-events:auto, so
+ * Playwright's login/add-to-cart clicks hit the stepper instead of the app
+ * ("subtree intercepts pointer events"). Empty/partial fills + a lucky
+ * edge click on Login then produced Sauce Demo's Epic sadface, verify
+ * still passed on the error banner, and the next block blew up. Collapse
+ * also matches the user's "step is running / can't interrupt" ask.
+ */
+export declare function markStepRunning(page: WgPage): Promise<void>;
+/**
+ * Real navigation wipes document + overlay helpers. Reinstall and re-paint
+ * carried todos / device / optional stubBefore ring so keep-dock and nav
+ * highlights do not vanish until the next ctx.todos() / stubAfter (PIA #15).
+ */
+export declare function restoreTheaterAfterNavigation(page: WgPage, todoDockRef: StepperRefs["todoDock"], deviceRef: StepperRefs["device"], stubBeforeRef: StepperRefs["stubBefore"]): Promise<void>;
+/**
+ * Removes every overlay element (panel, ring, ring-label, cursor,
+ * click-pulse, banner) and stops the live resize/scroll ring tracker, once
+ * the whole chain is genuinely done - "I want to see the same page just
+ * like the demo opened for the first time," not the last step's panel and
+ * highlight ring stuck over the real app forever. installOverlay only ever
+ * ADDS these elements back on demand (idempotent, per-page-load) - nothing
+ * re-creates them once torn down here unless another Block/fill/click runs.
+ */
+export declare function teardownOverlay(page: WgPage): Promise<void>;

package/dist/demo/stepper/teardown.js

@@ -0,0 +1,178 @@
+import { installOverlay } from "../overlay/overlay.js";
+import { applyDeviceToPage } from "../overlay/device-stage.js";
+import { showRing } from "../overlay/rings.js";
+import { formatHighlightCaption } from "../narration/style.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+/**
+ * Patches Locator.prototype.fill (via any real locator's own prototype
+ * chain - Playwright doesn't export the class directly) so every fill(),
+ * regardless of how the Block built that locator (page.locator, chained
+ * .getByLabel off a scoped form locator, etc.), highlights the real target
+ * first, then types it out character by character instead of snapping the
+ * whole value in - "when something is written from mem, it should
+ * highlight then slowly input." One-time patch (idempotent - guarded so a
+ * multi-step chain doesn't re-wrap an already-wrapped fill).
+ */
+/**
+ * Called once the gate resolves - manual click OR autoplay timeout, both
+ * covered from here rather than duplicating this in the in-page click
+ * handler - right before the Block's own act() actually starts. the user: "i
+ * want the button, step is running thing. so i wont be able to interrupt
+ * the playwright automation" - the "Run this step" button used to sit
+ * there still looking clickable for the entire multi-second duration a
+ * real act()/observe() takes, inviting a confusing extra click (harmless -
+ * __wgNext no-ops once already consumed - but looked live when it wasn't).
+ * Disables the button and mem-key textareas, and swaps whichever gate
+ * text was showing (manual button or "Auto-advancing...") to "Running...".
+ * ALWAYS collapses the panel while act() runs - leaving it expanded was a
+ * real bug: #wg-panel sits at z-index max with pointer-events:auto, so
+ * Playwright's login/add-to-cart clicks hit the stepper instead of the app
+ * ("subtree intercepts pointer events"). Empty/partial fills + a lucky
+ * edge click on Login then produced Sauce Demo's Epic sadface, verify
+ * still passed on the error banner, and the next block blew up. Collapse
+ * also matches the user's "step is running / can't interrupt" ask.
+ */
+export async function markStepRunning(page) {
+    await page
+        .evaluate(() => {
+        const runBtn = __wgById("wg-run");
+        if (runBtn) {
+            runBtn.disabled = true;
+            runBtn.textContent = "Running \u25B6";
+        }
+        const autoEl = __wgById("wg-gate-auto");
+        if (autoEl)
+            autoEl.textContent = "Running...";
+        __wgQA("#wg-panel textarea[data-key]").forEach((ta) => {
+            ta.disabled = true;
+        });
+        const panel = __wgById("wg-panel");
+        if (panel) {
+            panel.classList.add("wg-collapsed");
+            panel.setAttribute("data-wg-collapsed", "1");
+            panel.setAttribute("data-wg-phase", "running");
+            if (typeof window.__wgStampModal === "function") {
+                window.__wgStampModal(panel, "panel", {
+                    phase: "running",
+                    ready: true,
+                });
+            }
+            const toggle = panel.querySelector("[data-wg-toggle]");
+            if (toggle)
+                toggle.textContent = "Show";
+            const titleEl = panel.querySelector(".wg-chrome-title");
+            const label = panel.dataset.wgStepLabel;
+            if (titleEl && label)
+                titleEl.textContent = label;
+            const miniNext = panel.querySelector("[data-wg-mini-next]");
+            if (miniNext) {
+                miniNext.disabled = true;
+                miniNext.classList.remove("wg-mini-next-show");
+            }
+        }
+    })
+        .catch(ignorePageGone);
+}
+/**
+ * Real navigation wipes document + overlay helpers. Reinstall and re-paint
+ * carried todos / device / optional stubBefore ring so keep-dock and nav
+ * highlights do not vanish until the next ctx.todos() / stubAfter (PIA #15).
+ */
+export async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef) {
+    const needs = (await page
+        .evaluate(() => !window.__wgSyncTodos || !__wgById("wg-ring"))
+        .catch(ignorePageGone)) ?? true;
+    if (!needs) {
+        // Overlay survived (SPA / no full document wipe) - still refresh dock
+        // if Node has a carry and the DOM lost .wg-todo-dock.
+        const hasDock = await page
+            .evaluate(() => !!__wgQ(".wg-todo-dock, #wg-todo-dock"))
+            .catch(ignorePageGone);
+        if (hasDock || !todoDockRef || !todoDockRef.current)
+            return;
+    }
+    await installOverlay(page);
+    const dock = todoDockRef && todoDockRef.current;
+    if (dock) {
+        await page
+            .evaluate((d) => {
+            if (window.__wgSyncTodos)
+                window.__wgSyncTodos({ sync: "set", dock: d });
+        }, dock)
+            .catch(ignorePageGone);
+    }
+    if (deviceRef && deviceRef.current) {
+        await applyDeviceToPage(page, deviceRef.current, "set").catch(ignorePageGone);
+    }
+    // Re-show first matching stubBefore ring if selector still exists (sidebar
+    // nav targets often survive the route change).
+    const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+    for (const h of stubs) {
+        if (!h || !h.selector)
+            continue;
+        // 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 still exist" check (this selector routinely
+        // won't, after a route change - that's the whole point of the loop).
+        const hLoc = page.locator(h.selector).first();
+        const box = (await hLoc.count().catch(() => 0)) > 0
+            ? await hLoc
+                .evaluate((el) => {
+                const r = el.getBoundingClientRect();
+                if (r.width < 2 || r.height < 2)
+                    return null;
+                return { x: r.x, y: r.y, width: r.width, height: r.height };
+            })
+                .catch(() => null)
+            : null;
+        if (box) {
+            await showRing(page, box, formatHighlightCaption(h), h.tone || "planned", {
+                size: h.size,
+                weight: h.weight,
+                selector: h.selector,
+                focus: !!h.focus,
+            }).catch(ignorePageGone);
+            break;
+        }
+    }
+}
+/**
+ * Removes every overlay element (panel, ring, ring-label, cursor,
+ * click-pulse, banner) and stops the live resize/scroll ring tracker, once
+ * the whole chain is genuinely done - "I want to see the same page just
+ * like the demo opened for the first time," not the last step's panel and
+ * highlight ring stuck over the real app forever. installOverlay only ever
+ * ADDS these elements back on demand (idempotent, per-page-load) - nothing
+ * re-creates them once torn down here unless another Block/fill/click runs.
+ */
+export async function teardownOverlay(page) {
+    await page
+        .evaluate(() => {
+        if (window.__wgRingTrack) {
+            window.removeEventListener("resize", window.__wgRingTrack);
+            window.removeEventListener("scroll", window.__wgRingTrack, true);
+            window.__wgRingTrack = null;
+        }
+        window.__wgNarrateOwnsRing = false;
+        for (const id of [
+            "wg-panel",
+            "wg-ring",
+            "wg-ring-label",
+            "wg-cursor",
+            "wg-click-pulse",
+            "wg-banner",
+            "wg-todo-dock",
+            "wg-device-shell",
+            "wg-device-toast",
+            "wg-device-badge",
+        ]) {
+            const el = __wgById(id);
+            if (el)
+                el.remove();
+        }
+        __wgQA(".wg-todo-dock").forEach((el) => el.remove());
+        document.documentElement.classList.remove("wg-video-device-stage");
+    })
+        .catch(ignorePageGone);
+}

package/dist/demo/stepper/todo-advance.d.ts

@@ -0,0 +1,15 @@
+import type { StepperRefs, WgPage } from "../types.js";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
+/** Advance sequential todo dock to stubIndex and push to the page (Method act). */
+export declare function syncTodoDockAdvance(page: WgPage, todoDockRef: StepperRefs["todoDock"] | undefined, stubIndex: number, stub: ResolvedHighlight | null | undefined): Promise<void>;
+export declare function probeTodoDocksOnPage(page: WgPage): Promise<never[] | {
+    key: string;
+    pos: string;
+    top: number;
+    left: number;
+    w: number;
+    h: number;
+    onScreen: boolean;
+    n: number;
+    current: string;
+}[]>;

package/dist/demo/stepper/todo-advance.js

@@ -0,0 +1,110 @@
+import { advanceTodoDock } from "../narration/todo-dock.js";
+import { demoLog } from "./demo-log.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+/** Flatten dock items in order (sequential groups). */
+function flattenTodoDockItems(dock) {
+    const items = [];
+    if (!dock || !dock.groups)
+        return items;
+    for (const g of dock.groups) {
+        for (const t of g.items || [])
+            items.push(t);
+    }
+    return items;
+}
+/**
+ * Resolve which todo index a matched stub should advance to.
+ * Prefer stub.todo / stub.slotId / stub.id against item.id; never jump backward.
+ */
+function resolveTodoAdvanceIndex(dock, stub, stubIndex) {
+    const items = flattenTodoDockItems(dock);
+    if (!items.length)
+        return stubIndex;
+    const curIdx = items.findIndex((t) => t.current);
+    let idx = stubIndex;
+    const key = stub && (stub.todo || stub.slotId);
+    if (key) {
+        const k = String(key).trim().toLowerCase();
+        let found = items.findIndex((t) => t.id && String(t.id).toLowerCase() === k);
+        if (found < 0) {
+            // username -> login-user, password -> login-pass, submit -> login-submit
+            const aliases = {
+                username: ["login-user", "user", "email"],
+                password: ["login-pass", "pass"],
+                submit: ["login-submit", "login", "tap-login"],
+                user: ["login-user", "username"],
+                pass: ["login-pass", "password"],
+            };
+            const alts = aliases[k] || [];
+            for (const a of alts) {
+                found = items.findIndex((t) => t.id && String(t.id).toLowerCase() === a);
+                if (found >= 0)
+                    break;
+            }
+        }
+        if (found < 0) {
+            found = items.findIndex((t) => (t.id && String(t.id).toLowerCase().includes(k)) ||
+                (t.text && String(t.text).toLowerCase().includes(k)));
+        }
+        if (found >= 0)
+            idx = found;
+    }
+    // Monotonic: never retreat the walkthrough.
+    if (curIdx >= 0 && idx < curIdx)
+        idx = curIdx;
+    return idx;
+}
+/** Advance sequential todo dock to stubIndex and push to the page (Method act). */
+export async function syncTodoDockAdvance(page, todoDockRef, stubIndex, stub) {
+    if (!todoDockRef || stubIndex < 0)
+        return;
+    const prev = todoDockRef.current;
+    if (!prev)
+        return;
+    const idx = resolveTodoAdvanceIndex(prev, stub || null, stubIndex);
+    const advanced = advanceTodoDock(prev, idx);
+    todoDockRef.current = advanced;
+    demoLog("  todo advance -> idx=" +
+        idx +
+        (stub && (stub.slotId || stub.todo)
+            ? " slot=" + (stub.todo || stub.slotId)
+            : " stub#" + stubIndex) +
+        ' current="' +
+        String((flattenTodoDockItems(advanced).find((t) => t.current) || {}).text || "").slice(0, 40) +
+        '"');
+    await page
+        .evaluate((dock) => {
+        if (window.__wgSyncTodos) {
+            window.__wgSyncTodos({ sync: "set", dock });
+        }
+    }, advanced)
+        .catch(ignorePageGone);
+}
+export async function probeTodoDocksOnPage(page) {
+    return page
+        .evaluate(() => {
+        const docks = [...__wgQA(".wg-todo-dock, #wg-todo-dock")];
+        return docks.map((el) => {
+            const r = el.getBoundingClientRect();
+            const items = el.querySelectorAll("li");
+            let current = "";
+            items.forEach((li) => {
+                if (li.classList.contains("wg-todo-current")) {
+                    current = (li.textContent || "").replace(/\s+/g, " ").trim().slice(0, 48);
+                }
+            });
+            return {
+                key: el.getAttribute("data-wg-todo-key") || el.id || "?",
+                pos: el.dataset.pos || "?",
+                top: Math.round(r.top),
+                left: Math.round(r.left),
+                w: Math.round(r.width),
+                h: Math.round(r.height),
+                onScreen: r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth,
+                n: items.length,
+                current,
+            };
+        });
+    })
+        .catch(() => []);
+}