waygraph 0.15.53 → 0.16.0

package/dist/demo/overlay/rings.js

@@ -0,0 +1,448 @@
+import { ANSI, ansiPaint, demoFixture, demoHighlight, demoLog } from "../stepper/demo-log.js";
+import { playSwipeTrail } from "./cursor.js";
+import { advanceTodoDock, normalizeTodos } from "../narration/todo-dock.js";
+import { formatHighlightCaption } from "../narration/style.js";
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../engine/stub/ring.js";
+import { resolveFixtureDwellMs } from "../narration/demo-pace.js";
+import { envNumber } from "../../engine/env.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+/**
+ * Scroll a locator into view for demo theater.
+ * Prefer CSS smooth scroll + scrollend wait. Do NOT call Playwright's
+ * scrollIntoViewIfNeeded first - that jumps instantly and makes the
+ * following smooth scroll a no-op (looks like a teleport), especially
+ * noticeable under --fast when dwell is shorter.
+ * Pass opts.instant=true only for skipTheater / blitz.
+ */
+export async function ensureLocatorInView(locator, opts) {
+    const instant = !!(opts && opts.instant);
+    if (instant) {
+        await locator.scrollIntoViewIfNeeded().catch(ignorePageGone);
+        return;
+    }
+    // Touch mode: if the target is off-screen, show a swipe trail in the
+    // finger direction that would scroll it into view (not device morph).
+    const scrollPlan = await locator
+        .evaluate((el) => {
+        if (!el || typeof el.getBoundingClientRect !== "function")
+            return null;
+        const touch = window.__wgDeviceTouch === true ||
+            document.documentElement.dataset.wgTouch === "1" ||
+            window.__wgDevicePreset === "mobile" ||
+            window.__wgDevicePreset === "tablet";
+        if (!touch)
+            return null;
+        const r = el.getBoundingClientRect();
+        const vw = window.innerWidth || 390;
+        const vh = window.innerHeight || 844;
+        const margin = 48;
+        const below = r.top > vh - margin;
+        const above = r.bottom < margin;
+        const right = r.left > vw - margin;
+        const left = r.right < margin;
+        if (!below && !above && !left && !right)
+            return null;
+        // Finger direction to reveal the target (swipe up => content moves up).
+        let dir = "up";
+        if (below)
+            dir = "up";
+        else if (above)
+            dir = "down";
+        else if (right)
+            dir = "left";
+        else if (left)
+            dir = "right";
+        return { dir, hint: "scroll" };
+    })
+        .catch(() => null);
+    if (scrollPlan && scrollPlan.dir) {
+        demoLog("  swipe trail dir=" + scrollPlan.dir + " hint=scroll");
+        await playSwipeTrail(locator.page(), {
+            dir: scrollPlan.dir,
+            label: "swipe \u00b7 scroll",
+            hint: "scroll",
+            ms: envNumber("WAYGRAPH_SWIPE_MS") ?? 650,
+        });
+    }
+    await locator
+        .evaluate(async (el) => {
+        if (!el || typeof el.scrollIntoView !== "function")
+            return;
+        const waitScroll = (node, ms) => new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                try {
+                    node.removeEventListener("scrollend", finish);
+                }
+                catch {
+                    /* ignore */
+                }
+                clearTimeout(t);
+                resolve();
+            };
+            const t = setTimeout(finish, ms);
+            try {
+                node.addEventListener("scrollend", finish, { once: true });
+            }
+            catch {
+                /* scrollend unsupported - timeout only */
+            }
+        });
+        try {
+            el.scrollIntoView({ block: "center", inline: "center", behavior: "smooth" });
+        }
+        catch {
+            try {
+                el.scrollIntoView({ block: "center", inline: "center" });
+            }
+            catch {
+                try {
+                    el.scrollIntoView(true);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        await waitScroll(document.scrollingElement || document.documentElement, 650);
+        let p = el.parentElement;
+        while (p && p !== document.documentElement && p !== document.body) {
+            const st = getComputedStyle(p);
+            const ox = st.overflowX;
+            const oy = st.overflowY;
+            if (/(auto|scroll|overlay)/.test(ox) || /(auto|scroll|overlay)/.test(oy)) {
+                const er = el.getBoundingClientRect();
+                const pr = p.getBoundingClientRect();
+                if (er.left < pr.left || er.right > pr.right || er.top < pr.top || er.bottom > pr.bottom) {
+                    const left = p.scrollLeft + (er.left + er.width / 2 - (pr.left + pr.width / 2));
+                    const top = p.scrollTop + (er.top + er.height / 2 - (pr.top + pr.height / 2));
+                    try {
+                        p.scrollTo({ left, top, behavior: "smooth" });
+                    }
+                    catch {
+                        p.scrollLeft = left;
+                        p.scrollTop = top;
+                    }
+                    await waitScroll(p, 650);
+                }
+            }
+            p = p.parentElement;
+        }
+    })
+        .catch(ignorePageGone);
+}
+export async function ensureSelectorInView(page, selector, opts) {
+    await ensureLocatorInView(page.locator(selector).first(), opts);
+}
+export async function applyHighlightZoom(page, selector, zoom, zoomOut) {
+    const z = Number(zoom);
+    if (!Number.isFinite(z) || z <= 1.001) {
+        await page.evaluate(() => {
+            window.__wgZoomOutOnHide = true;
+            if (window.__wgClearZoom)
+                window.__wgClearZoom();
+        }).catch(ignorePageGone);
+        return;
+    }
+    demoFixture("zoom", "ctx/ring zoom(" + z + ") zoomOut=" + (zoomOut !== false), selector);
+    await page
+        .evaluate(({ sel, scale, zoomOut }) => {
+        // false = keep camera after ring hide (ctx.zoomOut(false) / ring.zoomOut).
+        window.__wgZoomOutOnHide = zoomOut !== false;
+        if (window.__wgApplyZoom)
+            window.__wgApplyZoom(sel, scale);
+    }, { sel: selector, scale: z, zoomOut: zoomOut !== false })
+        .catch(ignorePageGone);
+}
+export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
+    const list = highlights || [];
+    // defaultHoldMs: when set (fail path), use instead of the default 900/200 so BUG
+    // rings stay visible ~2s before the error panel (PIA stubOnError RFC).
+    const defaultHoldMs = opts && opts.defaultHoldMs != null ? opts.defaultHoldMs : null;
+    const pace = opts && opts.pace !== undefined ? opts.pace : undefined;
+    let dock = opts && opts.todoDock;
+    const advanceTodos = !(opts && opts.advanceTodos === false);
+    // Push stubAfter/before dock before the first ring so Method after-panels
+    // show the updated checklist immediately (not only after the ring cycle).
+    if (dock) {
+        await page
+            .evaluate((d) => {
+            if (window.__wgSyncTodos)
+                window.__wgSyncTodos({ sync: "set", dock: d });
+        }, dock)
+            .catch(ignorePageGone);
+    }
+    else if (opts && opts.todoSync === "clear") {
+        await page
+            .evaluate(() => {
+            if (window.__wgSyncTodos)
+                window.__wgSyncTodos({ sync: "clear" });
+        })
+            .catch(ignorePageGone);
+    }
+    let lastRingEndedAt = null;
+    for (let i = 0; i < list.length; i++) {
+        const h = list[i];
+        const ringStarted = Date.now();
+        try {
+            await ensureSelectorInView(page, h.selector);
+            await applyHighlightZoom(page, h.selector, h.zoom, h.zoomOut);
+            // Prefer live in-page rect (honors device-shell scale) over Playwright's own boundingBox() -
+            // but resolve the element through Playwright's OWN locator (full selector engine: >>
+            // piercing, :has-text(), :visible, ...), not a raw DOM querySelector, which only understands
+            // real CSS and silently fails to match any Playwright-specific selector syntax.
+            // count() gate: a real, caught regression - Locator.evaluate() has no timeout option and
+            // auto-waits (Playwright's default ~30s) for a match to appear, unlike the instant
+            // document.querySelector it replaced. count() alone never waits, so this stays an immediate
+            // "does it exist right now" check - ensureSelectorInView above already gave the page a real
+            // moment to settle.
+            const hLoc = page.locator(h.selector).first();
+            const box = (await hLoc.count().catch(() => 0)) > 0
+                ? await hLoc
+                    .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, h.label, h.tone || "planned", {
+                    size: h.size,
+                    weight: h.weight,
+                    selector: h.selector,
+                    focus: !!h.focus,
+                });
+                // focus is applied by FollowRing / showRing - no second apply needed
+                // Do NOT advanceTodoDock by ring index after stubAfter already set
+                // progress - that reset current back to 0 and the next block looked
+                // blank. Mid-act Method advance still uses syncTodoDockAdvance.
+                if (dock && advanceTodos) {
+                    dock = advanceTodoDock(dock, i);
+                    if (opts && opts.todoDockRef)
+                        opts.todoDockRef.current = dock;
+                    await page
+                        .evaluate((d) => {
+                        if (window.__wgSyncTodos)
+                            window.__wgSyncTodos({ sync: "set", dock: d });
+                    }, dock)
+                        .catch(ignorePageGone);
+                }
+                else if (!dock && ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length))) {
+                    const rows = opts && opts.todos && opts.todos.length
+                        ? opts.todos
+                        : normalizeTodos(h.todos, h.todoIndex);
+                    await page
+                        .evaluate((todos) => {
+                        if (window.__wgSyncTodos)
+                            window.__wgSyncTodos({ sync: "set", list: todos });
+                    }, rows)
+                        .catch(ignorePageGone);
+                }
+                const authored = resolveFixtureDwellMs(h, { gatesFast, pace });
+                const defaultMs = i === list.length - 1 ? 200 : 900;
+                const holdMs = authored != null ? authored : defaultHoldMs != null ? defaultHoldMs : defaultMs;
+                const gap = lastRingEndedAt != null ? ringStarted - lastRingEndedAt : null;
+                const holdExtra = "hold=" +
+                    holdMs +
+                    "ms" +
+                    (authored != null ? " authored" : " default") +
+                    " box=" +
+                    Math.round(box.x) +
+                    "," +
+                    Math.round(box.y) +
+                    " " +
+                    Math.round(box.width) +
+                    "x" +
+                    Math.round(box.height) +
+                    (gap != null ? " gap=" + gap + "ms" : "");
+                demoHighlight(h, holdExtra);
+                demoLog("  highlight " +
+                    (i + 1) +
+                    "/" +
+                    list.length +
+                    (gap != null && gap < 120 ? ansiPaint(ANSI.yellow, " WARN gap<120ms") : "") +
+                    (holdMs < 250 && list.length > 1 ? ansiPaint(ANSI.yellow, " WARN short hold") : ""));
+                await new Promise((res) => setTimeout(res, holdMs));
+                lastRingEndedAt = Date.now();
+            }
+            else {
+                demoHighlight(h, "SKIP no boundingBox");
+            }
+        }
+        catch (err) {
+            demoHighlight(h || { selector: h && h.selector, label: "(error)" }, "SKIP " + String(err instanceof Error ? err.message : err).slice(0, 80));
+        }
+    }
+    if (list.length > 0) {
+        const last = list[list.length - 1];
+        // Resolved through Playwright's own locator (>> piercing / :has-text() / :visible support),
+        // not handed to the page as a string for a raw DOM querySelector to fail silently on - see
+        // showRing's own comment (same fix, same reason) and __wgFollowRing's in core.js.
+        const handle = last.selector
+            ? await page.locator(last.selector).first().elementHandle({ timeout: 100 }).catch(() => null)
+            : null;
+        await page
+            .evaluate(({ h, el }) => {
+            if (el && window.__wgFollowRing) {
+                window.__wgFollowRing(el, h.label, h.tone || "planned", { size: h.size || "md", weight: h.weight || "normal" }, !!h.focus);
+                return;
+            }
+            if (!window.__wgPositionRing)
+                return;
+            if (!el) {
+                if (window.__wgHideRing)
+                    window.__wgHideRing();
+                return;
+            }
+            const reposition = () => {
+                const box = el.getBoundingClientRect();
+                window.__wgPositionRing(box, h.label, h.tone || "planned", {
+                    size: h.size || "md",
+                    weight: h.weight || "normal",
+                });
+                if (h.focus && window.__wgApplyFocus) {
+                    window.__wgApplyFocus({
+                        x: box.x,
+                        y: box.y,
+                        width: box.width,
+                        height: box.height,
+                    });
+                }
+            };
+            reposition();
+            window.__wgRingTrack = reposition;
+            window.addEventListener("resize", reposition);
+            window.addEventListener("scroll", reposition, true);
+        }, { h: last, el: handle })
+            .catch(ignorePageGone);
+    }
+    else {
+        await hideRing(page);
+    }
+}
+export async function showRing(page, box, label, tone, style) {
+    const size = normalizeHighlightSize(style && style.size);
+    const weight = normalizeHighlightWeight(style && style.weight);
+    const selector = style && style.selector ? String(style.selector) : "";
+    const focus = !!(style && style.focus);
+    // Resolve through Playwright's own locator (full selector engine), not a selector string handed
+    // to the page for a raw DOM lookup - >> piercing / :has-text() / :visible are Playwright-only
+    // syntax, invisible to document.querySelector. The resolved element handle is passed straight
+    // into evaluate (Playwright unwraps it to the real DOM node inside the page), so __wgFollowRing's
+    // per-frame RAF loop tracks that exact element directly - no repeated selector re-resolution.
+    const handle = selector ? await page.locator(selector).first().elementHandle({ timeout: 100 }).catch(() => null) : null;
+    await page
+        .evaluate(({ box, label, tone, size, weight, el, focus }) => {
+        if (el && window.__wgFollowRing) {
+            window.__wgFollowRing(el, label, tone || "planned", { size, weight }, focus);
+            return;
+        }
+        if (window.__wgStopRingFollow)
+            window.__wgStopRingFollow();
+        if (window.__wgPositionRing) {
+            window.__wgPositionRing(box, label, tone || "planned", { size, weight });
+        }
+        if (focus && box && window.__wgApplyFocus)
+            window.__wgApplyFocus(box);
+        else if (!focus && window.__wgClearFocus)
+            window.__wgClearFocus();
+    }, { box, label, tone: tone || "planned", size, weight, el: handle, focus })
+        .catch(ignorePageGone);
+}
+/** Match a locator to a stubBefore slot by overlapping bounding boxes. */
+async function matchStubForLocator(page, locator, stubs) {
+    if (!stubs || stubs.length === 0)
+        return null;
+    const box = await locator.boundingBox().catch(() => null);
+    if (!box)
+        return null;
+    for (const s of stubs) {
+        try {
+            const b = await page.locator(s.selector).first().boundingBox();
+            if (b &&
+                Math.abs(b.x - box.x) < 4 &&
+                Math.abs(b.y - box.y) < 4 &&
+                Math.abs(b.width - box.width) < 8) {
+                return s;
+            }
+        }
+        catch {
+            // A stub selector Playwright can't parse can't be this element either.
+        }
+    }
+    return null;
+}
+/** 0-based stub index for Method fill/click todo advance; -1 if none. */
+export async function matchStubIndexForLocator(page, locator, stubs) {
+    if (!stubs || stubs.length === 0)
+        return -1;
+    const box = await locator.boundingBox().catch(() => null);
+    if (!box)
+        return -1;
+    for (let i = 0; i < stubs.length; i++) {
+        const s = stubs[i];
+        try {
+            const b = await page.locator(s.selector).first().boundingBox();
+            if (b &&
+                Math.abs(b.x - box.x) < 4 &&
+                Math.abs(b.y - box.y) < 4 &&
+                Math.abs(b.width - box.width) < 8) {
+                return i;
+            }
+        }
+        catch {
+            // A stub selector Playwright can't parse can't be this element either.
+        }
+    }
+    return -1;
+}
+export async function captionForLocator(page, locator, stubs, fallback) {
+    const matched = await matchStubForLocator(page, locator, stubs);
+    if (matched) {
+        return {
+            label: formatHighlightCaption(matched),
+            tone: normalizeHighlightTone(matched.tone),
+            size: normalizeHighlightSize(matched.size),
+            weight: normalizeHighlightWeight(matched.weight),
+        };
+    }
+    return { label: fallback, tone: "auto", size: "md", weight: "normal" };
+}
+export async function dwellMatchedStub(page, locator, stubs, pacing) {
+    const matched = await matchStubForLocator(page, locator, stubs);
+    if (!matched)
+        return;
+    const ms = resolveFixtureDwellMs(matched, {
+        gatesFast: !!(pacing && pacing.gatesFast),
+        pace: pacing && pacing.demoPace,
+    });
+    if (ms != null && ms > 0) {
+        await new Promise((res) => setTimeout(res, ms));
+    }
+}
+export async function hideRing(page) {
+    await page
+        .evaluate(() => {
+        if (window.__wgHideRing)
+            window.__wgHideRing();
+    })
+        .catch(ignorePageGone);
+}
+/**
+ * True if the engine's own narrate() (waygraph's public export, for a Block
+ * author explicitly captioning one action) JUST positioned the ring for
+ * THIS action, moments ago - the automatic per-fill/per-click narration
+ * below should not immediately overwrite an author's own explicit caption
+ * with its generic guess.
+ */
+export async function wasJustNarrated(page) {
+    return page
+        .evaluate(() => {
+        const w = window;
+        return typeof w.__wgLastNarrate === "number" && Date.now() - w.__wgLastNarrate < 500;
+    })
+        .catch(() => false);
+}

