waygraph 0.15.53 → 0.16.0

package/dist/demo/stepper/banner-log.d.ts

@@ -0,0 +1,37 @@
+import type { WgPage } from "../types.js";
+/** Authored banner UX from a stub phase -> the { pos, collision, hidden } shape installOverlay takes. */
+export declare function bannerUiFromPhase(phase: any): Record<string, any>;
+/** Read the live banner: text, position, whether it was moved by ring collision; drains the move log. */
+export declare function probeBanner(page: WgPage): Promise<{
+    present: boolean;
+    log: any;
+    text?: never;
+    pos?: never;
+    home?: never;
+    moved?: never;
+    collision?: never;
+    hidden?: never;
+    authored?: never;
+    left?: never;
+    top?: never;
+    w?: never;
+    h?: never;
+} | {
+    present: boolean;
+    text: string;
+    pos: string | null;
+    home: string | null;
+    moved: string | null;
+    collision: boolean;
+    hidden: boolean;
+    authored: boolean;
+    left: number;
+    top: number;
+    w: number;
+    h: number;
+    log: any;
+} | {
+    present: boolean;
+    log: never[];
+}>;
+export declare function logBannerDom(tag: any, p: any): void;

package/dist/demo/stepper/banner-log.js

@@ -0,0 +1,63 @@
+import { demoLog } from "./demo-log.js";
+/** Authored banner UX from a stub phase -> the { pos, collision, hidden } shape installOverlay takes. */
+export function bannerUiFromPhase(phase) {
+    const ui = {};
+    if (phase && phase.titlePos)
+        ui.pos = phase.titlePos;
+    if (phase && phase.bannerUi) {
+        if (phase.bannerUi.collision !== undefined)
+            ui.collision = !!phase.bannerUi.collision;
+        if (phase.bannerUi.hidden !== undefined)
+            ui.hidden = !!phase.bannerUi.hidden;
+        if (phase.bannerUi.captionFadeMs !== undefined)
+            ui.captionFadeMs = Number(phase.bannerUi.captionFadeMs);
+    }
+    return ui;
+}
+/** Read the live banner: text, position, whether it was moved by ring collision; drains the move log. */
+export async function probeBanner(page) {
+    return page
+        .evaluate(() => {
+        const b = __wgById("wg-banner");
+        const log = window.__wgBannerLog || [];
+        window.__wgBannerLog = [];
+        if (!b)
+            return { present: false, log };
+        const r = b.getBoundingClientRect();
+        const text = b.querySelector(".wg-banner-text");
+        return {
+            present: true,
+            text: text ? text.textContent : "",
+            pos: b.dataset.pos || null,
+            home: b.dataset.home || null,
+            moved: b.dataset.moved || null,
+            collision: b.dataset.collision !== "0",
+            hidden: b.style.display === "none",
+            authored: b.dataset.authored === "1",
+            left: Math.round(r.left),
+            top: Math.round(r.top),
+            w: Math.round(r.width),
+            h: Math.round(r.height),
+            log,
+        };
+    })
+        .catch(() => ({ present: false, log: [] }));
+}
+export function logBannerDom(tag, p) {
+    if (!p)
+        return;
+    if (!p.present) {
+        demoLog("  " + tag + " banner-dom absent");
+        return;
+    }
+    demoLog("  " + tag + " banner-dom " +
+        JSON.stringify(String(p.text || "").slice(0, 60)) +
+        "@" + p.pos +
+        (p.home && p.home !== p.pos ? " (home=" + p.home + ")" : "") +
+        " " + p.left + "," + p.top + " " + p.w + "x" + p.h +
+        " collision=" + (p.collision ? "on" : "off") +
+        (p.hidden ? " HIDDEN" : "") +
+        (p.authored ? " authored" : ""));
+    for (const line of p.log || [])
+        demoLog("  " + tag + " banner " + line);
+}

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

@@ -0,0 +1,4 @@
+import type { StepperContext, StepView } from "./view.js";
+export declare function showBefore(ctx: StepperContext, view: StepView): Promise<void>;
+/** Logs where the todo docks actually landed on the page, warning when authored todos never painted. */
+export declare function logDocks(ctx: StepperContext, tag: string, expectDock: boolean, cleared?: boolean): Promise<void>;

