waygraph 0.15.32 → 0.15.34

package/dist/runner/inpage/banner.js

@@ -1,10 +1,11 @@
 // In-page installer (runs inside the browser via page.evaluate): must stay self-contained - no module-scope closure.
 // Split out of the former single installOverlay evaluate (see src/ARCHITECTURE.md). Shares state only via window.__wg*.
 /* eslint-disable no-unused-vars */
-export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi, bannerUi }) {
         const POSITIONS = ["left", "center", "right"];
         const applyPos = (el, pos) => {
           el.dataset.pos = pos;
+          el.dataset.home = pos;
           try {
             localStorage.setItem("wg-banner-pos", pos);
           } catch {
@@ -52,6 +53,60 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
             text.textContent = title;
           }
         }
+        // Authored banner UX (StubCtx.titlePos / bannerUi): applied every step, wins over click/env.
+        if (bannerUi) {
+          const cur = window.__wgBannerUi || {};
+          window.__wgBannerUi = { ...cur, ...bannerUi };
+        }
+        const bui = window.__wgBannerUi || {};
+        const bannerEl = __wgById("wg-banner");
+        if (bannerEl) {
+          if (bui.pos && POSITIONS.includes(bui.pos) && bannerEl.dataset.home !== bui.pos) {
+            bannerEl.dataset.pos = bui.pos;
+            bannerEl.dataset.home = bui.pos;
+            bannerEl.dataset.authored = "1";
+          }
+          bannerEl.dataset.collision = bui.collision === false ? "0" : "1";
+          bannerEl.style.display = bui.hidden ? "none" : "";
+        }
+        // Move the banner out of the way of a highlight ring (mirrors the todo dock's collision flip).
+        window.__wgBannerAvoidRing = (box) => {
+          const b = __wgById("wg-banner");
+          if (!b || !box || b.dataset.collision === "0" || b.style.display === "none") return;
+          const pad = 10;
+          const hits = () => {
+            const r = b.getBoundingClientRect();
+            return !(
+              r.right < box.x - pad ||
+              r.left > box.x + box.width + pad ||
+              r.bottom < box.y - pad ||
+              r.top > box.y + box.height + pad
+            );
+          };
+          const home = b.dataset.home || b.dataset.pos || "left";
+          b.dataset.pos = home;
+          if (!hits()) {
+            delete b.dataset.moved;
+            return;
+          }
+          for (const cand of POSITIONS.filter((p) => p !== home)) {
+            b.dataset.pos = cand;
+            if (!hits()) {
+              b.dataset.moved = home + ">" + cand;
+              (window.__wgBannerLog = window.__wgBannerLog || []).push("moved " + home + " -> " + cand + " (ring overlap)");
+              return;
+            }
+          }
+          b.dataset.pos = home;
+          b.dataset.moved = "none-free";
+          (window.__wgBannerLog = window.__wgBannerLog || []).push("overlap at every position (kept " + home + ")");
+        };
+        window.__wgBannerRestore = () => {
+          const b = __wgById("wg-banner");
+          if (!b) return;
+          if (b.dataset.home) b.dataset.pos = b.dataset.home;
+          delete b.dataset.moved;
+        };
         // Tab title/favicon: a real navigation resets document.title and any
         // <link rel="icon"> the new document brings, so re-check (not
         // re-append) on every call instead of a one-time flag.

package/dist/runner/inpage/core.js

@@ -114,6 +114,7 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ringLabel.style.top = labelTop + "px";
           if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(true);
           if (window.__wgTodosAvoidRingCollision) window.__wgTodosAvoidRingCollision(box);
+          if (window.__wgBannerAvoidRing) window.__wgBannerAvoidRing(box);
         };
         /** Dim/lower floating todo docks while a ring caption is the focus. */
         window.__wgTodosSetBehind = (on) => {
@@ -220,6 +221,7 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           if (ringLabel) ringLabel.style.opacity = "0";
           if (window.__wgClearFocus) window.__wgClearFocus();
           if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(false);
+          if (window.__wgBannerRestore) window.__wgBannerRestore();
           window.__wgTodoCollisionLocked = false;
           __wgQA(".wg-todo-dock[data-tucked], #wg-todo-dock[data-tucked]").forEach((el) => {
             delete el.dataset.tucked;

package/dist/runner/overlay-css.js

@@ -1,7 +1,5 @@
 // Moved verbatim from the former CHAIN_RUNNER_SCRIPT template string in cli.ts (see src/ARCHITECTURE.md).
 // Runs inside the target project's own waygraph copy - keep it dependency-light and self-contained.
-import { WAYGRAPH_RING_CSS } from "../highlights.js";
-import { cursorCss } from "../ui/components/cursor.js";
 import { SURFACE } from "../ui/tokens.js";
 
 // ---------------------------------------------------------------------------
@@ -13,22 +11,11 @@ import { SURFACE } from "../ui/tokens.js";
 // label-under-box language, minus everything camera/narration-specific).
 // Purely CLI-level orchestration - no engine changes, no change to the
 // non-STEP path above.
-export const RING_CSS =
-  // Shared with pilot-overlay.ts's showPilotVision - same ring/label CSS,
-  // one source of truth (highlights.ts), so a Blind Pilot vision ring and a
-  // demo stepper ring never visually drift apart.
-  WAYGRAPH_RING_CSS +
-  // Mouse cursor icon that travels to a target before it's acted on, plus a
-  // quick expanding ripple at the moment of a click - same idea as
-  // help-center-clip-engine's #clip-cursor/#clip-ring (video-pipeline). The
-  // shape itself is an inline SVG set as innerHTML in installOverlay below
-  // (dark fill + white stroke, same as the clip-engine's own cursor) - a
-  // plain solid-white CSS clip-path (the first attempt here) had no outline
-  // at all and all but disappeared against this app's light background.
-  // Travel duration is JS-driven per call via --wg-cursor-ms, same reason
-  // the clip engine's own comment gives: a hardcoded CSS duration would
-  // make the speed param a no-op.
-  cursorCss() +
+// Runner-only chrome (step panel, todo-dock legacy variant, zoom/typing/device chips) - NOT
+// ring/cursor/banner, which come from the one shared bundle every surface installs
+// (ui/css/*.css, see ensureShadowRoot in overlay-install.js). Injected under its own key so it
+// never collides with that bundle.
+export const RUNNER_EXTRA_CSS =
   // Spotlight: dim everything except the highlight target (focus: true).
   "#wg-focus-veil{position:fixed;z-index:2147483644;pointer-events:none;" +
   "border-radius:12px;box-shadow:0 0 0 9999px rgba(8,4,20,.62);" +
@@ -225,15 +212,7 @@ export const RING_CSS =
   "#wg-modules .wg-mod-done{background:#2a1650;color:#9a7ad1;}" +
   "#wg-modules .wg-mod-current{background:#7C3AED;color:#fff;}" +
   "#wg-modules .wg-mod-upcoming{background:transparent;color:#5a4a80;border:1px solid #3a2a60;}" +
-  "#wg-banner{position:fixed;z-index:2147483647;top:14px;max-width:320px;" +
-  "background:" + SURFACE + ";color:#fff;border-radius:12px;padding:10px 16px;" +
-  "font:14px/1.4 system-ui,sans-serif;box-shadow:0 8px 20px rgba(0,0,0,.3);" +
-  "border:1px solid rgba(124,58,237,.4);cursor:pointer;user-select:none;}" +
-  "#wg-banner[data-pos=left]{left:14px;right:auto;transform:none;}" +
-  "#wg-banner[data-pos=center]{left:50%;right:auto;transform:translateX(-50%);}" +
-  "#wg-banner[data-pos=right]{right:14px;left:auto;transform:none;}" +
-  "#wg-banner .wg-banner-tag{display:block;font-size:10px;font-weight:700;color:#c9a6ff;" +
-  "letter-spacing:.05em;text-transform:uppercase;margin-bottom:2px;}" +
+  // #wg-banner: comes from the shared bundle (ui/css/banner.css) now - not redefined here.
   "#wg-panel .wg-key{margin:8px 0;}" +
   // A live, human-readable preview of what's about to be written for this
   // MemKey - Dan: "i want pretty to exist in memkeys too... it shows what

package/dist/runner/overlay-install.js

@@ -1,6 +1,6 @@
 // Moved verbatim from the former CHAIN_RUNNER_SCRIPT template string in cli.ts (see src/ARCHITECTURE.md).
 // Runs inside the target project's own waygraph copy - keep it dependency-light and self-contained.
-import { HOST_CSS, RING_CSS, WAYGRAPH_FAVICON } from "./overlay-css.js";
+import { HOST_CSS, RUNNER_EXTRA_CSS, WAYGRAPH_FAVICON } from "./overlay-css.js";
 import { ensureShadowRoot } from "../ui/shadow.js";
 import { resolveTodoDockUi } from "../highlights.js";
 import { installCore } from "./inpage/core.js";
@@ -12,9 +12,12 @@ import { installTodos } from "./inpage/todos.js";
 import { installDevice } from "./inpage/device.js";
 import { applyVideoDeviceStage } from "./device-stage.js";
 
-export async function installOverlay(page, title) {
+/** `ui` = authored banner UX from the stub phase: { pos, collision, hidden } (all optional). */
+export async function installOverlay(page, title, ui) {
+  // ring/cursor/banner/dock come from the ONE shared bundle every surface installs (ui/css/*.css).
   await ensureShadowRoot(page);
-  await page.evaluate(([css, key]) => __wgCss(css, key), [RING_CSS, "wg-overlay-css"]).catch(() => {});
+  // Runner-only chrome (step panel, zoom/typing/device chips) - separate key, no collision.
+  await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(() => {});
   await page.addStyleTag({ content: HOST_CSS }).catch(() => {});
   // Default top-left; override with WAYGRAPH_TITLE_POS=left|center|right.
   // Click cycles left -> center -> right (persisted in localStorage so a
@@ -25,7 +28,7 @@ export async function installOverlay(page, title) {
   const todoPos = envTodoPos === "right" ? "right" : "left";
   const envAutoplay = process.env.WAYGRAPH_AUTOPLAY === "1";
   const todoDockUi = resolveTodoDockUi();
-  const args = { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay, todoDockUi };
+  const args = { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay, todoDockUi, bannerUi: ui || null };
   await page.evaluate(installCore, args).catch(() => {});
   await page.evaluate(installSwipeZoom, args).catch(() => {});
   await page.evaluate(installBanner, args).catch(() => {});

package/dist/runner/overlay-present.d.ts

@@ -0,0 +1,8 @@
+import type { Page } from "@playwright/test";
+import type { StubPhaseResult } from "../highlights/types.js";
+
+export interface SessionOverlay {
+  present(tag: string, phase: Partial<StubPhaseResult>): Promise<void>;
+  restore(): Promise<void>;
+}
+export function createSessionOverlay(page: Page, surface: string): SessionOverlay;

package/dist/runner/overlay-present.js

@@ -0,0 +1,57 @@
+// Presents a resolved stub phase ("waygraph overlay fixtures": ctx.todos / device / title / banner ...) on a LIVE page
+// for the session surfaces (auto / browser / pilot). Same OverlayStage + same in-page installers + same verbose log
+// lines as `waygraph demo`, so an overlay fixture behaves identically on every surface. Rings are painted separately
+// (pilot holds them; demo cycles them) - that is the only intended difference.
+import { installOverlay } from "./overlay-install.js";
+import { createOverlayStage } from "./overlay-stage.js";
+import { demoLog, logStubPhaseFixtures, logTodoDockFull, setDemoLogSurface, summarizeDevice } from "./demo-log.js";
+import { logBannerDom, probeBanner } from "./banner-log.js";
+import { probeTodoDocksOnPage } from "./todo-dock.js";
+
+export function createSessionOverlay(page, surface) {
+  setDemoLogSurface(surface);
+  const stage = createOverlayStage(page, { todoDockRef: { current: undefined }, deviceRef: { current: undefined } });
+  let title = undefined;
+  let painted = false;
+
+  const paintChrome = async (phaseParallel) => {
+    await installOverlay(page, title, stage.state.lastBannerUi);
+    await stage.syncAllTodoDocks({ parallel: !!phaseParallel });
+  };
+
+  return {
+    stage,
+    /** Apply one phase (tag = before | after | error | highlight) and log the resulting overlay state. */
+    async present(tag, phase) {
+      setDemoLogSurface(surface);
+      logStubPhaseFixtures(tag, phase);
+      await stage.pushTodoDockUi(phase.todoDockUi);
+      const { appliedTodo, appliedDevice } = await stage.applyPhase(phase, { reapplyDeviceOnKeep: true });
+      if (phase.title && String(phase.title).trim()) title = String(phase.title).trim();
+      const wantsChrome = !!(title || stage.state.lastTodoDock || phase.todoSync === "set");
+      if (wantsChrome) {
+        painted = true;
+        await paintChrome(phase.todoParallel);
+      }
+      logTodoDockFull(stage.state.lastTodoDock, "  " + tag);
+      demoLog("  " + tag + " device=" + summarizeDevice(stage.state.lastDevice) + " deviceSync=" + appliedDevice.sync);
+      demoLog("  " + tag + " todoSync=" + appliedTodo.sync);
+      const docks = await probeTodoDocksOnPage(page);
+      if (!docks.length && stage.state.lastTodoDock && appliedTodo.sync !== "clear") {
+        demoLog("  WARN " + tag + ": todos authored but dock-dom empty (not painted?)");
+      }
+      for (const d of docks) {
+        demoLog(
+          "  " + tag + " dock-dom " + d.key + "@" + d.pos + " " + d.left + "," + d.top + " " + d.w + "x" + d.h +
+            (d.onScreen ? "" : " OFFSCREEN") + " n=" + d.n + (d.current ? ' cur="' + d.current + '"' : ""),
+        );
+      }
+      if (title || painted) logBannerDom(tag, await probeBanner(page));
+    },
+    /** A navigation wipes the overlay DOM: rebuild what was authored (same job as the demo's post-navigation restore). */
+    async restore() {
+      if (!painted) return;
+      await paintChrome(false);
+    },
+  };
+}

package/dist/runner/overlay-stage.js

@@ -0,0 +1,105 @@
+// The waygraph OVERLAY stage: one owner of overlay state (todo docks, device, banner UX) and of how a resolved
+// stub phase is applied to the page. demo / auto / browser / pilot all go through this, so a "waygraph overlay
+// fixture" (ctx.todos / ctx.device / ctx.title / ...) means the same thing on every surface.
+// NOT Playwright test fixtures - these paint the waygraph overlay on the page under test.
+import { applyDevicePhase, applyTodoPhase, resolveTodoDockUi } from "../highlights.js";
+import { applyDeviceToPage } from "./device-stage.js";
+import { bannerUiFromPhase } from "./banner-log.js";
+
+export function createOverlayStage(page, { todoDockRef, deviceRef }) {
+  /** Carried across steps: omitting a fixture in a later phase = keep (todos, device, banner UX). */
+  const state = { lastTodoDock: undefined, lastDevice: undefined, lastBannerUi: {} };
+  /** Author todoDockUi patches (merged); resolved against env each step. */
+  let lastTodoDockUiPatch = undefined;
+  /** Multi-todo: every dock keyed by todoId (or "_default"), survives navigation. */
+  const todoDockById = new Map();
+
+  const pushTodoDockUi = async (patch) => {
+    if (patch && typeof patch === "object") {
+      lastTodoDockUiPatch = { ...(lastTodoDockUiPatch || {}), ...patch };
+    }
+    const ui = resolveTodoDockUi(lastTodoDockUiPatch);
+    await page
+      .evaluate((u) => {
+        window.__wgTodoDockUi = u;
+      }, ui)
+      .catch(() => {});
+  };
+  const dockRegistryKey = (dock) =>
+    dock && dock.id && String(dock.id).trim() ? String(dock.id).trim() : "_default";
+  const rememberTodoDock = (dock, sync, parallel) => {
+    if (sync === "clear") {
+      todoDockById.clear();
+      return;
+    }
+    if (sync === "set" && dock) {
+      if (!parallel) todoDockById.clear();
+      todoDockById.set(dockRegistryKey(dock), dock);
+      return;
+    }
+    // keep: refresh / re-seed so syncAllTodoDocks never sees an empty map
+    // while lastTodoDock still carries (nav wipe + mid-act advance).
+    if (sync === "keep" && dock) {
+      todoDockById.set(dockRegistryKey(dock), dock);
+    }
+  };
+  const syncAllTodoDocks = async (opts) => {
+    const docks = [...todoDockById.values()];
+    const parallel = !!(opts && opts.parallel);
+    if (!docks.length) {
+      // Empty registry: do NOT clear the DOM. renderBefore/After may have
+      // just painted from lastTodoDock (keep). Clearing here made todos
+      // vanish until the next ctx.todos() set (PIA #15).
+      return;
+    }
+    await page
+      .evaluate(
+        ({ list, parallel }) => {
+          if (!window.__wgSyncTodos) return;
+          for (let i = 0; i < list.length; i++) {
+            const d = list[i];
+            window.__wgSyncTodos({
+              sync: "set",
+              dock: d,
+              todoId: (d && d.id) || null,
+              pos: (d && d.pos) || null,
+              // First dock replaces; later ones keep siblings when parallel.
+              replace: !(parallel && i > 0),
+              parallel: parallel && i > 0,
+            });
+          }
+        },
+        { list: docks, parallel },
+      )
+      .catch(() => {});
+  };
+
+  /**
+   * Merge one resolved stub phase (banner UX, todo dock, device) into the carried state and push it to the page.
+   * `reapplyDeviceOnKeep`: also re-apply the carried device when the phase says keep (after a navigation wipe).
+   */
+  const applyPhase = async (phase, { reapplyDeviceOnKeep = false } = {}) => {
+    state.lastBannerUi = { ...state.lastBannerUi, ...bannerUiFromPhase(phase) };
+    const appliedTodo = applyTodoPhase(state.lastTodoDock, {
+      todoSync: phase.todoSync,
+      todoDock: phase.todoDock,
+      todos: phase.todos,
+      todoPos: phase.todoPos,
+    });
+    state.lastTodoDock = appliedTodo.dock;
+    todoDockRef.current = state.lastTodoDock;
+    rememberTodoDock(appliedTodo.dock, appliedTodo.sync, !!phase.todoParallel);
+    const appliedDevice = applyDevicePhase(state.lastDevice, {
+      deviceSync: phase.deviceSync,
+      device: phase.device,
+    });
+    state.lastDevice = appliedDevice.device;
+    deviceRef.current = state.lastDevice;
+    if (appliedDevice.sync !== "keep" || (reapplyDeviceOnKeep && state.lastDevice)) {
+      await applyDeviceToPage(page, state.lastDevice, appliedDevice.sync);
+    }
+    return { appliedTodo, appliedDevice };
+  };
+
+  return { state, pushTodoDockUi, rememberTodoDock, syncAllTodoDocks, applyPhase };
+}

package/dist/runner/step-mode.js

@@ -1,12 +1,13 @@
 // Moved verbatim from the former CHAIN_RUNNER_SCRIPT template string in cli.ts (see src/ARCHITECTURE.md).
 // Runs inside the target project's own waygraph copy - keep it dependency-light and self-contained.
 import { instrumentInteractionHighlighting } from "./interaction-patch.js";
-import { applyDevicePhase, applyHighlightStyleDefaults, applyTodoPhase, demoPaceGateMs, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, formatHighlightCaption, hasAuthoredStubAfter, resolveSlides, resolveStepDemoPace, resolveTodoDockUi, runStubPhase } from "../highlights.js";
+import { applyHighlightStyleDefaults, demoPaceGateMs, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, formatHighlightCaption, hasAuthoredStubAfter, resolveSlides, resolveStepDemoPace, resolveTodoDockUi, runStubPhase } from "../highlights.js";
 import { markStepRunning, resetPageState, teardownOverlay } from "./teardown.js";
 import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
-import { applyDeviceToPage } from "./device-stage.js";
 import { extractVerifyHighlights, presentFailPanel, renderAfterStep, renderBeforeStep } from "./step-panels.js";
 import { probeTodoDocksOnPage } from "./todo-dock.js";
+import { logBannerDom, probeBanner } from "./banner-log.js";
+import { createOverlayStage } from "./overlay-stage.js";
 import { join } from "node:path";
 import { presentSlides } from "./slides.js";
 
@@ -26,9 +27,9 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
   const stepperMode = process.env.WAYGRAPH_STEPPER === "full" ? "full" : "carousel";
   const pacing = { gatesFast: demoFast, gatesSlow: false, skipTheater: false, demoPace: "normal" };
   const stubBeforeRef = { current: [] };
-  /** Live todo dock for Method fill/click advance (same carry as lastTodoDock). */
+  /** Live todo dock for Method fill/click advance (same carry as stage.state.lastTodoDock). */
   const todoDockRef = { current: undefined };
-  /** Live device fixture for touch theater (same carry as lastDevice). */
+  /** Live device fixture for touch theater (same carry as stage.state.lastDevice). */
   const deviceRef = { current: undefined };
   instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef, todoDockRef, deviceRef);
   // Force the panel checkbox from this process's flags/env at run start.
@@ -158,73 +159,8 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
   }
 
   let result;
-  /** Carry floating todo dock across steps (empty stubBefore must not wipe). */
-  let lastTodoDock = undefined;
-  /** Author todoDockUi patches (merged); resolved against env each step. */
-  let lastTodoDockUiPatch = undefined;
-  /** Multi-todo: every dock keyed by todoId (or "_default"), survives navigation. */
-  const todoDockById = new Map();
-  const pushTodoDockUi = async (patch) => {
-    if (patch && typeof patch === "object") {
-      lastTodoDockUiPatch = { ...(lastTodoDockUiPatch || {}), ...patch };
-    }
-    const ui = resolveTodoDockUi(lastTodoDockUiPatch);
-    await page
-      .evaluate((u) => {
-        window.__wgTodoDockUi = u;
-      }, ui)
-      .catch(() => {});
-  };
-  const dockRegistryKey = (dock) =>
-    dock && dock.id && String(dock.id).trim() ? String(dock.id).trim() : "_default";
-  const rememberTodoDock = (dock, sync, parallel) => {
-    if (sync === "clear") {
-      todoDockById.clear();
-      return;
-    }
-    if (sync === "set" && dock) {
-      if (!parallel) todoDockById.clear();
-      todoDockById.set(dockRegistryKey(dock), dock);
-      return;
-    }
-    // keep: refresh / re-seed so syncAllTodoDocks never sees an empty map
-    // while lastTodoDock still carries (nav wipe + mid-act advance).
-    if (sync === "keep" && dock) {
-      todoDockById.set(dockRegistryKey(dock), dock);
-    }
-  };
-  const syncAllTodoDocks = async (opts) => {
-    const docks = [...todoDockById.values()];
-    const parallel = !!(opts && opts.parallel);
-    if (!docks.length) {
-      // Empty registry: do NOT clear the DOM. renderBefore/After may have
-      // just painted from lastTodoDock (keep). Clearing here made todos
-      // vanish until the next ctx.todos() set (PIA #15).
-      return;
-    }
-    await page
-      .evaluate(
-        ({ list, parallel }) => {
-          if (!window.__wgSyncTodos) return;
-          for (let i = 0; i < list.length; i++) {
-            const d = list[i];
-            window.__wgSyncTodos({
-              sync: "set",
-              dock: d,
-              todoId: (d && d.id) || null,
-              pos: (d && d.pos) || null,
-              // First dock replaces; later ones keep siblings when parallel.
-              replace: !(parallel && i > 0),
-              parallel: parallel && i > 0,
-            });
-          }
-        },
-        { list: docks, parallel },
-      )
-      .catch(() => {});
-  };
-  /** Carry device / touch fixture across steps (omit = keep, like todos). */
-  let lastDevice = undefined;
+  const stage = createOverlayStage(page, { todoDockRef, deviceRef });
+  const { pushTodoDockUi, rememberTodoDock, syncAllTodoDocks } = stage;
   for (let i = 0; i < resolved.length; i++) {
     const r = resolved[i];
     // The block breadcrumb is scoped to THIS step's own episode, not the
@@ -322,26 +258,12 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
         label: formatHighlightCaption(h),
       })),
     });
