waygraph 0.15.27 → 0.15.29

package/dist/highlights/css.js

@@ -1,3 +1,4 @@
+import { ringCss } from "../ui/components/ring.js";
 // Split out of the former 2,100-line highlights.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 /**
  * The `#wg-ring` / `#wg-ring-label` CSS (tone/size/weight variants) - the
@@ -12,47 +13,4 @@
  * renders them belongs alongside it for the same reason. `cli.ts` imports
  * this constant instead of keeping its own duplicate copy.
  */
-export const WAYGRAPH_RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
-    "border:2.5px solid #7C3AED;border-radius:10px;" +
-    // Opacity fade only - NEVER transition border-color/box-shadow. Tone swaps
-    // (auto gray -> planned purple -> warning yellow) must snap instantly;
-    // color transitions read as a muddy gray/purple/yellow morph on ring 2+.
-    "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease;}" +
-    // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
-    // Automation (verify fallback, unmatched fill/click) = gray - operators
-    // can ignore engine checks and watch purple + semantic tones.
-    "#wg-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}" +
-    "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
-    "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
-    "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
-    "#wg-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}" +
-    "#wg-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.22);}" +
-    // Real, direct user request: a visible color distinction between a real
-    // Playwright-driven action (auto gray, unchanged) and a pure DOM
-    // inspection (this - orange).
-    "#wg-ring[data-tone=orange]{border-color:#F97316;box-shadow:0 0 0 4px rgba(249,115,22,.22);}" +
-    // A real element, not a ::after pseudo-element - a pseudo-element's
-    // position is CSS-relative to the ring's own box (left:0 always meant
-    // "the ring's own left edge"), so it had no way to be clamped back onto
-    // screen when that box sat near a viewport edge - the label's text just
-    // ran off, invisibly, with no overflow guard at all. A real sibling can
-    // be measured (its actual rendered width) and repositioned in JS -
-    // pushed back onto screen, same width, never shrunk. See
-    // window.__wgPositionRing in cli.ts's own installOverlay.
-    "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
-    "max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:#7C3AED;color:#fff;" +
-    "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
-    "#wg-ring-label[data-tone=planned]{background:#7C3AED;color:#fff;}" +
-    "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
-    "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
-    "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
-    "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
-    "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
-    "#wg-ring-label[data-tone=orange]{background:#EA580C;color:#fff;}" +
-    // size: ring pad + label font; weight: label boldness
-    "#wg-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}" +
-    "#wg-ring[data-size=lg]{border-width:4px;border-radius:12px;}" +
-    "#wg-ring-label[data-size=sm]{font-size:10px;line-height:1.25;padding:4px 7px;border-radius:5px;}" +
-    "#wg-ring-label[data-size=lg]{font-size:16px;line-height:1.35;padding:8px 14px;border-radius:9px;max-width:min(480px,85vw);}" +
-    "#wg-ring-label[data-weight=bold]{font-weight:800;}" +
-    "#wg-ring-label[data-weight=normal]{font-weight:600;}";
+export const WAYGRAPH_RING_CSS = ringCss();

package/dist/pilot-overlay.d.ts

@@ -1,21 +1,3 @@
-/**
- * A small, self-contained on-page indicator for a live AutoSession -
- * "this browser is being driven by Waygraph," plus an expandable panel
- * showing the session's own current live menu. Real, direct user request:
- * a headful Pilot session looks like an ordinary browser tab with no
- * indication anything is driving it, which matters once a human might be
- * co-driving the same visible session (see `AutoSession.resync()`'s own
- * doc comment for the related state-desync problem that scenario causes).
- *
- * Deliberately NOT built on `src/cli.ts`'s own demo-panel/banner overlay
- * system, for the same reason `pilot-v1`'s narrate-mode ring renderer
- * wasn't either (see the git history at tag
- * `waygraph-pilot-v1-logs-prettified`): `cli.ts` runs `main().catch(...)`
- * unconditionally at module load with no `import.meta.url` guard, so
- * importing anything from it here would trigger the whole CLI's argument
- * dispatch as a side effect of loading a library module - unsafe. This
- * ships its own small, purpose-built badge + panel instead.
- */
 import type { BrowserContext, Page } from "@playwright/test";
 import type { SessionSnapshot } from "./auto-session.js";
 import { type HighlightTone, type DevicePreset, type DeviceState, type TodoDockUiOpts } from "./highlights.js";

package/dist/pilot-overlay.js