package/dist/demo/stepper/before.js

@@ -0,0 +1,110 @@
+// Before a demo step runs: play the Block's stubBefore narration (rings, todos, device, title, caption) and show the
+// step's panel, then log what was painted so an agent without eyes can check it.
+import { runStubPhase } from "../narration/narration.js";
+import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
+import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
+import { renderBeforeStep } from "./step-panels.js";
+import { probeTodoDocksOnPage } from "./todo-advance.js";
+import { logBannerDom, probeBanner } from "./banner-log.js";
+import { forceCollapsed } from "./view.js";
+import { envFlag } from "../../engine/env.js";
+const quiet = () => envFlag("WAYGRAPH_JSON");
+export async function showBefore(ctx, view) {
+    const { stage } = ctx;
+    const phase = await narrateBefore(ctx, view);
+    const { appliedTodo } = await stage.applyPhase(phase, { reapplyDeviceOnKeep: true });
+    if (phase.title && String(phase.title).trim())
+        ctx.stickyTitle = String(phase.title).trim();
+    view.overlayTitle = ctx.stickyTitle || (view.step.episodeTitle && String(view.step.episodeTitle).trim()) || ctx.title || "waygraph demo";
+    view.overlayTodoPos = stage.state.lastTodoDock?.pos || phase.todoPos || undefined;
+    const paceSpeak = paceSpeakFields(ctx.pacing.demoPace, ctx.gate.autoplayMs);
+    if (!quiet())
+        logBefore(ctx, view, phase, appliedTodo.sync, paceSpeak.paceLabel);
+    const step = view.step;
+    await renderBeforeStep(ctx.page, {
+        index: view.index,
+        total: ctx.steps.length,
+        blockName: step.block.name,
+        description: step.block.description || "",
+        keys: memKeysOf(ctx, view),
+        allNames: view.moduleNames,
+        allDescriptions: view.moduleDescriptions,
+        moduleIndex: view.moduleIndex,
+        allEpisodes: ctx.allEpisodes,
+        justEnteredEpisode: view.justEnteredEpisode,
+        title: view.overlayTitle,
+        bannerUi: stage.state.lastBannerUi,
+        caption: phase.caption,
+        networkTabVisible: phase.networkTabVisible,
+        fastForward: !!step.block.fastForward,
+        isApi: step.block.__waygraphKind === "api",
+        todoPos: view.overlayTodoPos,
+        episodeNumber: step.episodeNumber,
+        episodeTitle: step.episodeTitle,
+        stepperMode: ctx.stepperMode,
+        forceCollapsed: forceCollapsed(),
+        todos: stage.state.lastTodoDock?.groups[0]?.items || phase.todos || [],
+        todoDock: stage.state.lastTodoDock,
+        todoSync: appliedTodo.sync,
+        todoId: stage.state.lastTodoDock?.id,
+        ...paceSpeak,
+    });
+    // renderBeforeStep syncs the active dock; this repaints every dock so a replaced one is gone.
+    await stage.syncAllTodoDocks({ parallel: !!phase.todoParallel });
+    if (!quiet()) {
+        await logDocks(ctx, "", !!stage.state.lastTodoDock);
+        logBannerDom("before", await probeBanner(ctx.page));
+    }
+}
+/** Runs the Block's stubBefore and remembers its rings, so a fill/click inside the step can find its ring. */
+async function narrateBefore(ctx, view) {
+    const phase = await runStubPhase(view.step.block, "stubBefore", { mem: ctx.mem });
+    await ctx.stage.pushTodoDockUi(phase.todoDockUi);
+    ctx.refs.stubBefore.current = phase.highlights.map((h) => applyHighlightStyleDefaults(h, view.step.highlightStyle));
+    logStubPhaseFixtures("before", {
+        ...phase,
+        highlights: ctx.refs.stubBefore.current.map((h) => ({ ...h, label: formatHighlightCaption(h) })),
+    });
+    return phase;
+}
+/** The step's `requires` keys and their current values, editable in the panel. */
+function memKeysOf(ctx, view) {
+    return (view.step.block.requires ?? []).map((k) => {
+        let value = "<not yet set>";
+        try {
+            value = JSON.stringify(ctx.mem.get(k));
+        }
+        catch {
+            // not written yet - shown as a placeholder, not a crash
+        }
+        return { name: k.name, value };
+    });
+}
+function logBefore(ctx, view, phase, todoSync, paceLabel) {
+    const { step } = view;
+    demoLog(`step ${view.index + 1}/${ctx.steps.length} ${step.block.name} · ${paceLabel}` + (step.episodeNumber ? " · episode " + step.episodeNumber : ""));
+    demoLog(`  gate~${ctx.gate.autoplayMs}ms skipTheater=${!!ctx.pacing.skipTheater} gatesFast=${!!ctx.pacing.gatesFast}`);
+    demoLog("  " + summarizeDevice(ctx.stage.state.lastDevice));
+    const zoom = phase.zoom != null && Number(phase.zoom) > 0 ? Number(phase.zoom) : null;
+    const zoomOut = phase.zoomOut !== undefined ? !!phase.zoomOut : null;
+    demoLog("  zoom=" + (zoom != null ? zoom + "x" : "default") + (zoomOut != null ? " zoomOut=" + zoomOut : "") +
+        " (StubCtx / API; live chip top-left when ring zoom >1)");
+    logTodoDockFull(ctx.stage.state.lastTodoDock, "  before");
+    demoLog("  todoSync=" + todoSync);
+}
+/** Logs where the todo docks actually landed on the page, warning when authored todos never painted. */
+export async function logDocks(ctx, tag, expectDock, cleared = false) {
+    const docks = await probeTodoDocksOnPage(ctx.page);
+    if (!docks.length && expectDock && !cleared) {
+        demoLog(tag ? `  WARN ${tag.trim()}: todos authored but dock-dom empty` : "  WARN todos authored but dock-dom empty (not painted?)");
+    }
+    else if (docks.length) {
+        demoLog(`  ${tag}dock-dom ` +
+            docks
+                .map((d) => `${d.key}@${d.pos} ${d.left},${d.top} ${d.w}x${d.h}` + (d.onScreen ? "" : " OFFSCREEN") + ` n=${d.n}` + (d.current ? ` cur="${d.current}"` : ""))
+                .join(" | "));
+    }
+    else if (cleared) {
+        demoLog(`  ${tag}dock-dom cleared (expected)`);
+    }
+}

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