package/dist/{ui → demo/overlay/ui}/components/ring.js

@@ -33,5 +33,5 @@ export function ringCss() {
 }
 // A former `pilotFxRingCss()` used to live here, generating a SECOND, byte-identical copy of
 // ringCss()'s own rules under `.wg-pilot-fx-ring`/`.wg-pilot-fx-label`. Pilot's fixture rings now
-// paint through the same shared primitive (`ui/css/ring.css`'s `.wg-ring-el`, `runner/inpage/core.js`'s
-// `__wgPaintRingAt`) as the demo/auto singleton ring - see src/ui/css/ring.css's own header.
+// paint through the same shared primitive (`ui/css/ring.css`'s `.wg-ring-el`, `demo/overlay/inpage/core.ts`'s
+// `__wgPaintRingAt`) as the demo/auto singleton ring - see src/demo/overlay/ui/css/ring.css's own header.

package/dist/{ui → demo/overlay/ui}/overlay.css

@@ -1,4 +1,4 @@
-/* Bundled at build time by scripts/copy-ui-css.mjs - do not hand-edit. Edit src/ui/css/*.css. */
+/* Bundled at build time by scripts/copy-ui-css.mjs - do not hand-edit. Edit src/demo/overlay/ui/css/*.css. */
 
 :host{--layer-1:1;--layer-2:2;--layer-3:3;--layer-4:4;--layer-5:5;--layer-important:2147483647}
 