@@ -1,3 +1,23 @@
+/**
+ * A small, self-contained on-page indicator for a live AutoSession -
+ * "this browser is being driven by Waygraph," plus an expandable panel
+ * showing the session's own current live menu. Real, direct user request:
+ * a headful Pilot session looks like an ordinary browser tab with no
+ * indication anything is driving it, which matters once a human might be
+ * co-driving the same visible session (see `AutoSession.resync()`'s own
+ * doc comment for the related state-desync problem that scenario causes).
+ *
+ * Deliberately NOT built on `src/cli.ts`'s own demo-panel/banner overlay
+ * system, for the same reason `pilot-v1`'s narrate-mode ring renderer
+ * wasn't either (see the git history at tag
+ * `waygraph-pilot-v1-logs-prettified`): `cli.ts` runs `main().catch(...)`
+ * unconditionally at module load with no `import.meta.url` guard, so
+ * importing anything from it here would trigger the whole CLI's argument
+ * dispatch as a side effect of loading a library module - unsafe. This
+ * ships its own small, purpose-built badge + panel instead.
+ */
+import { pilotFxRingCss } from "./ui/components/ring.js";
+import { SURFACE } from "./ui/tokens.js";
 import { WAYGRAPH_RING_CSS, normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, formatHighlightCaption, resolveDeviceState, resolveTodoDockUi, } from "./highlights.js";
 // Real, direct user request: this overlay's own colors were an improvised
 // purple/white scheme (#a78bfa / #1a1033) that didn't match anything else -
@@ -22,7 +42,7 @@ const OVERLAY_CSS = `
 }
 #wg-pilot-panel {
   display: none; margin-top: 6px; max-width: 420px; max-height: 320px;
-  overflow-y: auto; background: rgba(20,10,40,.94); color: #fff; border-radius: 8px;
+  overflow-y: auto; background: ${SURFACE}; color: #fff; border-radius: 8px;
   box-shadow: 0 2px 8px rgba(0,0,0,0.25); padding: 8px 10px;
 }
 /* The graph tab renders a real Mermaid flowchart, which needs more room than
@@ -55,42 +75,17 @@ const OVERLAY_CSS = `
 #wg-pilot-activity {
   position: fixed; z-index: 2147483000; bottom: 12px; left: 12px;
   font: 12px/1.4 ui-monospace, "SF Mono", Consolas, monospace;
-  background: rgba(20,10,40,.94); color: #fff; padding: 6px 10px; border-radius: 8px;
+  background: ${SURFACE}; color: #fff; padding: 6px 10px; border-radius: 8px;
   box-shadow: 0 2px 8px rgba(0,0,0,0.25); white-space: nowrap; pointer-events: none;
   opacity: 0; transform: translateY(4px); transition: opacity 0.15s, transform 0.15s;
 }
 #wg-pilot-activity.wg-pilot-toast-show { opacity: 1; transform: translateY(0); }