@@ -0,0 +1,31 @@
+export declare function demoPaceKind(pace: any): "normal" | "blitz" | "fast" | "slow" | "ms" | "num-slow";
+export declare function paceSpeakFields(pace: any, baseAutoplayMs: any): {
+    pace: import("../../index.js").DemoPace;
+    paceBadge: string;
+    paceLabel: string;
+    paceKind: string;
+};
+export declare const ANSI: {
+    reset: string;
+    bold: string;
+    dim: string;
+    purple: string;
+    blue: string;
+    yellow: string;
+    red: string;
+    green: string;
+    gray: string;
+    cyan: string;
+    magenta: string;
+    white: string;
+};
+export declare function ansiPaint(code: any, text: any): string;
+export declare function demoLog(msg: any): void;
+/** Fixture catch-all: how it was called + value. */
+export declare function demoFixture(kind: any, call: any, value: any): void;
+/** Highlight trigger line: PURPLE · Cart items - Product landed in cart */
+export declare function demoHighlight(h: any, extra: any): void;
+export declare function logStubPhaseFixtures(phaseName: any, phase: any): void;
+/** Full todo dump for agents (every group/item id + flags). */
+export declare function logTodoDockFull(dock: any, tag: any): void;
+export declare function summarizeDevice(d: any): string;

package/dist/demo/stepper/demo-log.js

