waygraph 0.15.32 → 0.15.33

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/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

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

package/dist/pilot-overlay.js

@@ -3,3 +3,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";
+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;

package/dist/runner/overlay-css.js

@@ -1,7 +1,5 @@
 // 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 { WAYGRAPH_RING_CSS } from "../highlights.js";
-import { cursorCss } from "../ui/components/cursor.js";
 import { SURFACE } from "../ui/tokens.js";
 
 // ---------------------------------------------------------------------------
@@ -13,22 +11,11 @@ import { SURFACE } from "../ui/tokens.js";
 // label-under-box language, minus everything camera/narration-specific).
 // Purely CLI-level orchestration - no engine changes, no change to the
 // non-STEP path above.
-export const RING_CSS =
-  // Shared with pilot-overlay.ts's showPilotVision - same ring/label CSS,
-  // one source of truth (highlights.ts), so a Blind Pilot vision ring and a
-  // demo stepper ring never visually drift apart.
-  WAYGRAPH_RING_CSS +
-  // Mouse cursor icon that travels to a target before it's acted on, plus a
-  // quick expanding ripple at the moment of a click - same idea as
-  // help-center-clip-engine's #clip-cursor/#clip-ring (video-pipeline). The
-  // shape itself is an inline SVG set as innerHTML in installOverlay below
-  // (dark fill + white stroke, same as the clip-engine's own cursor) - a
-  // plain solid-white CSS clip-path (the first attempt here) had no outline
-  // at all and all but disappeared against this app's light background.
-  // Travel duration is JS-driven per call via --wg-cursor-ms, same reason
-  // the clip engine's own comment gives: a hardcoded CSS duration would
-  // make the speed param a no-op.
-  cursorCss() +
+// Runner-only chrome (step panel, todo-dock legacy variant, zoom/typing/device chips) - NOT
+// ring/cursor/banner, which come from the one shared bundle every surface installs
+// (ui/css/*.css, see ensureShadowRoot in overlay-install.js). Injected under its own key so it
+// never collides with that bundle.
+export const RUNNER_EXTRA_CSS =
   // Spotlight: dim everything except the highlight target (focus: true).
   "#wg-focus-veil{position:fixed;z-index:2147483644;pointer-events:none;" +
   "border-radius:12px;box-shadow:0 0 0 9999px rgba(8,4,20,.62);" +
@@ -225,15 +212,7 @@ export const RING_CSS =
   "#wg-modules .wg-mod-done{background:#2a1650;color:#9a7ad1;}" +
   "#wg-modules .wg-mod-current{background:#7C3AED;color:#fff;}" +
   "#wg-modules .wg-mod-upcoming{background:transparent;color:#5a4a80;border:1px solid #3a2a60;}" +
-  "#wg-banner{position:fixed;z-index:2147483647;top:14px;max-width:320px;" +
-  "background:" + SURFACE + ";color:#fff;border-radius:12px;padding:10px 16px;" +
-  "font:14px/1.4 system-ui,sans-serif;box-shadow:0 8px 20px rgba(0,0,0,.3);" +
-  "border:1px solid rgba(124,58,237,.4);cursor:pointer;user-select:none;}" +
-  "#wg-banner[data-pos=left]{left:14px;right:auto;transform:none;}" +
-  "#wg-banner[data-pos=center]{left:50%;right:auto;transform:translateX(-50%);}" +
-  "#wg-banner[data-pos=right]{right:14px;left:auto;transform:none;}" +
-  "#wg-banner .wg-banner-tag{display:block;font-size:10px;font-weight:700;color:#c9a6ff;" +
-  "letter-spacing:.05em;text-transform:uppercase;margin-bottom:2px;}" +
+  // #wg-banner: comes from the shared bundle (ui/css/banner.css) now - not redefined here.
   "#wg-panel .wg-key{margin:8px 0;}" +
   // A live, human-readable preview of what's about to be written for this
   // MemKey - Dan: "i want pretty to exist in memkeys too... it shows what

package/dist/runner/overlay-install.js

@@ -1,6 +1,6 @@
 // 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 { HOST_CSS, RING_CSS, WAYGRAPH_FAVICON } from "./overlay-css.js";
+import { HOST_CSS, RUNNER_EXTRA_CSS, WAYGRAPH_FAVICON } from "./overlay-css.js";
 import { ensureShadowRoot } from "../ui/shadow.js";
 import { resolveTodoDockUi } from "../highlights.js";
 import { installCore } from "./inpage/core.js";
@@ -12,9 +12,12 @@ import { installTodos } from "./inpage/todos.js";
 import { installDevice } from "./inpage/device.js";
 import { applyVideoDeviceStage } from "./device-stage.js";
 
-export async function installOverlay(page, title) {
+/** `ui` = authored banner UX from the stub phase: { pos, collision, hidden } (all optional). */
+export async function installOverlay(page, title, ui) {
+  // ring/cursor/banner/dock come from the ONE shared bundle every surface installs (ui/css/*.css).
   await ensureShadowRoot(page);
-  await page.evaluate(([css, key]) => __wgCss(css, key), [RING_CSS, "wg-overlay-css"]).catch(() => {});
+  // Runner-only chrome (step panel, zoom/typing/device chips) - separate key, no collision.
+  await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-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
@@ -25,7 +28,7 @@ export async function installOverlay(page, title) {
   const todoPos = envTodoPos === "right" ? "right" : "left";
   const envAutoplay = process.env.WAYGRAPH_AUTOPLAY === "1";
   const todoDockUi = resolveTodoDockUi();
-  const args = { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay, todoDockUi };
+  const args = { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay, todoDockUi, bannerUi: ui || null };
   await page.evaluate(installCore, args).catch(() => {});
   await page.evaluate(installSwipeZoom, args).catch(() => {});
   await page.evaluate(installBanner, args).catch(() => {});

package/dist/runner/overlay-present.d.ts

@@ -0,0 +1,8 @@
+import type { Page } from "@playwright/test";
+import type { StubPhaseResult } from "../highlights/types.js";
+
+export interface SessionOverlay {
+  present(tag: string, phase: Partial<StubPhaseResult>): Promise<void>;
+  restore(): Promise<void>;
+}
+export function createSessionOverlay(page: Page, surface: string): SessionOverlay;