-/* Agent-sent fixture rings share tone/size CSS with #wg-ring (demo language). */
-.wg-pilot-fx-ring{position:fixed;z-index:2147483645;pointer-events:none;opacity:0;
-  border:3px solid #7C3AED;border-radius:10px;box-sizing:border-box;
-  transition:opacity .12s ease,left .12s,top .12s,width .12s,height .12s;}
-.wg-pilot-fx-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}
-.wg-pilot-fx-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}
-.wg-pilot-fx-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}
-.wg-pilot-fx-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}
-.wg-pilot-fx-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}
-.wg-pilot-fx-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.22);}
-.wg-pilot-fx-ring[data-tone=orange]{border-color:#F97316;box-shadow:0 0 0 4px rgba(249,115,22,.22);}
-.wg-pilot-fx-label{position:fixed;z-index:2147483645;pointer-events:none;opacity:0;
-  font:600 12px/1.3 ui-sans-serif,system-ui,sans-serif;padding:5px 9px;border-radius:6px;
-  max-width:min(360px,80vw);box-shadow:0 2px 8px rgba(0,0,0,.25);white-space:nowrap;
-  overflow:hidden;text-overflow:ellipsis;transition:opacity .12s ease;}
-.wg-pilot-fx-label[data-tone=planned]{background:#7C3AED;color:#fff;}
-.wg-pilot-fx-label[data-tone=auto]{background:#6B7280;color:#fff;}
-.wg-pilot-fx-label[data-tone=info]{background:#2563EB;color:#fff;}
-.wg-pilot-fx-label[data-tone=warning]{background:#EAB308;color:#1c1917;}
-.wg-pilot-fx-label[data-tone=danger]{background:#DC2626;color:#fff;}
-.wg-pilot-fx-label[data-tone=success]{background:#16A34A;color:#fff;}
-.wg-pilot-fx-label[data-tone=orange]{background:#EA580C;color:#fff;}
-.wg-pilot-fx-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}
-.wg-pilot-fx-ring[data-size=lg]{border-width:4px;border-radius:12px;}
-.wg-pilot-fx-label[data-size=sm]{font-size:10px;padding:4px 7px;}
-.wg-pilot-fx-label[data-size=lg]{font-size:16px;padding:8px 14px;}
-.wg-pilot-fx-label[data-weight=bold]{font-weight:800;}
+/* Agent-sent fixture rings: generated from ui/tokens (tones shared with #wg-ring). */
+${pilotFxRingCss()}
 #wg-pilot-fx-todos{
   position:fixed;z-index:2147483645;top:72px;max-width:280px;max-height:calc(100vh - 100px);overflow:auto;
   font:12px/1.4 ui-sans-serif,system-ui,sans-serif;color:#fff;
-  background:rgba(20,10,40,.94);border-radius:10px;padding:10px 12px;
+  background:${SURFACE};border-radius:10px;padding:10px 12px;
   box-shadow:0 2px 10px rgba(0,0,0,.3);pointer-events:auto;
   transition:opacity .25s ease;
 }
@@ -113,7 +108,7 @@ const OVERLAY_CSS = `
 /* Zoom HUD (demo parity - badge only; no CSS scale of the page). */
 #wg-pilot-fx-zoom{position:fixed;z-index:2147483646;bottom:14px;right:14px;
   display:flex;align-items:center;gap:7px;padding:6px 11px 6px 8px;
-  border-radius:999px;background:rgba(20,10,40,.94);color:#f0e8ff;
+  border-radius:999px;background:${SURFACE};color:#f0e8ff;
   border:1px solid rgba(250,204,21,.6);box-shadow:0 6px 18px rgba(0,0,0,.4);
   font:700 12px/1.2 system-ui,sans-serif;pointer-events:none;}
 #wg-pilot-fx-zoom .wg-pilot-fx-zoom-ico{width:18px;height:18px;display:flex;align-items:center;justify-content:center;
@@ -122,7 +117,7 @@ const OVERLAY_CSS = `
 #wg-pilot-fx-zoom .wg-pilot-fx-zoom-val{color:#fde68a;font-variant-numeric:tabular-nums;font-weight:800;min-width:3.2em;}
 #wg-pilot-fx-zoom[data-zoomed="1"]{border-color:#fbbf24;}
 #wg-pilot-fx-device{position:fixed;z-index:2147483646;top:14px;right:14px;
-  padding:8px 12px;border-radius:10px;background:rgba(20,10,40,.94);color:#f0e8ff;
+  padding:8px 12px;border-radius:10px;background:${SURFACE};color:#f0e8ff;
   border:1px solid rgba(124,58,237,.55);font:700 12px/1.2 system-ui,sans-serif;
   pointer-events:none;box-shadow:0 6px 18px rgba(0,0,0,.35);}
 #wg-pilot-fx-device[data-preset=mobile]{border-color:#3B82F6;}

package/dist/runner/inpage/banner.js

@@ -0,0 +1,68 @@
+// 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 }) {
+        const POSITIONS = ["left", "center", "right"];
+        const applyPos = (el, pos) => {
+          el.dataset.pos = pos;
+          try {
+            localStorage.setItem("wg-banner-pos", pos);
+          } catch {
+            /* private mode / blocked storage - position still applies this page */
+          }
+        };
+        if (title) {
+          let banner = document.getElementById("wg-banner");
+          if (!banner) {
+            banner = document.createElement("div");
+            banner.id = "wg-banner";
+            let saved = null;
+            try {
+              saved = localStorage.getItem("wg-banner-pos");
+            } catch {
+              /* ignore */
+            }
+            const startPos =
+              saved && POSITIONS.includes(saved) ? saved : bannerPos;
+            applyPos(banner, startPos);
+            banner.title = "Click to move: top left / center / right";
+            banner.addEventListener("click", (e) => {
+              e.stopPropagation();
+              const i = POSITIONS.indexOf(banner.dataset.pos || "left");
+              applyPos(banner, POSITIONS[(i + 1) % POSITIONS.length]);
+            });
+            const tag = document.createElement("span");
+            tag.className = "wg-banner-tag";
+            tag.textContent = "waygraph demo";
+            const text = document.createElement("span");
+            text.className = "wg-banner-text";
+            text.textContent = title;
+            banner.appendChild(tag);
+            banner.appendChild(text);
+            document.documentElement.appendChild(banner);
+          } else {
+            // Fixture / episode title changes every step - update in place
+            // (banner is created once; do not leave the first step's text stuck).
+            let text = banner.querySelector(".wg-banner-text");
+            if (!text) {
+              text = document.createElement("span");
+              text.className = "wg-banner-text";
+              banner.appendChild(text);
+            }
+            text.textContent = title;
+          }
+        }
+        // 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.
+        if (!document.title.startsWith("[waygraph] ")) {
+          document.title = "[waygraph] " + document.title;
+        }
+        let iconLink = document.querySelector("link[rel~='icon']");
+        if (!iconLink) {
+          iconLink = document.createElement("link");
+          iconLink.rel = "icon";
+          document.head.appendChild(iconLink);
+        }
+        if (iconLink.href !== favicon) iconLink.href = favicon;
+}

package/dist/runner/inpage/core.js

@@ -0,0 +1,267 @@
+// 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 installCore({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+        window.__wgTodoDockUi = todoDockUi || {
+          compact: true,
+          cap: 5,
+          expandCap: 14,
+          collision: true,
+          behindRing: true,
+        };
+        // Seed the live autoplay toggle from the env default on first ever
+        // load only - a real navigation re-runs this, and re-stamping here
+        // would silently undo a human's mid-run checkbox click.
+        try {
+          if (localStorage.getItem("wg-autoplay") === null) {
+            localStorage.setItem("wg-autoplay", envAutoplay ? "1" : "0");
+          }
+        } catch {
+          /* private mode / blocked storage - falls back to manual gating */
+        }
+        if (!document.getElementById("wg-ring")) {
+          const ring = document.createElement("div");
+          ring.id = "wg-ring";
+          document.documentElement.appendChild(ring);
+        }
+        if (!document.getElementById("wg-ring-label")) {
+          const ringLabel = document.createElement("div");
+          ringLabel.id = "wg-ring-label";
+          document.documentElement.appendChild(ringLabel);
+        }
+        if (!document.getElementById("wg-cursor")) {
+          const cursor = document.createElement("div");
+          cursor.id = "wg-cursor";
+          // Dark fill + white stroke, same as help-center-clip-engine's own
+          // #clip-cursor - visible against any page background, light or
+          // dark, unlike a plain solid-white shape.
+          cursor.innerHTML =
+            "<svg viewBox='0 0 32 32' width='24' height='24'>" +
+            "<path fill='#0C0C1A' stroke='#fff' stroke-width='1.4' stroke-linejoin='round' " +
+            "d='M6 3.5l1.4 22.5 5.8-5.4 4.2 9.4 3.6-1.6-4.2-9.2H26z'/></svg>";
+          document.documentElement.appendChild(cursor);
+        }
+        if (!document.getElementById("wg-click-pulse")) {
+          const pulse = document.createElement("div");
+          pulse.id = "wg-click-pulse";
+          document.documentElement.appendChild(pulse);
+        }
+        window.__wgMoveCursorTo = (x, y, ms, instant) => {
+          const cursor = document.getElementById("wg-cursor");
+          if (!cursor) return;
+          cursor.style.setProperty("--wg-cursor-ms", (ms || 600) + "ms");
+          if (instant) {
+            const prev = cursor.style.transition;
+            cursor.style.transition = "none";
+            cursor.style.transform = "translate(" + x + "px," + y + "px)";
+            void cursor.offsetWidth;
+            cursor.style.transition = prev || "";
+          } else {
+            cursor.style.transform = "translate(" + x + "px," + y + "px)";
+          }
+          cursor.style.opacity = "1";
+        };
+        window.__wgHideCursor = () => {
+          const cursor = document.getElementById("wg-cursor");
+          if (cursor) cursor.style.opacity = "0";
+        };
+        window.__wgPositionRing = (box, label, tone, style) => {
+          const ring = document.getElementById("wg-ring");
+          const ringLabel = document.getElementById("wg-ring-label");
+          if (!ring || !ringLabel || !box) return;
+          const raw = (tone || "planned") + "";
+          const t =
+            raw === "auto" || raw === "info" || raw === "warning" || raw === "danger" || raw === "success"
+              ? raw
+              : "planned";
+          const st = style && typeof style === "object" ? style : {};
+          const sizeRaw = (st.size || "md") + "";
+          const size =
+            sizeRaw === "sm" || sizeRaw === "lg" ? sizeRaw : "md";
+          const weightRaw = (st.weight || "normal") + "";
+          const weight = weightRaw === "bold" ? "bold" : "normal";
+          ring.dataset.tone = t;
+          ringLabel.dataset.tone = t;
+          ring.dataset.size = size;
+          ringLabel.dataset.size = size;
+          ringLabel.dataset.weight = weight;
+          const pad = size === "sm" ? 3 : size === "lg" ? 10 : 6;
+          const margin = 6;
+          const vw = window.innerWidth;
+          const vh = window.innerHeight;
+          // Pin ring EXACTLY to the element - never clamp the ring away from
+          // the target (that looked "strapped on" the viewport).
+          const left = box.x - pad;
+          const top = box.y - pad;
+          const width = Math.max(4, box.width + pad * 2);
+          const height = Math.max(4, box.height + pad * 2);
+          ring.style.left = left + "px";
+          ring.style.top = top + "px";
+          ring.style.width = width + "px";
+          ring.style.height = height + "px";
+          ring.style.opacity = "1";
+          ringLabel.textContent = label || "";
+          ringLabel.style.opacity = "1";
+          const lw = ringLabel.offsetWidth;
+          const lh = ringLabel.offsetHeight;
+          let labelLeft = left;
+          let labelTop = top + height + 8;
+          if (labelTop + lh > vh - margin) labelTop = top - lh - 8;
+          if (labelTop < margin) labelTop = margin;
+          if (labelLeft + lw > vw - margin) labelLeft = Math.max(margin, vw - margin - lw);
+          if (labelLeft < margin) labelLeft = margin;
+          ringLabel.style.left = labelLeft + "px";
+          ringLabel.style.top = labelTop + "px";
+          if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(true);
+          if (window.__wgTodosAvoidRingCollision) window.__wgTodosAvoidRingCollision(box);
+        };
+        /** Dim/lower floating todo docks while a ring caption is the focus. */
+        window.__wgTodosSetBehind = (on) => {
+          const ui = window.__wgTodoDockUi || {};
+          if (ui.behindRing === false) {
+            document.querySelectorAll(".wg-todo-dock, #wg-todo-dock").forEach((el) => {
+              el.classList.remove("wg-todo-behind");
+            });
+            return;
+          }
+          document.querySelectorAll(".wg-todo-dock, #wg-todo-dock").forEach((el) => {
+            el.classList.toggle("wg-todo-behind", !!on);
+          });
+        };
+        /**
+         * If the active ring box intersects a todo dock, flip L/R once.
+         * Locked until hideRing so follow-rAF does not thrash.
+         */
+        window.__wgTodosAvoidRingCollision = (box) => {
+          const ui = window.__wgTodoDockUi || {};
+          if (ui.collision === false) return;
+          if (!box || window.__wgTodoCollisionLocked) return;
+          const pad = 10;
+          const rx1 = box.x - pad;
+          const ry1 = box.y - pad;
+          const rx2 = box.x + box.width + pad;
+          const ry2 = box.y + box.height + pad;
+          const overlaps = (el) => {
+            const r = el.getBoundingClientRect();
+            return !(r.right < rx1 || r.left > rx2 || r.bottom < ry1 || r.top > ry2);
+          };
+          const docks = [...document.querySelectorAll(".wg-todo-dock, #wg-todo-dock")].filter(
+            (el, i, arr) => arr.indexOf(el) === i,
+          );
+          for (const dock of docks) {
+            if (!overlaps(dock)) continue;
+            const cur = dock.dataset.pos === "right" ? "right" : "left";
+            dock.dataset.pos = cur === "right" ? "left" : "right";
+            try {
+              localStorage.setItem("wg-todo-pos", dock.dataset.pos);
+            } catch {
+              /* ignore */
+            }
+            // Still colliding after flip - tuck (shorter max-height).
+            if (overlaps(dock)) dock.dataset.tucked = "1";
+            else delete dock.dataset.tucked;
+            window.__wgTodoCollisionLocked = true;
+            break;
+          }
+        };
+        /** Live-follow a selector with rAF (accurate under device shell scale). */
+        window.__wgStopRingFollow = () => {
+          if (window.__wgRingFollowRaf) {
+            cancelAnimationFrame(window.__wgRingFollowRaf);
+            window.__wgRingFollowRaf = 0;
+          }
+          window.__wgRingFollowSel = "";
+        };
+        window.__wgFollowRing = (sel, label, tone, style, focus) => {
+          window.__wgStopRingFollow();
+          if (!sel) return;
+          window.__wgRingFollowSel = sel;
+          const tick = () => {
+            if (window.__wgRingFollowSel !== sel) return;
+            const el = document.querySelector(sel);
+            if (!el) {
+              window.__wgRingFollowRaf = requestAnimationFrame(tick);
+              return;
+            }
+            const r = el.getBoundingClientRect();
+            const box = { x: r.x, y: r.y, width: r.width, height: r.height };
+            if (window.__wgPositionRing) {
+              window.__wgPositionRing(box, label, tone || "planned", style || {});
+            }
+            if (focus && window.__wgApplyFocus) window.__wgApplyFocus(box);
+            window.__wgRingFollowRaf = requestAnimationFrame(tick);
+          };
+          tick();
+        };
+        window.__wgClickPulse = (x, y, tone) => {
+          const pulse = document.getElementById("wg-click-pulse");
+          if (!pulse) return;
+          const raw = (tone || "planned") + "";
+          pulse.dataset.tone =
+            raw === "auto" || raw === "info" || raw === "warning" || raw === "danger" || raw === "success"
+              ? raw
+              : "planned";
+          pulse.style.left = x + "px";
+          pulse.style.top = y + "px";
+          pulse.classList.remove("wg-pulse");
+          void pulse.offsetWidth;
+          pulse.classList.add("wg-pulse");
+        };
+        window.__wgHideRing = (opts) => {
+          // While a narrate() call owns the ring (mid multi-step action),
+          // the auto-highlight click/fill patches' own end-of-step hide is
+          // a no-op - narrate() itself clears it once the WHOLE wrapped
+          // action finishes, not just its first sub-step.
+          if (window.__wgNarrateOwnsRing) return;
+          if (window.__wgStopRingFollow) window.__wgStopRingFollow();
+          const ring = document.getElementById("wg-ring");
+          const ringLabel = document.getElementById("wg-ring-label");
+          if (ring) ring.style.opacity = "0";
+          if (ringLabel) ringLabel.style.opacity = "0";
+          if (window.__wgClearFocus) window.__wgClearFocus();
+          if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(false);
+          window.__wgTodoCollisionLocked = false;
+          document.querySelectorAll(".wg-todo-dock[data-tucked], #wg-todo-dock[data-tucked]").forEach((el) => {
+            delete el.dataset.tucked;
+          });
+          // Honor zoomOut:false - keep camera until next zoom / desktop clear.
+          const forceClear = opts && opts.clearZoom === true;
+          const skipClear = opts && opts.clearZoom === false;
+          if (
+            !skipClear &&
+            (forceClear || window.__wgZoomOutOnHide !== false) &&
+            window.__wgClearZoom
+          ) {
+            window.__wgClearZoom();
+          }
+        };
+        window.__wgClearFocus = () => {
+          const veil = document.getElementById("wg-focus-veil");
+          if (!veil) return;
+          veil.classList.remove("wg-in");
+          setTimeout(() => {
+            const v = document.getElementById("wg-focus-veil");
+            if (v && !v.classList.contains("wg-in")) v.remove();
+          }, 320);
+        };
+        window.__wgApplyFocus = (box) => {
+          if (!box) {
+            if (window.__wgClearFocus) window.__wgClearFocus();
+            return;
+          }
+          let veil = document.getElementById("wg-focus-veil");
+          if (!veil) {
+            veil = document.createElement("div");
+            veil.id = "wg-focus-veil";
+            veil.setAttribute("data-wg-ui", "1");
+            document.documentElement.appendChild(veil);
+          }
+          const pad = 10;
+          veil.style.left = Math.max(0, box.x - pad) + "px";
+          veil.style.top = Math.max(0, box.y - pad) + "px";
+          veil.style.width = Math.max(8, box.width + pad * 2) + "px";
+          veil.style.height = Math.max(8, box.height + pad * 2) + "px";
+          void veil.offsetWidth;
+          veil.classList.add("wg-in");
+        };
+}