@@ -0,0 +1,309 @@
+// The demo's console log ([hh:mm:ss] waygraph demo: ...): what each step painted, so an agent without eyes can follow.
+import { demoPaceIsFast, demoPaceIsSlow, formatDemoPaceBadge, formatDemoPaceLabel, normalizeDemoPace } from "../narration/demo-pace.js";
+import { normalizeHighlightTone } from "../../engine/stub/ring.js";
+import { envFlag } from "../../engine/env.js";
+export function demoPaceKind(pace) {
+    const p = normalizeDemoPace(pace);
+    if (typeof p === "number" && p > 20)
+        return "ms";
+    if (typeof p === "number")
+        return demoPaceIsSlow(p) ? "num-slow" : demoPaceIsFast(p) ? "fast" : "normal";
+    if (p === "blitz" || p === "fast" || p === "slow")
+        return p;
+    return "normal";
+}
+export function paceSpeakFields(pace, baseAutoplayMs) {
+    const p = normalizeDemoPace(pace);
+    const base = Number.isFinite(baseAutoplayMs) && baseAutoplayMs > 0 ? baseAutoplayMs : 1800;
+    return {
+        pace: p,
+        paceBadge: formatDemoPaceBadge(p, base),
+        paceLabel: formatDemoPaceLabel(p, base),
+        paceKind: demoPaceKind(p),
+    };
+}
+/** Demo CLI chatter (agents use this to ballpark timing / todo layout). Off for WAYGRAPH_JSON. */
+function demoQuiet() {
+    return envFlag("WAYGRAPH_JSON");
+}
+/** Node's own colour rule (FORCE_COLOR, NO_COLOR, NODE_DISABLE_COLORS, TERM=dumb); off a terminal, only FORCE_COLOR turns it on. */
+function demoColorEnabled() {
+    const terminal = [process.stderr, process.stdout].find((s) => s.isTTY);
+    if (terminal)
+        return terminal.hasColors();
+    const force = process.env.FORCE_COLOR;
+    return force !== undefined && force !== "0" && force !== "false";
+}
+const ESC = String.fromCharCode(27);
+export const ANSI = {
+    reset: ESC + "[0m",
+    bold: ESC + "[1m",
+    dim: ESC + "[2m",
+    purple: ESC + "[38;5;141m",
+    blue: ESC + "[38;5;75m",
+    yellow: ESC + "[38;5;220m",
+    red: ESC + "[38;5;203m",
+    green: ESC + "[38;5;114m",
+    gray: ESC + "[38;5;246m",
+    cyan: ESC + "[38;5;87m",
+    magenta: ESC + "[38;5;213m",
+    white: ESC + "[37m",
+};
+export function ansiPaint(code, text) {
+    if (!demoColorEnabled() || text == null || text === "")
+        return String(text ?? "");
+    return code + String(text) + ANSI.reset;
+}
+function toneAnsi(tone) {
+    const t = normalizeHighlightTone(tone);
+    if (t === "info")
+        return ANSI.blue;
+    if (t === "warning")
+        return ANSI.yellow;
+    if (t === "danger")
+        return ANSI.red;
+    if (t === "success")
+        return ANSI.green;
+    if (t === "auto")
+        return ANSI.gray;
+    return ANSI.purple;
+}
+function toneName(tone) {
+    const t = normalizeHighlightTone(tone);
+    if (t === "info")
+        return "BLUE";
+    if (t === "warning")
+        return "YELLOW";
+    if (t === "danger")
+        return "RED";
+    if (t === "success")
+        return "GREEN";
+    if (t === "auto")
+        return "GRAY";
+    return "PURPLE";
+}
+/** Optional authored CSS color (#rrggbb) -> truecolor ANSI when TTY. */
+function hexAnsi(hex) {
+    if (!hex || typeof hex !== "string")
+        return null;
+    const m = String(hex).trim().match(/^#?([0-9a-fA-F]{6})$/);
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 16);
+    const r = (n >> 16) & 255;
+    const g = (n >> 8) & 255;
+    const b = n & 255;
+    return ESC + "[38;2;" + r + ";" + g + ";" + b + "m";
+}
+function demoTs() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, "0");
+    const ms = String(d.getMilliseconds()).padStart(3, "0");
+    return (p(d.getHours()) +
+        ":" +
+        p(d.getMinutes()) +
+        ":" +
+        p(d.getSeconds()) +
+        "." +
+        ms);
+}
+function demoPrefix() {
+    return ansiPaint(ANSI.dim, "[" + demoTs() + "]") + " waygraph demo: ";
+}
+export function demoLog(msg) {
+    if (demoQuiet())
+        return;
+    console.log(demoPrefix() + msg);
+}
+/** Fixture catch-all: how it was called + value. */
+export function demoFixture(kind, call, value) {
+    if (demoQuiet())
+        return;
+    const head = ansiPaint(ANSI.cyan, "FIXTURE") + " " + ansiPaint(ANSI.bold, kind);
+    const callPart = call ? " " + ansiPaint(ANSI.dim, call) : "";
+    let val = "";
+    if (value !== undefined) {
+        if (typeof value === "string")
+            val = value;
+        else {
+            try {
+                val = JSON.stringify(value);
+            }
+            catch {
+                val = String(value);
+            }
+        }
+        if (val.length > 220)
+            val = val.slice(0, 217) + "...";
+        val = " = " + ansiPaint(ANSI.white, val);
+    }
+    console.log(demoPrefix() + head + callPart + val);
+}
+/** Highlight trigger line: PURPLE · Cart items - Product landed in cart */
+export function demoHighlight(h, extra) {
+    if (demoQuiet())
+        return;
+    const tone = h && h.tone != null ? h.tone : "planned";
+    const paint = hexAnsi(h && h.color) || toneAnsi(tone);
+    const name = toneName(tone);
+    const label = String((h && h.label) || "").trim() || "(no label)";
+    const sel = h && h.selector ? String(h.selector) : "";
+    const bits = [];
+    if (h && h.focus)
+        bits.push("focus");
+    if (h && h.zoom != null && Number(h.zoom) > 1)
+        bits.push("zoom=" + h.zoom);
+    if (h && h.zoomOut === false)
+        bits.push("zoomOut=false");
+    if (h && h.gesture)
+        bits.push("gesture=" + h.gesture);
+    if (h && h.weight && h.weight !== "normal")
+        bits.push("weight=" + h.weight);
+    if (h && h.size && h.size !== "md")
+        bits.push("size=" + h.size);
+    if (h && h.color)
+        bits.push("color=" + h.color);
+    if (extra)
+        bits.push(extra);
+    const line = ansiPaint(paint, name) +
+        " · " +
+        ansiPaint(paint, label) +
+        (sel ? ansiPaint(ANSI.dim, "  sel=" + sel) : "") +
+        (bits.length ? ansiPaint(ANSI.dim, "  [" + bits.join(" ") + "]") : "");
+    console.log(demoPrefix() + ansiPaint(ANSI.magenta, "HIGHLIGHT") + " " + line);
+}
+export function logStubPhaseFixtures(phaseName, phase) {
+    if (demoQuiet() || !phase)
+        return;
+    const tag = "stub." + phaseName;
+    if (phase.title)
+        demoFixture(tag, "ctx.title(...)", JSON.stringify(phase.title));
+    if (phase.titlePos)
+        demoFixture(tag, "ctx.titlePos(...)", JSON.stringify(phase.titlePos));
+    if (phase.bannerUi)
+        demoFixture(tag, "ctx.bannerUi(...)", JSON.stringify(phase.bannerUi));
+    if (phase.deviceSync && phase.deviceSync !== "keep") {
+        demoFixture(tag, phase.deviceSync === "clear" ? "ctx.hideDevice()" : "ctx.device(...)", phase.device
+            ? {
+                preset: phase.device.preset,
+                w: phase.device.viewport && phase.device.viewport.width,
+                h: phase.device.viewport && phase.device.viewport.height,
+                orient: phase.device.orientation,
+                touch: !!phase.device.touchMode,
+            }
+            : phase.deviceSync);
+    }
+    if (phase.zoom != null)
+        demoFixture(tag, "ctx.zoom(" + phase.zoom + ")", phase.zoom + "x");
+    if (phase.zoomOut !== undefined)
+        demoFixture(tag, "ctx.zoomOut(" + !!phase.zoomOut + ")", !!phase.zoomOut);
+    if (phase.todoSync && phase.todoSync !== "keep") {
+        demoFixture(tag, phase.todoSync === "clear" ? "ctx.hideTodos() / clear" : "ctx.todos(...)", phase.todoDock
+            ? {
+                id: phase.todoDock.id,
+                pos: phase.todoDock.pos,
+                title: phase.todoDock.title,
+                n: (phase.todos && phase.todos.length) || 0,
+            }
+            : phase.todoSync);
+    }
+    const rings = phase.highlights || [];
+    for (let i = 0; i < rings.length; i++) {
+        const h = rings[i];
+        demoFixture(tag, "ctx.ring/highlights[" + i + "]", {
+            selector: h.selector,
+            label: h.label || h.caption,
+            detail: h.detail,
+            tone: h.tone || "planned",
+            color: h.color,
+            focus: !!h.focus,
+            zoom: h.zoom,
+            zoomOut: h.zoomOut,
+            gesture: h.gesture,
+            duration: h.duration,
+        });
+    }
+    if (phase.slides && phase.slides.length) {
+        demoFixture(tag, "ctx.slides(...)", { n: phase.slides.length });
+    }
+}
+function summarizeTodoDock(dock) {
+    if (!dock)
+        return "todos=none";
+    const id = dock.id || "_default";
+    const pos = dock.pos || "left";
+    const style = dock.style || "sequential";
+    const title = dock.title ? String(dock.title) : "";
+    const items = [];
+    for (const g of dock.groups || []) {
+        for (const t of g.items || [])
+            items.push(t);
+    }
+    const cur = items.find((t) => t.current);
+    const done = items.filter((t) => t.done).length;
+    return ("todos id=" +
+        id +
+        " pos=" +
+        pos +
+        " style=" +
+        style +
+        (title ? ' title="' + title + '"' : "") +
+        " n=" +
+        items.length +
+        " done=" +
+        done +
+        (cur && cur.text ? ' current="' + String(cur.text).slice(0, 48) + '"' : ""));
+}
+/** Full todo dump for agents (every group/item id + flags). */
+export function logTodoDockFull(dock, tag) {
+    const prefix = tag ? tag + " " : "";
+    if (!dock) {
+        demoLog(prefix + "todos=none");
+        return;
+    }
+    demoLog(prefix + summarizeTodoDock(dock));
+    const groups = dock.groups || [];
+    if (!groups.length) {
+        demoLog(prefix + "  (no groups)");
+        return;
+    }
+    for (let gi = 0; gi < groups.length; gi++) {
+        const g = groups[gi];
+        const gLabel = "group[" +
+            gi +
+            "]" +
+            (g.id ? " id=" + g.id : "") +
+            (g.title ? ' title="' + String(g.title).slice(0, 40) + '"' : "") +
+            (g.style ? " style=" + g.style : "");
+        demoLog(prefix + "  " + gLabel);
+        const items = g.items || [];
+        for (let ti = 0; ti < items.length; ti++) {
+            const t = items[ti];
+            const mark = t.done ? "done" : t.current ? "CURRENT" : "pending";
+            demoLog(prefix +
+                "    [" +
+                ti +
+                "] " +
+                mark +
+                (t.id ? " id=" + t.id : "") +
+                ' text="' +
+                String(t.text || "").slice(0, 80) +
+                '"' +
+                (t.detail ? ' detail="' + String(t.detail).slice(0, 40) + '"' : ""));
+        }
+    }
+}
+export function summarizeDevice(d) {
+    if (!d)
+        return "device=none";
+    const vp = d.viewport || {};
+    return ("device=" +
+        (d.preset || "?") +
+        " " +
+        (vp.width || "?") +
+        "x" +
+        (vp.height || "?") +
+        " " +
+        (d.orientation || "?") +
+        (d.touchMode ? " touch" : ""));
+}

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

