waygraph 0.15.30 → 0.15.31

package/dist/auto-explore-run.js

@@ -1,4 +1,5 @@
 import { createInterface } from "node:readline/promises";
+import { ensureShadowRoot } from "./ui/shadow.js";
 import { stdin as input, stdout as output } from "node:process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -168,7 +169,7 @@ export async function ensureMem(entry, mem, cli) {
 async function setAutoPanelRunning(page, label) {
     await page
         .evaluate((label) => {
-        const panel = document.getElementById("wg-auto-panel");
+        const panel = __wgById("wg-auto-panel");
         if (!panel)
             return;
         const body = "<h3>waygraph auto</h3><div style='padding:12px 0;color:#c9a6ff'>" +
@@ -291,9 +292,10 @@ function memKeysForMenu(menu, library) {
 async function syncPanelMem(page, mem, keys) {
     if (keys.length === 0)
         return;
+    await ensureShadowRoot(page);
     const edits = (await page.evaluate(() => {
         const out = {};
-        document.querySelectorAll("textarea.wg-mem-input").forEach((ta) => {
+        __wgQA("textarea.wg-mem-input").forEach((ta) => {
             const key = ta.getAttribute("data-mem-key");
             if (key)
                 out[key] = ta.value;
@@ -382,14 +384,15 @@ async function headfulPick(page, menu, library, mem, waitPick) {
     html =
         `<style id="wg-auto-style">${PANEL_CSS}</style><div id="wg-auto-panel">` +
             html.slice(html.indexOf("<h3>"));
+    await ensureShadowRoot(page);
     await page.evaluate(`((inner) => {
-      let panel = document.getElementById("wg-auto-panel");
+      let panel = __wgById("wg-auto-panel");
       if (!panel) {
         panel = document.createElement("div");
-        document.documentElement.appendChild(panel);
+        __wgAdd(panel);
       }
       panel.outerHTML = inner;
-      const root = document.getElementById("wg-auto-panel");
+      const root = __wgById("wg-auto-panel");
       if (!root) return;
       window.__wgWirePanelChrome = (el, storageKey, chromeTitle) => {
         if (!el) return;
@@ -446,7 +449,7 @@ async function headfulPick(page, menu, library, mem, waitPick) {
         window.__wgOverlayBeacon =
           window.__wgOverlayBeacon ||
           (() =>
-            Array.from(document.querySelectorAll('[data-wg-ui="1"]')).map((el) => {
+            Array.from(__wgQA('[data-wg-ui="1"]')).map((el) => {
               const r = el.getBoundingClientRect();
               const st = getComputedStyle(el);
               return {

package/dist/pilot-overlay/fixtures.js

@@ -98,22 +98,22 @@ export async function showPilotFixtures(page, fixtures) {
         if (w.__wgPilotFxHideTimer)
             clearTimeout(w.__wgPilotFxHideTimer);
         const clearFocus = () => {
-            const veil = document.getElementById("wg-pilot-fx-focus");
+            const veil = __wgById("wg-pilot-fx-focus");
             if (!veil)
                 return;
             veil.classList.remove("wg-in");
             setTimeout(() => {
-                const v = document.getElementById("wg-pilot-fx-focus");
+                const v = __wgById("wg-pilot-fx-focus");
                 if (v && !v.classList.contains("wg-in"))
                     v.remove();
             }, 320);
         };
         const applyFocus = (box) => {
-            let veil = document.getElementById("wg-pilot-fx-focus");
+            let veil = __wgById("wg-pilot-fx-focus");
             if (!veil) {
                 veil = document.createElement("div");
                 veil.id = "wg-pilot-fx-focus";
-                document.documentElement.appendChild(veil);
+                __wgAdd(veil);
             }
             const pad = 10;
             veil.style.left = `${Math.max(0, box.x - pad)}px`;
@@ -125,11 +125,11 @@ export async function showPilotFixtures(page, fixtures) {
         };
         const setZoomBadge = (scale) => {
             const level = Number.isFinite(scale) && scale > 0 ? scale : 1;
-            let badge = document.getElementById("wg-pilot-fx-zoom");
+            let badge = __wgById("wg-pilot-fx-zoom");
             if (!badge) {
                 badge = document.createElement("div");
                 badge.id = "wg-pilot-fx-zoom";
-                document.documentElement.appendChild(badge);
+                __wgAdd(badge);
             }
             const zoomed = level > 1.001 || level < 0.999;
             badge.dataset.zoomed = zoomed ? "1" : "0";
@@ -143,27 +143,27 @@ export async function showPilotFixtures(page, fixtures) {
             root.style.removeProperty("transform");
             root.style.removeProperty("transform-origin");
             root.style.removeProperty("transition");
-            document.getElementById("wg-pilot-fx-zoom")?.remove();
+            __wgById("wg-pilot-fx-zoom")?.remove();
         };
         const setDeviceChip = (label) => {
-            document.getElementById("wg-pilot-fx-device")?.remove();
+            __wgById("wg-pilot-fx-device")?.remove();
             if (!label)
                 return;
             const chip = document.createElement("div");
             chip.id = "wg-pilot-fx-device";
             chip.dataset.preset = label;
             chip.textContent = `device \u00b7 ${label}`;
-            document.documentElement.appendChild(chip);
+            __wgAdd(chip);
         };
         w.__wgPilotFxZoomOutOnHide = zoomOut;
         const clearFx = () => {
-            document.querySelectorAll(".wg-pilot-fx-ring, .wg-pilot-fx-label").forEach((el) => el.remove());
-            document.getElementById("wg-pilot-fx-todos")?.remove();
+            __wgQA(".wg-pilot-fx-ring, .wg-pilot-fx-label").forEach((el) => el.remove());
+            __wgById("wg-pilot-fx-todos")?.remove();
             clearFocus();
             if (w.__wgPilotFxZoomOutOnHide !== false || clearAll)
                 clearZoom();
             if (clearAll) {
-                document.getElementById("wg-pilot-fx-device")?.remove();
+                __wgById("wg-pilot-fx-device")?.remove();
                 clearZoom();
             }
         };
@@ -206,8 +206,8 @@ export async function showPilotFixtures(page, fixtures) {
             if (ring.color) {
                 labelEl.style.color = ring.color;
             }
-            document.documentElement.appendChild(ringEl);
-            document.documentElement.appendChild(labelEl);
+            __wgAdd(ringEl);
+            __wgAdd(labelEl);
             const lw = labelEl.offsetWidth;
             const lh = labelEl.offsetHeight;
             let labelLeft = rect.left - pad;
@@ -266,18 +266,18 @@ export async function showPilotFixtures(page, fixtures) {
                 more.textContent = "+" + (todos.length - (end - start)) + " more";
                 dock.appendChild(more);
             }
-            document.documentElement.appendChild(dock);
+            __wgAdd(dock);
         }
         if (focusBox)
             applyFocus(focusBox);
         // Dim todos under rings / focus so captions stay readable.
-        const dockEl = document.getElementById("wg-pilot-fx-todos");
+        const dockEl = __wgById("wg-pilot-fx-todos");
         if (dockEl && todoUi.behindRing !== false && (painted > 0 || focusBox)) {
             dockEl.classList.add("wg-todo-behind");
         }
         // Collision flip: if a painted ring intersects the dock, flip side once.
         if (dockEl && todoUi.collision !== false && painted > 0) {
-            const firstRing = document.querySelector(".wg-pilot-fx-ring");
+            const firstRing = __wgQ(".wg-pilot-fx-ring");
             if (firstRing) {
                 const rr = firstRing.getBoundingClientRect();
                 const dr = dockEl.getBoundingClientRect();

package/dist/pilot-overlay/panel.js

@@ -10,9 +10,9 @@ export async function updatePilotOverlay(page, info) {
     await ensureInstalled(page);
     await page
         .evaluate(async ({ sessionId, snapshot, graph }) => {
-        const badge = document.getElementById("wg-pilot-badge");
-        const current = document.getElementById("wg-pilot-panel-current");
-        const graphPanel = document.getElementById("wg-pilot-panel-graph");
+        const badge = __wgById("wg-pilot-badge");
+        const current = __wgById("wg-pilot-panel-current");
+        const graphPanel = __wgById("wg-pilot-panel-graph");
         if (!badge || !current || !graphPanel)
             return;
         const idPart = sessionId ? `session ${sessionId}` : "no session id";

package/dist/pilot-overlay/shell.js

@@ -1,5 +1,6 @@
 // Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { SURFACE } from "../ui/tokens.js";
+import { ensureShadowRoot, installShadowRoot } from "../ui/shadow.js";
 import { pilotFxRingCss } from "../ui/components/ring.js";
 import { WAYGRAPH_RING_CSS } from "../highlights.js";
 // Real, direct user request: this overlay's own colors were an improvised
@@ -109,12 +110,9 @@ ${pilotFxRingCss()}
 ` + WAYGRAPH_RING_CSS;
 /** Browser-side shell install — runs on every document via context.addInitScript. */
 function installPilotOverlayShell(css) {
-    if (document.getElementById("wg-pilot-overlay"))
+    if (__wgById("wg-pilot-overlay"))
         return;
-    const style = document.createElement("style");
-    style.id = "wg-pilot-overlay-css";
-    style.textContent = css;
-    document.documentElement.appendChild(style);
+    __wgCss(css, "wg-pilot-overlay-css");
     const root = document.createElement("div");
     root.id = "wg-pilot-overlay";
     root.innerHTML =
@@ -125,36 +123,36 @@ function installPilotOverlayShell(css) {
             '<div id="wg-pilot-panel-current"></div>' +
             '<div id="wg-pilot-panel-graph" style="display:none"></div>' +
             "</div>";
-    document.documentElement.appendChild(root);
-    document.getElementById("wg-pilot-badge").addEventListener("click", () => {
-        document.getElementById("wg-pilot-panel").classList.toggle("wg-pilot-open");
+    __wgAdd(root);
+    __wgById("wg-pilot-badge").addEventListener("click", () => {
+        __wgById("wg-pilot-panel").classList.toggle("wg-pilot-open");
     });
-    document.getElementById("wg-pilot-view-current").addEventListener("click", () => {
-        document.getElementById("wg-pilot-view-current").classList.add("wg-pilot-tab-active");
-        document.getElementById("wg-pilot-view-graph").classList.remove("wg-pilot-tab-active");
-        document.getElementById("wg-pilot-panel-current").style.display = "";
-        document.getElementById("wg-pilot-panel-graph").style.display = "none";
+    __wgById("wg-pilot-view-current").addEventListener("click", () => {
+        __wgById("wg-pilot-view-current").classList.add("wg-pilot-tab-active");
+        __wgById("wg-pilot-view-graph").classList.remove("wg-pilot-tab-active");
+        __wgById("wg-pilot-panel-current").style.display = "";
+        __wgById("wg-pilot-panel-graph").style.display = "none";
     });
-    document.getElementById("wg-pilot-view-graph").addEventListener("click", () => {
-        document.getElementById("wg-pilot-view-graph").classList.add("wg-pilot-tab-active");
-        document.getElementById("wg-pilot-view-current").classList.remove("wg-pilot-tab-active");
-        document.getElementById("wg-pilot-panel-graph").style.display = "";
-        document.getElementById("wg-pilot-panel-current").style.display = "none";
+    __wgById("wg-pilot-view-graph").addEventListener("click", () => {
+        __wgById("wg-pilot-view-graph").classList.add("wg-pilot-tab-active");
+        __wgById("wg-pilot-view-current").classList.remove("wg-pilot-tab-active");
+        __wgById("wg-pilot-panel-graph").style.display = "";
+        __wgById("wg-pilot-panel-current").style.display = "none";
     });
-    if (!document.getElementById("wg-pilot-activity")) {
+    if (!__wgById("wg-pilot-activity")) {
         const toast = document.createElement("div");
         toast.id = "wg-pilot-activity";
-        document.documentElement.appendChild(toast);
+        __wgAdd(toast);
     }
-    if (!document.getElementById("wg-ring")) {
+    if (!__wgById("wg-ring")) {
         const ring = document.createElement("div");
         ring.id = "wg-ring";
-        document.documentElement.appendChild(ring);
+        __wgAdd(ring);
     }
-    if (!document.getElementById("wg-ring-label")) {
+    if (!__wgById("wg-ring-label")) {
         const ringLabel = document.createElement("div");
         ringLabel.id = "wg-ring-label";
-        document.documentElement.appendChild(ringLabel);
+        __wgAdd(ringLabel);
     }
 }
 /**
@@ -163,10 +161,12 @@ function installPilotOverlayShell(css) {
  * page is blank or replaced.
  */
 export async function installPersistentPilotOverlay(context) {
+    await context.addInitScript(installShadowRoot);
     await context.addInitScript(installPilotOverlayShell, OVERLAY_CSS);
 }
 /** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
 export async function ensureInstalled(page) {
+    await ensureShadowRoot(page);
     await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(() => { });
 }
 /**
@@ -183,7 +183,7 @@ export async function showPilotActivity(page, text) {
     await ensureInstalled(page);
     await page
         .evaluate((text) => {
-        const toast = document.getElementById("wg-pilot-activity");
+        const toast = __wgById("wg-pilot-activity");
         if (!toast)
             return;
         toast.textContent = text;
@@ -227,8 +227,8 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
     await ensureInstalled(page);
     await page
         .evaluate(({ selector, label, tone }) => {
-        const ring = document.getElementById("wg-ring");
-        const tag = document.getElementById("wg-ring-label");
+        const ring = __wgById("wg-ring");
+        const tag = __wgById("wg-ring-label");
         if (!ring || !tag)
             return;
         const w = window;

package/dist/runner/cursor.js

@@ -48,7 +48,7 @@ export async function playSwipeTrail(page, opts) {
           : "left";
       const ms = Math.max(280, Math.min(1400, Number(payload.ms) || 720));
       const label = payload.label || "swipe";
-      let layer = document.getElementById("wg-swipe-layer");
+      let layer = __wgById("wg-swipe-layer");
       if (layer) layer.remove();
       layer = document.createElement("div");
       layer.id = "wg-swipe-layer";
@@ -67,7 +67,7 @@ export async function playSwipeTrail(page, opts) {
         "border:1px solid rgba(56,189,248,.55);font:700 12px/1.2 system-ui,sans-serif;";
       layer.appendChild(lab);
       layer.appendChild(finger);
-      document.documentElement.appendChild(layer);
+      __wgAdd(layer);
       const vw = window.innerWidth || 390;
       const vh = window.innerHeight || 844;
       const pad = Math.min(vw, vh) * 0.18;
@@ -121,7 +121,7 @@ export async function playSwipeTrail(page, opts) {
           });
           if (i === steps) {
             setTimeout(() => {
-              const el = document.getElementById("wg-swipe-layer");
+              const el = __wgById("wg-swipe-layer");
               if (el) el.remove();
             }, 400);
           }

package/dist/runner/inpage/banner.js

@@ -12,7 +12,7 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
           }
         };
         if (title) {
-          let banner = document.getElementById("wg-banner");
+          let banner = __wgById("wg-banner");
           if (!banner) {
             banner = document.createElement("div");
             banner.id = "wg-banner";
@@ -39,7 +39,7 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
             text.textContent = title;
             banner.appendChild(tag);
             banner.appendChild(text);
-            document.documentElement.appendChild(banner);
+            __wgAdd(banner);
           } else {
             // Fixture / episode title changes every step - update in place
             // (banner is created once; do not leave the first step's text stuck).

package/dist/runner/inpage/core.js

@@ -19,17 +19,17 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
         } catch {
           /* private mode / blocked storage - falls back to manual gating */
         }
-        if (!document.getElementById("wg-ring")) {
+        if (!__wgById("wg-ring")) {
           const ring = document.createElement("div");
           ring.id = "wg-ring";
-          document.documentElement.appendChild(ring);
+          __wgAdd(ring);
         }
-        if (!document.getElementById("wg-ring-label")) {
+        if (!__wgById("wg-ring-label")) {
           const ringLabel = document.createElement("div");
           ringLabel.id = "wg-ring-label";
-          document.documentElement.appendChild(ringLabel);
+          __wgAdd(ringLabel);
         }
-        if (!document.getElementById("wg-cursor")) {
+        if (!__wgById("wg-cursor")) {
           const cursor = document.createElement("div");
           cursor.id = "wg-cursor";
           // Dark fill + white stroke, same as help-center-clip-engine's own
@@ -39,15 +39,15 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
             "<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);
+          __wgAdd(cursor);
         }
-        if (!document.getElementById("wg-click-pulse")) {
+        if (!__wgById("wg-click-pulse")) {
           const pulse = document.createElement("div");
           pulse.id = "wg-click-pulse";
-          document.documentElement.appendChild(pulse);
+          __wgAdd(pulse);
         }
         window.__wgMoveCursorTo = (x, y, ms, instant) => {
-          const cursor = document.getElementById("wg-cursor");
+          const cursor = __wgById("wg-cursor");
           if (!cursor) return;
           cursor.style.setProperty("--wg-cursor-ms", (ms || 600) + "ms");
           if (instant) {
@@ -62,12 +62,12 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           cursor.style.opacity = "1";
         };
         window.__wgHideCursor = () => {
-          const cursor = document.getElementById("wg-cursor");
+          const cursor = __wgById("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");
+          const ring = __wgById("wg-ring");
+          const ringLabel = __wgById("wg-ring-label");
           if (!ring || !ringLabel || !box) return;
           const raw = (tone || "planned") + "";
           const t =
@@ -119,12 +119,12 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
         window.__wgTodosSetBehind = (on) => {
           const ui = window.__wgTodoDockUi || {};
           if (ui.behindRing === false) {
-            document.querySelectorAll(".wg-todo-dock, #wg-todo-dock").forEach((el) => {
+            __wgQA(".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) => {
+          __wgQA(".wg-todo-dock, #wg-todo-dock").forEach((el) => {
             el.classList.toggle("wg-todo-behind", !!on);
           });
         };
@@ -145,7 +145,7 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
             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(
+          const docks = [...__wgQA(".wg-todo-dock, #wg-todo-dock")].filter(
             (el, i, arr) => arr.indexOf(el) === i,
           );
           for (const dock of docks) {
@@ -194,7 +194,7 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           tick();
         };
         window.__wgClickPulse = (x, y, tone) => {
-          const pulse = document.getElementById("wg-click-pulse");
+          const pulse = __wgById("wg-click-pulse");
           if (!pulse) return;
           const raw = (tone || "planned") + "";
           pulse.dataset.tone =
@@ -214,14 +214,14 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           // 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");
+          const ring = __wgById("wg-ring");
+          const ringLabel = __wgById("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) => {
+          __wgQA(".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.
@@ -236,11 +236,11 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           }
         };
         window.__wgClearFocus = () => {
-          const veil = document.getElementById("wg-focus-veil");
+          const veil = __wgById("wg-focus-veil");
           if (!veil) return;
           veil.classList.remove("wg-in");
           setTimeout(() => {
-            const v = document.getElementById("wg-focus-veil");
+            const v = __wgById("wg-focus-veil");
             if (v && !v.classList.contains("wg-in")) v.remove();
           }, 320);
         };
@@ -249,12 +249,12 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
             if (window.__wgClearFocus) window.__wgClearFocus();
             return;
           }
-          let veil = document.getElementById("wg-focus-veil");
+          let veil = __wgById("wg-focus-veil");
           if (!veil) {
             veil = document.createElement("div");
             veil.id = "wg-focus-veil";
             veil.setAttribute("data-wg-ui", "1");
-            document.documentElement.appendChild(veil);
+            __wgAdd(veil);
           }
           const pad = 10;
           veil.style.left = Math.max(0, box.x - pad) + "px";

package/dist/runner/inpage/device.js

@@ -10,7 +10,7 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
               ? payload.sync
               : "keep";
           const device = payload && payload.device ? payload.device : null;
-          const cursor = document.getElementById("wg-cursor");
+          const cursor = __wgById("wg-cursor");
           const MOUSE_SVG =
             "<svg viewBox='0 0 32 32' width='24' height='24'>" +
             "<path fill='#0C0C1A' stroke='#fff' stroke-width='1.4' stroke-linejoin='round' " +
@@ -45,12 +45,12 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
             }
           };
           const ensureChip = (preset, touch, remain, orientation) => {
-            let badge = document.getElementById("wg-device-badge");
+            let badge = __wgById("wg-device-badge");
             if (preset === "desktop" && !touch) {
               if (badge) {
                 badge.classList.remove("wg-in");
                 setTimeout(() => {
-                  const b = document.getElementById("wg-device-badge");
+                  const b = __wgById("wg-device-badge");
                   if (b) b.remove();
                 }, 320);
               }
@@ -60,7 +60,7 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
               badge = document.createElement("div");
               badge.id = "wg-device-badge";
               badge.setAttribute("data-wg-ui", "1");
-              document.documentElement.appendChild(badge);
+              __wgAdd(badge);
             }
             badge.dataset.preset = preset;
             badge.dataset.touch = touch ? "1" : "0";
@@ -85,7 +85,7 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
             badge.classList.add("wg-in");
           };
           const showToast = (preset, touch, title, sub, orientation) => {
-            let toast = document.getElementById("wg-device-toast");
+            let toast = __wgById("wg-device-toast");
             if (toast && toast._wgTimer) {
               clearTimeout(toast._wgTimer);
               toast._wgTimer = null;
@@ -94,10 +94,10 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
               toast = document.createElement("div");
               toast.id = "wg-device-toast";
               toast.setAttribute("data-wg-ui", "1");
-              document.documentElement.appendChild(toast);
+              __wgAdd(toast);
             }
             // Hide chip while toast is up (same corner).
-            const badge = document.getElementById("wg-device-badge");
+            const badge = __wgById("wg-device-badge");
             if (badge) badge.classList.remove("wg-in");
             toast.dataset.preset = preset;
             toast.innerHTML =
@@ -115,7 +115,7 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
               toast.classList.add("wg-out");
               toast.classList.remove("wg-in");
               setTimeout(() => {
-                const t = document.getElementById("wg-device-toast");
+                const t = __wgById("wg-device-toast");
                 if (t) t.remove();
                 if (preset !== "desktop" || touch) {
                   ensureChip(preset, touch, true, orientation);
@@ -142,13 +142,13 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
                 "landscape",
               );
               setTimeout(() => {
-                const badge = document.getElementById("wg-device-badge");
+                const badge = __wgById("wg-device-badge");
                 if (badge) badge.remove();
               }, 2600);
             } else {
-              const badge = document.getElementById("wg-device-badge");
+              const badge = __wgById("wg-device-badge");
               if (badge) badge.remove();
-              const toast = document.getElementById("wg-device-toast");
+              const toast = __wgById("wg-device-toast");
               if (toast) toast.remove();
             }
             window.__wgDevicePreset = "desktop";

package/dist/runner/inpage/panel-chrome.js

@@ -69,7 +69,7 @@ export function installPanelChrome({ title, favicon, bannerPos, todoPos, envAuto
             } catch {
               /* ignore */
             }
-            const runBtn = document.getElementById("wg-run");
+            const runBtn = __wgById("wg-run");
             const show = !!hidden && !auto && !!runBtn;
             miniNext.classList.toggle("wg-mini-next-show", show);
             if (runBtn) {
@@ -125,7 +125,7 @@ export function installPanelChrome({ title, favicon, bannerPos, todoPos, envAuto
             miniNext.dataset.wgWired = "1";
             miniNext.addEventListener("click", (e) => {
               e.stopPropagation();
-              const runBtn = document.getElementById("wg-run");
+              const runBtn = __wgById("wg-run");
               if (runBtn && !runBtn.disabled) {
                 runBtn.click();
                 return;
@@ -133,7 +133,7 @@ export function installPanelChrome({ title, favicon, bannerPos, todoPos, envAuto
               if (typeof window.__wgNext === "function") window.__wgNext({});
             });
           }
-          const autoCb = document.getElementById("wg-autoplay-cb");
+          const autoCb = __wgById("wg-autoplay-cb");
           if (autoCb && !autoCb.dataset.wgMiniWired) {
             autoCb.dataset.wgMiniWired = "1";
             autoCb.addEventListener("change", () => {

package/dist/runner/inpage/stamp.js

@@ -20,7 +20,7 @@ export function installStamp({ title, favicon, bannerPos, todoPos, envAutoplay,
           el.setAttribute("data-wg-ready", meta.ready === false ? "0" : "1");
         };
         window.__wgOverlayBeacon = () => {
-          return Array.from(document.querySelectorAll("[data-wg-ui=\"1\"]")).map((el) => {
+          return Array.from(__wgQA("[data-wg-ui=\"1\"]")).map((el) => {
             const r = el.getBoundingClientRect();
             const st = getComputedStyle(el);
             return {
@@ -41,6 +41,6 @@ export function installStamp({ title, favicon, bannerPos, todoPos, envAutoplay,
             };
           });
         };
-        const existingBanner = document.getElementById("wg-banner");
+        const existingBanner = __wgById("wg-banner");
         if (existingBanner) window.__wgStampModal(existingBanner, "banner", { ready: true });
 }

package/dist/runner/inpage/swipe-zoom.js

@@ -15,7 +15,7 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
             o.label ||
             (dir === "left" || dir === "right" ? "swipe" : "swipe") +
               (o.hint ? " \u00b7 " + o.hint : "");
-          let layer = document.getElementById("wg-swipe-layer");
+          let layer = __wgById("wg-swipe-layer");
           if (layer && layer._wgTimer) {
             clearTimeout(layer._wgTimer);
             layer._wgTimer = null;
@@ -31,7 +31,7 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
           lab.textContent = label;
           layer.appendChild(lab);
           layer.appendChild(finger);
-          document.documentElement.appendChild(layer);
+          __wgAdd(layer);
           const vw = window.innerWidth || 390;
           const vh = window.innerHeight || 844;
           const pad = Math.min(vw, vh) * 0.18;
@@ -89,7 +89,7 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
               finger.style.opacity = "0";
               layer.classList.remove("wg-in");
               layer._wgTimer = setTimeout(() => {
-                const el = document.getElementById("wg-swipe-layer");
+                const el = __wgById("wg-swipe-layer");
                 if (el) el.remove();
               }, 380);
             }
@@ -108,7 +108,7 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
             delete el.dataset.wgZoomed;
           });
           // Undo any prior shell-camera experiment - restore device fit scale only.
-          const shell = document.getElementById("wg-device-shell");
+          const shell = __wgById("wg-device-shell");
           if (shell && shell.dataset.wgCamBase != null) {
             shell.style.transform = shell.dataset.wgCamBase;
             if (shell.dataset.wgCamOrigin) {
@@ -130,12 +130,12 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
         window.__wgSetZoomBadge = (scale, sel) => {
           const n = Number(scale);
           const level = Number.isFinite(n) && n > 0 ? n : 1;
-          let badge = document.getElementById("wg-zoom-badge");
+          let badge = __wgById("wg-zoom-badge");
           if (!badge) {
             badge = document.createElement("div");
             badge.id = "wg-zoom-badge";
             badge.setAttribute("data-wg-ui", "1");
-            document.documentElement.appendChild(badge);
+            __wgAdd(badge);
           }
           const zoomed = level > 1.001 || level < 0.999;
           badge.dataset.zoomed = zoomed ? "1" : "0";
@@ -156,12 +156,12 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
           }
         };
         window.__wgSetTypingBadge = (on, label) => {
-          let badge = document.getElementById("wg-typing-badge");
+          let badge = __wgById("wg-typing-badge");
           if (!on) {
             if (badge) {
               badge.classList.remove("wg-in");
               setTimeout(() => {
-                const b = document.getElementById("wg-typing-badge");
+                const b = __wgById("wg-typing-badge");
                 if (b && !b.classList.contains("wg-in")) b.remove();
               }, 220);
             }
@@ -171,7 +171,7 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
             badge = document.createElement("div");
             badge.id = "wg-typing-badge";
             badge.setAttribute("data-wg-ui", "1");
-            document.documentElement.appendChild(badge);
+            __wgAdd(badge);
           }
           const text = label ? String(label).slice(0, 40) : "typing";
           badge.innerHTML =
@@ -196,7 +196,7 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
             el.style.removeProperty("position");
             delete el.dataset.wgZoomed;
           });
-          const shell = document.getElementById("wg-device-shell");
+          const shell = __wgById("wg-device-shell");
           if (shell && shell.dataset.wgCamBase != null) {
             shell.style.transform = shell.dataset.wgCamBase;
             shell.style.transformOrigin = shell.dataset.wgCamOrigin || "center center";

package/dist/runner/inpage/todos.js

@@ -43,10 +43,10 @@ export function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay,
             "_default";
 
           // Drop any in-panel leftover (old builds put #wg-todos in .wg-body).
-          document.querySelectorAll("#wg-panel #wg-todos").forEach((el) => el.remove());
+          __wgQA("#wg-panel #wg-todos").forEach((el) => el.remove());
 
           const allDocks = () =>
-            [...document.querySelectorAll(".wg-todo-dock, #wg-todo-dock")].filter(
+            [...__wgQA(".wg-todo-dock, #wg-todo-dock")].filter(
               (el, i, arr) => arr.indexOf(el) === i,
             );
           const relayoutTodoDocks = () => {
@@ -60,11 +60,11 @@ export function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay,
           const findDock = (key) => {
             if (key === "_default") {
               return (
-                document.querySelector('.wg-todo-dock[data-wg-todo-key="_default"]') ||
-                document.getElementById("wg-todo-dock")
+                __wgQ('.wg-todo-dock[data-wg-todo-key="_default"]') ||
+                __wgById("wg-todo-dock")
               );
             }
-            const all = document.querySelectorAll(".wg-todo-dock");
+            const all = __wgQA(".wg-todo-dock");
             for (let i = 0; i < all.length; i++) {
               if (all[i].getAttribute("data-wg-todo-key") === String(key)) return all[i];
             }
@@ -141,7 +141,7 @@ export function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay,
                 /* ignore */
               }
             });
-            document.documentElement.appendChild(dock);
+            __wgAdd(dock);
           } else if (wantPos) {
             dock.dataset.pos = wantPos;
             try {

package/dist/runner/overlay-css.js

@@ -115,24 +115,6 @@ export const RING_CSS =
   ".wg-todo-dock .wg-todo-dock-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
   "letter-spacing:.04em;text-transform:uppercase;margin:0 0 8px;}" +
   ".wg-todo-dock .wg-todos-list,#wg-todo-dock #wg-todos,.wg-todo-dock #wg-todos{list-style:none;margin:0;padding:0;background:transparent;border:none;}" +
-  // Video device stage: keep recordVideo size fixed; center a device-sized shell.
-  "html.wg-video-device-stage{background:#0b1220 !important;}" +
-  "html.wg-video-device-stage body{margin:0 !important;min-height:100vh !important;" +
-  "display:flex !important;align-items:center !important;justify-content:center !important;" +
-  "background:#0b1220 !important;overflow:hidden !important;}" +
-  "#wg-device-shell{flex-shrink:0;overflow:auto;background:#fff;" +
-  "border-radius:16px;box-shadow:0 24px 80px rgba(0,0,0,.55),0 0 0 1px rgba(255,255,255,.08);" +
-  "transform-origin:center center;" +
-  /* Force radius clip on all corners (Chrome + transform/scale). */
-  "-webkit-mask-image:-webkit-radial-gradient(white,black);" +
-  "isolation:isolate;" +
-  "transition:border-radius .55s cubic-bezier(.22,1,.36,1),box-shadow .55s ease," +
-  "transform .55s cubic-bezier(.22,1,.36,1),width .5s ease,height .5s ease,max-width .5s ease,max-height .5s ease;}" +
-  "#wg-device-shell.wg-shell-enter{border-radius:0;box-shadow:none;}" +
-  "#wg-device-shell.wg-shell-shutter-out{border-radius:0 !important;" +
-  "box-shadow:none !important;outline:none !important;border:none !important;}" +
-  "#wg-device-shell.wg-shell-desktop-flat{border-radius:0 !important;box-shadow:none !important;" +
-  "outline:none !important;border:none !important;-webkit-mask-image:none;}" +
   // Always-on zoom HUD - bottom-right (top-left is crowded: todos + banners).
   "#wg-zoom-badge{position:fixed;z-index:2147483646;bottom:14px;right:14px;" +
   "display:flex;align-items:center;gap:7px;padding:6px 11px 6px 8px;" +
@@ -329,3 +311,24 @@ export const WAYGRAPH_FAVICON =
     "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'>" +
       "<circle cx='16' cy='16' r='14' fill='#7C3AED'/></svg>",
   );
+
+// Rules that style the HOST page (device stage) - these must stay in the light DOM, outside the overlay's shadow root.
+export const HOST_CSS =
+  // Video device stage: keep recordVideo size fixed; center a device-sized shell.
+  "html.wg-video-device-stage{background:#0b1220 !important;}" +
+  "html.wg-video-device-stage body{margin:0 !important;min-height:100vh !important;" +
+  "display:flex !important;align-items:center !important;justify-content:center !important;" +
+  "background:#0b1220 !important;overflow:hidden !important;}" +
+  "#wg-device-shell{flex-shrink:0;overflow:auto;background:#fff;" +
+  "border-radius:16px;box-shadow:0 24px 80px rgba(0,0,0,.55),0 0 0 1px rgba(255,255,255,.08);" +
+  "transform-origin:center center;" +
+  /* Force radius clip on all corners (Chrome + transform/scale). */
+  "-webkit-mask-image:-webkit-radial-gradient(white,black);" +
+  "isolation:isolate;" +
+  "transition:border-radius .55s cubic-bezier(.22,1,.36,1),box-shadow .55s ease," +
+  "transform .55s cubic-bezier(.22,1,.36,1),width .5s ease,height .5s ease,max-width .5s ease,max-height .5s ease;}" +
+  "#wg-device-shell.wg-shell-enter{border-radius:0;box-shadow:none;}" +
+  "#wg-device-shell.wg-shell-shutter-out{border-radius:0 !important;" +
+  "box-shadow:none !important;outline:none !important;border:none !important;}" +
+  "#wg-device-shell.wg-shell-desktop-flat{border-radius:0 !important;box-shadow:none !important;" +
+  "outline:none !important;border:none !important;-webkit-mask-image:none;}";

package/dist/runner/overlay-install.js

@@ -1,6 +1,7 @@
 // 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 { RING_CSS, WAYGRAPH_FAVICON } from "./overlay-css.js";
+import { HOST_CSS, RING_CSS, WAYGRAPH_FAVICON } from "./overlay-css.js";
+import { ensureShadowRoot } from "../ui/shadow.js";
 import { resolveTodoDockUi } from "../highlights.js";
 import { installCore } from "./inpage/core.js";
 import { installSwipeZoom } from "./inpage/swipe-zoom.js";
@@ -12,7 +13,9 @@ import { installDevice } from "./inpage/device.js";
 import { applyVideoDeviceStage } from "./device-stage.js";
 
 export async function installOverlay(page, title) {
-  await page.addStyleTag({ content: RING_CSS }).catch(() => {});
+  await ensureShadowRoot(page);
+  await page.evaluate(([css, key]) => __wgCss(css, key), [RING_CSS, "wg-overlay-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
   // navigation that rebuilds the banner keeps the human's last pick).

package/dist/runner/rings.js

@@ -247,7 +247,7 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
                 return;
               }
               // Fallback for pages that never got installOverlay sync helper.
-              const ul = document.getElementById("wg-todos");
+              const ul = __wgById("wg-todos");
               if (!ul) return;
               ul.innerHTML = todos
                 .map((t) => {

package/dist/runner/slides.js

@@ -66,7 +66,7 @@ export async function presentSlides(page, slides, _gate, opts) {
     }
     await page.evaluate(
       (info) => {
-        let panel = document.getElementById("wg-panel");
+        let panel = __wgById("wg-panel");
         const isNew = !panel;
         if (!panel) {
           panel = document.createElement("div");
@@ -139,7 +139,7 @@ export async function presentSlides(page, slides, _gate, opts) {
           ">Auto-advancing...</div>" +
           "</div>";
         if (isNew) {
-          document.documentElement.appendChild(panel);
+          __wgAdd(panel);
           requestAnimationFrame(() => panel.classList.add("wg-in"));
         }
         if (window.__wgWirePanelChrome) {
@@ -172,7 +172,7 @@ export async function presentSlides(page, slides, _gate, opts) {
         } catch {
           /* ignore */
         }
-        const cb = document.getElementById("wg-autoplay-cb");
+        const cb = __wgById("wg-autoplay-cb");
         if (cb) {
           cb.checked = autoNow;
           cb.addEventListener("change", () => {
@@ -181,17 +181,17 @@ export async function presentSlides(page, slides, _gate, opts) {
             } catch {
               /* ignore */
             }
-            const manual = document.getElementById("wg-gate-manual");
-            const auto = document.getElementById("wg-gate-auto");
+            const manual = __wgById("wg-gate-manual");
+            const auto = __wgById("wg-gate-auto");
             if (manual) manual.style.display = cb.checked ? "none" : "";
             if (auto) auto.style.display = cb.checked ? "" : "none";
           });
         }
-        const manual = document.getElementById("wg-gate-manual");
-        const auto = document.getElementById("wg-gate-auto");
+        const manual = __wgById("wg-gate-manual");
+        const auto = __wgById("wg-gate-auto");
         if (manual) manual.style.display = autoNow ? "none" : "";
         if (auto) auto.style.display = autoNow ? "" : "none";
-        const runBtn = document.getElementById("wg-run");
+        const runBtn = __wgById("wg-run");
         if (runBtn) {
           runBtn.removeAttribute("data-wg-acked");
           runBtn.addEventListener("click", (e) => {
@@ -205,8 +205,8 @@ export async function presentSlides(page, slides, _gate, opts) {
           const unlockAt = Date.now() + info.dwellMs;
           const tick = () => {
             const left = Math.max(0, unlockAt - Date.now());
-            const hint = document.getElementById("wg-dwell-hint");
-            const btn = document.getElementById("wg-run");
+            const hint = __wgById("wg-dwell-hint");
+            const btn = __wgById("wg-run");
             if (left <= 0) {
               if (hint) hint.remove();
               if (btn) btn.disabled = false;
@@ -248,7 +248,7 @@ export async function presentSlides(page, slides, _gate, opts) {
     for (;;) {
       const acked = await page
         .evaluate(() => {
-          const btn = document.getElementById("wg-run");
+          const btn = __wgById("wg-run");
           return !!(btn && btn.getAttribute("data-wg-acked") === "1");
         })
         .catch(() => false);

package/dist/runner/step-panels.js

@@ -33,7 +33,7 @@ export async function renderBeforeStep(page, info) {
       // flash - it only ever fades in ONCE, the first time this page
       // genuinely has no panel yet (a real navigation wiped the whole
       // document, or this is the very first step).
-      let panel = document.getElementById("wg-panel");
+      let panel = __wgById("wg-panel");
       const isNewPanel = !panel;
       if (!panel) {
         panel = document.createElement("div");
@@ -126,7 +126,7 @@ export async function renderBeforeStep(page, info) {
         ">Auto-advancing...</div>";
       panel.innerHTML = html;
       if (isNewPanel) {
-        document.documentElement.appendChild(panel);
+        __wgAdd(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
       } else {
         panel.classList.add("wg-in");
@@ -204,7 +204,7 @@ export async function renderBeforeStep(page, info) {
       panel.querySelectorAll("textarea[data-key]").forEach((ta) => {
         ta.addEventListener("input", applyKeyPretty);
       });
-      const runBtn = document.getElementById("wg-run");
+      const runBtn = __wgById("wg-run");
       if (runBtn) {
         runBtn.addEventListener("click", () => {
           const edits = {};
@@ -220,7 +220,7 @@ export async function renderBeforeStep(page, info) {
       // still always wins over an active autoplay wait, whichever the
       // checkbox says - this is the "hybrid" control: autoplay is a
       // default, not a lockout.
-      const cb = document.getElementById("wg-autoplay-cb");
+      const cb = __wgById("wg-autoplay-cb");
       if (cb) {
         cb.addEventListener("change", () => {
           try {
@@ -228,8 +228,8 @@ export async function renderBeforeStep(page, info) {
           } catch {
             /* private mode / blocked storage - toggle still works this page */
           }
-          const manual = document.getElementById("wg-gate-manual");
-          const auto = document.getElementById("wg-gate-auto");
+          const manual = __wgById("wg-gate-manual");
+          const auto = __wgById("wg-gate-auto");
           if (manual) manual.style.display = cb.checked ? "none" : "";
           if (auto) auto.style.display = cb.checked ? "" : "none";
         });
@@ -256,8 +256,8 @@ export async function renderBeforeStep(page, info) {
           return {
             ok: !!(panel && textOk && opacityOk),
             beacons,
-            hasRun: !!document.getElementById("wg-run"),
-            readyAttr: document.getElementById("wg-panel")?.getAttribute("data-wg-ready") || null,
+            hasRun: !!__wgById("wg-run"),
+            readyAttr: __wgById("wg-panel")?.getAttribute("data-wg-ready") || null,
           };
         })
         .catch((e) => ({ ok: false, reason: String(e && e.message ? e.message : e) }));
@@ -412,7 +412,7 @@ export async function renderAfterStep(page, info) {
   await page
     .evaluate((info) => {
       // Reused in place - see renderBeforeStep's own comment on this.
-      let panel = document.getElementById("wg-panel");
+      let panel = __wgById("wg-panel");
       const isNewPanel = !panel;
       if (!panel) {
         panel = document.createElement("div");
@@ -497,7 +497,7 @@ export async function renderAfterStep(page, info) {
         resultHtml +
         gateHtml;
       if (isNewPanel) {
-        document.documentElement.appendChild(panel);
+        __wgAdd(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
       } else {
         panel.classList.add("wg-in");
@@ -546,9 +546,9 @@ export async function renderAfterStep(page, info) {
           panel.querySelector(".wg-result-json").style.display = wantPretty ? "none" : "block";
         });
       });
-      const runBtn = document.getElementById("wg-run");
+      const runBtn = __wgById("wg-run");
       if (runBtn) runBtn.addEventListener("click", () => window.__wgNext({}));
-      const cb = document.getElementById("wg-autoplay-cb");
+      const cb = __wgById("wg-autoplay-cb");
       if (cb) {
         cb.addEventListener("change", () => {
           try {
@@ -556,8 +556,8 @@ export async function renderAfterStep(page, info) {
           } catch {
             /* private mode / blocked storage - toggle still works this page */
           }
-          const manual = document.getElementById("wg-gate-manual");
-          const auto = document.getElementById("wg-gate-auto");
+          const manual = __wgById("wg-gate-manual");
+          const auto = __wgById("wg-gate-auto");
           if (manual) manual.style.display = cb.checked ? "none" : "";
           if (auto) auto.style.display = cb.checked ? "" : "none";
         });
@@ -579,7 +579,7 @@ async function renderStepError(page, info) {
   await page
     .evaluate((info) => {
       // Reused in place - see renderBeforeStep's own comment on this.
-      let panel = document.getElementById("wg-panel");
+      let panel = __wgById("wg-panel");
       const isNewPanel = !panel;
       if (!panel) {
         panel = document.createElement("div");
@@ -631,7 +631,7 @@ async function renderStepError(page, info) {
         "<button id=\"wg-run\" class=\"wg-error-stop\">Stop</button>" +
         "</div>";
       if (isNewPanel) {
-        document.documentElement.appendChild(panel);
+        __wgAdd(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
       } else {
         panel.classList.add("wg-in");
@@ -651,9 +651,9 @@ async function renderStepError(page, info) {
           ready: true,
         });
       }
-      const runBtn = document.getElementById("wg-run");
+      const runBtn = __wgById("wg-run");
       if (runBtn) runBtn.addEventListener("click", () => window.__wgNext({}));
-      const retryBtn = document.getElementById("wg-error-retry");
+      const retryBtn = __wgById("wg-error-retry");
       if (retryBtn) retryBtn.addEventListener("click", () => window.__wgNext({ __wgRetry: "1" }));
     }, errorPayload)
     .catch(() => {});

package/dist/runner/teardown.js

@@ -38,17 +38,17 @@ import { formatHighlightCaption } from "../highlights.js";
 export async function markStepRunning(page, _opts) {
   await page
     .evaluate(() => {
-      const runBtn = document.getElementById("wg-run");
+      const runBtn = __wgById("wg-run");
       if (runBtn) {
         runBtn.disabled = true;
         runBtn.textContent = "Running \u25B6";
       }
-      const autoEl = document.getElementById("wg-gate-auto");
+      const autoEl = __wgById("wg-gate-auto");
       if (autoEl) autoEl.textContent = "Running...";
-      document.querySelectorAll("#wg-panel textarea[data-key]").forEach((ta) => {
+      __wgQA("#wg-panel textarea[data-key]").forEach((ta) => {
         ta.disabled = true;
       });
-      const panel = document.getElementById("wg-panel");
+      const panel = __wgById("wg-panel");
       if (panel) {
         panel.classList.add("wg-collapsed");
         panel.setAttribute("data-wg-collapsed", "1");
@@ -83,13 +83,13 @@ export async function markStepRunning(page, _opts) {
 export async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef) {
   const needs =
     (await page
-      .evaluate(() => !window.__wgSyncTodos || !document.getElementById("wg-ring"))
+      .evaluate(() => !window.__wgSyncTodos || !__wgById("wg-ring"))
       .catch(() => true)) || false;
   if (!needs) {
     // Overlay survived (SPA / no full document wipe) - still refresh dock
     // if Node has a carry and the DOM lost .wg-todo-dock.
     const hasDock = await page
-      .evaluate(() => !!document.querySelector(".wg-todo-dock, #wg-todo-dock"))
+      .evaluate(() => !!__wgQ(".wg-todo-dock, #wg-todo-dock"))
       .catch(() => false);
     if (hasDock || !todoDockRef || !todoDockRef.current) return;
   }
@@ -162,10 +162,10 @@ export async function teardownOverlay(page) {
         "wg-device-toast",
         "wg-device-badge",
       ]) {
-        const el = document.getElementById(id);
+        const el = __wgById(id);
         if (el) el.remove();
       }
-      document.querySelectorAll(".wg-todo-dock").forEach((el) => el.remove());
+      __wgQA(".wg-todo-dock").forEach((el) => el.remove());
       document.documentElement.classList.remove("wg-video-device-stage");
     })
     .catch(() => {});

package/dist/runner/todo-dock.js

@@ -115,7 +115,7 @@ export async function syncTodoDockAdvance(page, todoDockRef, stubIndex, stub) {
 export async function probeTodoDocksOnPage(page) {
   return page
     .evaluate(() => {
-      const docks = [...document.querySelectorAll(".wg-todo-dock, #wg-todo-dock")];
+      const docks = [...__wgQA(".wg-todo-dock, #wg-todo-dock")];
       return docks.map((el) => {
         const r = el.getBoundingClientRect();
         const items = el.querySelectorAll("li");

package/dist/step-overlay.js

@@ -1,38 +1,40 @@
+import { ensureShadowRoot } from "./ui/shadow.js";
 import { composeStepOverlay } from "./ui/compose.js";
 const RING_CSS = composeStepOverlay();
 const FAVICON = "data:image/svg+xml," +
     encodeURIComponent("<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><circle cx='16' cy='16' r='14' fill='#7C3AED'/></svg>");
 export async function installDemoChrome(page, title = "waygraph auto", options = {}) {
     const showBanner = options.banner !== false;
-    await page.addStyleTag({ content: RING_CSS }).catch(() => { });
+    await ensureShadowRoot(page);
+    await page.evaluate(([css, key]) => __wgCss(css, key), [RING_CSS, "wg-overlay-css"]).catch(() => { });
     await page
         .evaluate(({ title, favicon, showBanner }) => {
-        if (!document.getElementById("wg-ring")) {
+        if (!__wgById("wg-ring")) {
             const ring = document.createElement("div");
             ring.id = "wg-ring";
-            document.documentElement.appendChild(ring);
+            __wgAdd(ring);
         }
-        if (!document.getElementById("wg-ring-label")) {
+        if (!__wgById("wg-ring-label")) {
             const ringLabel = document.createElement("div");
             ringLabel.id = "wg-ring-label";
-            document.documentElement.appendChild(ringLabel);
+            __wgAdd(ringLabel);
         }
-        if (!document.getElementById("wg-cursor")) {
+        if (!__wgById("wg-cursor")) {
             const cursor = document.createElement("div");
             cursor.id = "wg-cursor";
             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);
+            __wgAdd(cursor);
         }
-        if (!document.getElementById("wg-click-pulse")) {
+        if (!__wgById("wg-click-pulse")) {
             const pulse = document.createElement("div");
             pulse.id = "wg-click-pulse";
-            document.documentElement.appendChild(pulse);
+            __wgAdd(pulse);
         }
         window.__wgMoveCursorTo = (x, y, ms) => {
-            const cursor = document.getElementById("wg-cursor");
+            const cursor = __wgById("wg-cursor");
             if (!cursor)
                 return;
             cursor.style.setProperty("--wg-cursor-ms", (ms || 600) + "ms");
@@ -40,7 +42,7 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             cursor.style.opacity = "1";
         };
         window.__wgClickPulse = (x, y, tone) => {
-            const pulse = document.getElementById("wg-click-pulse");
+            const pulse = __wgById("wg-click-pulse");
             if (!pulse)
                 return;
             const raw = (tone || "planned") + "";
@@ -59,8 +61,8 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             pulse.classList.add("wg-pulse");
         };
         window.__wgPositionRing = (box, label, tone, style) => {
-            const ring = document.getElementById("wg-ring");
-            const ringLabel = document.getElementById("wg-ring-label");
+            const ring = __wgById("wg-ring");
+            const ringLabel = __wgById("wg-ring-label");
             if (!ring || !ringLabel)
                 return;
             const raw = (tone || "planned") + "";
@@ -92,25 +94,25 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             ringLabel.style.opacity = "1";
         };
         window.__wgHideRing = () => {
-            const ring = document.getElementById("wg-ring");
-            const ringLabel = document.getElementById("wg-ring-label");
+            const ring = __wgById("wg-ring");
+            const ringLabel = __wgById("wg-ring-label");
             if (ring)
                 ring.style.opacity = "0";
             if (ringLabel)
                 ringLabel.style.opacity = "0";
         };
-        if (showBanner && title && !document.getElementById("wg-banner")) {
+        if (showBanner && title && !__wgById("wg-banner")) {
             const banner = document.createElement("div");
             banner.id = "wg-banner";
             banner.innerHTML =
                 "<span class='wg-banner-tag'>waygraph auto</span><span>" + title + "</span>";
-            document.documentElement.appendChild(banner);
+            __wgAdd(banner);
             banner.setAttribute("data-wg-ui", "1");
             banner.setAttribute("data-wg-modal", "banner");
             banner.setAttribute("data-wg-ready", "1");
         }
         else {
-            const existing = document.getElementById("wg-banner");
+            const existing = __wgById("wg-banner");
             if (existing) {
                 existing.setAttribute("data-wg-ui", "1");
                 existing.setAttribute("data-wg-modal", "banner");

package/dist/ui/shadow.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shadow-DOM mount for every waygraph overlay element. Overlay UI lives in one open shadow root under
+ * `<div id="wg-root">`, so the host page's CSS can't restyle it and ours can't leak out.
+ *
+ * `installShadowRoot` runs INSIDE the page (page.evaluate / addInitScript), so it must stay
+ * self-contained. It defines the `__wg*` helpers the overlay code uses in place of `document.*`:
+ * lookups check the shadow root first and fall back to the light DOM (the device stage shell and
+ * host-page markers such as `[data-wg-zoomed]` intentionally stay in the light DOM).
+ */
+import type { BrowserContext, Page } from "@playwright/test";
+export declare function installShadowRoot(): void;
+/** Idempotent; call before any overlay install on a page. */
+export declare function ensureShadowRoot(page: Page): Promise<void>;
+/** Also define the helpers on every future document (pilot overlay persists across navigations). */
+export declare function installShadowRootEverywhere(context: BrowserContext): Promise<void>;

package/dist/ui/shadow.js

@@ -0,0 +1,42 @@
+export function installShadowRoot() {
+    const w = window;
+    if (w.__wgById)
+        return;
+    const root = () => {
+        let host = document.getElementById("wg-root");
+        if (!host || !host.shadowRoot) {
+            host?.remove();
+            host = document.createElement("div");
+            host.id = "wg-root";
+            // No box of its own: children are position:fixed, so the host must never affect page layout.
+            host.style.cssText = "display:contents";
+            host.attachShadow({ mode: "open" });
+            document.documentElement.appendChild(host);
+        }
+        return host.shadowRoot;
+    };
+    w.__wgRoot = root;
+    w.__wgById = (id) => root().getElementById(id) || document.getElementById(id);
+    w.__wgQ = (sel) => root().querySelector(sel) || document.querySelector(sel);
+    w.__wgQA = (sel) => Array.from(root().querySelectorAll(sel)).concat(Array.from(document.querySelectorAll(sel)));
+    w.__wgAdd = (node) => root().appendChild(node);
+    w.__wgCss = (css, key) => {
+        const r = root();
+        let style = Array.from(r.children).find((c) => c.tagName === "STYLE" && c.getAttribute("data-key") === key);
+        if (!style) {
+            style = document.createElement("style");
+            style.setAttribute("data-key", key);
+            r.insertBefore(style, r.firstChild);
+        }
+        if (style.textContent !== css)
+            style.textContent = css;
+    };
+}
+/** Idempotent; call before any overlay install on a page. */
+export async function ensureShadowRoot(page) {
+    await page.evaluate(installShadowRoot).catch(() => { });
+}
+/** Also define the helpers on every future document (pilot overlay persists across navigations). */
+export async function installShadowRootEverywhere(context) {
+    await context.addInitScript(installShadowRoot);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.30",
+  "version": "0.15.31",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",