waygraph 0.15.44 → 0.15.46

package/dist/analysis/coverage-gap.d.ts

@@ -1,4 +1,4 @@
-import type { BlockEntry } from "../auto-explore.js";
+import type { BlockEntry } from "../session/auto-explore.js";
 /** Collect selector strings from NavClick blocks and Block/*Sel source files. */
 export declare function collectKnownInteractionSelectors(projectDir: string, library: {
     navBlocks: BlockEntry[];

package/dist/analysis/coverage-gap.js

@@ -5,7 +5,7 @@
  */
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { exploreRoots } from "../block-inject.js";
+import { exploreRoots } from "../session/block-inject.js";
 const SELECTOR_LITERAL = /(?:locator|visible|click|fill|press|selector|getByRole)\(\s*['"`]([^'"`]+)['"`]/g;
 const HASH_ID = /#([a-zA-Z][\w-]*)/g;
 const DATA_TEST = /\[data-test(?:-id)?(?:=["'`][^"'`]+["'`])?\]/g;

package/dist/analysis/graph.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, dirname, relative, resolve } from "node:path";
 import { matchBlocksSelect, } from "../blocks-select.js";
-import { exploreRoots, injectTaggedFile } from "../block-inject.js";
+import { exploreRoots, injectTaggedFile } from "../session/block-inject.js";
 /**
  * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
  * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`

package/dist/auto-session/helpers.d.ts

@@ -1,6 +1,6 @@
 import type { StubPhaseResult } from "../highlights.js";
-import type { BlockEntry, ExploreMenu } from "../auto-explore.js";
-import type { PickResult } from "../auto-explore-run.js";
+import type { BlockEntry, ExploreMenu } from "../session/auto-explore.js";
+import type { PickResult } from "../session/auto-explore-run.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 export declare function stubPhaseHasContent(r: StubPhaseResult): boolean;
 export interface SessionSnapshotEdge {

package/dist/auto-session/session.js

@@ -1,10 +1,10 @@
 // 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 { instrumentPilotActions, installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, phaseToOverlayFixtures, describeOverlayFixtures, updatePilotOverlay } from "../pilot-overlay.js";
-import { buildExploreContext, buildExploreMenu } from "../auto-explore.js";
+import { buildExploreContext, buildExploreMenu } from "../session/auto-explore.js";
 import { MemPage } from "../mem-page.js";
 import { Engine } from "../engine.js";
-import { detectHere, ensureLivePage, ensureMem, resolveBaseUrl, runOneBlock, seedDefaultMem } from "../auto-explore-run.js";
+import { detectHere, ensureLivePage, ensureMem, resolveBaseUrl, runOneBlock, seedDefaultMem } from "../session/auto-explore-run.js";
 import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../analysis/coverage-gap.js";
 import { runStubPhase } from "../highlights.js";
 import { verboseLog } from "../verbose-log.js";

package/dist/cli/usage.d.ts

@@ -1,4 +1,4 @@
-import type { SessionMeta } from "../browser.js";
+import type { SessionMeta } from "../session/browser.js";
 export declare function printBrowserUsage(): void;
 export declare function printBrowserSessionsList(sessions: SessionMeta[], projectDir: string): void;
 export declare function usage(): void;

package/dist/commands/session.js

@@ -4,14 +4,14 @@ import { applyRunFlags, looksLikeFlowFileRef, parseRunFlags, resolveBaseUrl } fr
 import { runChain } from "../cli/run-chain.js";
 import { runChainAuto } from "./check.js";
 import { resolve } from "node:path";
-import { browserStart, listBrowserSessions, stopAllBrowserSessions, stopBrowserSession } from "../browser.js";
+import { browserStart, listBrowserSessions, stopAllBrowserSessions, stopBrowserSession } from "../session/browser.js";
 import { existsSync, statSync } from "node:fs";
-import { resolveInjectRoots } from "../block-inject.js";
-import { requestSession, resolveSessionMeta, runAttachLoop, runAutoServeCommand, spawnDetachedSession } from "../auto-session-ipc.js";
-import { pilotAttach, pilotStart } from "../pilot.js";
+import { resolveInjectRoots } from "../session/block-inject.js";
+import { requestSession, resolveSessionMeta, runAttachLoop, runAutoServeCommand, spawnDetachedSession } from "../session/auto-session-ipc.js";
+import { pilotAttach, pilotStart } from "../session/pilot.js";
 import { parseHighlightShorthand } from "../highlights/shorthand.js";
 import { isFileSelectToken, parseBlocksSelect } from "../blocks-select.js";
-import { runAutoExplore } from "../auto-explore-run.js";
+import { runAutoExplore } from "../session/auto-explore-run.js";
 import { discoverGraph, findOrphanBlocks, toMermaid } from "../analysis/graph.js";
 export async function sessionCase(args, command) {
     if (command === "browser") {

package/dist/index.d.ts

@@ -21,9 +21,9 @@ export { runTraverse } from "./traverse/run.js";
 export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse/run.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse/coverage.js";
 export type { TraverseCoverageReport } from "./traverse/coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
-export type { WgModalKind, WgBeaconRow } from "./overlay-beacon.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./session/overlay-beacon.js";
+export type { WgModalKind, WgBeaconRow } from "./session/overlay-beacon.js";
 export { AutoSession, stubFilePath } from "./auto-session.js";
 export type { AutoSessionInit, SessionSnapshot, SessionSnapshotEdge, SessionSnapshotSection, ApplyPickResult, ApplyPathResult, TraceStep, ConsoleLogEntry, StorageSnapshot, ServiceWorkerRegistrationInfo, CookieInfo, StubFileKind, } from "./auto-session.js";
-export { pilotStart } from "./pilot.js";
-export type { PilotStartResult } from "./pilot.js";
+export { pilotStart } from "./session/pilot.js";
+export type { PilotStartResult } from "./session/pilot.js";

package/dist/index.js

@@ -11,6 +11,6 @@ export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp,
 export { EdgeLeaseCoordinator } from "./traverse/lease.js";
 export { runTraverse } from "./traverse/run.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse/coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./session/overlay-beacon.js";
 export { AutoSession, stubFilePath } from "./auto-session.js";
-export { pilotStart } from "./pilot.js";
+export { pilotStart } from "./session/pilot.js";

package/dist/pilot-overlay/fixtures.js

@@ -188,7 +188,7 @@ export async function showPilotFixtures(page, fixtures) {
         };
         w.__wgPilotFxZoomOutOnHide = zoomOut;
         const clearFx = () => {
-            __wgQA(".wg-pilot-fx-ring, .wg-pilot-fx-label").forEach((el) => el.remove());
+            __wgQA('[id^="wg-fx-ring-"]').forEach((el) => el.remove());
             __wgById("wg-pilot-fx-todos")?.remove();
             clearFocus();
             if (w.__wgPilotFxZoomOutOnHide !== false || clearAll)
@@ -205,59 +205,34 @@ export async function showPilotFixtures(page, fixtures) {
         const missing = [];
         let painted = 0;
         let focusBox = null;
-        for (const ring of rings) {
+        // Paint through the SAME shared ring primitive the demo/auto singleton ring uses
+        // (window.__wgPaintRingAt, installed by runner/inpage/core.js's installCore - see
+        // ensureInstalled) - one ring implementation, not a separate DOM-building copy here.
+        rings.forEach((ring, i) => {
             const el = document.querySelector(ring.selector);
             if (!el) {
                 missing.push(ring.selector);
-                continue;
+                return;
             }
             const rect = el.getBoundingClientRect();
             if (rect.width === 0 && rect.height === 0) {
                 missing.push(ring.selector);
-                continue;
-            }
-            const pad = ring.size === "sm" ? 3 : ring.size === "lg" ? 10 : 6;
-            const ringEl = document.createElement("div");
-            ringEl.className = "wg-pilot-fx-ring";
-            ringEl.dataset.tone = ring.tone;
-            ringEl.dataset.size = ring.size;
-            ringEl.style.left = `${rect.left - pad}px`;
-            ringEl.style.top = `${rect.top - pad}px`;
-            ringEl.style.width = `${Math.max(4, rect.width + pad * 2)}px`;
-            ringEl.style.height = `${Math.max(4, rect.height + pad * 2)}px`;
-            ringEl.style.opacity = "1";
-            const labelEl = document.createElement("div");
-            labelEl.className = "wg-pilot-fx-label";
-            labelEl.dataset.tone = ring.tone;
-            labelEl.dataset.size = ring.size;
-            labelEl.dataset.weight = ring.weight;
-            labelEl.textContent = ring.label;
-            labelEl.style.opacity = "1";
-            if (ring.color) {
-                labelEl.style.color = ring.color;
+                return;
             }
-            __wgAdd(ringEl);
-            __wgAdd(labelEl);
-            const lw = labelEl.offsetWidth;
-            const lh = labelEl.offsetHeight;
-            let labelLeft = rect.left - pad;
-            let labelTop = rect.top - pad + rect.height + pad * 2 + 8;
-            if (labelTop + lh > window.innerHeight - 6)
-                labelTop = rect.top - pad - lh - 8;
-            if (labelTop < 6)
-                labelTop = 6;
-            if (labelLeft + lw > window.innerWidth - 6) {
-                labelLeft = Math.max(6, window.innerWidth - 6 - lw);
+            const box = { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+            const ringId = `wg-fx-ring-${i}`;
+            const labelId = `wg-fx-ring-${i}-label`;
+            if (window.__wgPaintRingAt) {
+                window.__wgPaintRingAt(ringId, labelId, box, ring.label, ring.tone, {
+                    size: ring.size,
+                    weight: ring.weight,
+                    color: ring.color,
+                });
             }
-            if (labelLeft < 6)
-                labelLeft = 6;
-            labelEl.style.left = `${labelLeft}px`;
-            labelEl.style.top = `${labelTop}px`;
             painted += 1;
-            if (ring.focus) {
-                focusBox = { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
-            }
-        }
+            if (ring.focus)
+                focusBox = box;
+        });
         // Real TodoDockState groups (same shape/builder the demo runner uses) - a group's own
         // style (sequential/checklist/bullets) and its own done/current flags drive rendering here,
         // not a re-derived index over a flattened string list.
@@ -324,7 +299,7 @@ export async function showPilotFixtures(page, fixtures) {
         }
         // Collision flip: if a painted ring intersects the dock, flip side once.
         if (dockEl && todoUi.collision !== false && painted > 0) {
-            const firstRing = __wgQ(".wg-pilot-fx-ring");
+            const firstRing = __wgQ('[id^="wg-fx-ring-"]:not([id$="-label"])');
             if (firstRing) {
                 const rr = firstRing.getBoundingClientRect();
                 const dr = dockEl.getBoundingClientRect();

package/dist/pilot-overlay/shell.js

@@ -62,7 +62,8 @@ const OVERLAY_CSS = `
   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 fixture rings (.wg-pilot-fx-ring/label), #wg-pilot-fx-todos, #wg-ring/#wg-ring-label and
+/* Agent fixture rings (painted via the shared .wg-ring-el primitive, see ui/css/ring.css and
+   runner/inpage/core.js's __wgPaintRingAt), #wg-pilot-fx-todos, #wg-ring/#wg-ring-label and
    #wg-banner all come from the ONE shared bundle ensureShadowRoot installs (ui/css/*.css) - not
    redefined here. */
 /* Spotlight (demo focus:true) - dim page, cutout around target. */
@@ -149,6 +150,11 @@ export async function installPersistentPilotOverlay(context) {
 export async function ensureInstalled(page) {
     await ensureShadowRoot(page);
     await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(() => { });
+    // The shared ring primitive (__wgEnsureRingEl/__wgPaintRingAt) - so Pilot's fixture rings paint
+    // through the SAME implementation the demo/auto singleton ring uses (see ui/css/ring.css / this
+    // file's own header comment on redundancy), not a separate DOM-building copy.
+    const { installCore } = await import("../runner/inpage/core.js");
+    await page.evaluate(installCore, {}).catch(() => { });
     // Device toast/chip CSS (runner/overlay-css.js's RUNNER_EXTRA_CSS) - same rules the demo runner
     // uses, reused here (not re-authored) so a device fixture looks identical on Pilot.
     const { RUNNER_EXTRA_CSS } = await import("../runner/overlay-css.js");

package/dist/runner/inpage/core.d.ts

@@ -0,0 +1,4 @@
+/** In-page installer (page.evaluate target) - see core.js's own header. Installs the shared ring
+ * primitive (__wgEnsureRingEl/__wgPaintRingAt/__wgHideRingAt), cursor, click-pulse, focus veil,
+ * and the #wg-ring singleton every surface's "current action" ring uses. */
+export function installCore(args: Record<string, unknown>): void;

package/dist/runner/inpage/core.js

@@ -19,65 +19,37 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
         } catch {
           /* private mode / blocked storage - falls back to manual gating */
         }
-        if (!__wgById("wg-ring")) {
-          const ring = document.createElement("div");
-          ring.id = "wg-ring";
-          __wgAdd(ring);
-        }
-        if (!__wgById("wg-ring-label")) {
-          const ringLabel = document.createElement("div");
-          ringLabel.id = "wg-ring-label";
-          __wgAdd(ringLabel);
-        }
-        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
-          // #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>";
-          __wgAdd(cursor);
-        }
-        if (!__wgById("wg-click-pulse")) {
-          const pulse = document.createElement("div");
-          pulse.id = "wg-click-pulse";
-          __wgAdd(pulse);
-        }
-        window.__wgMoveCursorTo = (x, y, ms, instant) => {
-          const cursor = __wgById("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)";
+        // The one shared ring primitive (ui/css/ring.css) - #wg-ring/#wg-ring-label is just this
+        // surface's OWN ring instance, found by id like any other (see __wgEnsureRingEl below).
+        window.__wgEnsureRingEl = (ringId, labelId) => {
+          let ring = __wgById(ringId);
+          if (!ring) {
+            ring = document.createElement("div");
+            ring.id = ringId;
+            ring.className = "wg-ring-el";
+            __wgAdd(ring);
           }
-          cursor.style.opacity = "1";
-        };
-        window.__wgHideCursor = () => {
-          const cursor = __wgById("wg-cursor");
-          if (cursor) cursor.style.opacity = "0";
+          let label = __wgById(labelId);
+          if (!label) {
+            label = document.createElement("div");
+            label.id = labelId;
+            label.className = "wg-ring-el-label";
+            __wgAdd(label);
+          }
+          return [ring, label];
         };
-        window.__wgPositionRing = (box, label, tone, style) => {
-          const ring = __wgById("wg-ring");
-          const ringLabel = __wgById("wg-ring-label");
-          if (!ring || !ringLabel || !box) return;
+        /** Bare positioning only - no collision/follow/focus-veil (those are #wg-ring's own extras, see __wgPositionRing). */
+        window.__wgPaintRingAt = (ringId, labelId, box, label, tone, style) => {
+          const [ring, ringLabel] = window.__wgEnsureRingEl(ringId, labelId);
+          if (!box) return null;
           const raw = (tone || "planned") + "";
           const t =
-            raw === "auto" || raw === "info" || raw === "warning" || raw === "danger" || raw === "success"
+            raw === "auto" || raw === "info" || raw === "warning" || raw === "danger" || raw === "success" || raw === "orange"
               ? raw
               : "planned";
           const st = style && typeof style === "object" ? style : {};
           const sizeRaw = (st.size || "md") + "";
-          const size =
-            sizeRaw === "sm" || sizeRaw === "lg" ? sizeRaw : "md";
+          const size = sizeRaw === "sm" || sizeRaw === "lg" ? sizeRaw : "md";
           const weightRaw = (st.weight || "normal") + "";
           const weight = weightRaw === "bold" ? "bold" : "normal";
           ring.dataset.tone = t;
@@ -85,12 +57,12 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           ring.dataset.size = size;
           ringLabel.dataset.size = size;
           ringLabel.dataset.weight = weight;
+          if (st.color) ringLabel.style.color = st.color;
+          else ringLabel.style.removeProperty("color");
           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);
@@ -112,6 +84,57 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           if (labelLeft < margin) labelLeft = margin;
           ringLabel.style.left = labelLeft + "px";
           ringLabel.style.top = labelTop + "px";
+          return [ring, ringLabel];
+        };
+        window.__wgHideRingAt = (ringId, labelId) => {
+          const ring = __wgById(ringId);
+          const label = __wgById(labelId);
+          if (ring) ring.style.opacity = "0";
+          if (label) label.style.opacity = "0";
+        };
+        window.__wgEnsureRingEl("wg-ring", "wg-ring-label");
+        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
+          // #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>";
+          __wgAdd(cursor);
+        }
+        if (!__wgById("wg-click-pulse")) {
+          const pulse = document.createElement("div");
+          pulse.id = "wg-click-pulse";
+          __wgAdd(pulse);
+        }
+        window.__wgMoveCursorTo = (x, y, ms, instant) => {
+          const cursor = __wgById("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 = __wgById("wg-cursor");
+          if (cursor) cursor.style.opacity = "0";
+        };
+        // #wg-ring's own extras on top of the shared __wgPaintRingAt primitive: todo/banner
+        // collision avoidance only makes sense for the ONE "current action" ring, not Pilot's
+        // several independent fixture rings - kept here, not pushed down into the shared painter.
+        window.__wgPositionRing = (box, label, tone, style) => {
+          if (!box) return;
+          window.__wgPaintRingAt("wg-ring", "wg-ring-label", box, label, tone, style);
           if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(true);
           if (window.__wgTodosAvoidRingCollision) window.__wgTodosAvoidRingCollision(box);
           if (window.__wgBannerAvoidRing) window.__wgBannerAvoidRing(box);

package/dist/runner/rings.js

@@ -363,6 +363,55 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
 }
 
 
+/**
+ * Paint a NAMED ring instance (ui/css/ring.css's shared `.wg-ring-el`/`.wg-ring-el-label`) at a
+ * known viewport box - the primitive both the demo/auto singleton (`showRing`, always "wg-ring")
+ * and Pilot's several simultaneous fixture rings (their own ids) paint through, so there is one
+ * ring-rendering implementation, not two. No collision/follow/focus - those are `#wg-ring`'s own
+ * extras (see `showRing`/`inpage/core.js`'s `__wgPositionRing`), meaningless for an independent
+ * fixture ring that isn't "the current action."
+ */
+export async function showRingAt(page, ringId, labelId, box, label, tone, style) {
+  const size = normalizeHighlightSize(style && style.size);
+  const weight = normalizeHighlightWeight(style && style.weight);
+  const color = style && style.color ? String(style.color) : "";
+  await page
+    .evaluate(
+      ({ ringId, labelId, box, label, tone, size, weight, color }) => {
+        if (window.__wgPaintRingAt) {
+          window.__wgPaintRingAt(ringId, labelId, box, label, tone, { size, weight, color });
+        }
+      },
+      { ringId, labelId, box, label, tone: tone || "planned", size, weight, color },
+    )
+    .catch(() => {});
+}
+
+/** Hide (not remove) a named ring instance painted via {@link showRingAt}. */
+export async function hideRingAt(page, ringId, labelId) {
+  await page
+    .evaluate(
+      ({ ringId, labelId }) => {
+        if (window.__wgHideRingAt) window.__wgHideRingAt(ringId, labelId);
+      },
+      { ringId, labelId },
+    )
+    .catch(() => {});
+}
+
+/** Remove a named ring instance entirely (Pilot's fixture rings are short-lived, not reused). */
+export async function removeRingAt(page, ringId, labelId) {
+  await page
+    .evaluate(
+      ({ ringId, labelId }) => {
+        __wgById(ringId)?.remove();
+        __wgById(labelId)?.remove();
+      },
+      { ringId, labelId },
+    )
+    .catch(() => {});
+}
+
 export async function showRing(page, box, label, tone, style) {
   const size = normalizeHighlightSize(style && style.size);
   const weight = normalizeHighlightWeight(style && style.weight);

package/dist/session/auto-explore-run.d.ts

@@ -0,0 +1,37 @@
+import type { Page, BrowserContext } from "@playwright/test";
+import { Engine } from "../engine.js";
+import { MemPage } from "../mem-page.js";
+import { type BlockEntry } from "./auto-explore.js";
+import type { Checkpoint } from "../types.js";
+export interface AutoExploreOptions {
+    /** Terminal menu (browser still runs for act()). Default false = headful picker panel. */
+    cli?: boolean;
+    baseURL?: string;
+    /** Initial URL when the page is blank (defaults to baseURL). */
+    startUrl?: string;
+    /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
+    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+}
+export declare function resolveBaseUrl(projectDir: string): string | undefined;
+export declare function detectHere(page: Page, navBlocks: BlockEntry[]): Promise<string | null>;
+export declare function ensureLivePage(context: BrowserContext, page: Page, startUrl: string | undefined): Promise<Page>;
+/**
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`.
+ * A consumer's own `key<string>("login-email")` must stay unset here, or it
+ * silently gets a saucedemo credentials object instead of its own default.
+ */
+export declare function defaultMemValueForKey(keyName: string): unknown | undefined;
+/** Pre-seed known demo keys (saucedemo creds) so headful/cli do not stop for mem forms. */
+export declare function seedDefaultMem(library: Map<string, BlockEntry>, mem: MemPage): void;
+export declare function ensureMem(entry: BlockEntry, mem: MemPage, cli: boolean): Promise<void>;
+export declare function runOneBlock(engine: Engine, entry: BlockEntry, context: BrowserContext, page: Page, mem: MemPage, headful: boolean): Promise<Checkpoint<string>>;
+export type PickResult = {
+    type: "pick";
+    index: number;
+} | {
+    type: "quit";
+};
+/**
+ * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
+ */
+export declare function runAutoExplore(projectDir: string, options?: AutoExploreOptions): Promise<void>;