@@ -0,0 +1,11 @@
+import type { WgPage } from "../types.js";
+import type { Pacing } from "./pacing.js";
+export interface Gate {
+    /** Resolves with the mem edits typed into the panel (or `{}` when auto-advance moved on). */
+    wait(): Promise<Record<string, string>>;
+    /** Puts the panel's Auto-advance checkbox to WAYGRAPH_AUTOPLAY (after start and after a session reset). */
+    syncAutoplay(): Promise<void>;
+    /** Base auto-advance delay, scaled by each step's pace. */
+    autoplayMs: number;
+}
+export declare function installGate(page: WgPage, pacing: Pacing, demoFast: boolean): Promise<Gate>;

package/dist/demo/stepper/gate.js

@@ -0,0 +1,78 @@
+import { demoPaceGateMs } from "../narration/demo-pace.js";
+import { envFlag, envNumber, envString } from "../../engine/env.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+export async function installGate(page, pacing, demoFast) {
+    const autoplayMs = envNumber("WAYGRAPH_AUTOPLAY_MS") ?? (demoFast ? 450 : 1800);
+    // installOverlay only seeds the checkbox when unset (so a mid-run click survives navigation); the CLI flag must
+    // still win at start. localStorage is per origin, so this runs on the demo's page, not about:blank.
+    const syncAutoplay = async () => {
+        if (envString("WAYGRAPH_AUTOPLAY") === undefined)
+            return;
+        const on = envFlag("WAYGRAPH_AUTOPLAY");
+        await page
+            .evaluate((want) => {
+            try {
+                localStorage.setItem("wg-autoplay", want ? "1" : "0");
+            }
+            catch {
+                /* private mode / blocked storage */
+            }
+        }, on)
+            .catch(ignorePageGone);
+    };
+    // A Next click can land before wait() starts listening (there is an await in between on the slides path); keep it
+    // for the next wait() instead of dropping it, or the panel looks stuck.
+    let resolveNext = null;
+    let pendingNext = null;
+    await page.exposeFunction("__wgNext", (edits) => {
+        if (resolveNext) {
+            const r = resolveNext;
+            resolveNext = null;
+            r(edits);
+        }
+        else {
+            pendingNext = edits;
+        }
+    });
+    const waitForNext = () => new Promise((res) => {
+        if (pendingNext !== null) {
+            const edits = pendingNext;
+            pendingNext = null;
+            res(edits);
+            return;
+        }
+        resolveNext = res;
+    });
+    const autoplayOn = () => page
+        .evaluate(() => {
+        try {
+            return localStorage.getItem("wg-autoplay") === "1";
+        }
+        catch {
+            return false;
+        }
+    })
+        .catch(() => false);
+    const wait = async () => {
+        const next = waitForNext();
+        // A step that skips the theater (WAYGRAPH_FAST_BLOCKS, fast-forward) blows past its gates too.
+        const ms = demoPaceGateMs(pacing.skipTheater ? "blitz" : pacing.demoPace, autoplayMs);
+        let elapsed = 0;
+        for (;;) {
+            const auto = await autoplayOn();
+            const slice = auto ? Math.min(250, Math.max(50, ms - elapsed)) : 250;
+            const winner = await Promise.race([
+                next.then((edits) => ({ clicked: true, edits })),
+                new Promise((res) => setTimeout(() => res({ clicked: false }), slice)),
+            ]);
+            if (winner.clicked)
+                return winner.edits;
+            if (!auto)
+                continue;
+            elapsed += slice;
+            if (elapsed >= ms)
+                return {};
+        }
+    };
+    return { wait, syncAutoplay, autoplayMs };
+}

package/dist/demo/stepper/interaction-patch.d.ts

@@ -0,0 +1,3 @@
+import type { WgPage } from "../types.js";
+import type { MemPage } from "../../engine/mem/mem.js";
+export declare function instrumentInteractionHighlighting(page: WgPage, mem: MemPage, slowMo: number, pacing: any, stubBeforeRef: any, todoDockRef: any, deviceRef: any): void;