waygraph 0.15.31 → 0.15.33

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/highlights/run-phase.js

@@ -107,6 +107,8 @@ export async function runStubPhase(block, phase, opts) {
         ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
         ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
+        ...(bag.titlePos !== undefined ? { titlePos: bag.titlePos } : {}),
+        ...(bag.bannerUi !== undefined ? { bannerUi: bag.bannerUi } : {}),
         ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
         ...(bag.todoDockUi !== undefined ? { todoDockUi: bag.todoDockUi } : {}),
         ...(bag.todoParallel === true ? { todoParallel: true } : {}),

package/dist/highlights/stub-ctx.js

@@ -162,11 +162,35 @@ export function createStubCtx(bag, opts) {
         zoomOut(keep) {
             bag.zoomOut = !!keep;
         },
-        title(text) {
+        title(text, opts) {
             bag.title = String(text ?? "");
+            const p = normalizeBannerPos(opts?.pos);
+            if (p)
+                bag.titlePos = p;
         },
-        banner(text) {
+        banner(text, opts) {
             bag.title = String(text ?? "");
+            const p = normalizeBannerPos(opts?.pos);
+            if (p)
+                bag.titlePos = p;
+        },
+        titlePos(side) {
+            const p = normalizeBannerPos(side);
+            if (p)
+                bag.titlePos = p;
+        },
+        bannerPos(side) {
+            const p = normalizeBannerPos(side);
+            if (p)
+                bag.titlePos = p;
+        },
+        bannerUi(opts) {
+            if (!opts || typeof opts !== "object")
+                return;
+            bag.bannerUi = { ...(bag.bannerUi || {}), ...opts };
+        },
+        hideBanner() {
+            bag.bannerUi = { ...(bag.bannerUi || {}), hidden: true };
         },
         todoPos(side) {
             const p = normalizeTodoPos(side);
@@ -256,6 +280,12 @@ export function createStubCtx(bag, opts) {
                 bag.zoomOut = !!partial.zoomOut;
             if (partial.title !== undefined)
                 bag.title = String(partial.title ?? "");
+            const bp = normalizeBannerPos(partial.titlePos);
+            if (bp)
+                bag.titlePos = bp;
+            if (partial.bannerUi && typeof partial.bannerUi === "object") {
+                bag.bannerUi = { ...(bag.bannerUi || {}), ...partial.bannerUi };
+            }
             const tp = normalizeTodoPos(partial.todoPos);
             if (tp)
                 bag.todoPos = tp;
@@ -279,3 +309,7 @@ export function liftLegacySlotTodos(bag) {
         }
     }
 }
+function normalizeBannerPos(raw) {
+    const v = String(raw ?? "").toLowerCase();
+    return v === "left" || v === "center" || v === "right" ? v : undefined;
+}

package/dist/highlights/types.d.ts

@@ -41,6 +41,15 @@ export type WaygraphTodoInput = string | WaygraphTodoItem;
  * - `bullets` - flat bullet list (no arrow/checkbox; open notes / trimmed dock)
  */
 export type TodoListStyle = "sequential" | "checklist" | "bullets";
+/** Where the top banner sits. */
+export type BannerPos = "left" | "center" | "right";
+/** Banner UX, mirrors {@link TodoDockUiOpts}: pass `false` fields to opt out for this phase. */
+export interface BannerUiOpts {
+    /** Move to a free spot while a highlight ring would overlap it (default true). */
+    collision?: boolean;
+    /** Hide the banner entirely for this phase. */
+    hidden?: boolean;
+}
 /** One titled group in the floating todo dock (FR / Scenarios / ACs, etc.). */
 export type WaygraphTodoGroupInput = {
     /** Stable group id -> `data-wg-todo-group`. */
@@ -146,6 +155,10 @@ export type StubPhaseFixtures = {
     zoomOut?: boolean;
     /** Top demo banner title (the purple "waygraph demo" card). */
     title?: string;
+    /** Banner side/position (`left` | `center` | `right`). Authored control, like {@link todoPos}. */
+    titlePos?: BannerPos;
+    /** Banner UX: collision (move away from a ring it overlaps), hidden. See {@link BannerUiOpts}. */
+    bannerUi?: BannerUiOpts;
     /**
      * Floating checklist dock side. `left` | `right`.
      * Authored control (also click / WAYGRAPH_TODO_POS / --todo-left|right).
@@ -373,10 +386,25 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
      * Default zoomOut for rings in this phase. `false` = keep camera between rings.
      */
     zoomOut(keep: boolean): void;
-    /** Top banner title (waygraph demo card). */
-    title(text: string): void;
+    /** Top banner title (waygraph demo card). `opts.pos` also places it (left | center | right). */
+    title(text: string, opts?: {
+        pos?: BannerPos;
+    }): void;
     /** Alias for {@link StubCtx.title}. */
-    banner(text: string): void;
+    banner(text: string, opts?: {
+        pos?: BannerPos;
+    }): void;
+    /** Place the banner: `left` | `center` | `right` (authored; click / env are fallbacks). */
+    titlePos(side: BannerPos): void;
+    /** Alias for {@link StubCtx.titlePos}. */
+    bannerPos(side: BannerPos): void;
+    /**
+     * Banner UX: `{ collision: false }` keeps it put even over a ring; `{ hidden: true }` hides it.
+     * @example ctx.bannerUi({ collision: false });
+     */
+    bannerUi(opts: BannerUiOpts): void;
+    /** Shorthand for `bannerUi({ hidden: true })`. */
+    hideBanner(): void;
     /**
      * Floating checklist dock side (`left` | `right`). Authors control this in
      * code; click / env / --todo-left|right are fallbacks.
@@ -433,6 +461,8 @@ export type StubPhaseResult = {
     zoom?: number;
     zoomOut?: boolean;
     title?: string;
+    titlePos?: BannerPos;
+    bannerUi?: BannerUiOpts;
     todoPos?: "left" | "right";
     /** When true, keep other docks (multi-todo). Default false = replace. */
     todoParallel?: boolean;
@@ -528,6 +558,8 @@ export type StubBagState = {
     zoom?: number | undefined;
     zoomOut?: boolean | undefined;
     title?: string | undefined;
+    titlePos?: BannerPos | undefined;
+    bannerUi?: BannerUiOpts | undefined;
     todoPos?: "left" | "right" | undefined;
     /** Author patched todo-dock UX this phase. */
     todoDockUi?: TodoDockUiOpts | undefined;

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
-export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
+export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, BannerPos, BannerUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

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.d.ts

@@ -1,4 +1,4 @@
-import type { DevicePreset, DeviceState, HighlightTone, TodoDockUiOpts } from "../highlights.js";
+import type { BannerPos, BannerUiOpts, DevicePreset, DeviceState, HighlightTone, TodoDockUiOpts } from "../highlights.js";
 import type { Page } from "@playwright/test";
 /** One ring the Pilot agent wants painted (same fields as demo stub rings). */
 export type PilotFixtureRing = {
@@ -68,6 +68,14 @@ export type PilotHighlightFixtures = {
     device?: DevicePreset | DeviceState;
     /** Drop every agent fixture ring/todo/focus/zoom immediately. */
     clear?: boolean;
+    /** Top banner title card (same as `ctx.title`). */
+    title?: string;
+    /** Banner position (same as `ctx.titlePos`). */
+    titlePos?: BannerPos;
+    /** Banner UX: collision / hidden (same as `ctx.bannerUi`). */
+    bannerUi?: BannerUiOpts;
+    /** Alias of {@link todoUi} - the name `ctx.todoDockUi` uses. */
+    todoDockUi?: TodoDockUiOpts;
 };
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.

package/dist/pilot-overlay/fixtures.js

@@ -92,8 +92,41 @@ export async function showPilotFixtures(page, fixtures) {
             : typeof fixtures.device === "string"
                 ? fixtures.device
                 : fixtures.device.preset || "device";
+    const bannerTitle = fixtures.clear ? undefined : fixtures.title;
+    const bannerPos = fixtures.clear ? undefined : fixtures.titlePos;
+    const bannerHidden = !!fixtures.clear || !!fixtures.bannerUi?.hidden;
+    const bannerCollision = fixtures.bannerUi?.collision !== false;
     return page
-        .evaluate(({ rings, todos, todoIndex, todoTitle, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, deviceLabel, todoUi, }) => {
+        .evaluate(({ rings, todos, todoIndex, todoTitle, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, deviceLabel, todoUi, bannerTitle, bannerPos, bannerHidden, bannerCollision, }) => {
+        // Same #wg-banner element/CSS the demo runner paints (ui/css/banner.css, already in the
+        // shared bundle) - so ctx.title / ctx.titlePos / ctx.bannerUi behave identically on a Pilot
+        // session, not a separate re-implementation.
+        if (bannerHidden) {
+            const b = __wgById("wg-banner");
+            if (b)
+                b.style.display = "none";
+        }
+        else if (bannerTitle) {
+            let banner = __wgById("wg-banner");
+            if (!banner) {
+                banner = document.createElement("div");
+                banner.id = "wg-banner";
+                const tag = document.createElement("span");
+                tag.className = "wg-banner-tag";
+                tag.textContent = "waygraph pilot";
+                const text = document.createElement("span");
+                text.className = "wg-banner-text";
+                banner.appendChild(tag);
+                banner.appendChild(text);
+                __wgAdd(banner);
+            }
+            banner.style.display = "";
+            banner.dataset.pos = bannerPos || banner.dataset.pos || "left";
+            banner.dataset.collision = bannerCollision ? "1" : "0";
+            const textEl = banner.querySelector(".wg-banner-text");
+            if (textEl)
+                textEl.textContent = bannerTitle;
+        }
         const w = window;
         if (w.__wgPilotFxHideTimer)
             clearTimeout(w.__wgPilotFxHideTimer);
@@ -329,6 +362,10 @@ export async function showPilotFixtures(page, fixtures) {
         clearAll: fixtures.clear === true,
         deviceLabel,
         todoUi,
+        bannerTitle,
+        bannerPos,
+        bannerHidden,
+        bannerCollision,
     })
         .catch(() => ({ painted: 0, missing: rings.map((r) => r.selector) }));
 }

package/dist/pilot-overlay/overlay-fixtures.d.ts

@@ -0,0 +1,9 @@
+import type { StubPhaseResult } from "../highlights.js";
+import type { PilotHighlightFixtures } from "./fixtures.js";
+/**
+ * Resolve agent-sent "waygraph overlay fixtures" (`auto highlight` JSON / shorthand) through the SAME
+ * stub-ctx path a Block's `stubBefore(ctx)` uses, so ctx.todos / ctx.device / ctx.title / ctx.bannerUi semantics
+ * (keep vs set vs clear, defaults, normalisation) cannot diverge between `waygraph demo` and pilot/auto/browser.
+ * Not Playwright test fixtures - these describe what the waygraph overlay paints on the page under test.
+ */
+export declare function overlayFixturesToPhase(f: PilotHighlightFixtures): Promise<StubPhaseResult>;

package/dist/pilot-overlay/overlay-fixtures.js

@@ -0,0 +1,45 @@
+import { runStubPhase } from "../highlights.js";
+/**
+ * Resolve agent-sent "waygraph overlay fixtures" (`auto highlight` JSON / shorthand) through the SAME
+ * stub-ctx path a Block's `stubBefore(ctx)` uses, so ctx.todos / ctx.device / ctx.title / ctx.bannerUi semantics
+ * (keep vs set vs clear, defaults, normalisation) cannot diverge between `waygraph demo` and pilot/auto/browser.
+ * Not Playwright test fixtures - these describe what the waygraph overlay paints on the page under test.
+ */
+export async function overlayFixturesToPhase(f) {
+    const lifecycle = (ctx) => {
+        if (f.clear) {
+            ctx.hideTodos();
+            ctx.hideDevice();
+            return;
+        }
+        if (f.title !== undefined)
+            ctx.title(f.title, f.titlePos ? { pos: f.titlePos } : undefined);
+        else if (f.titlePos)
+            ctx.titlePos(f.titlePos);
+        if (f.bannerUi)
+            ctx.bannerUi(f.bannerUi);
+        if (f.todos !== undefined) {
+            ctx.todos("pilot", f.todos, {
+                title: f.todoTitle ?? "Plan",
+                index: f.todoIndex ?? 0,
+                pos: f.todoPos === "left" ? "left" : "right",
+            });
+        }
+        const ui = f.todoDockUi ?? f.todoUi;
+        if (ui)
+            ctx.todoDockUi(ui);
+        if (f.device)
+            ctx.device(f.device);
+        if (typeof f.zoom === "number" && Number.isFinite(f.zoom) && f.zoom > 0)
+            ctx.zoom(f.zoom);
+        if (f.zoomOut !== undefined)
+            ctx.zoomOut(f.zoomOut);
+        if (f.rings?.length) {
+            f.rings.forEach((r, i) => {
+                const { selector, label, ...rest } = r;
+                ctx.ring(`ring${i + 1}`, { selector, label, ...rest });
+            });
+        }
+    };
+    return runStubPhase({ name: "overlay-fixtures", stubBefore: lifecycle }, "stubBefore");
+}

package/dist/pilot-overlay/shell.js

@@ -1,8 +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
 // purple/white scheme (#a78bfa / #1a1033) that didn't match anything else -
 // "our design here seems like barely shares with the ui on the stepper
@@ -64,26 +62,9 @@ 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-sent fixture rings: generated from ui/tokens (tones shared with #wg-ring). */
-${pilotFxRingCss()}
-#wg-pilot-fx-todos{
-  position:fixed;z-index:2147483645;top:72px;max-width:280px;max-height:calc(100vh - 100px);overflow:auto;
-  font:12px/1.4 ui-sans-serif,system-ui,sans-serif;color:#fff;
-  background:${SURFACE};border-radius:10px;padding:10px 12px;
-  box-shadow:0 2px 10px rgba(0,0,0,.3);pointer-events:auto;
-  transition:opacity .25s ease;
-}
-#wg-pilot-fx-todos.wg-todo-behind{z-index:2147483643;opacity:.42;pointer-events:none;}
-#wg-pilot-fx-todos[data-pos=left]{left:14px;right:auto;}
-#wg-pilot-fx-todos[data-pos=right]{right:14px;left:auto;}
-#wg-pilot-fx-todos .wg-pilot-fx-todo-title{font-weight:700;color:#c9a6ff;margin-bottom:6px;}
-#wg-pilot-fx-todos ol{margin:0;padding-left:18px;}
-#wg-pilot-fx-todos li{margin:3px 0;color:#ddd;}
-#wg-pilot-fx-todos li.wg-pilot-fx-todo-done{color:#888;text-decoration:line-through;}
-#wg-pilot-fx-todos li.wg-pilot-fx-todo-now{color:#fff;font-weight:700;}
-#wg-pilot-fx-todos[data-compact="1"]:not(:hover) li.wg-todo-fold{display:none;}
-#wg-pilot-fx-todos .wg-todo-more{margin-top:6px;padding:4px 8px;border-radius:8px;
-  background:rgba(124,58,237,.22);font:700 11px/1.2 system-ui,sans-serif;color:#e8dcff;}
+/* Agent fixture rings (.wg-pilot-fx-ring/label), #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. */
 #wg-pilot-fx-focus{position:fixed;z-index:2147483644;pointer-events:none;
   border-radius:12px;box-shadow:0 0 0 9999px rgba(8,4,20,.62);
@@ -107,7 +88,7 @@ ${pilotFxRingCss()}
 #wg-pilot-fx-device[data-preset=mobile]{border-color:#3B82F6;}
 #wg-pilot-fx-device[data-preset=tablet]{border-color:#22C55E;}
 #wg-pilot-fx-device[data-preset=desktop]{border-color:#9CA3AF;}
-` + WAYGRAPH_RING_CSS;
+`;
 /** Browser-side shell install — runs on every document via context.addInitScript. */
 function installPilotOverlayShell(css) {
     if (__wgById("wg-pilot-overlay"))

package/dist/pilot-overlay.d.ts

@@ -1,3 +1,5 @@
 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";
+export * from "./pilot-overlay/overlay-fixtures.js";

package/dist/pilot-overlay.js

@@ -2,3 +2,5 @@
 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";
+export * from "./pilot-overlay/overlay-fixtures.js";

package/dist/runner/banner-log.js

@@ -0,0 +1,62 @@
+// Banner (title card) authoring + verbose log helpers. Mirrors the todo dock's probe/log path
+// so an agent without eyes can read banner state from the demo log.
+import { demoLog } from "./demo-log.js";
+
+/** Authored banner UX from a stub phase -> the { pos, collision, hidden } shape installOverlay takes. */
+export function bannerUiFromPhase(phase) {
+  const ui = {};
+  if (phase && phase.titlePos) ui.pos = phase.titlePos;
+  if (phase && phase.bannerUi) {
+    if (phase.bannerUi.collision !== undefined) ui.collision = !!phase.bannerUi.collision;
+    if (phase.bannerUi.hidden !== undefined) ui.hidden = !!phase.bannerUi.hidden;
+  }
+  return ui;
+}
+
+/** Read the live banner: text, position, whether it was moved by ring collision; drains the move log. */
+export async function probeBanner(page) {
+  return page
+    .evaluate(() => {
+      const b = __wgById("wg-banner");
+      const log = window.__wgBannerLog || [];
+      window.__wgBannerLog = [];
+      if (!b) return { present: false, log };
+      const r = b.getBoundingClientRect();
+      const text = b.querySelector(".wg-banner-text");
+      return {
+        present: true,
+        text: text ? text.textContent : "",
+        pos: b.dataset.pos || null,
+        home: b.dataset.home || null,
+        moved: b.dataset.moved || null,
+        collision: b.dataset.collision !== "0",
+        hidden: b.style.display === "none",
+        authored: b.dataset.authored === "1",
+        left: Math.round(r.left),
+        top: Math.round(r.top),
+        w: Math.round(r.width),
+        h: Math.round(r.height),
+        log,
+      };
+    })
+    .catch(() => ({ present: false, log: [] }));
+}
+
+export function logBannerDom(tag, p) {
+  if (!p) return;
+  if (!p.present) {
+    demoLog("  " + tag + " banner-dom absent");
+    return;
+  }
+  demoLog(
+    "  " + tag + " banner-dom " +
+      JSON.stringify(String(p.text || "").slice(0, 60)) +
+      "@" + p.pos +
+      (p.home && p.home !== p.pos ? " (home=" + p.home + ")" : "") +
+      " " + p.left + "," + p.top + " " + p.w + "x" + p.h +
+      " collision=" + (p.collision ? "on" : "off") +
+      (p.hidden ? " HIDDEN" : "") +
+      (p.authored ? " authored" : ""),
+  );
+  for (const line of p.log || []) demoLog("  " + tag + " banner " + line);
+}

package/dist/runner/demo-log.js

@@ -109,8 +109,14 @@ function demoTs() {
   );
 }
 
+let logSurface = "demo";
+/** Which surface is talking (demo | auto | browser | pilot) - same log format everywhere, only the tag differs. */
+export function setDemoLogSurface(name) {
+  logSurface = String(name || "demo");
+}
+
 function demoPrefix() {
-  return ansiPaint(ANSI.dim, "[" + demoTs() + "]") + " waygraph demo: ";
+  return ansiPaint(ANSI.dim, "[" + demoTs() + "]") + " waygraph " + logSurface + ": ";
 }
 
 export function demoLog(msg) {
@@ -170,6 +176,8 @@ export function logStubPhaseFixtures(phaseName, phase) {
   const tag = "stub." + phaseName;
   if (phase.title) demoFixture(tag, "ctx.title(...)", JSON.stringify(phase.title));
   if (phase.banner) demoFixture(tag, "ctx.banner(...)", JSON.stringify(phase.banner));
+  if (phase.titlePos) demoFixture(tag, "ctx.titlePos(...)", JSON.stringify(phase.titlePos));
+  if (phase.bannerUi) demoFixture(tag, "ctx.bannerUi(...)", JSON.stringify(phase.bannerUi));
   if (phase.deviceSync && phase.deviceSync !== "keep") {
     demoFixture(
       tag,

package/dist/runner/inpage/banner.js

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

package/dist/runner/inpage/core.js

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