@@ -54,7 +54,7 @@
  * ONE ring implementation, shared by every surface (demo/auto's singleton #wg-ring, and Pilot's
  * multiple simultaneous fixture rings) - `.wg-ring-el`/`.wg-ring-el-label` is the real class every
  * ring element carries; `#wg-ring`/`#wg-ring-label` and Pilot's per-instance ids are just how each
- * surface finds/targets ITS OWN ring(s) in JS (runner/inpage/core.js's __wgEnsureRingEl/
+ * surface finds/targets ITS OWN ring(s) in JS (demo/overlay/inpage/core.ts's __wgEnsureRingEl/
  * __wgPaintRingAt). Before this file existed as one, the demo/auto ring and Pilot's fixture ring
  * were two byte-identical copies of the same tone/size/weight rules - a real, provable case of the
  * "why do we have two of everything" complaint that's easy to lose track of once it's spread across
@@ -132,7 +132,7 @@
 
 /* Top title banner (#wg-banner). Sits BELOW the ring/label/dock layers (--wg-z-banner) - a title
  * card must never shadow a highlight; see tokens.css. Moves out of the way of a ring it overlaps
- * (data-collision, driven from inpage/banner.js's __wgBannerAvoidRing) unless authored off. */
+ * (data-collision, driven from inpage/banner.ts's __wgBannerAvoidRing) unless authored off. */
 #wg-banner {
   position: fixed; z-index: var(--wg-z-banner); top: 14px; left: 14px;
   background: var(--wg-surface); color: #fff; border-radius: var(--wg-radius-lg); padding: 10px 16px;
@@ -154,7 +154,7 @@
 
 /*
  * Floating fixture todo dock for Pilot (#wg-pilot-fx-todos). The demo runner's OWN `.wg-todo-dock` /
- * `#wg-todo-dock` (src/runner/overlay-css.js) is a separate, richer implementation - fold/tucked/
+ * `#wg-todo-dock` (demo/overlay/overlay-css.ts) is a separate, richer implementation - fold/tucked/
  * slide-position transitions this file does not replicate - and deliberately NOT redefined here:
  * two rule sets for the same selector, injected in different orders, is exactly the "sometimes it
  * doesn't line up" bug class this split guards against. Only #wg-pilot-fx-todos, a genuine

package/dist/{ui → demo/overlay/ui}/shadow.d.ts

@@ -10,7 +10,7 @@
 import type { Page } from "@playwright/test";
 /**
  * `overlaySheet` is the ONE real-CSS bundle (`ui/stylesheet.ts` -> `dist/ui/overlay.css`, built on
- * Open Props - see `src/ui/css/README.md`) every surface shares; passed in from Node since in-page
+ * Open Props - see `src/demo/overlay/ui/css/README.md`) every surface shares; passed in from Node since in-page
  * code can't read a file. Installed once per shadow root, before anything else runs.
  */
 export declare function installShadowRoot(overlaySheet?: string): void;

package/dist/{ui → demo/overlay/ui}/shadow.js

@@ -1,7 +1,8 @@
 import { getOverlaySheet } from "./stylesheet.js";
+import { ignorePageGone } from "../../../engine/page-gone.js";
 /**
  * `overlaySheet` is the ONE real-CSS bundle (`ui/stylesheet.ts` -> `dist/ui/overlay.css`, built on
- * Open Props - see `src/ui/css/README.md`) every surface shares; passed in from Node since in-page
+ * Open Props - see `src/demo/overlay/ui/css/README.md`) every surface shares; passed in from Node since in-page
  * code can't read a file. Installed once per shadow root, before anything else runs.
  */
 export function installShadowRoot(overlaySheet) {
@@ -37,10 +38,46 @@ export function installShadowRoot(overlaySheet) {
         if (style.textContent !== css)
             style.textContent = css;
     };
+    const toNodes = (children, out = []) => {
+        for (const c of children) {
+            if (c == null || c === false)
+                continue;
+            if (Array.isArray(c))
+                toNodes(c, out);
+            else
+                out.push(c instanceof Node ? c : document.createTextNode(String(c)));
+        }
+        return out;
+    };
+    w.__wgEl = (tag, props, ...children) => {
+        const el = document.createElement(tag);
+        if (props?.id)
+            el.id = props.id;
+        if (props?.class)
+            el.className = props.class;
+        if (props?.style)
+            el.style.cssText = props.style;
+        if (props?.title)
+            el.title = props.title;
+        for (const [k, v] of Object.entries(props?.data ?? {}))
+            if (v != null)
+                el.dataset[k] = String(v);
+        for (const [k, v] of Object.entries(props?.attrs ?? {}))
+            if (v != null)
+                el.setAttribute(k, String(v));
+        el.append(...toNodes(children));
+        return el;
+    };
+    w.__wgSet = (el, ...children) => el.replaceChildren(...toNodes(children));
+    // Waygraph's own static icons (constants in this package, never page or author text), parsed as SVG.
+    w.__wgSvg = (markup) => {
+        const xml = markup.includes("xmlns=") ? markup : markup.replace("<svg", '<svg xmlns="http://www.w3.org/2000/svg"');
+        return document.importNode(new DOMParser().parseFromString(xml, "image/svg+xml").documentElement, true);
+    };
     if (overlaySheet)
         w.__wgCss(overlaySheet, "wg-overlay-css");
 }
 /** Idempotent; call before any overlay install on a page. Installs the shared stylesheet bundle. */
 export async function ensureShadowRoot(page) {
-    await page.evaluate(installShadowRoot, getOverlaySheet()).catch(() => { });
+    await page.evaluate(installShadowRoot, getOverlaySheet()).catch(ignorePageGone);
 }

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

@@ -0,0 +1,3 @@
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import type { StepperContext, StepView } from "./view.js";
+export declare function showAfter(ctx: StepperContext, view: StepView, result: Checkpoint<string>): Promise<void>;

package/dist/demo/stepper/after.js

@@ -0,0 +1,113 @@
+import { hasAuthoredStubAfter, resolveSlides, runStubPhase } from "../narration/narration.js";
+import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
+import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
+import { extractVerifyHighlights, renderAfterStep } from "./step-panels.js";
+import { presentSlides } from "./slides.js";
+import { logBannerDom, probeBanner } from "./banner-log.js";
+import { logDocks } from "./before.js";
+import { forceCollapsed } from "./view.js";
+import { envFlag } from "../../engine/env.js";
+const quiet = () => envFlag("WAYGRAPH_JSON");
+export async function showAfter(ctx, view, result) {
+    const { stage, refs } = ctx;
+    await showSlides(ctx, view, result);
+    const after = hasAuthoredStubAfter(view.step.block, result) ? await narrateAfter(ctx, view, result) : undefined;
+    const applied = after ? await stage.applyPhase(after.phase) : { appliedTodo: { sync: "keep" }, appliedDevice: { sync: "keep" } };
+    await renderAfterStep(ctx.page, {
+        index: view.index,
+        total: ctx.steps.length,
+        blockName: view.step.block.name,
+        result,
+        resultTag: JSON.stringify(result),
+        highlights: after?.highlights ?? verifyRings(view, result),
+        gatesFast: ctx.pacing.gatesFast,
+        ...paceSpeakFields(ctx.pacing.demoPace, ctx.gate.autoplayMs),
+        isLast: view.index === ctx.steps.length - 1,
+        allNames: view.moduleNames,
+        allDescriptions: view.moduleDescriptions,
+        moduleIndex: view.moduleIndex,
+        allEpisodes: ctx.allEpisodes,
+        title: after?.phase.title && String(after.phase.title).trim() ? String(after.phase.title).trim() : view.overlayTitle,
+        bannerUi: stage.state.lastBannerUi,
+        // undefined leaves the caption and network tab as they are
+        caption: after?.phase.caption,
+        networkTabVisible: after?.phase.networkTabVisible,
+        fastForward: !!view.step.block.fastForward,
+        isApi: view.step.block.__waygraphKind === "api",
+        todoPos: after ? stage.state.lastTodoDock?.pos || after.phase.todoPos || view.overlayTodoPos : view.overlayTodoPos,
+        episodeNumber: view.step.episodeNumber,
+        episodeTitle: view.step.episodeTitle,
+        stepperMode: ctx.stepperMode,
+        todos: after ? stage.state.lastTodoDock?.groups[0]?.items || after.phase.todos || [] : [],
+        todoDock: stage.state.lastTodoDock,
+        todoSync: applied.appliedTodo.sync,
+        todoId: stage.state.lastTodoDock?.id,
+        todoDockRef: refs.todoDock,
+        forceCollapsed: forceCollapsed(),
+    });
+    const parallel = !!after?.phase.todoParallel;
+    await stage.syncAllTodoDocks({ parallel });
+    // The ring cycle or stubAfter may have advanced the dock; the next step starts from there.
+    if (refs.todoDock.current) {
+        stage.state.lastTodoDock = refs.todoDock.current;
+        stage.rememberTodoDock(refs.todoDock.current, "set", parallel);
+    }
+    if (!quiet()) {
+        demoLog("  after " + summarizeDevice(stage.state.lastDevice) + " deviceSync=" + applied.appliedDevice.sync);
+        logTodoDockFull(stage.state.lastTodoDock, "  after");
+        demoLog("  after todoSync=" + applied.appliedTodo.sync);
+        await logDocks(ctx, "after ", !!stage.state.lastTodoDock, applied.appliedTodo.sync === "clear");
+        logBannerDom("after", await probeBanner(ctx.page));
+    }
+    await ctx.gate.wait();
+}
+async function showSlides(ctx, view, result) {
+    const slides = resolveSlides(view.step.block, { out: result }).map((s) => applyHighlightStyleDefaults(s, view.step.highlightStyle));
+    if (slides.length === 0)
+        return;
+    await presentSlides(ctx.page, slides, ctx.gate.wait, {
+        title: ctx.title,
+        blockName: view.step.block.name,
+        fast: ctx.pacing.gatesFast,
+        pace: ctx.pacing.demoPace,
+        episodeNumber: view.step.episodeNumber,
+        episodeTitle: view.step.episodeTitle,
+        autoplayMs: ctx.gate.autoplayMs,
+    });
+}
+/** Runs the Block's stubAfter; its rings carry the flow's highlight style and a caption. */
+async function narrateAfter(ctx, view, result) {
+    const style = view.step.highlightStyle;
+    const phase = await runStubPhase(view.step.block, "stubAfter", { out: result, mem: ctx.mem });
+    if (phase.todoDockUi)
+        await ctx.stage.pushTodoDockUi(phase.todoDockUi);
+    logStubPhaseFixtures("after", {
+        ...phase,
+        highlights: (phase.highlights || []).map((h) => {
+            const styled = applyHighlightStyleDefaults(h, style);
+            return { ...styled, label: formatHighlightCaption(styled) };
+        }),
+    });
+    const highlights = phase.highlights.map((h) => {
+        const styled = applyHighlightStyleDefaults(h, style);
+        return {
+            selector: styled.selector,
+            label: formatHighlightCaption(styled),
+            duration: styled.duration,
+            fastMode: styled.fastMode,
+            tone: styled.tone,
+            size: styled.size,
+            weight: styled.weight,
+            zoom: styled.zoom,
+            zoomOut: styled.zoomOut,
+            focus: !!styled.focus,
+            color: styled.color,
+            detail: styled.detail,
+        };
+    });
+    return { phase, highlights };
+}
+/** No stubAfter: ring what the Block's verify checked. */
+function verifyRings(view, result) {
+    return extractVerifyHighlights(view.step.block, result.__state).map((h) => applyHighlightStyleDefaults(h, view.step.highlightStyle));
+}