waygraph 0.15.54 → 0.16.1

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.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?.selector,
+                    label: cap.label,
+                    tone: cap.tone || (stub?.tone) || "planned",
+                    color: stub?.color,
+                    focus: !!(stub?.focus),
+                    zoom: stub?.zoom,
+                    zoomOut: stub?.zoomOut,
+                    gesture: 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?.selector,
+                    focus: !!(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?.selector,
+                    label: cap.label,
+                    tone: cap.tone || (stub?.tone) || "planned",
+                    color: stub?.color,
+                    focus: !!(stub?.focus),
+                    zoom: stub?.zoom,
+                    zoomOut: stub?.zoomOut,
+                    gesture: 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?.selector,
+                    focus: !!(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/panel-after.d.ts

@@ -0,0 +1,17 @@
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
+import type { TodoDockState } from "../../engine/stub/todos.js";
+import type { Ref, WgPage } from "../types.js";
+import { type PanelTodos, type StepPanelInfo } from "./step-panels.js";
+/** The panel after a step: the Checkpoint it resolved to, the rings to cycle, and whether it was the last step. */
+export interface AfterPanelInfo extends StepPanelInfo, PanelTodos {
+    result: Checkpoint<string>;
+    resultTag: string;
+    highlights: readonly ResolvedHighlight[];
+    gatesFast?: boolean | undefined;
+    isLast: boolean;
+    pace?: DemoPace | undefined;
+    todoDockRef?: Ref<TodoDockState | undefined> | undefined;
+}
+export declare function renderAfterStep(page: WgPage, info: AfterPanelInfo): Promise<void>;

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

@@ -0,0 +1,166 @@
+// The demo panel after a step: what it resolved to (pretty / JSON), its rings, and the Next gate.
+import { ignorePageGone } from "../../engine/page-gone.js";
+import { installOverlay } from "../overlay/overlay.js";
+import { cycleHighlightRings } from "../overlay/rings.js";
+import { miniStepLabel } from "./step-panels.js";
+export async function renderAfterStep(page, info) {
+    await installOverlay(page, info.title, info.bannerUi, info.caption, info.networkTabVisible);
+    // Clear any tracker from a previous highlight before cycling through this
+    // step's own.
+    await page
+        .evaluate(() => {
+        if (window.__wgRingTrack) {
+            window.removeEventListener("resize", window.__wgRingTrack);
+            window.removeEventListener("scroll", window.__wgRingTrack, true);
+            window.__wgRingTrack = null;
+        }
+    })
+        .catch(ignorePageGone);
+    const highlights = info.highlights || [];
+    const gatesFast = !!info.gatesFast;
+    // Cycle through EVERY declared/recovered highlight in order, each shown
+    // long enough to actually register - "it highlights something [...] then
+    // it highlights something [else] and next," not just the first one.
+    // duration / fastMode on stubAfter (or flow fixtures) override the default
+    // 900ms / 200ms holds when set.
+    await cycleHighlightRings(page, highlights, gatesFast, {
+        pace: info.pace,
+        stepLabel: miniStepLabel(info),
+        todoDock: info.todoDock,
+        todos: info.todos,
+        todoSync: info.todoSync,
+        todoDockRef: info.todoDockRef,
+        // stubAfter already authored progress - do not re-index by ring 0..n
+        advanceTodos: false,
+    });
+    // After-ring advances may have moved the dock - surface latest for caller.
+    if (info.todoDockRef && info.todoDockRef.current) {
+        info.todoDock = info.todoDockRef.current;
+    }
+    const afterPayload = { ...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 pct = Math.round(((info.index + 1) / info.total) * 100);
+        const heading = info.isLast
+            ? "End of chain - " + info.total + " / " + info.total + " blocks covered - " + info.blockName + " done"
+            : "Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " done";
+        const buttonLabel = info.isLast ? "Finish" : "Next \u25B6";
+        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" : "wg-mod-upcoming";
+            const desc = info.allDescriptions && info.allDescriptions[idx];
+            return __wgEl("span", { class: "wg-mod " + cls, title: desc || undefined }, String(name));
+        });
+        // QA-friendly by default ("LoginSuccess" -> "Login Success") - raw
+        // JSON is one click away for whoever actually wants __state.
+        const stateTag = info.result && info.result.__state ? info.result.__state : "";
+        const prettyText = stateTag
+            .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+            .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2") || info.resultTag;
+        const pretty = window.__wgPretty !== false;
+        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;
+        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 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;
+        // Todos float in #wg-todo-dock via __wgSyncTodos, never in the panel.
+        __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, heading), __wgEl("div", { class: "wg-toggle" }, __wgEl("button", { class: "wg-toggle-btn" + (pretty ? " wg-active" : ""), data: { mode: "pretty" } }, "Pretty"), __wgEl("button", { class: "wg-toggle-btn" + (pretty ? "" : " wg-active"), data: { mode: "json" } }, "JSON")), __wgEl("div", { class: "wg-result wg-result-pretty", style: "display:" + (pretty ? "block" : "none") }, String(prettyText)), __wgEl("div", { class: "wg-result wg-result-json", style: "display:" + (pretty ? "none" : "block") }, String(info.resultTag)), __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" }, buttonLabel)), __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: "after",
+                step: info.index + 1,
+                total: info.total,
+                block: info.blockName || "",
+                ready: true,
+            });
+        }
+        panel.querySelectorAll(".wg-toggle-btn").forEach((btn) => {
+            btn.addEventListener("click", () => {
+                const wantPretty = btn.getAttribute("data-mode") === "pretty";
+                window.__wgPretty = wantPretty;
+                panel.querySelectorAll(".wg-toggle-btn").forEach((b) => b.classList.remove("wg-active"));
+                btn.classList.add("wg-active");
+                panel.querySelector(".wg-result-pretty").style.display = wantPretty ? "block" : "none";
+                panel.querySelector(".wg-result-json").style.display = wantPretty ? "none" : "block";
+            });
+        });
+        const runBtn = __wgById("wg-run");
+        if (runBtn)
+            runBtn.addEventListener("click", () => window.__wgNext({}));
+        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";
+            });
+        }
+    }, afterPayload)
+        .catch(ignorePageGone);
+}

package/dist/demo/stepper/panel-before.d.ts

@@ -0,0 +1,12 @@
+import type { WgPage } from "../types.js";
+import { type PanelTodos, type StepPanelInfo } from "./step-panels.js";
+/** The panel before a step: its description, the mem it reads (editable), and whether its episode just began. */
+export interface BeforePanelInfo extends StepPanelInfo, PanelTodos {
+    description: string;
+    keys: readonly {
+        name: string;
+        value: string;
+    }[];
+    justEnteredEpisode: boolean;
+}
+export declare function renderBeforeStep(page: WgPage, info: BeforePanelInfo): Promise<void>;