-    const appliedBefore = applyTodoPhase(lastTodoDock, {
-      todoSync: stubBeforePhase.todoSync,
-      todoDock: stubBeforePhase.todoDock,
-      todos: stubBeforePhase.todos,
-      todoPos: stubBeforePhase.todoPos,
-    });
-    lastTodoDock = appliedBefore.dock;
-    todoDockRef.current = lastTodoDock;
-    rememberTodoDock(appliedBefore.dock, appliedBefore.sync, !!stubBeforePhase.todoParallel);
-    const appliedDeviceBefore = applyDevicePhase(lastDevice, {
-      deviceSync: stubBeforePhase.deviceSync,
-      device: stubBeforePhase.device,
-    });
-    lastDevice = appliedDeviceBefore.device;
-    deviceRef.current = lastDevice;
-    if (appliedDeviceBefore.sync !== "keep" || lastDevice) {
-      await applyDeviceToPage(page, lastDevice, appliedDeviceBefore.sync);
-    }
+    const { appliedTodo: appliedBefore, appliedDevice: appliedDeviceBefore } = await stage.applyPhase(
+      stubBeforePhase,
+      { reapplyDeviceOnKeep: true },
+    );
     const stubBeforeTodos =
-      (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
+      (stage.state.lastTodoDock && stage.state.lastTodoDock.groups[0] && stage.state.lastTodoDock.groups[0].items) ||
       stubBeforePhase.todos ||
       [];
     const overlayTitle =
@@ -350,7 +272,7 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       title ||
       "waygraph demo";
     const overlayTodoPos =
-      (lastTodoDock && lastTodoDock.pos) || stubBeforePhase.todoPos || undefined;
+      (stage.state.lastTodoDock && stage.state.lastTodoDock.pos) || stubBeforePhase.todoPos || undefined;
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
     // Video / --mini: compact pill. Never pass false - Hide/localStorage wins.
@@ -391,7 +313,7 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
           " gatesFast=" +
           !!pacing.gatesFast,
       );
