waygraph 0.15.30 → 0.15.32

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/auto-session/session.js

@@ -1,6 +1,6 @@
 // Split out of the former 1,078-line auto-session.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { CONSOLE_LOG_MAX_ENTRIES, FULL_MODE_DEFAULT_DEPTH, FULL_MODE_MAX_NODES, FULL_MODE_MAX_TEXT_LENGTH, TRACE_MAX_STEPS, buildSessionSnapshot, parsePick, stubFilePath, stubPhaseHasContent, walkFullDom } from "./helpers.js";
-import { installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, updatePilotOverlay } from "../pilot-overlay.js";
+import { instrumentPilotActions, installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, updatePilotOverlay } from "../pilot-overlay.js";
 import { buildExploreContext, buildExploreMenu } from "../auto-explore.js";
 import { MemPage } from "../mem-page.js";
 import { Engine } from "../engine.js";
@@ -92,6 +92,7 @@ export class AutoSession {
         const context = await browser.newContext(contextOpts);
         await installPersistentPilotOverlay(context);
         const page = await context.newPage();
+        instrumentPilotActions(page, headless ? 0 : 450);
         if (startUrl) {
             await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
             await page.waitForLoadState("load").catch(() => { });

package/dist/pilot-overlay/action-ring.d.ts

@@ -0,0 +1,16 @@
+import type { Page } from "@playwright/test";
+type Box = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
+export declare function showPilotRect(page: Page, box: Box, label: string, tone?: string): Promise<void>;
+/**
+ * Every Playwright instruction a Block runs against this session's page gets a gray (auto) ring + robot
+ * label first, so a human watching a pilot window sees WHAT is being driven. `dwellMs` holds the ring
+ * long enough to read before the action fires (0 for headless).
+ */
+export declare function instrumentPilotActions(page: Page, dwellMs: number): void;
+export {};

package/dist/pilot-overlay/action-ring.js

@@ -0,0 +1,67 @@
+import { ensureInstalled } from "./shell.js";
+/** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
+export async function showPilotRect(page, box, label, tone = "auto") {
+    await ensureInstalled(page);
+    await page
+        .evaluate(({ box, label, tone }) => {
+        const ring = __wgById("wg-ring");
+        const tag = __wgById("wg-ring-label");
+        if (!ring || !tag)
+            return;
+        const w = window;
+        if (w.__wgVisionHideTimer)
+            clearTimeout(w.__wgVisionHideTimer);
+        ring.dataset.tone = tone;
+        ring.dataset.size = "md";
+        tag.dataset.tone = tone;
+        tag.dataset.size = "md";
+        tag.dataset.weight = "normal";
+        ring.style.left = `${box.x - 3}px`;
+        ring.style.top = `${box.y - 3}px`;
+        ring.style.width = `${box.width + 6}px`;
+        ring.style.height = `${box.height + 6}px`;
+        tag.textContent = label;
+        tag.style.left = `${Math.max(0, box.x)}px`;
+        tag.style.top = `${Math.max(0, box.y - 24)}px`;
+        ring.style.opacity = "1";
+        tag.style.opacity = "1";
+        w.__wgVisionHideTimer = setTimeout(() => {
+            ring.style.opacity = "0";
+            tag.style.opacity = "0";
+        }, 4_000);
+    }, { box, label, tone })
+        .catch(() => { });
+}
+const LOCATOR_ACTIONS = ["click", "dblclick", "hover", "tap", "fill", "check", "uncheck", "selectOption", "press", "pressSequentially", "setInputFiles"];
+const patched = new WeakSet();
+/**
+ * Every Playwright instruction a Block runs against this session's page gets a gray (auto) ring + robot
+ * label first, so a human watching a pilot window sees WHAT is being driven. `dwellMs` holds the ring
+ * long enough to read before the action fires (0 for headless).
+ */
+export function instrumentPilotActions(page, dwellMs) {
+    const proto = Object.getPrototypeOf(page.locator("html"));
+    if (patched.has(proto))
+        return;
+    patched.add(proto);
+    for (const action of LOCATOR_ACTIONS) {
+        const original = proto[action];
+        if (typeof original !== "function")
+            continue;
+        proto[action] = async function (...args) {
+            try {
+                const box = await this.first().boundingBox({ timeout: 1_500 });
+                if (box) {
+                    const desc = String(this).replace(/^locator\(['"]?|['"]?\)$/g, "").slice(0, 60);
+                    await showPilotRect(this.page(), box, `${action} ${desc}`);
+                    if (dwellMs > 0)
+                        await this.page().waitForTimeout(dwellMs);
+                }
+            }
+            catch {
+                /* decoration only - never block the real action */
+            }
+            return original.apply(this, args);
+        };
+    }
+}

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/pilot-overlay.d.ts

@@ -1,3 +1,4 @@
 export * from "./pilot-overlay/shell.js";
 export * from "./pilot-overlay/fixtures.js";
 export * from "./pilot-overlay/panel.js";
+export * from "./pilot-overlay/action-ring.js";

package/dist/pilot-overlay.js

@@ -2,3 +2,4 @@
 export * from "./pilot-overlay/shell.js";
 export * from "./pilot-overlay/fixtures.js";
 export * from "./pilot-overlay/panel.js";
+export * from "./pilot-overlay/action-ring.js";

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";