-      demoLog("  " + summarizeDevice(lastDevice));
+      demoLog("  " + summarizeDevice(stage.state.lastDevice));
       const phaseZoom =
         stubBeforePhase.zoom != null && Number(stubBeforePhase.zoom) > 0
           ? Number(stubBeforePhase.zoom)
@@ -404,7 +326,7 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
           (phaseZoomOut != null ? " zoomOut=" + phaseZoomOut : "") +
           " (StubCtx / API; live chip top-left when ring zoom >1)",
       );
-      logTodoDockFull(lastTodoDock, "  before");
+      logTodoDockFull(stage.state.lastTodoDock, "  before");
       demoLog("  todoSync=" + appliedBefore.sync);
     }
     await renderBeforeStep(page, {
@@ -419,22 +341,23 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       allEpisodes,
       justEnteredEpisode,
       title: overlayTitle,
+      bannerUi: stage.state.lastBannerUi,
       todoPos: overlayTodoPos,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
       stepperMode,
       forceCollapsed,
       todos: stubBeforeTodos,
-      todoDock: lastTodoDock,
+      todoDock: stage.state.lastTodoDock,
       todoSync: appliedBefore.sync,
-      todoId: lastTodoDock && lastTodoDock.id,
+      todoId: stage.state.lastTodoDock && stage.state.lastTodoDock.id,
       ...paceSpeak,
     });
     // Re-paint dock(s) - renderBeforeStep syncs the active one; this enforces replace.
     await syncAllTodoDocks({ parallel: !!stubBeforePhase.todoParallel });
     if (process.env.WAYGRAPH_JSON !== "1") {
       const docks = await probeTodoDocksOnPage(page);
-      if (!docks.length && lastTodoDock) {
+      if (!docks.length && stage.state.lastTodoDock) {
         demoLog("  WARN todos authored but dock-dom empty (not painted?)");
       } else if (docks.length) {
         demoLog(
@@ -462,6 +385,7 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
         );
       }
     }
+    if (process.env.WAYGRAPH_JSON !== "1") logBannerDom("before", await probeBanner(page));
     const edits = await gate();
     for (const k of requires) {
       if (edits[k.name] !== undefined) {
@@ -554,9 +478,9 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       .catch(() => {});
     result = stepOutcome.result;
     // Mid-act Method fill/click advances live on todoDockRef - fold that
-    // back into lastTodoDock before stubAfter / next-block keep, or the
+    // back into stage.state.lastTodoDock before stubAfter / next-block keep, or the
     // next step reverts to the pre-act (blank / index-0) checklist.
-    if (todoDockRef.current) lastTodoDock = todoDockRef.current;
+    if (todoDockRef.current) stage.state.lastTodoDock = todoDockRef.current;
     // withExpectedFailure last block that SUCCEEDS on the intentional fail
     // branch (e.g. submit-login -> LoginPage + error banner). Still show
     // stubOnError rings + amber "expected outcome" panel - branching no
@@ -621,8 +545,8 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
     let stubAfterTodos = [];
     let afterOverlayTitle = overlayTitle;
     let afterTodoPos = overlayTodoPos;
-    let appliedAfter = { dock: lastTodoDock, sync: "keep" };
-    let appliedDeviceAfter = { device: lastDevice, sync: "keep" };
+    let appliedAfter = { dock: stage.state.lastTodoDock, sync: "keep" };
+    let appliedDeviceAfter = { device: stage.state.lastDevice, sync: "keep" };
     let afterTodoParallel = false;
     if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
       const afterPhase = await runStubPhase(r.block, "stubAfter", {
@@ -641,33 +565,16 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
         }),
       });
       afterTodoParallel = !!afterPhase.todoParallel;
-      appliedAfter = applyTodoPhase(lastTodoDock, {
-        todoSync: afterPhase.todoSync,
-        todoDock: afterPhase.todoDock,
-        todos: afterPhase.todos,
-        todoPos: afterPhase.todoPos,
-      });
-      lastTodoDock = appliedAfter.dock;
-      todoDockRef.current = lastTodoDock;
-      rememberTodoDock(appliedAfter.dock, appliedAfter.sync, afterTodoParallel);
-      appliedDeviceAfter = applyDevicePhase(lastDevice, {
-        deviceSync: afterPhase.deviceSync,
-        device: afterPhase.device,
-      });
-      lastDevice = appliedDeviceAfter.device;
-      deviceRef.current = lastDevice;
-      if (appliedDeviceAfter.sync !== "keep" || (appliedDeviceAfter.sync === "set" && lastDevice)) {
-        await applyDeviceToPage(page, lastDevice, appliedDeviceAfter.sync);
-      }
+      ({ appliedTodo: appliedAfter, appliedDevice: appliedDeviceAfter } = await stage.applyPhase(afterPhase));
       stubAfterTodos =
-        (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
+        (stage.state.lastTodoDock && stage.state.lastTodoDock.groups[0] && stage.state.lastTodoDock.groups[0].items) ||
         afterPhase.todos ||
         [];
       if (afterPhase.title && String(afterPhase.title).trim()) {
         afterOverlayTitle = String(afterPhase.title).trim();
       }
       if (afterPhase.todoPos) afterTodoPos = afterPhase.todoPos;
-      if (lastTodoDock && lastTodoDock.pos) afterTodoPos = lastTodoDock.pos;
+      if (stage.state.lastTodoDock && stage.state.lastTodoDock.pos) afterTodoPos = stage.state.lastTodoDock.pos;
       highlights = afterPhase.highlights.map((h) => {
         const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
         return {
@@ -707,14 +614,15 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       moduleIndex,
       allEpisodes,
       title: afterOverlayTitle,
+      bannerUi: stage.state.lastBannerUi,
       todoPos: afterTodoPos,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
       stepperMode,
       todos: stubAfterTodos,
-      todoDock: lastTodoDock,
+      todoDock: stage.state.lastTodoDock,
       todoSync: appliedAfter.sync,
-      todoId: lastTodoDock && lastTodoDock.id,
+      todoId: stage.state.lastTodoDock && stage.state.lastTodoDock.id,
       todoDockRef,
       forceCollapsed:
         !!process.env.WAYGRAPH_VIDEO ||
@@ -726,20 +634,20 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
     await syncAllTodoDocks({ parallel: afterTodoParallel });
     // Ring cycle / stubAfter may have advanced the dock - persist for next block.
     if (todoDockRef.current) {
-      lastTodoDock = todoDockRef.current;
+      stage.state.lastTodoDock = todoDockRef.current;
       rememberTodoDock(todoDockRef.current, "set", afterTodoParallel);
     }
     if (process.env.WAYGRAPH_JSON !== "1") {
       demoLog(
         "  after " +
-          summarizeDevice(lastDevice) +
+          summarizeDevice(stage.state.lastDevice) +
           " deviceSync=" +
           appliedDeviceAfter.sync,
       );
-      logTodoDockFull(lastTodoDock, "  after");
+      logTodoDockFull(stage.state.lastTodoDock, "  after");
       demoLog("  after todoSync=" + appliedAfter.sync);
       const docksAfter = await probeTodoDocksOnPage(page);
-      if (!docksAfter.length && lastTodoDock && appliedAfter.sync !== "clear") {
+      if (!docksAfter.length && stage.state.lastTodoDock && appliedAfter.sync !== "clear") {
         demoLog("  WARN after: todos authored but dock-dom empty");
       } else if (docksAfter.length) {
         demoLog(
@@ -769,6 +677,7 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
         demoLog("  after dock-dom cleared (expected)");
       }
     }
+    if (process.env.WAYGRAPH_JSON !== "1") logBannerDom("after", await probeBanner(page));
     await gate();
   }
   await teardownOverlay(page);